TinyBase

addResultSortedRowIdsListener

The addResultSortedRowIdsListener method registers a listener function with the Queries object that will be called whenever sorted (and optionally, paginated) Row Ids in a result Table change.

addResultSortedRowIdsListener(
  queryId: string,
  cellId: undefined | string,
  descending: boolean,
  offset: number,
  limit: undefined | number,
  listener: ResultSortedRowIdsListener,
): string
TypeDescription
queryIdstring

The Id of the query to listen to.

cellIdundefined | string

The Id of the Cell whose values are used for the sorting, or undefined to by sort the result Row Id itself.

descendingboolean

Whether the sorting should be in descending order.

offsetnumber

The number of Row Ids to skip for pagination purposes, if any.

limitundefined | number

The maximum number of Row Ids to return, or undefined for all.

listenerResultSortedRowIdsListener

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

returnsstring

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

The provided listener is a ResultSortedRowIdsListener function, and will be called with a reference to the Queries object, the Id of the result Table whose Row Ids sorting changed (which is also the query Id), the Cell Id being used to sort them, whether descending or not, and the offset and limit of the number of Ids returned, for pagination purposes. It also receives the sorted array of Ids itself, so that you can use them in the listener without the additional cost of an explicit call to getResultSortedRowIds

Such a listener is called when a Row is added or removed, but also when a value in the specified Cell (somewhere in the result Table) has changed enough to change the sorting of the Row Ids.

Unlike most other listeners, you cannot provide wildcards (due to the cost of detecting changes to the sorting). You can only listen to a single specified result Table, sorted by a single specified Cell.

The sorting of the rows is alphanumeric, and you can indicate whether it should be in descending order. The offset and limit parameters are used to paginate results, but default to 0 and undefined to return all available Row Ids if not specified.

Examples

This example registers a listener that responds to any change to the sorted Row Ids of a specific result Table.

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.addResultSortedRowIdsListener(
  'dogColors',
  'color',
  false,
  0,
  undefined,
  (queries, tableId, cellId, descending, offset, limit, sortedRowIds) => {
    console.log(`Sorted Row Ids for dogColors result table changed`);
    console.log(sortedRowIds);
    // ^ cheaper than calling getResultSortedRowIds again
  },
);

store.setRow('pets', 'rex', {species: 'dog', color: 'tan'});
// -> 'Sorted Row Ids for dogColors result table changed'
// -> ['cujo', 'fido', 'rex']

store.delListener(listenerId);

This example registers a listener that responds to any change to the sorted Row Ids of a specific Table. The Row Ids are sorted by their own value, since the cellId parameter is explicitly undefined.

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');
  },
);
console.log(queries.getResultSortedRowIds('dogColors', undefined));
// -> ['cujo', 'fido']

const listenerId = queries.addResultSortedRowIdsListener(
  'dogColors',
  undefined,
  false,
  0,
  undefined,
  (queries, tableId, cellId, descending, offset, limit, sortedRowIds) => {
    console.log(`Sorted Row Ids for dogColors result table changed`);
    console.log(sortedRowIds);
    // ^ cheaper than calling getSortedRowIds again
  },
);

store.setRow('pets', 'rex', {species: 'dog', color: 'tan'});
// -> 'Sorted Row Ids for dogColors result table changed'
// -> ['cujo', 'fido', 'rex']

store.delListener(listenerId);

Since

v2.0.0