`addCellListener`

Essential

The addCellListener method registers a listener function with the Store that will be called whenever data in a Cell changes.

addCellListener(
  tableId: IdOrNull,
  rowId: IdOrNull,
  cellId: IdOrNull,
  listener: CellListener<Store>,
  mutator?: boolean,
): string

	Type	Description
`tableId`	`IdOrNull`	The `Id` of the `Table` to listen to, or `null` as a wildcard.
`rowId`	`IdOrNull`	The `Id` of the `Row` to listen to, or `null` as a wildcard.
`cellId`	`IdOrNull`	The `Id` of the `Cell` to listen to, or `null` as a wildcard.
`listener`	`CellListener<Store>`	The function that will be called whenever data in the matching `Cell` changes.
`mutator?`	`boolean`	An optional boolean that indicates that the listener mutates `Store` data.
returns	`string`	A unique `Id` for the listener that can later be used to call it explicitly, or to remove it.

The provided listener is a CellListener function, and will be called with a reference to the Store, the Id of the Table that changed, the Id of the Row that changed, the Id of the Cell that changed, the new Cell value, the old Cell value, and a GetCellChange function in case you need to inspect any changes that occurred.

You can either listen to a single Cell (by specifying the Table Id, Row Id, and Cell Id as the method's first three parameters) or changes to any Cell (by providing null wildcards).

All, some, or none of the tableId, rowId, and cellId parameters can be wildcarded with null. You can listen to a specific Cell in a specific Row in a specific Table, any Cell in any Row in any Table, for example - or every other combination of wildcards.

Use the optional mutator parameter to indicate that there is code in the listener that will mutate Store data. If set to false (or omitted), such mutations will be silently ignored. All relevant mutator listeners (with this flag set to true) are called before any non-mutator listeners (since the latter may become relevant due to changes made in the former). The changes made by mutator listeners do not fire other mutating listeners, though they will fire non-mutator listeners.

Examples

This example registers a listener that responds to any changes to a specific Cell.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
});
const listenerId = store.addCellListener(
  'pets',
  'fido',
  'color',
  (store, tableId, rowId, cellId, newCell, oldCell, getCellChange) => {
    console.log('color cell in fido row in pets table changed');
    console.log([oldCell, newCell]);
    console.log(getCellChange('pets', 'fido', 'color'));
  },
);

store.setCell('pets', 'fido', 'color', 'walnut');
// -> 'color cell in fido row in pets table changed'
// -> ['brown', 'walnut']
// -> [true, 'brown', 'walnut']

store.delListener(listenerId);

This example registers a listener that responds to any changes to any Cell.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
});
const listenerId = store.addCellListener(
  null,
  null,
  null,
  (store, tableId, rowId, cellId) => {
    console.log(
      `${cellId} cell in ${rowId} row in ${tableId} table changed`,
    );
  },
);

store.setCell('pets', 'fido', 'color', 'walnut');
// -> 'color cell in fido row in pets table changed'
store.setTable('species', {dog: {price: 5}});
// -> 'price cell in dog row in species table changed'

store.delListener(listenerId);

This example registers a listener that responds to any changes to a specific Cell, and which also mutates the Store itself.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
});
const listenerId = store.addCellListener(
  'pets',
  'fido',
  'color',
  (store, tableId, rowId, cellId) =>
    store.setCell('meta', 'update', `${tableId}_${rowId}_${cellId}`, true),
  true,
);

store.delCell('pets', 'fido', 'color');
console.log(store.getTable('meta'));
// -> {update: {pets_fido_color: true}}

store.delListener(listenerId);

Since

v1.0.0