TinyBase logoTinyBase beta

addResultCellListener

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

addResultCellListener(
  queryId: IdOrNull,
  rowId: IdOrNull,
  cellId: IdOrNull,
  listener: ResultCellListener,
): 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.

cellIdIdOrNull

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

listenerResultCellListener

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

returnsstring

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 Table that changed (which is also the query Id), the Id of the Row that changed, the Id of the Cell that changed, the new Cell value, the old Cell value, 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, Row Id, and Cell Id as the method's first three parameters) or changes to any result Cell (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 Cell in a specific result Row in a specific query, any Cell in any result Row 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 result Cell.

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 result Cell.

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