`finishTransaction`

The finishTransaction method allows you to explicitly finish a transaction that has made multiple mutations to the Store, triggering all calls to the relevant listeners.

finishTransaction(doRollback?: DoRollback): Store

Type Description

	Type	Description
`doRollback?`	`DoRollback`	An optional callback that should return `true` if you want to rollback the transaction at the end.
returns	`Store`	A reference to the `Store`.

doRollback?

DoRollback

An optional callback that should return true if you want to rollback the transaction at the end.

returns

Store

A reference to the Store.

Transactions are useful for making bulk changes to the data in a Store, and when you don't want listeners to be called as you make each change. Changes are made silently during the transaction, and listeners relevant to the changes you have made will instead only be called when the whole transaction is complete.

Generally it is preferable to use the transaction method to wrap a block of code as a transaction. It simply calls both the startTransaction and finishTransaction methods for you. See that method for several transaction examples.

Use this finishTransaction method when you have a more 'open-ended' transaction, such as one containing mutations triggered from other events that are asynchronous or not occurring inline to your code. There must have been a corresponding startTransaction method that this completes, of course, otherwise this function has no effect.

The optional parameter, doRollback is a DoRollback callback that you can use to rollback the transaction if it did not complete to your satisfaction. It is called with getTransactionChanges and getTransactionLog parameters, which inform you of the net changes that have been made during the transaction, at different levels of detail. See the DoRollback documentation for more details.

Examples

This example makes changes to two Cells, first outside, and secondly within, a transaction that is explicitly started and finished. In the second case, the Row listener is only called once.

const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
store.addRowListener('pets', 'fido', () => console.log('Fido changed'));

store
  .setCell('pets', 'fido', 'color', 'brown')
  .setCell('pets', 'fido', 'sold', false);
// -> 'Fido changed'
// -> 'Fido changed'

store
  .startTransaction()
  .setCell('pets', 'fido', 'color', 'walnut')
  .setCell('pets', 'fido', 'sold', true)
  .finishTransaction();
// -> 'Fido changed'

This example makes multiple changes to the Store, including some attempts to update a Cell with invalid values. The doRollback callback receives information about the changes and invalid attempts, and then judges that the transaction should be rolled back to its original state.

const store = createStore()
  .setTables({pets: {fido: {species: 'dog', color: 'brown'}}})
  .setValues({open: true});

store
  .startTransaction()
  .setCell('pets', 'fido', 'color', 'black')
  .setCell('pets', 'fido', 'eyes', ['left', 'right'])
  .setCell('pets', 'fido', 'info', {sold: null})
  .setValue('open', false)
  .setValue('employees', ['alice', 'bob'])
  .finishTransaction((_, getTransactionLog) => {
    const {changedCells, invalidCells, changedValues, invalidValues} =
      getTransactionLog();
    console.log(store.getTables());
    console.log(changedCells);
    console.log(invalidCells);
    console.log(changedValues);
    console.log(invalidValues);
    return invalidCells['pets'] != null;
  });
// -> {pets: {fido: {species: 'dog', color: 'black'}}}
// -> {pets: {fido: {color: ['brown', 'black']}}}
// -> {pets: {fido: {eyes: [['left', 'right']], info: [{sold: null}]}}}
// -> {open: [true, false]}
// -> {employees: [['alice', 'bob']]}

console.log(store.getTables());
// -> {pets: {fido: {species: 'dog', color: 'brown'}}}
console.log(store.getValues());
// -> {open: true}

Since

v1.3.0