TinyBase logoTinyBase

addResultSortedRowIdsListener

The addResultSortedRowIdsListener method registers a listener function with the Queries object that will be called whenever sorted (and optionally, paginated) ResultRow Ids in a ResultTable 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 ResultCell whose values are used for the sorting, or undefined to by sort the ResultRow Id itself.

descendingboolean

Whether the sorting should be in descending order.

offsetnumber

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

limitundefined | number

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

listenerResultSortedRowIdsListener

The function that will be called whenever the sorted ResultRow Ids in the ResultTable 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 ResultTable whose ResultRow Ids sorting changed (which is also the query Id), the ResultCell 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 the getResultSortedRowIds method.

Such a listener is called when a ResultRow is added or removed, but also when a value in the specified ResultCell (somewhere in the ResultTable) has changed enough to change the sorting of the ResultRow 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 ResultTable, sorted by a single specified ResultCell.

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 ResultRow Ids if not specified.

Examples

This example registers a listener that responds to any change to the sorted ResultRow Ids of a specific ResultTable.

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.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 ResultRow Ids of a specific ResultTable. The ResultRow Ids are sorted by their own value, since the cellId parameter is explicitly undefined.

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');
  },
);
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