GraphqElm

Why use this package over the other available Elm GraphQL packages? This is the only one that generates type-safe code for your entire schema. (It's also the only type-safe library with Elm 0.18 support, see this discourse thread ).

I built this package because I wanted to have something that:

1. Gives you type-safe GraphQL queries (if it compiles, it's valid according to the schema),
2. Creates decoders for you in a seamless and failsafe way, and
3. Eliminates GraphQL features in favor of Elm language constructs where possible for a simpler UX (for example, GraphQL variables & fragments should just be Elm functions, constants, lets).

See an example in action on Ellie.

See more end-to-end example code in the examples/ folder.

Overview

graphqelm is an Elm package and accompanying command-line code generator that creates type-safe Elm code for your GraphQL endpoint. You don't write any decoders for your API with graphqelm, instead you simply select which fields you would like, similar to a standard GraphQL query but in Elm. For example, this GraphQL query

query {
  human(id: "1001") {
    name
  }
}

would look like this in graphqelm (the code in this example that is prefixed with StarWars is auto-generated)

import Graphqelm.Operation exposing (RootQuery)
import Graphqelm.SelectionSet exposing (SelectionSet, with)
import StarWars.Object
import StarWars.Object.Human as Human
import StarWars.Query as Query


type alias Response =
    { vader : Maybe Human }


query : SelectionSet Response RootQuery
query =
    Query.selection Response
        |> with (Query.human { id = StarWars.Scalar.Id "1001" } human)


type alias Human =
    { name : String }


human : SelectionSet Human Human.Human
human =
    Human.selection Human
        |> with Human.name

GraphQL and Elm are a perfect match because GraphQL is used to enforce the types that your API takes as inputs and outputs, much like Elm's type system does within Elm. elm-graphql simply bridges this gap by making your Elm code aware of your GraphQL server's schema. If you are new to GraphQL, graphql.org/learn/ is an excellent way to learn the basics.

After installing the command line tool and Elm package, running elm-graphql just looks like

graphqelm https://graphqelm.herokuapp.com --base Swapi --output examples/src

Usage

graphqelm generates Elm code that allows you to build up type-safe GraphQL requests. Here are the steps to setup graphqelm.

1. Add the Graphqelm elm package as a dependency in your elm-package.json.

   elm package install dillonkearns/graphqelm

2. Install the graphqelm command line tool through npm. This is what you will use to generate Elm code for your API. It is recommended that you save the graphqelm command line tool as a dev dependency so that everyone on your project is using the same version.

   npm install --save-dev graphqelm
   # you can now run it locally with the ./node_modules/.bin/graphqelm binary,
   # or by calling it through an npm script as in this project's package.json

3. Run the graphqelm command line tool installed above to generate your code. If you used the --save-dev method above, you can simply create a script in your package.json like the following:

   {
     "name": "star-wars-graphqelm-project",
     "version": "1.0.0",
     "scripts": {
       "api": "graphqelm https://graphqelm.herokuapp.com/api --base StarWars"
     }

4. With the above in your package.json, running npm run api will generate Graphqelm code for you to call in ./src/StarWars/. You can now use the generated code as in this Ellie example or in the examples folder.

Frequently Asked Questions

If you're wondering why code is generated a certain way, you're likely to find an answer in the FAQ. There's also a very helpful group of people in the #graphql channel in the Elm Slack.

Contributors

Thank you Mario Martinez (martimatix) for all your feedback, the elm-format PR, and for the incredible logo design!

Thank you Mike Stock (mikeastock) for setting up Travis CI!

Thanks for the reserved words pull request @madsflensted!

Roadmap

All core features are supported. That is, you can build any query or mutation with your graphqelm-generated code, and it is guaranteed to be valid according to your server's schema.

I am currently experimenting with subscriptions, checkout this live demo or examples/src/Subscription.elm for an example using Phoenix/Absinthe as a backend.

I would like to investigate generating helpers to make pagination simpler for Connections (based on the Relay Cursor Connections Specification). If you have ideas on this chime in on this thread.

See the full roadmap on Trello.