`addResultRowListener`

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

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

	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.
`listener`	`ResultRowListener`	The function that will be called whenever data in the matching `ResultRow` changes.
returns	`string`	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 ResultTable that changed (which is also the query Id), 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 and ResultRow Id as the method's first two parameters) or changes to any ResultRow (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 ResultRow in a specific query, any ResultRow in a specific query, a specific ResultRow in any query, or any ResultRow in any query.

Examples

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

import {createQueries, createStore} from 'tinybase';

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 ResultRow.

import {createQueries, createStore} from 'tinybase';

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