Support for Relay Classic mutations with single inputs and client mutation IDs.

The payload macro can be used by schema designers to support mutation fields that receive a single input object argument with a client mutation ID and return that ID as part of the response payload.

More information can be found at https://facebook.github.io/relay/docs/guides-mutations.html

example

Example

In this example we add a mutation field :simple_mutation that accepts an input argument (which is defined for us automatically) which contains an :input_data field.

We also declare the output will contain a field, :result.

Notice the resolve function doesn't need to know anything about the wrapping input argument -- it only concerns itself with the contents -- and the client mutation ID doesn't need to be dealt with, either. It will be returned as part of the response payload automatically.

mutation do
  payload field :simple_mutation do
    input do
      field :input_data, non_null(:integer)
    end
    output do
      field :result, :integer
    end
    resolve fn
      %{input_data: input_data}, _ ->
        # Some mutation side-effect here
        {:ok, %{result: input_data * 2}}
    end
  end
end

Here's a query document that would hit this field:

mutation DoSomethingSimple {
  simpleMutation(input: {inputData: 2, clientMutationId: "abc"}) {
    result
    clientMutationId
  }
}

And here's the response:

{
  "data": {
    "simpleMutation": {
      "result": 4,
      "clientMutationId": "abc"
    }
  }
}

Note the above code would create the following types in our schema, ad hoc:

• SimpleMutationInput
• SimpleMutationPayload

For this reason, the identifier passed to payload field must be unique across your schema.

the-escape-hatch

The Escape Hatch

The mutation macros defined here are just for convenience; if you want something that goes against these restrictions, don't worry! You can always just define your types and fields using normal (field, arg, input_object, etc) schema notation macros as usual.