straw-hat-labs/straw_hat_graphql

Utility Package for GraphQL

StrawHat.GraphQL

GraphQL utils.

Installation

def deps do
  [
    {:straw_hat_graphql, "~> 0.1"}
  ]
end

Usage

The package come with predefined types that you could use in your project. Most of those types dictate how your data structure and responses from your mutations will look like but it will help you to speed up your development.

defmodule YourApp.AbsintheSchema do
  use Absinthe.Schema
  use Absinthe.Schema.Notation

  # Should be include it before you use it

  import_types StrawHat.GraphQL.Types
  import_types StrawHat.GraphQL.Scalars

  # ...
end

Check StrawHat.GraphQL.Types and StrawHat.GraphQL.Scalars for more information about the included types.

Paginations

There is some types for doing paginations. We follow Scrivener for formatting the response.

Note: For now there is some boilerplate code for the paginations. We are aware of using macros but to be honest sometimes is better a repeated code that shoot ourself in the foot, still thinking about creating macros for this.

object :person do
  interface :straw_hat_node

  field :id, non_null(:id)

  # ... more fields
end

# We recommend to use `_pagination`, this is another place where we could macros.
object :people_pagination do
  # This will force you to defined the schemas
  interface(:straw_hat_pagination)

  field(:page, non_null(:straw_hat_pagination_page))
  field(:total_entries, non_null(:integer))
  field(:total_pages, non_null(:integer))

  # This is where it gets tricky and probably we could use macros
  # the reason is that we can't put this field inside `:straw_hat_pagination`
  # because the type is not the same for all the objects.
  field(:entries, list_of(:person))
end

Now let's create the query.

field :people, :people_pagination do
  arg(:pagination, non_null(:straw_hat_pagination_page_input))
  resolve(&PeopleResolver.get_people/2)
end

Mutations

Mutations is something that comes really handy and with a really nice API.

Note: For now there is some boilerplate code for the mutations. We are aware of using macros but to be honest sometimes is better a repeated code that shoot ourself in the foot, still thinking about creating macros for this.

First, you need to create the mutation response which normally should extend from the interface of mutation_response

object :person do
  interface :straw_hat_node

  field :id, non_null(:id)

  # ... more fields
end

# We recommend to use `_payload`, this is another place where we could macros
object :person_payload do
  # This will force you to defined the schemas
  interface :straw_hat_mutation_response

  field :successful, non_null(:boolean)
  field :errors, list_of(:straw_hat_error)

  # This is where it gets tricky and probably we could use macros
  # the reason is that we can't put this field inside `:straw_hat_mutation_response`
  # because the type is not the same for all mutations.
  field :payload, :person
end

Now we create the mutation

object :person_mutations do
  field :person_update, :person_payload do
    arg :person, non_null(:person_input)

    # other resolvers, maybe authorization
    resolve &MyApp.PersonResolvers.update_person/2
  end
end

Now what is left is the resolver function itself

defmodule MyApp.PersonResolvers do
  alias StrawHat.GraphQL.MutationResponse

  def update_person(%{person: person_params}, _) do
    response = MyApp.Person.update_person(person_params)

    # We do not want to force anything the responses from your modules
    # it up to you, make sure you call the correct function for format
    # the data structure
    case response do
      {:ok, response} -> MutationResponse.succeeded(response)
      {:error, reason} -> MutationResponse.failed(reason)
    end
  end
end

If you want to avoid doing the pattern matching constantly which it is up to your application design, you could create a function that does it for you

defmodule MyApp.ResolverHelpers
  alias StrawHat.GraphQL.MutationResponse

  def response_with({:ok, response}), do: MutationResponse.succeeded(response)
  def response_with({:error, reason}), do: MutationResponse.failed(reason)
  def response_with(_), do: raise(ArgumentError)
end

then your resolver becomes

import MyApp.ResolverHelpers

def update_person(%{person: person_params}, _) do
  person_params
  |> MyApp.Person.update_person()
  |> response_with()
end

And now you are go to go. Or use StrawHat.GraphQL.MutationResponse.response_with/1 but be aware that it is constrain by the inputs.

Any suggestion and code pattern that you notice in your app, open an issue and let's talk about it.