addResultRowListener

The addResultRowListener method registers a listener function with the Queries object that will be called whenever data in a result Row changes.

addResultRowListener(
  queryId: IdOrNull,
  rowId: IdOrNull,
  listener: ResultRowListener,
): string
TypeDescription
queryIdIdOrNull

The Id of the query to listen to, or null as a wildcard.

rowIdIdOrNull

The Id of the result Row to listen to, or null as a wildcard.

listenerResultRowListener

The function that will be called whenever data in the matching result Row changes.

returnsstring

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

The provided listener is a ResultRowListener function, and will be called with a reference to the Queries object, the Id of the Table that changed (which is also the query Id), and a GetCellChange function in case you need to inspect any changes that occurred.

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

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

Examples

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

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.addResultRowListener(
  'dogColors',
  'fido',
  (queries, tableId, rowId, getCellChange) => {
    console.log('fido row in dogColors result table changed');
    console.log(getCellChange('dogColors', 'fido', 'color'));
  },
);

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

store.delListener(listenerId);

This example registers a listener that responds to any changes to any result Row.

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');
  })
  .setQueryDefinition('catColors', 'pets', ({select, where}) => {
    select('color');
    where('species', 'cat');
  });

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

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

store.delListener(listenerId);

Since

v2.0.0