Data in the store is always mutated via the
mutate method on a
Paper instance by passing in a Mutation Transaction callback. Within the Mutation Transaction callback there are several operations available to support being able to make changes easily to the store, even custom ones can be added.
mutate and the Mutate Transaction callback
To make any changes call the
mutate method on the
Paper instance and provide a Mutate Transaction callback.
Operations can be destructured from the first argument provided in the Mutation Transaction callback.
For example, an
Actor document could be created within
mutate by using the
create operation. In this example only
create is being destructured for use but any combination of operations can be used with the callback (see more of the library-provided operations below).
With a GraphQL Schema:
The following Mutate Transaction callback will create a
Document of the GraphQL
mutate returns a promise and the transaction callback is not considered executed until the promise is fulfilled. Calls to
mutate will process transaction callbacks in the order they are called.
All changes within a Mutation Transaction callback will be validated via Validators after the transaction to ensure the new version of the
DocumentStore is consistent.
Out of the box the following operations can be destructured within the callback:
Creating custom operations can be helpful for creating common functional mutations on the GraphQL Paper
DocumentStore or to provide common helpers that are useful within a Transaction Callback.
The first argument is the GraphQL type for the document and the second is an object representing its data, mapping GraphQL fields to the object properties.
Creating a Documented with Connections
In order to make changes to documents it's important to have access to a version of the document that can be mutated. If there is access to a read-only/frozen/stale document in scope, a mutable version can be looked up via
To remove a
Document from the store use the
clone operation to create a new document that copies the properties and connections of an existing document.
This operation gives the current mutable version of the
DocumentStore available for mutating within the Mutation Transaction callback. This is useful for when access to underlying
DocumentStore data structure and its
If common modifications are being done via
getStore consider making a custom operation.
queueEvent operation to queue an event to be dispatched after the transaction is complete. The
queueEvent takes an instance of
Creating Connections Between Documents
A Connection is used to create a relationship between Documents where one GraphQL type references another GraphQL type in the GraphQL schema.
Document reference can be:
- one-to-one, ie: one film can have one leading actor:
- one-to-many, ie: one film can have many actors:
Note: Non-null (denoted by a
[Actor]!) variations of these also work and are validated.
Note: Connections are one direction. If "Document A" is connected to "Document B" and "Document B" is also connected to "Document A" then two connections must be defined explicitly. There is no automatic reflexive assumptions or setup done between connections (although a custom operation could be created to handle these cases).
Creating Connections via Document Properties
Within a Mutate Transaction callback changes can be made to any documents and their properties.
To create a one-way one-to-one connection between a document and another, assign the property to a
Document, see below where the
leadingActor property is connected by assigning the
To create a one-way one-to-many connection reference documents on the property via an Array, this works with new and existing documents.
Note: While less typical in GraphQL Schemas, if a one-to-many property can nullable (ie:
actors: [Actor] without an
! outside the list) then it's important to make sure you are working with an array before pushing to it. The
?? can help in this case. If working with a non-null list (
[Actor!]!) then it will already be an array by default.
Creating Connections within
create via Nesting
One powerful technique is to use the
create operation with a nested object that includes its connections. This nesting will work recursively. Other documents that have already been created can be included, too.
create will end up creating a
Film document and four
Actor documents, skipping creating
scarlettJohansson because the
Actor document was already created but it will still be included as a connection.
Returning Data Outside the Mutate Transaction callback
It's also very useful to return documents that have been used or created within a
mutate transaction to be referenced afterwards. This can be done by returning a document, an array of documents, or an object with documents values, from the Mutate Transaction callback. See Returning Documents from Mutation Transactions for examples.