Feature: Transactions

The GraphQL servers generated by woo.sh support mutation requests that contain multiple mutation operations (i.e., sequences of multiple create, update, and delete operations) and treat such request as transactions with ACID guarantees. The operations within such a request may even depend on one another; that is, (scalar) values returned by one operation in the sequence may be used as input in any subsequent operation within the sequence. To this end, the returned values have to be assigned to variables which can be done by using the @export directive as demonstrated in the following example.

mutation( $bloggerID: ID! ) {     # declare $bloggerID as a variable that is used in this mutation request
   newBlogger: createBlogger(
      data: {
         name: "Alice"
      }
   ) {
      id   @export(as: "bloggerID")  # assign the 'id' of the newly-created Blogger to the variable 'bloggerID'
   }

   newBlog: createBlog(
      data: {
         text: "Some text"
         author: {
            connect: $bloggerID  # here we use the value assigned to the variable
         }
      }
   ) {
      id
   }
}

There are some restrictions regarding the usage of this feature:

1. Every variable that is mentioned by an @export directive must be declared as a variable of the mutation request, and it must not already be assigned an external value when issuing the request.
2. The value assigned to the variable must be of the type mentioned in the declaration of the variable.
3. The @export directive can be used only for scalar-typed fields or for lists of scalars.
4. The @export directive can be used only for fields of the immediate return type of the mutation operation.

As an example regarding the latter two restrictions, consider the following mutation request.

mutation(
   $blogID: ID!
   $blogText: String!
   $authorID: ID!
   $authorObject: Blogger!
) {
   createBlog(
      data: {
         text: "Some text"
         author: {
            connect: "8713"
         }
      }
   ) {
      id       @export(as: "blogID")     # this is allowed
      author   @export(as: "authorObject")  # this is *not* allowed
      {
         id     @export(as: "authorID")  # this is *not* allowed
      }
   }
}