`addSortedRowIdsListener`

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

addSortedRowIdsListener(
  tableId: string,
  cellId: undefined | string,
  descending: boolean,
  offset: number,
  limit: undefined | number,
  listener: SortedRowIdsListener<Store>,
  mutator?: boolean,
): string

	Type	Description
`tableId`	`string`	The `Id` of the `Table` to listen to.
`cellId`	`undefined \| string`	The `Id` of the `Cell` whose values are used for the sorting, or `undefined` to sort by the `Row` `Id` itself.
`descending`	`boolean`	Whether the sorting should be in descending order.
`offset`	`number`	The number of `Row` `Ids` to skip for pagination purposes, if any.
`limit`	`undefined \| number`	The maximum number of `Row` `Ids` to return, or `undefined` for all.
`listener`	`SortedRowIdsListener<Store>`	The function that will be called whenever the sorted `Row` `Ids` in the `Table` change.
`mutator?`	`boolean`	An optional boolean that indicates that the listener mutates `Store` data.
returns	`string`	A unique `Id` for the listener that can later be used to call it explicitly, or to remove it.

The provided listener is a SortedRowIdsListener function, and will be called with a reference to the Store, the Id of the Table whose Row Ids sorting changed, 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 getSortedRowIds.

Such a listener is called when a Row is added or removed, but also when a value in the specified Cell (somewhere in the 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 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.

Use the optional mutator parameter to indicate that there is code in the listener that will mutate Store data. If set to false (or omitted), such mutations will be silently ignored. All relevant mutator listeners (with this flag set to true) are called before any non-mutator listeners (since the latter may become relevant due to changes made in the former). The changes made by mutator listeners do not fire other mutating listeners, though they will fire non-mutator listeners.

Examples

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

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {
    cujo: {species: 'wolf'},
    felix: {species: 'cat'},
  },
});
console.log(store.getSortedRowIds('pets', 'species', false));
// -> ['felix', 'cujo']

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

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

store.delListener(listenerId);

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

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {
    fido: {price: 6},
    felix: {price: 5},
    mickey: {price: 2},
    tom: {price: 4},
    carnaby: {price: 3},
    lowly: {price: 1},
  },
});

const listenerId = store.addSortedRowIdsListener(
  'pets',
  'price',
  false,
  0,
  3,
  (store, tableId, cellId, descending, offset, limit, sortedRowIds) => {
    console.log(`First three sorted Row Ids for ${tableId} table changed`);
    console.log(sortedRowIds);
    // ^ cheaper than calling getSortedRowIds again
  },
);
console.log(store.getSortedRowIds('pets', 'price', false, 0, 3));
// -> ['lowly', 'mickey', 'carnaby']

store.setCell('pets', 'carnaby', 'price', 4.5);
// -> 'First three sorted Row Ids for pets table changed'
// -> ['lowly', 'mickey', 'tom']

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.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {
    fido: {species: 'dog'},
    felix: {species: 'cat'},
  },
});
console.log(store.getSortedRowIds('pets', undefined, false));
// -> ['felix', 'fido']

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

store.setRow('pets', 'cujo', {species: 'wolf'});
// -> 'Sorted Row Ids for pets table changed'
// -> ['cujo', 'felix', 'fido']

store.delListener(listenerId);

This example registers a listener that responds to a change in the sorting of the rows of a specific Table, even though the set of Ids themselves has not changed.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {
    fido: {species: 'dog'},
    felix: {species: 'cat'},
  },
});
console.log(store.getSortedRowIds('pets', 'species', false));
// -> ['felix', 'fido']

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

store.setCell('pets', 'felix', 'species', 'tiger');
// -> 'Sorted Row Ids for pets table changed'
// -> ['fido', 'felix']

store.delListener(listenerId);

This example registers a listener that responds to any change to the sorted Row Ids of a specific Table, and which also mutates the Store itself.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {
    cujo: {species: 'wolf'},
    felix: {species: 'cat'},
  },
});
const listenerId = store.addSortedRowIdsListener(
  'pets',
  'species',
  false,
  0,
  undefined,
  (store, tableId) => store.setCell('meta', 'sorted', tableId, true),
  true, // mutator
);

store.setRow('pets', 'fido', {species: 'dog'});
console.log(store.getTable('meta'));
// -> {sorted: {pets: true}}

store.delListener(listenerId);

Since

v2.0.0

When called with an object as the first argument, the addSortedRowIdsListener method destructures it to make it easier to skip optional parameters.

addSortedRowIdsListener(
  args: SortedRowIdsArgs,
  listener: SortedRowIdsListener<Store>,
  mutator?: boolean,
): string

	Type	Description
`args`	`SortedRowIdsArgs`	A `SortedRowIdsArgs` object containing the `Id` of the `Table` in the `Store`, and optional `cellId`, `descending`, `offset`, and `limit` parameters.
`listener`	`SortedRowIdsListener<Store>`	The function that will be called whenever the sorted `Row` `Ids` in the `Table` change.
`mutator?`	`boolean`	An optional boolean that indicates that the listener mutates `Store` data.
returns	`string`	A unique `Id` for the listener that can later be used to call it explicitly, or to remove it.

Example

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

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {fido: {price: 6}, felix: {price: 5}},
});

const listenerId = store.addSortedRowIdsListener(
  {tableId: 'pets', limit: 1},
  (store, tableId, cellId, descending, offset, limit, sortedRowIds) => {
    console.log(`First sorted Row Id for ${tableId} table changed`);
    console.log(sortedRowIds);
    // ^ cheaper than calling getSortedRowIds again
  },
);
console.log(store.getSortedRowIds({tableId: 'pets', limit: 1}));
// -> ['felix']

store.setRow('pets', 'carnaby', {price: 4.5});
// -> 'First sorted Row Id for pets table changed'
// -> ['carnaby']

store.delListener(listenerId);

Since

v6.1.0