Cognac View Source

Build GraphQL queries efficiently without string mashing. Pairs well with Absinthe.

Usage

Add Cognac as a dependency in your mix.exs file:

def deps do
  [{:cognac, "~> 0.1.0"}]
end

Then, run mix deps.get in your shell to fetch and compile Cognac. Start an interactive Elixir shell with iex -S mix.

iex> alias Cognac, as: C
iex> query = [hero: [:name, friends: [:name]]]
iex> C.query(query)
"query{hero{name friends{name}}}"

Examples

In the current version, only simple queries, mutations and subscriptions are possible. Operation names and variables will be added in a future release.

Basic query

iex> query = [hero: [:name, friends: [:name]]]
iex> Cognac.query(query)
"query{hero{name friends{name}}}"

Fields can also be specified using strings, albeit not as readably.

iex> query = [{"hero", ["name", {"friends", ["name"]}]}]
iex> Cognac.query(query)
"query{hero{name friends{name}}}"

Query with parameters

Parameters are specified by assigning a tuple to a key, where the first element is a keyword list of parameters, and the second element is a list of subfields.

iex> query = [heroes: {[name: "Steve", paginate: nil],[:name, friends: [:name]]}]
iex> Cognac.query(query)
"query{heroes(name:\"Steve\",paginate:null){name friends{name}}}"

Which can be achieved at any level

iex> query = [heroes: {[name: "Steve", paginate: nil],[:name, friends: {[class: :WARRIOR],[:name]}]}]
iex> Cognac.query(query)
"query{heroes(name:\"Steve\",paginate:null){name friends(class:WARRIOR){name}}}"

Note that atom values are handled processed as unescaped strings, which can be useful for enumerable type values

Options

Use the :output option to either get the result as a :string (default) or :iodata.

iex> query = [hero: [:name, friends: [:name]]]
iex> Cognac.query(query, output: :iodata)
[
  "query",
  [123, ["hero", 123, ["name", " ", "friends", 123, ["name"], 125], 125], 125]
]

Cognac uses IO data to build the finished query binary, so using this option essentially skips the conversion step.

Use the :pretty option (defaults to false) to introduce indentation and line breaks which could possibly help with debugging.

iex> query = [hero: [:name, friends: [:name]]]
iex> Cognac.query(query, pretty: true) |> IO.puts
query {
  hero {
    name
    friends {
      name
    }
  }
}