graphqelm
v3.1.12
Published
<img src="https://cdn.rawgit.com/martimatix/logo-graphqelm/master/logo.svg" alt="graphqelm logo" width="40%" align="right">
Downloads
99
Readme
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:
- Gives you type-safe GraphQL queries (if it compiles, it's valid according to the schema),
- Creates decoders for you in a seamless and failsafe way, and
- 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
.
Add the
Graphqelm
elm package as a dependency in yourelm-package.json
.elm package install dillonkearns/graphqelm
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 thegraphqelm
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
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" }
With the above in your
package.json
, runningnpm 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 theexamples
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.