TinyBase

addWillFinishTransactionListener

The addWillFinishTransactionListener method registers a listener function with the Store that will be called just before other non-mutating listeners are called at the end of the transaction.

addWillFinishTransactionListener(listener: TransactionListener): string
TypeDescription
listenerTransactionListener
returnsstring

A unique Id for the listener that can later be used to remove it.

This is useful if you need to know that a set of listeners are about to be called at the end of a transaction, perhaps to batch their consequences together.

The provided TransactionListener will receive a reference to the Store and a boolean to indicate whether Cell values have been touched during the transaction. The latter flag is intended as a hint about whether non-mutating listeners might be being called at the end of the transaction.

Here, 'touched' means that Cell values have either been changed, or changed and then changed back to its original value during the transaction. The exception is a transaction that has been rolled back, for which the value of cellsTouched in the listener will be false because all changes have been reverted.

Example

This example registers a listener that is called at the end of the transaction, just before its listeners will be called. The transactions shown here variously change, touch, and rollback cells, demonstrating how the cellsTouched parameter in the listener works.

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
});
const listenerId = store.addWillFinishTransactionListener(
  (store, cellsTouched) => console.log(`Cells touched: ${cellsTouched}`),
);
const listenerId2 = store.addTablesListener(() =>
  console.log('Tables changed'),
);

store.transaction(() => store.setCell('pets', 'fido', 'color', 'brown'));
// -> 'Cells touched: false'

store.transaction(() => store.setCell('pets', 'fido', 'color', 'walnut'));
// -> 'Cells touched: true'
// -> 'Tables changed'

store.transaction(() => {
  store.setRow('pets', 'felix', {species: 'cat'});
  store.delRow('pets', 'felix');
});
// -> 'Cells touched: true'

store.transaction(
  () => store.setRow('pets', 'fido', {species: 'dog'}),
  () => true,
);
// -> 'Cells touched: false'
// Transaction was rolled back.

store.callListener(listenerId);
// -> 'Cells touched: undefined'
// It is meaningless to call this listener directly.

store.delListener(listenerId).delListener(listenerId2);

Since

v1.3.0