Skip to main content

Transactions

TODO:#27374: update this page to describe the new transaction API

If you want the SharedTree to treat a set of changes atomically, then you can wrap these changes in a transaction. Using a transaction guarantees that (if applied) all of the changes will be applied together synchronously and no other changes (either from this client or from a remote client) can be interleaved with those changes. Note that the Fluid Framework guarantees this already for any sequence of changes that are submitted synchronously. However, using a transaction has the following additional implications:

  • If reverted (e.g. via an "undo" operation), all the changes in the transaction are reverted together.
  • It is also more efficient for SharedTree to process and transmit a large number of changes as a transaction rather than as changes submitted separately.
  • It is possible to specify constraints on a transaction so that the transaction will be ignored if one or more of these constraints are not met.

To create a transaction use the Tree.runTransaction() method. You can cancel a transaction from within the callback function by returning the special "rollback object", available via Tree.runTransaction.rollback. Also, if an error occurs within the callback, the transaction will be canceled automatically before propagating the error.

In this example, myNode can be any node in the SharedTree. It will be optionally passed into the callback function.

Tree.runTransaction(myNode, (node) => {
    // Make multiple changes to the tree.
    // This can be changes to the referenced node but is not limited to that scope.
    if (
        // Something is wrong here!
    ) return "rollback";
})

You can also pass a TreeView object to runTransaction().

Tree.runTransaction(myTreeView, (treeView) => {
	// Make multiple changes to the tree.
});

There are example transactions here: Shared Tree Demo.