GraphQL PPX rewriter for Bucklescript/ReasonML
Clone or download
Latest commit 14e7119 Aug 8, 2018
Permalink
Failed to load latest commit information.
ci Build static binary in Alpine container to force musl Jul 24, 2018
discover Use ocamlc system config to determine if build should be static Jul 21, 2018
doc Add README Aug 13, 2017
src Fix issue with custom scalars in argument position Aug 8, 2018
tests Fix issue with custom scalars in argument position Aug 8, 2018
tests_apollo Try to run apollo tests on Windows now that bs-platform quotes its pp… Aug 8, 2018
.gitignore merge with master Jul 31, 2018
.merlin Create npm package, run tests on node through bucklescript Aug 12, 2017
.npmignore Switch over to jbuilder Mar 3, 2018
.travis.yml New npm token Jul 25, 2018
CHANGELOG.md Release version 0.2.7 Aug 8, 2018
DEVELOPING.md Running tests through esy isn't supported currently Jul 24, 2018
LICENSE Add opam package metadata and install/uninstall targets Aug 12, 2017
Makefile Remove "skip apollo tests" functionality Aug 8, 2018
README.md Tidy up the README a bit Jul 31, 2018
appveyor.yml Remove "skip apollo tests" functionality Aug 8, 2018
bsconfig.json Update bs-platform and super-errors Sep 8, 2017
copyPlatformBinaryInPlace.js Copy binary to both `ppx` and `ppx.exe` for Windows support May 10, 2018
dune Upgrade from jbuilder to dune Jul 14, 2018
dune-project Upgrade from jbuilder to dune Jul 14, 2018
esy.json Support for esy local development. Jul 19, 2018
esyi.lock.json Support for esy local development. Jul 19, 2018
jbuild-ignore Support for esy local development. Jul 19, 2018
opam Upgrade from jbuilder to dune Jul 14, 2018
package.json Release version 0.2.7 Aug 8, 2018
sendIntrospectionQuery.js Provide headers with sendIntrospectionQuery (#21) Feb 7, 2018
yarn.lock Try to run apollo tests on Windows now that bs-platform quotes its pp… Aug 8, 2018

README.md

GraphQL syntax extension for Bucklescript/ReasonML

Build Status Build Status npm

This library lets you construct type-safe and validated queries at compile time, and generates response validation code for you. If you're writing a Bucklescript app that talks to a GraphQL server, this library will cut down on the boilerplate you have to write.

It is compatible with both OCaml and ReasonML syntax. There are no runtime dependencies except for Js.Json and Js.Dict, both included in the Bucklescript standard library.

Installation

Assuming that you've already got a Bucklescript project set up, installing this syntax extension consists of two steps:

First, add this package as a dependency to your package.json:

yarn add --dev graphql_ppx
# or, if you use npm:
npm install --saveDev graphql_ppx

Second, add the PPX to your bsconfig.json:

{
    "ppx-flags": [
        "graphql_ppx/ppx"
    ]
}

Examples

If you add a field that does not exist, you'll get a compiler error on the exact location this happens. This automatically works with Merlin, giving you immediate feedback in your editor:

Misspelled field, immediate compiler errors

Variables sent to queries and mutations are of course typed too. Nullable variables are translated to optional labelled arguments, while non-null variables become mandatory arguments:

Remove a variable argument, get a compiler error

(The Api.sendQuery function here is a small wrapper around bs-fetch, check it out below)

The result of a query is turned into a typed Js.t object, which will generate compiler errors if you try to access fields that don't exist:

Remove a field, get compiler errors

While these examples use the ReasonML syntax, using the standard OCaml syntax works as well.

Usage

Download the server schema

This plugin requires a graphql_schema.json file to exist somewhere in the project hierarchy, containing the result of sending an introspection query to your backend. To help you with this, a simple script is included to send this query to a server and save the result as graphql_schema.json in the current directory:

yarn send-introspection-query http://my-api.example.com/api
# or, if you use npm
npm run send-introspection-query http://my-api.example.com/api

Custom schema name

If you've already got a schema file downloaded for other purposes, you can tell graphql_ppx to use that one by updating the "ppx-flags" in bsconfig.json. Note: no space around the equal sign!

{
  "ppx-flags": [
    "graphql_ppx/ppx\\ -schema=your_schema.json"
  ]
}

While you can pass a path higher up the folder structure, like -schema=../somedir/your_schema.json, you might result into some path parsing problems with BuckleScript or Merlin.

Ignore .graphql_ppx_cache in your version control

This plugin will generate a .graphql_ppx_cache folder alongside your JSON schema to optimize parsing performance for BuckleScript and Merlin. If you're using a version control system, you don't need to check it in.

Send queries

To define a query, you declare a new module and type the query as a string inside the graphql extension:

module HeroQuery = [%graphql {|
{
  hero {
    name
  }
}
|}];

This module exposes a few functions, but the most useful one is make, which takes all arguments to the query/mutation as labelled function arguments, ending with (). It an object containing three things: query, which is a string containing the query itself; variables, a Js.Json.t object containing the serialized variables for the query; and parse, a function that takes a Js.Json.t instance and returns a typed object corresponding to the query.

A simple example might make this a bit clear:

module HeroQuery = [%graphql {| { hero { name } } |}];

/* Construct a "packaged" query; HeroQuery takes no arguments: */
let heroQuery = HeroQuery.make();

/* Send this query string to the server */
let query = heroQuery##query;

/* Let's assume that this was the result we got back from the server */
let sampleResponse = "{ \"hero\": {\"name\": \"R2-D2\"} }";

/* Convert the response to JSON and parse the result */
let result = Js.Json.parseExn(sampleResponse) |> query##parse;

/* Now you've got a well-typed object! */
Js.log("The hero of the story is " ++ result##hero##name);

Integrating with the Fetch API

bs-fetch is a wrapper around the Fetch API. I've been using this simple function to send/parse queries:

exception Graphql_error(string);

let sendQuery = q =>
  Bs_fetch.(
    fetchWithInit(
      "/graphql",
      RequestInit.make(
        ~method_=Post,
        ~body=
          Js.Dict.fromList([
            ("query", Js.Json.string(q##query)),
            ("variables", q##variables)
          ])
          |> Js.Json.object_
          |> Js.Json.stringify
          |> BodyInit.make,
        ~credentials=Include,
        ~headers=
          HeadersInit.makeWithArray([|("content-type", "application/json")|]),
        ()
      )
    )
    |> Js.Promise.then_(resp =>
         if (Response.ok(resp)) {
           Response.json(resp)
           |> Js.Promise.then_(data =>
                switch (Js.Json.decodeObject(data)) {
                | Some(obj) =>
                  Js.Dict.unsafeGet(obj, "data")
                  |> q##parse
                  |> Js.Promise.resolve
                | None =>
                  Js.Promise.reject(Graphql_error("Response is not an object"))
                }
              );
         } else {
           Js.Promise.reject(
             Graphql_error("Request failed: " ++ Response.statusText(resp))
           );
         }
       )
  );

Limitations

This implementation is incomplete. It does not support:

  • Non-inline fragments of any kind.
  • Interfaces.
  • All GraphQL validations. It will not validate argument types and do other sanity-checking of the queries. The fact that a query compiles does not mean that it will pass server-side validation.

Things that do work

  • Objects are converted into Js.t objects
  • Enums are converted into polymorphic variants
  • Floats, ints, strings, booleans, id are converted into their corresponding native OCaml types.
  • Custom scalars are parsed as Js.Json.t
  • Arguments with input objects
  • Using @skip and @include will force non-optional fields to become optional.
  • Unions are converted to polymorphic variants, with exhaustiveness checking. This only works for object types, not for unions containing interfaces.

Extra features

By using some directives prefixed bs, graphql_ppx lets you modify how the result of a query is parsed. All these directives will be removed from the query at compile time, so your server doesn't have to support them.

Record conversion

While Js.t objects often have their advantages, they also come with some limitations. For example, you can't create new objects using the spread (...) syntax or pattern match on their contents. Since they are not named, they also result in quite large type error messages when there are mismatches.

OCaml records, on the other hand, can be pattern matched, created using the spread syntax, and give nicer error messages when they mismatch. graphql_ppx gives you the option to decode a field as a record using the @bsRecord directive:

type hero = {
  name: string,
  height: number,
  mass: number
};

module HeroQuery = [%graphql {|
{
  hero @bsRecord {
    name
    height
    mass
  }
}
|}];

Note that the record has to already exist and be in scope for this to work. graphql_ppx will not create the record. Even though this involves some duplication of both names and types, type errors will be generated if there are any mismatches.

Custom field decoders

If you've got a custom scalar, or just want to convert e.g. an integer to a string to properly fit a record type (see above), you can use the @bsDecoder directive to insert a custom function in the decoder:

module HeroQuery = [%graphql {|
{
  hero {
    name
    height @bsDecoder(fn: "string_of_float")
    mass
  }
}
|}];

In this example, height will be converted from a number to a string in the result. Using the fn argument, you can specify any function literal you want.

Non-union variant conversion

If you've got an object which in practice behave like a variant - like signUp above, where you either get a user or a list of errors - you can add a @bsVariant directive to the field to turn it into a polymorphic variant:

module SignUpQuery = [%graphql
  {|
mutation($name: String!, $email: String!, $password: String!) {
  signUp(email: $email, email: $email, password: $password) @bsVariant {
    user {
      name
    }

    errors {
      field
      message
    }
  }
}
|}
];

let x =
  SignUpQuery.make(~name="My name", ~email="email@example.com", ~password="secret", ())
  |> Api.sendQuery |> Promise.then_(response =>
    switch (response##signUp) {
    | `User(user) => Js.log2("Signed up a user with name ", user##name)
    | `Errors(errors) => Js.log2("Errors when signing up: ", errors)
    } |> Promise.resolve);

This helps with the fairly common pattern for mutations that can fail with user-readable errors.

Alternative Query.make syntax

When you define a query with variables, the make function will take corresponding labelled arguments. This is convenient when constructing and sending the queries yourself, but might be problematic when trying to abstract over multiple queries.

For this reason, another function called makeWithVariables is also generated. This function takes a single Js.t object containing all variables.

module MyQuery = [%graphql {|
  mutation ($username: String!, $password: String!) {
    ...
  }
|}];

/* You can either use `make` with labelled arguments: */
let query = MyQuery.make(~username="testUser", password="supersecret", ());

/* Or, you can use `makeWithVariables`: */
let query = MyQuery.makeWithVariables({ "username": "testUser", "password": "supersecret" });

Getting the type of the parsed value

If you want to get the type of the parsed and decoded value - useful in places where you can't use OCaml's type inference - use the t type of the query module:

module MyQuery = [%graphql {| { hero { name height }} |}];


/* This is something like Js.t({ . hero: Js.t({ name: string, weight: float }) }) */
type resultType = MyQuery.t;

Verbose mode (Contributors only)

You can pass -verbose in bsconfig.json to turn on the verbose mode. You can also use the Log module to log into verbose mode.

Future work

Core GraphQL features that need to be implemented:

  • Inline fragments
  • Fragment spreads
  • Selecting on interfaces
  • Selecting on unions
  • Input object arguments
  • Query validations (only partially implemented)
  • Explicit resolvers for custom scalars

Experimental: graphql-tag replacement

To simplify integration with e.g. Apollo, this PPX can write the query AST instead of the raw source, in a way that should be compatible with how graphql-tag works.

To enable this, change your bsconfig.json to:

{
    "ppx-flags": [
        "graphql_ppx/ppx\\ -ast-out"
    ]
}

Now, the query field will be a Js.Json.t structure instead of a string, ready to be sent to Apollo.

module HeroQuery = [%graphql {| { hero { name } } |}];

/* Construct a "packaged" query; HeroQuery takes no arguments: */
let heroQuery = HeroQuery.make();

/* This is no longer a string, but rather an object structure */
let query = heroQuery##query;

Building manually on unsupported platforms

graphql_ppx supports 64 bit Linux, Windows, and macOS, as well as 32 bit Windows out of the box. If you're on any other platform, please open an issue on this repository so we can support it.