daikini / graphql-relay-ruby

Relay helpers for GraphQL & Ruby

graphql-relay

Helpers for using graphql with Relay.

Installation

gem "graphql-relay"

bundle install

Usage

Global Ids

Global Ids provide refetching & global identification for Relay.

You should create GraphQL::Relay::GlobalNodeIdentification helper by defining object_from_id(global_id) & type_from_object(object). The resulting object provides ID resultion methods, a find-by-global-id field and a node interface. Example

ObjectTypes should implement that interface with the global_id_field helper: Example

You should attach the field to your query type: Example

Connections

Connections will provide arguments, pagination and pageInfo for Arrays or ActiveRecord::Relations. You can use the connection definition helper.

Then, implement the field. It's different than a normal field:

• use the connection helper to define it, instead of field
• Call #connection_type on an ObjectType for the field's return type (eg, ShipType.connection_type)

Examples:

• Connection with custom arguments
• Connection with a different name than the underlying property

You can also add custom fields to connection objects: Example

At runtime, graphql-relay chooses a connection implementation to expose a collection. graphql-relay provides ArrayConnection and RelationConnection, but you can also provide your own with BaseConnection.register_connection_implementation.

Mutations

Mutations allow Relay to mutate your system. When you define a mutation, you'll be defining:

• A field for your schema's mutation root
• A derived InputObjectType for input values
• A derived ObjectType for return values

You don't define anything having to do with clientMutationId. That's automatically created.

To define a mutation, use GraphQL::Relay::Mutation.define. Inside the block, you should configure:

• name, which will name the mutation field & derived types
• input_fields, which will be applied to the derived InputObjectType
• return_fields, which will be applied to the derived ObjectType
• resolve(-> (inputs, ctx)), the mutation which will actually happen

The resolve proc:

• Takes inputs, which is a hash whose keys are the ones defined by input_field
• Takes ctx, which is the query context you passed with the context: keyword
• Must return a hash with keys matching your defined return_fields

Examples:

• Definition: example
• Mount on mutation type: example

Todo

• Show how to wrap a simple field in a connection field with ConnectionField.create
• Add a max_page_size config for connections?
• Refactor some RelationConnection issues:
  • fix unbounded count in page info, details

More Resources

• GraphQL Slack, come join us in the #ruby channel!
• graphql Ruby gem
• graphql-relay-js JavaScript helpers for GraphQL and Relay