View Source GraphQLDocument (GraphQLDocument v0.1.0)

A utility for building GraphQL documents. (Strings that contain a GraphQL query/mutation.)

syntax

Syntax

GraphQLDocument.to_string converts nested lists/keyword lists into the analogous GraphQL syntax.

Simply write lists and keyword lists "as they look in GraphQL".

Let's take a look at some examples.

object-fields

Object Fields

To request a list of fields in an object, include them in a list:

[query: [
  human: [:name, :height]
]]

GraphQLDocument.to_string/1 will take that Elixir structure and return

"""
query {
  human {
    name
    height
  }
}
"""

arguments

Arguments

When a field includes arguments, wrap the arguments and child fields in a tuple, like this:

{args, fields}

For example, GraphQLDocument.to_string/1 will take this Elixir structure

[query: [
  human: {
    [id: "1000"],
    [:name, :height]
  }
]]

and return this GraphQL document:

"""
query {
  human(id: "1000") {
    name
    height
  }
}
"""

Argument types and Enums

GraphQLDocument.to_string/1 will translate Elixir primitives into the analogous GraphQL primitive type for arguments.

GraphQL enums can be expressed as an atom (e.g. FOOT) or in a tuple syntax, {:enum, "FOOT"}.

For example:

[query: [
  human: {
    [id: "1000"],
    [:name, height: {[unit: FOOT], []}]
  }
]]

becomes

query {
  human(id: "1000") {
    name
    height(unit: FOOT)
  }
}

We can specify [unit: FOOT] as [unit: {:enum, "FOOT"}], which is useful for interpolating dynamic values into the query.

Expressing arguments without sub-fields

Notice the slightly complicated syntax above: height: {[unit: FOOT], []}

The way to include arguments is in an {args, fields} tuple. So if a field has arguments but no sub-fields, put [] where the sub-fields go.

nesting-fields

Nesting Fields

Since GraphQL supports a theoretically infinite amount of nesting, you can also nest as much as needed in the Elixir structure.

Furthermore, we can take advantage of Elixir's syntax feature that allows a regular list to be "mixed" with a keyword list:

# Elixir allows lists with a Keyword List as the final members
[:name, :height, friends: [:name, :age]]

Using this syntax, we can build a nested structure like this:

[query: [
  human: {
    [id: "1000"],
    [
      :name,
      :height,
      friends: {
        [olderThan: 30],
        [:name, :height]
      }
    ]
  }
]]
query {
  human(id: "1000") {
    name
    height
    friends(olderThan: 30) {
      name
      height
    }
  }
}

aliases

Aliases

In order to name a field with an alias, follow the syntax below, where me is the alias and user is the field:

[query: [
  me: {
    :user
    [id: 100],
    [:name, :email]
  }
]]

Which will emit this GraphQL document:

query {
  me: user(id: 100) {
    name
    email
  }
}

Link to this section Summary

Functions

Wraps an enum string value (such as user input from a form) into a GraphQLDocument-friendly tuple.

Generates GraphQL syntax from a nested Elixir keyword list.

Link to this section Functions

Wraps an enum string value (such as user input from a form) into a GraphQLDocument-friendly tuple.

example

Example

iex> GraphQLDocument.enum("soundex")
{:enum, "soundex"}
Link to this function

to_string(params, indent_level \\ 0)

View Source

Generates GraphQL syntax from a nested Elixir keyword list.

example

Example

iex> GraphQLDocument.to_string(query: [user: {[id: 3], [:name, :age, :height, documents: [:filename, :url]]}])
"""
query {
  user(id: 3) {
    name
    age
    height
    documents {
      filename
      url
    }
  }
}\
"""