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.
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()
static create( mutation: RelayConcreteNode, variables: Object, environment: RelayEnvironmentInterface ): RelayGraphQLMutation;
Convenience method that wraps the constructor, passing some default parameters and returning an instance.
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
.
See also: GraphQLMutation > Constructor
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;
// 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 );
See also: GraphQLMutation > 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:
Relay.GraphQLMutation
API).If not supplied, a unique collision key is derived (meaning that the created mutation will be independent and not collide with any other).
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 );
See also: Relay.Mutation::getCollisionKey()
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.
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, );
See also: Relay.Mutation::getConfigs()
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.
const configs = [{ type: 'RANGE_ADD', connectionName: 'topLevelComments', edgeName: 'feedbackCommentEdge', parentID: 'aFeedbackId', parentName: 'feedback', rangeBehaviors: { '': GraphQLMutatorConstants.PREPEND, }, }]; const transaction = mutation.commit(configs);
See also: Relay.Mutation::getConfigs()
rollback(): void;
Rolls back an optimistic mutation.
A number of more detailed usage examples can be found in the test suite.
© 2013–present Facebook Inc.
Licensed under the BSD License.
https://facebook.github.io/relay/docs/api-reference-relay-graphql-mutation.html