`addResultCellListener`

The addResultCellListener method registers a listener function with the Queries object that will be called whenever data in a ResultCell changes.

addResultCellListener(
  queryId: IdOrNull,
  rowId: IdOrNull,
  cellId: IdOrNull,
  listener: ResultCellListener,
): Id

	Type	Description
`queryId`	`IdOrNull`	The `Id` of the query to listen to, or `null` as a wildcard.
`rowId`	`IdOrNull`	The `Id` of the `ResultRow` to listen to, or `null` as a wildcard.
`cellId`	`IdOrNull`	The `Id` of the `ResultCell` to listen to, or `null` as a wildcard.
`listener`	`ResultCellListener`	The function that will be called whenever data in the matching `ResultCell` changes.
returns	`Id`	A unique `Id` for the listener that can later be used to remove it.

The provided listener is a ResultCellListener function, and will be called with a reference to the Queries object, the Id of the ResultTable that changed (which is also the query Id), the Id of the ResultRow that changed, the Id of the ResultCell that changed, the new ResultCell value, the old ResultCell value, and a GetResultCellChange function in case you need to inspect any changes that occurred.

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

All, some, or none of the queryId, rowId, and cellId parameters can be wildcarded with null. You can listen to a specific ResultCell in a specific ResultRow in a specific query, any ResultCell in any ResultRow in any query, for example - or every other combination of wildcards.

Examples

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

const store = createStore().setTable('pets', {
  fido: {species: 'dog', color: 'brown'},
  felix: {species: 'cat', color: 'black'},
  cujo: {species: 'dog', color: 'black'},
});

const queries = createQueries(store).setQueryDefinition(
  'dogColors',
  'pets',
  ({select, where}) => {
    select('color');
    where('species', 'dog');
  },
);

const listenerId = queries.addResultCellListener(
  'dogColors',
  'fido',
  'color',
  (queries, tableId, rowId, cellId, newCell, oldCell, getCellChange) => {
    console.log(
      'color cell in fido row in dogColors result table changed',
    );
    console.log([oldCell, newCell]);
    console.log(getCellChange('dogColors', 'fido', 'color'));
  },
);

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

store.delListener(listenerId);

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

const store = createStore().setTable('pets', {
  fido: {species: 'dog', color: 'brown', price: 5},
  felix: {species: 'cat', color: 'black', price: 4},
  cujo: {species: 'dog', color: 'black', price: 5},
});

const queries = createQueries(store)
  .setQueryDefinition('dogColors', 'pets', ({select, where}) => {
    select('color');
    where('species', 'dog');
  })
  .setQueryDefinition('catColors', 'pets', ({select, where}) => {
    select('color');
    select('price');
    where('species', 'cat');
  });

const listenerId = queries.addResultCellListener(
  null,
  null,
  null,
  (queries, tableId, rowId, cellId) => {
    console.log(
      `${cellId} cell in ${rowId} row in ${tableId} result table changed`,
    );
  },
);

store.setCell('pets', 'fido', 'color', 'walnut');
// -> 'color cell in fido row in dogColors result table changed'
store.setCell('pets', 'felix', 'price', 3);
// -> 'price cell in felix row in catColors result table changed'

store.delListener(listenerId);

Since

v2.0.0