Relay.GraphQLMutation

Relay.GraphQLMutation is a low-level API for modeling a GraphQL mutation.

This is the lowest level of abstraction at which product code may deal with mutations in Relay, and it corresponds to the mutation operation ("a write followed by a fetch") described in the GraphQL Specification. You specify the mutation, the inputs, and the query.

Relay.GraphQLMutation doesn't provide any bells and whistles such as fat queries or tracked queries (that is, automatic synthesis at runtime of the mutation query to be sent to the server), instead having the user define a static and explicit query. Restricting yourself to the low-level API is a useful preparatory step that will help you ready your codebase for migration to the new static Relay core. In the meantime, if you want those dynamic features, you can opt in to the higher-level Relay.Mutation API.

Overview

Properties

static create(mutation, variables, environment) Create a static mutation
static createWithFiles(mutation, variables, files, environment) Create a static mutation that accepts a "files" object

Methods

constructor(query, variables, files, environment, callbacks, collisionKey)
applyOptimistic(optimisticQuery, optimisticResponse, configs)
commit(configs)
rollback()

Properties

create (static method)

static create(
  mutation: RelayConcreteNode,
  variables: Object,
  environment: RelayEnvironmentInterface
): RelayGraphQLMutation;

Convenience method that wraps the constructor, passing some default parameters and returning an instance.

Example

const environment = new Relay.Environment();
const query = Relay.QL`mutation FeedbackLikeMutation {
  feedbackLike(input: $input) {
    clientMutationId
    feedback {
      doesViewerLike
    }
  }
}`;
const variables = {
  input: {
    feedbackId: 'aFeedbackId',
  },
};

const mutation = Relay.GraphQLMutation.create(
  query,
  variables,
  environment
);

Note: In most cases, it is possible to rely on the default singleton instance of the environment, which is exposed as Relay.Store.

createWithFiles (static method)

Convenience method that wraps the constructor, passing some default parameters and returning an instance.

static createWithFiles(
  mutation: RelayConcreteNode,
  variables: Variables,
  files: FileMap,
  environment: RelayEnvironmentInterface
): RelayGraphQLMutation;

Example

// Given a `files` object of:
//
//   type FileMap = {[key: string]: File};
//
// and `query`, `variables` and `environment` arguments
// as in the previous example:
const mutation = Relay.GraphQLMutation.createWithFiles(
  query,
  variables,
  files,
  environment
);

Methods

constructor

constructor(
  query: RelayConcreteNode,
  variables: Variables,
  files: ?FileMap,
  environment: RelayEnvironmentInterface,
  callbacks: ?RelayMutationTransactionCommitCallbacks,
  collisionKey: ?string
);

This is the general constructor for creating Relay.GraphQLMutation instances with optional files, callbacks and collisionKey arguments.

Callers must provide an appropriate query and variables. As per the GraphQL Relay Specification:

The mutation should take a single argument named "input".
That input argument should contain a (string) "clientMutationId" property for the purposes of reconciling requests and responses (automatically added by the Relay.GraphQLMutation API).
The query should request "clientMutationId" as a subselection.

If not supplied, a unique collision key is derived (meaning that the created mutation will be independent and not collide with any other).

Example

const collisionKey = 'feedback-like: ' + variables.input.feedbackId;
const mutation = new Relay.GraphQLMutation(
  query,
  variables,
  null, // No files.
  environment,
  {
    onFailure: err => console.warn(err),
    onSuccess: () => console.log('Success!'),
  },
  collisionKey
);

applyOptimistic

applyOptimistic(
  optimisticQuery: RelayConcreteNode,
  optimisticResponse: Object,
  configs: ?Array<RelayMutationConfig>
): RelayMutationTransaction;

Call this to optimistically apply an update to the store.

The optional config parameter can be used to configure a RANGE_ADD or other type of mutation, as per the Relay.Mutation API. This tells Relay how to process the response.

Optionally, follow up with a call to commit() to send the mutation to the server.

Note: An optimistic update may only be applied once.

Example

const optimisticQuery = Relay.QL`mutation FeedbackLikeOptimisticUpdate {
  feedbackLike(input: $input) {
    clientMutationId
    feedback {
      doesViewerLike
      id
    }
  }
}`;
const optimisticResponse = {
  feedback: {
    doesViewerLike: true,
    id: 'aFeedbackId',
    __typename: 'Feedback',
  },
};

const transaction = mutation.applyOptimistic(
  optimisticQuery,
  optimisticResponse,
);

commit

commit(configs: ?Array<RelayMutationConfig>): RelayMutationTransaction;

Call this to send the mutation to the server.

The optional config parameter can be used to configure a RANGE_ADD or other type of mutation, similar to the Relay.Mutation API.

Optionally, precede with a call to applyOptimistic() to apply an update optimistically to the store.

Note: This method may only be called once per instance.

Example

const configs = [{
  type: 'RANGE_ADD',
  connectionName: 'topLevelComments',
  edgeName: 'feedbackCommentEdge',
  parentID: 'aFeedbackId',
  parentName: 'feedback',
  rangeBehaviors: {
    '': GraphQLMutatorConstants.PREPEND,
  },
}];
const transaction = mutation.commit(configs);

rollback

rollback(): void;

Rolls back an optimistic mutation.

Relay.GraphQLMutation