Skip to content
Validates graphql queries and converts them to elm code.
Branch: master
Clone or download
Pull request Compare This branch is 1 commit behind harmboschloo:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode
examples
src
test
.gitignore
.travis.yml
LICENSE
README.md
index.d.ts
index.js
package.json
tsconfig.json
yarn.lock

README.md

graphql-to-elm

Build Status

graphql-to-elm validates GraphQL queries and converts them to Elm code. Can be used with elm 0.19 and graphql 0.12, 0.13 and 14.

This package assumes that you use GraphQL query documents and a schema document to write your queries and schema in. Or that you have a way to generate these documents.

If you want to write your GraphQL queries in Elm have a look at dillonkearns/graphqelm or jamesmacaulay/elm-graphql. For more options have a look at this discussion.

How does it work

Suppose you have a GraphQL query file (myQuery.gql):

query UserName {
  user {
    name
  }
}

Then you create a code generation script (prebuild.js) like this:

const { graphqlToElm } = require("graphql-to-elm");

graphqlToElm({
  schema: "./src/mySchema.gql",
  queries: ["./src/myQuery.gql"],
  src: "./src",
  dest: "./src-generated"
});

You run the code generation script (node prebuild.js).

Then in your Elm code you can do this (full code and GraphQL package):

import GraphQL.Errors exposing (Errors)
import GraphQL.Http.Basic exposing (postQuery)
import GraphQL.Response as Response exposing (Response)
import Http
import MyQuery

init : () -> ( String, Cmd Msg )
init _ =
    ( "", Http.send GotUserName (postQuery "/graphql" MyQuery.userName) )

type Msg
    = GotUserName (Result Http.Error (Response Errors MyQuery.UserNameQuery))

update : Msg -> String -> ( String, Cmd Msg )
update msg model =
    case msg of
        GotUserName (Ok (Response.Data data)) ->
            ( "user name: " ++ data.user.name, Cmd.none )

        GotUserName (Ok (Response.Errors _ _)) ->
            ( "GraphQL error", Cmd.none )

        GotUserName (Err _) ->
            ( "Http error", Cmd.none )

Overview

For every query document graphql-to-elm will generate valid Elm types, encoders and decoders that you can use in your code.

It includes support for:

  • operations (queries, mutations, subscriptions)
  • operation names
  • fragments
  • inline fragments
  • variables
  • aliases
  • directives
  • enums
  • custom scalar encoders and decoders
  • custom enum encoders and decoders
  • custom error decoder
  • batched queries

Usage

You'll need to have node/npm installed.

  1. Install graphql-to-elm from the command line through npm.
    To add it to your project's package.json as a dev dependency use this command:

    npm install --save-dev graphql-to-elm
  2. Create a JavaScript file (for instance prebuild.js) similar to this one:

    const { graphqlToElm } = require("graphql-to-elm");
    
    graphqlToElm({
      schema: "./src/schema.gql",
      queries: ["./src/MyQueries1.gql", "./src/MyQueries2.gql"],
      src: "./src",
      dest: "./src-generated"
    });
  3. You can run this file from the command line with:

    node prebuild.js

    Running this command will read and validate your schema and queries. And for every query file it will generate and Elm file in the destination folder with Elm types, encoders and decoders.

  4. To use the generated files in your project you have to include the destination folder in the source-directories field of your elm-package.json. It should look something like this:

    "source-directories": [
        "src",
        "src-generated"
    ],
  5. Now you can import the generated Elm files (which include the graphql-to-elm package files) in your project and use them.

    For full usage examples see the examples folder or have a look at the test fixtures folder.

Options

option type default description
schema `string { string: string }`
enums EnumOptions { baseModule: "GraphQL.Enum" } Options for generating union types from GraphQL enums. 'baseModule' is the base module name for the union types.
queries string[] Array of filenames of the query documents.
scalarEncoders TypeEncoders {} Scalar type encoders.
enumEncoders TypeEncoders {} Enum type encoders.
scalarDecoders TypeDecoders {} Scalar type decoders.
enumDecoders TypeDecoders {} Enum type decoders.
errorsDecoder TypeDecoder GraphQL.Errors decoder GraphQL response errors decoder
src string . Base folder of the queries.
dest string src option Destination folder for the generateed Elm files.
operationKind "query", "named" or "named_prefixed" "query" Send the full query to the server or only the operation name. The operation name can be prefixed with the query filename: [filename]:[operationName].
log (message: string) => void console.log Callback for log messages. Set to null to disable.
interface EnumOptions {
  baseModule?: string;
}

interface TypeEncoders {
  [graphqlType: string]: TypeEncoder;
}

interface TypeEncoder {
  type: string;
  encoder: string;
}

interface TypeDecoders {
  [graphqlType: string]: TypeDecoder;
}

interface TypeDecoder {
  type: string;
  decoder: string;
}
You can’t perform that action at this time.