addResultCellIdsListener

The addResultCellIdsListener method registers a listener function with the Queries object that will be called whenever the Cell Ids in a result Row change.

addResultCellIdsListener(
  queryId: IdOrNull,
  rowId: IdOrNull,
  listener: ResultCellIdsListener,
): 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.

listenerResultCellIdsListener

The function that will be called whenever the Cell Ids in the result Row change.

returnsstring

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

The provided listener is a ResultCellIdsListener function, and will be called with a reference to the Queries object, the Id of the Table (which is also the query Id), and the Id of the result Row that changed.

Such a listener is only called when a Cell is added to, or removed from, the result Row. To listen to all changes in the result Row, use the addResultRowListener method.

You can either listen to a single result Row (by specifying the query Id and Row Id as the method's first two parameters) or changes to any 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 change to the Cell Ids of 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');
    select('price');
    where('species', 'dog');
  },
);

const listenerId = queries.addResultCellIdsListener(
  'dogColors',
  'fido',
  (store, tableId, rowId) => {
    console.log(`Cell Ids for fido row in dogColors result table changed`);
    console.log(queries.getResultCellIds('dogColors', 'fido'));
  },
);

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

store.delListener(listenerId);

This example registers a listener that responds to any change to the Cell Ids of 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');
    select('price');
    where('species', 'dog');
  })
  .setQueryDefinition('catColors', 'pets', ({select, where}) => {
    select('color');
    select('purrs');
    where('species', 'cat');
  });

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

store.setCell('pets', 'fido', 'price', 5);
// -> 'Cell Ids for fido row in dogColors result table changed'
store.setCell('pets', 'felix', 'purrs', true);
// -> 'Cell Ids for felix row in catColors result table changed'

store.delListener(listenerId);

Since

v2.0.0