`addTableCellIdsListener`

The addTableCellIdsListener method registers a listener function with the Store that will be called whenever the Cell Ids that appear anywhere in a Table change.

addTableCellIdsListener(
  tableId: IdOrNull,
  listener: TableCellIdsListener,
  mutator?: boolean,
): Id

	Type	Description
`tableId`	`IdOrNull`	The `Id` of the `Table` to listen to, or `null` as a wildcard.
`listener`	`TableCellIdsListener`	The function that will be called whenever the `Cell` `Ids` that appear anywhere in a `Table` change.
`mutator?`	`boolean`	An optional boolean that indicates that the listener mutates `Store` data.
returns	`Id`	A unique `Id` for the listener that can later be used to call it explicitly, or to remove it.

The provided listener is a TableCellIdsListener function, and will be called with a reference to the Store and the Id of the Table that changed.

By default, such a listener is only called when a Cell Id is added or removed from the whole of the Table. To listen to all changes in the Table, use the addTableListener method.

You can either listen to a single Table (by specifying its Id as the method's first parameter) or changes to any Table (by providing a null wildcard).

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 change to the Cell Ids that appear anywhere in a Table.

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
});
const listenerId = store.addTableCellIdsListener('pets', (store) => {
  console.log('Cell Ids in pets table changed');
  console.log(store.getTableCellIds('pets'));
});

store.setRow('pets', 'felix', {species: 'cat', legs: 4});
// -> 'Cell Ids in pets table changed'
// -> ['species', 'color', 'legs']

store.delListener(listenerId);

This example registers a listener that responds to any change to the Cell Ids that appear anywhere in any Table.

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
  species: {dog: {price: 5}},
});
const listenerId = store.addTableCellIdsListener(
  null,
  (store, tableId) => {
    console.log(`Cell Ids in ${tableId} table changed`);
    console.log(store.getTableCellIds(tableId));
  },
);

store.setRow('pets', 'felix', {species: 'cat', legs: 4});
// -> 'Cell Ids in pets table changed'
// -> ['species', 'color', 'legs']

store.setRow('species', 'cat', {price: 4, friendly: true});
// -> 'Cell Ids in species table changed'
// -> ['price', 'friendly']

store.delListener(listenerId);

This example registers a listener that responds to the Cell Ids that appear anywhere in a Table, and which also mutates the Store itself.

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
});
const listenerId = store.addTableCellIdsListener(
  'pets',
  (store, tableId) => store.setCell('meta', 'update', tableId, true),
  true, // mutator
);

store.setRow('pets', 'felix', {species: 'cat', legs: 4});
console.log(store.getTable('meta'));
// -> {update: {pets: true}}

store.delListener(listenerId);