`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

	Type	Description
`queryId`	`string`	The `Id` of the query to listen to.
`cellId`	`undefined \| string`	The `Id` of the `ResultCell` whose values are used for the sorting, or `undefined` to by sort the `ResultRow` `Id` itself.
`descending`	`boolean`	Whether the sorting should be in descending order.
`offset`	`number`	The number of `ResultRow` `Ids` to skip for pagination purposes, if any.
`limit`	`undefined \| number`	The maximum number of `ResultRow` `Ids` to return, or `undefined` for all.
`listener`	`ResultSortedRowIdsListener`	The function that will be called whenever the sorted `ResultRow` `Ids` in the `ResultTable` change.
returns	`string`	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