`addCellIdsListener`

The addCellIdsListener method registers a listener function with the Store that will be called whenever the Cell Ids in a Row change.

addCellIdsListener(
  tableId: IdOrNull,
  rowId: IdOrNull,
  listener: CellIdsListener,
  mutator?: boolean,
): Id

	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.
`listener`	`CellIdsListener`	The function that will be called whenever the `Cell` `Ids` in the `Row` 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 CellIdsListener function, and will be called with a reference to the Store, the Id of the Table, and the Id of the Row that changed.

By default, such a listener is only called when a Cell is added or removed. To listen to all changes in the Row, use the addRowListener method.

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

Both, either, or neither of the tableId and rowId parameters can be wildcarded with null. You can listen to a specific Row in a specific Table, any Row in a specific Table, a specific Row in any Table, or any Row in any Table.

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 of a specific Row.

const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
const listenerId = store.addCellIdsListener('pets', 'fido', (store) => {
  console.log('Cell Ids for fido row in pets table changed');
  console.log(store.getCellIds('pets', 'fido'));
});

store.setCell('pets', 'fido', 'color', 'brown');
// -> 'Cell Ids for fido row in pets table changed'
// -> ['species', 'color']

store.delListener(listenerId);

This example registers a listener that responds to any change to the Cell Ids of any Row.

const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
const listenerId = store.addCellIdsListener(
  null,
  null,
  (store, tableId, rowId) => {
    console.log(`Cell Ids for ${rowId} row in ${tableId} table changed`);
    console.log(store.getCellIds(tableId, rowId));
  },
);

store.setCell('pets', 'fido', 'color', 'brown');
// -> 'Cell Ids for fido row in pets table changed'
// -> ['species', 'color']
store.setCell('species', 'dog', 'price', 5);
// -> 'Cell Ids for dog row in species table changed'
// -> ['price']

store.delListener(listenerId);

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

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

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

store.delListener(listenerId);