tinybase 2.0.0-beta.0 → 2.0.0-beta.3

package/lib/debug/queries.d.ts

@@ -24,7 +24,7 @@ import {
   Table,
   TableCallback,
 } from './store.d';
-import {Id, IdOrNull, Ids, SortKey} from './common.d';
+import {Id, IdOrNull, Ids} from './common.d';
 
 /**
  * The Aggregate type describes a custom function that takes an array of Cell
@@ -194,6 +194,41 @@ export type ResultTableListener = (
  */
 export type ResultRowIdsListener = (queries: Queries, tableId: Id) => void;
 
+/**
+ * The ResultSortedRowIdsListener type describes a function that is used to
+ * listen to changes to the sorted Row Ids in a query's result Table.
+ *
+ * A ResultSortedRowIdsListener is provided when using the
+ * addResultSortedRowIdsListener method. See that method for specific examples.
+ *
+ * When called, a ResultSortedRowIdsListener is given a reference to the Queries
+ * object, the Id of the Table whose Row Ids changed (which is the same as 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.
+ *
+ * @param queries A reference to the Queries object that changed.
+ * @param tableId The Id of the Table that changed, which is also the query Id.
+ * @param cellId The Id of the Cell whose values were used for the sorting.
+ * @param descending Whether the sorting was in descending order.
+ * @param offset The number of Row Ids skipped.
+ * @param limit The maximum number of Row Ids returned.
+ * @param sortedRowIds The sorted Row Ids themselves.
+ * @category Listener
+ * @since v2.0.0-beta
+ */
+export type ResultSortedRowIdsListener = (
+  queries: Queries,
+  tableId: Id,
+  cellId: Id | undefined,
+  descending: boolean,
+  offset: number,
+  limit: number | undefined,
+  sortedRowIds: Ids,
+) => void;
+
 /**
  * The ResultRowListener type describes a function that is used to listen to
  * changes to a Row in a query's result Table.
@@ -290,23 +325,23 @@ export type ResultCellListener = (
  */
 export type QueriesListenerStats = {
   /**
-   * The number of ResultTableListeners registered with the Store.
+   * The number of ResultTableListener functions registered with the Store.
    */
   table?: number;
   /**
-   * The number of ResultRowIdsListeners registered with the Store.
+   * The number of ResultRowIdsListener functions registered with the Store.
    */
   rowIds?: number;
   /**
-   * The number of ResultRowListeners registered with the Store.
+   * The number of ResultRowListener functions registered with the Store.
    */
   row?: number;
   /**
-   * The number of ResultCellIdsListeners registered with the Store.
+   * The number of ResultCellIdsListener functions registered with the Store.
    */
   cellIds?: number;
   /**
-   * The number of ResultCellListeners registered with the Store.
+   * The number of ResultCellListener functions registered with the Store.
    */
   cell?: number;
 };
@@ -1293,214 +1328,6 @@ export type Having = {
   (condition: (getSelectedOrGroupedCell: GetCell) => boolean): void;
 };
 
-/**
- * The Order type describes a function that lets you specify how you want the
- * Rows in the result Table to be ordered, based on values within.
- *
- * The Order function is provided as an parameter in the `build` parameter of
- * the setQueryDefinition method.
- *
- * An Order clause can either order alphanumerically by the value of a single
- * Cell or by a 'sort key' calculated from Cell values. The alphanumeric sorting
- * will be ascending by default, or descending if the second parameter is set to
- * `true`.
- *
- * This is applied after any grouping.
- *
- * It is possible to provide multiple Order clauses, and a later clause will be
- * used to establish the order of pairs of Rows if the earlier clauses have not
- * been able to.
- *
- * Note that the Order clause does not work by changing the Row Ids of the
- * result Table, but by changing their insert order. Therefore the Ids array
- * returned from the getResultRowIds method will be correctly ordered, even if
- * the Ids themselves might seem out of order based on their values. If you _do_
- * want to sort Rows by their Id, that is provided as a second parameter to the
- * getSortKey callback.
- *
- * Importantly, if you are using the addResultRowIdsListener method to listen to
- * changes to the order of Rows due to this clause, you will need to set the
- * optional `trackReorder` parameter to `true` to track when the set of Ids has
- * not changed, but the order has.
- *
- * trackReorder
- *
- * @example
- * This example shows a query that orders a Table by a numeric Cell, in a
- * descending fashion.
- *
- * ```js
- * const store = createStore().setTable('pets', {
- *   cujo: {price: 4},
- *   fido: {price: 5},
- *   tom: {price: 3},
- *   carnaby: {price: 3},
- *   felix: {price: 4},
- *   polly: {price: 3},
- * });
- *
- * const queries = createQueries(store);
- * queries.setQueryDefinition('query', 'pets', ({select, order}) => {
- *   select('pets', 'price');
- *   order('price', true);
- * });
- *
- * queries.forEachResultRow('query', (rowId) => {
- *   console.log({[rowId]: queries.getResultRow('query', rowId)});
- * });
- * // -> {fido: {price: 5}}
- * // -> {cujo: {price: 4}}
- * // -> {felix: {price: 4}}
- * // -> {tom: {price: 3}}
- * // -> {carnaby: {price: 3}}
- * // -> {polly: {price: 3}}
- * ```
- * @example
- * This example shows a query that orders a Table by a string Cell, and then a
- * calculated sort key based on the Row Id.
- *
- * ```js
- * const store = createStore().setTable('pets', {
- *   cujo: {species: 'dog'},
- *   fido: {species: 'dog'},
- *   tom: {species: 'cat'},
- *   carnaby: {species: 'parrot'},
- *   felix: {species: 'cat'},
- *   polly: {species: 'parrot'},
- * });
- *
- * const queries = createQueries(store);
- * queries.setQueryDefinition('query', 'pets', ({select, order}) => {
- *   select('pets', 'species');
- *   order('species');
- *   order((getSelectedOrGroupedCell, rowId) => rowId);
- * });
- *
- * queries.forEachResultRow('query', (rowId) => {
- *   console.log({[rowId]: queries.getResultRow('query', rowId)});
- * });
- * // -> {felix: {species: 'cat'}}
- * // -> {tom: {species: 'cat'}}
- * // -> {cujo: {species: 'dog'}}
- * // -> {fido: {species: 'dog'}}
- * // -> {carnaby: {species: 'parrot'}}
- * // -> {polly: {species: 'parrot'}}
- * ```
- * @category Definition
- * @since v2.0.0-beta
- */
-export type Order = {
-  /**
-   * Calling this function with the first parameter as an Id is used to sort the
-   * Rows by the value in that Cell.
-   *
-   * @param selectedOrGroupedCellId The Id of the Cell in the query to sort by.
-   * @param descending Set to `true` to have the Rows sorted in descending
-   * order.
-   */
-  (selectedOrGroupedCellId: Id, descending?: boolean): void;
-  /**
-   * Calling this function with the first parameter as a function is used to
-   * sort the Rows by a value calculate from their Cells or Id.
-   *
-   * @param getSortKey A callback that takes a GetCell function and that should
-   * return a 'sort key' to be used for ordering the Rows.
-   * @param descending Set to `true` to have the Rows sorted in descending
-   * order.
-   */
-  (
-    getSortKey: (getSelectedOrGroupedCell: GetCell, rowId: Id) => SortKey,
-    descending?: boolean,
-  ): void;
-};
-
-/**
- * The Limit type describes a function that lets you specify how many Rows you
- * want in the result Table, and how they should be offset.
- *
- * The Limit function is provided as an parameter in the `build` parameter of
- * the setQueryDefinition method.
- *
- * A Limit clause can either provide an 'page' offset and size limit, or just
- * the limit. The offset is zero-based, so if you specify `2`, say, the results
- * will skip the first two Rows and start with the third.
- *
- * This is applied after any grouping and sorting.
- *
- * @example
- * This example shows a query that limits a Table to four Rows from its first.
- *
- * ```js
- * const store = createStore().setTable('pets', {
- *   cujo: {price: 4},
- *   fido: {price: 5},
- *   tom: {price: 3},
- *   carnaby: {price: 3},
- *   felix: {price: 4},
- *   polly: {price: 3},
- * });
- *
- * const queries = createQueries(store);
- * queries.setQueryDefinition('query', 'pets', ({select, limit}) => {
- *   select('pets', 'price');
- *   limit(4);
- * });
- *
- * queries.forEachResultRow('query', (rowId) => {
- *   console.log({[rowId]: queries.getResultRow('query', rowId)});
- * });
- * // -> {cujo: {price: 4}}
- * // -> {fido: {price: 5}}
- * // -> {tom: {price: 3}}
- * // -> {carnaby: {price: 3}}
- * ```
- * @example
- * This example shows a query that limits a Table to three Rows, offset by two.
- *
- * ```js
- * const store = createStore().setTable('pets', {
- *   cujo: {price: 4},
- *   fido: {price: 5},
- *   tom: {price: 3},
- *   carnaby: {price: 3},
- *   felix: {price: 4},
- *   polly: {price: 3},
- * });
- *
- * const queries = createQueries(store);
- * queries.setQueryDefinition('query', 'pets', ({select, limit}) => {
- *   select('pets', 'price');
- *   limit(2, 3);
- * });
- *
- * queries.forEachResultRow('query', (rowId) => {
- *   console.log({[rowId]: queries.getResultRow('query', rowId)});
- * });
- * // -> {tom: {price: 3}}
- * // -> {carnaby: {price: 3}}
- * // -> {felix: {price: 4}}
- * ```
- * @category Definition
- * @since v2.0.0-beta
- */
-export type Limit = {
-  /**
-   * Calling this function with one numeric parameter is used to limit the Rows
-   * returned, starting from the first.
-   *
-   * @param limit The number of Rows to return.
-   */
-  (limit: number): void;
-  /**
-   * Calling this function with two numeric parameters is used to offset the
-   * start of the results, and then limit the Rows returned.
-   *
-   * @param offset The number of Rows to skip.
-   * @param limit The number of Rows to return.
-   */
-  (offset: number, limit: number): void;
-};
-
 /**
  * A Queries object lets you create and track queries of the data in Store
  * objects.
@@ -1562,33 +1389,32 @@ export type Limit = {
  * console.log(queries.getResultTable('petOwners'));
  * // -> {fido: {owner: 'Alice'}, felix: {owner: 'Bob'}, cujo: {owner: 'Carol'}}
  *
- * // A grouped and ordered query:
+ * // A grouped query:
  * queries.setQueryDefinition(
  *   'colorPrice',
  *   'pets',
- *   ({select, join, group, order}) => {
+ *   ({select, join, group}) => {
  *     select('color');
  *     select('species', 'price');
  *     join('species', 'species');
  *     group('price', 'avg');
- *     order('price');
  *   },
  * );
  * console.log(queries.getResultTable('colorPrice'));
  * // -> {"1": {color: 'black', price: 4.5}, "0": {color: 'brown', price: 5}}
- * console.log(queries.getResultRowIds('colorPrice'));
- * // -> ["1", "0"]
+ * console.log(queries.getResultSortedRowIds('colorPrice', 'price', true));
+ * // -> ["0", "1"]
  *
  * const listenerId = queries.addResultTableListener('colorPrice', () => {
  *   console.log('Average prices per color changed');
  *   console.log(queries.getResultTable('colorPrice'));
- *   console.log(queries.getResultRowIds('colorPrice'));
+ *   console.log(queries.getResultSortedRowIds('colorPrice', 'price', true));
  * });
  *
  * store.setRow('pets', 'lowly', {species: 'worm', color: 'brown'});
  * // -> 'Average prices per color changed'
  * // -> {"0": {color: 'brown', price: 3}, "1": {color: 'black', price: 4.5}}
- * // -> ["0", "1"]
+ * // -> ["1", "0"]
  *
  * queries.delListener(listenerId);
  * queries.destroy();
@@ -1611,7 +1437,7 @@ export interface Queries {
    * The third `build` parameter is a callback that you provide to define the
    * query. That callback is provided with a `builders` object that contains the
    * named 'keywords' for the query, like `select`, `join`, and so on. You can
-   * see how that is used in the simple example below. The following seven
+   * see how that is used in the simple example below. The following five
    * clause types are supported:
    *
    * - The Select type describes a function that lets you specify a Cell or
@@ -1625,13 +1451,12 @@ export interface Queries {
    *   of a Cell in multiple result Rows should be aggregated together.
    * - The Having type describes a function that lets you specify conditions to
    *   filter results, based on the grouped Cells resulting from a Group clause.
-   * - The Order type describes a function that lets you specify how you want
-   *   the Rows in the result Table to be ordered, based on values within.
-   * - The Limit type describes a function that lets you specify how many Rows
-   *   you want in the result Table, and how they should be offset.
    *
    * Full documentation and examples are provided in the sections for each of
    * those clause types.
+   * 
+   * Additionally, you can use the getResultSortedRowIds method and
+   * addResultSortedRowIdsListener method to sort and paginate the results.
    *
    * @param queryId The Id of the query to define.
    * @param tableId The Id of the main Table the query will be based on.
@@ -1671,8 +1496,6 @@ export interface Queries {
       where: Where;
       group: Group;
       having: Having;
-      order: Order;
-      limit: Limit;
     }) => void,
   ): Queries;
 
@@ -1914,9 +1737,6 @@ export interface Queries {
    * returns a copy of, rather than a reference to the list of Ids, so changes
    * made to the list object are not made to the query results themselves.
    *
-   * An Order clause in the query explicitly affects the order of entries in
-   * this array.
-   *
    * @param queryId The Id of a query.
    * @returns An array of the Ids of every Row in the result of the query.
    * @example
@@ -1951,6 +1771,72 @@ export interface Queries {
    */
   getResultRowIds(queryId: Id): Ids;
 
+  /**
+   * The getResultSortedRowIds method returns the Ids of every Row in the result
+   * Table of the given query, sorted according to the values in a specified
+   * Cell.
+   *
+   * This has the same behavior as a Store's getSortedRowIds method. For
+   * example, if the query Id is invalid, the method returns an empty array.
+   * Similarly, 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.
+   *
+   * Note that every call to this method will perform the sorting afresh - there
+   * is no caching of the results - and so you are advised to memoize the
+   * results yourself, especially when the result Table is large. For a
+   * performant approach to tracking the sorted Row Ids when they change, use
+   * the addResultSortedRowIdsListener method.
+   *
+   * @param queryId The Id of a query.
+   * @param cellId The Id of the Cell whose values are used for the sorting, or
+   * `undefined` to by sort the Row Id itself.
+   * @param descending Whether the sorting should be in descending order.
+   * @param offset The number of Row Ids to skip for pagination purposes, if
+   * any.
+   * @param limit The maximum number of Row Ids to return, or `undefined` for
+   * all.
+   * @returns An array of the sorted Ids of every Row in the result of the
+   * query.
+   * @example
+   * This example creates a Queries object, a single query definition, and then
+   * calls this method on it (as well as a non-existent definition) to get the
+   * result Row Ids.
+   *
+   * ```js
+   * 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', 'color'));
+   * // -> ['cujo', 'fido']
+   *
+   * console.log(queries.getResultSortedRowIds('catColors', 'color'));
+   * // -> []
+   * ```
+   * @category Result
+   * @since v2.0.0-beta
+   */
+  getResultSortedRowIds(
+    queryId: Id,
+    cellId?: Id,
+    descending?: boolean,
+    offset?: number,
+    limit?: number,
+  ): Ids;
+
   /**
    * The getResultRow method returns an object containing the entire data of a
    * single Row in the result Table of the given query.
@@ -2122,8 +2008,8 @@ export interface Queries {
   hasResultTable(queryId: Id): boolean;
 
   /**
-   * The hasResultRow method returns a boolean indicating whether a given
-   * result Row exists.
+   * The hasResultRow method returns a boolean indicating whether a given result
+   * Row exists.
    *
    * @param queryId The Id of a possible query.
    * @param rowId The Id of a possible Row.
@@ -2437,22 +2323,13 @@ export interface Queries {
    * the method's first parameter) or changes to any result Table (by providing
    * a `null` wildcard).
    *
-   * Use the optional `trackReorder` parameter to additionally track when the
-   * set of Ids has not changed, but the order has - for example when the Order
-   * clause of the query causes the Row Ids to be re-sorted. This behavior is
-   * disabled by default due to the potential performance cost of detecting such
-   * changes.
-   *
    * @param queryId The Id of the query to listen to, or `null` as a wildcard.
    * @param listener The function that will be called whenever the Row Ids in
    * the result Table change.
-   * @param trackReorder An optional boolean that indicates that the listener
-   * should be called if the set of Ids remains the same but their order
-   * changes.
    * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example registers a listener that responds to any change to the Row
-   * Ids of a specific result Table, but not their order.
+   * Ids of a specific result Table.
    *
    * ```js
    * const store = createStore().setTable('pets', {
@@ -2464,16 +2341,15 @@ export interface Queries {
    * const queries = createQueries(store).setQueryDefinition(
    *   'dogColors',
    *   'pets',
-   *   ({select, where, order}) => {
+   *   ({select, where}) => {
    *     select('color');
    *     where('species', 'dog');
-   *     order('color');
    *   },
    * );
    *
    * const listenerId = queries.addResultRowIdsListener(
    *   'dogColors',
-   *   (store, tableId) => {
+   *   (queries, tableId) => {
    *     console.log(`Row Ids for dogColors result table changed`);
    *     console.log(queries.getResultRowIds('dogColors'));
    *   },
@@ -2481,18 +2357,93 @@ export interface Queries {
    *
    * store.setRow('pets', 'rex', {species: 'dog', color: 'tan'});
    * // -> 'Row Ids for dogColors result table changed'
-   * // -> ['cujo', 'fido', 'rex']
+   * // -> ['fido', 'cujo', 'rex']
    *
-   * store.setCell('pets', 'fido', 'color', 'walnut');
-   * // -> undefined
-   * // trackReorder not set for listener
+   * store.delListener(listenerId);
+   * ```
+   * @example
+   * This example registers a listener that responds to any change to the Row
+   * Ids of any result Table.
+   *
+   * ```js
+   * 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.addResultRowIdsListener(
+   *   null,
+   *   (queries, tableId) => {
+   *     console.log(`Row Ids for ${tableId} result table changed`);
+   *   },
+   * );
+   *
+   * store.setRow('pets', 'rex', {species: 'dog', color: 'tan'});
+   * // -> 'Row Ids for dogColors result table changed'
+   * store.setRow('pets', 'tom', {species: 'cat', color: 'gray'});
+   * // -> 'Row Ids for catColors result table changed'
    *
    * store.delListener(listenerId);
    * ```
+   * @category Listener
+   */
+  addResultRowIdsListener(
+    queryId: IdOrNull,
+    listener: ResultRowIdsListener,
+  ): Id;
+
+  /**
+   * 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.
+   *
+   * 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.
+   *
+   * @param queryId The Id of the query to listen to.
+   * @param cellId The Id of the Cell whose values are used for the sorting, or
+   * `undefined` to by sort the result Row Id itself.
+   * @param descending Whether the sorting should be in descending order.
+   * @param offset The number of Row Ids to skip for pagination purposes, if
+   * any.
+   * @param limit The maximum number of Row Ids to return, or `undefined` for
+   * all.
+   * @param listener The function that will be called whenever the sorted Row
+   * Ids in the result Table change.
+   * @returns A unique Id for the listener that can later be used to remove it.
    * @example
-   * This example registers a listener that responds to a change of order in the
-   * rows of a specific result Table, even though the set of Ids themselves has
-   * not changed.
+   * This example registers a listener that responds to any change to the sorted
+   * Row Ids of a specific result Table.
    *
    * ```js
    * const store = createStore().setTable('pets', {
@@ -2504,35 +2455,35 @@ export interface Queries {
    * const queries = createQueries(store).setQueryDefinition(
    *   'dogColors',
    *   'pets',
-   *   ({select, where, order}) => {
+   *   ({select, where}) => {
    *     select('color');
    *     where('species', 'dog');
-   *     order('color');
    *   },
    * );
    *
-   * const listenerId = queries.addResultRowIdsListener(
+   * const listenerId = queries.addResultSortedRowIdsListener(
    *   'dogColors',
-   *   (store, tableId) => {
-   *     console.log(`Row Ids for dogColors result table changed`);
-   *     console.log(queries.getResultRowIds('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
    *   },
-   *   true, // track reorder
    * );
    *
    * store.setRow('pets', 'rex', {species: 'dog', color: 'tan'});
-   * // -> 'Row Ids for dogColors result table changed'
+   * // -> 'Sorted Row Ids for dogColors result table changed'
    * // -> ['cujo', 'fido', 'rex']
    *
-   * store.setCell('pets', 'fido', 'color', 'walnut');
-   * // -> 'Row Ids for dogColors result table changed'
-   * // -> ['cujo', 'rex', 'fido']
-   *
    * store.delListener(listenerId);
    * ```
    * @example
-   * This example registers a listener that responds to any change to the Row
-   * Ids of any result Table.
+   * 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.
    *
    * ```js
    * const store = createStore().setTable('pets', {
@@ -2541,36 +2492,45 @@ export interface Queries {
    *   cujo: {species: 'dog', color: 'black'},
    * });
    *
-   * const queries = createQueries(store)
-   *   .setQueryDefinition('dogColors', 'pets', ({select, where}) => {
+   * const queries = createQueries(store).setQueryDefinition(
+   *   'dogColors',
+   *   'pets',
+   *   ({select, where}) => {
    *     select('color');
    *     where('species', 'dog');
-   *   })
-   *   .setQueryDefinition('catColors', 'pets', ({select, where}) => {
-   *     select('color');
-   *     where('species', 'cat');
-   *   });
+   *   },
+   * );
+   * console.log(queries.getResultSortedRowIds('dogColors', undefined));
+   * // -> ['cujo', 'fido']
    *
-   * const listenerId = queries.addResultRowIdsListener(
-   *   null,
-   *   (queries, tableId) => {
-   *     console.log(`Row Ids for ${tableId} result table changed`);
+   * 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'});
-   * // -> 'Row Ids for dogColors result table changed'
-   * store.setRow('pets', 'tom', {species: 'cat', color: 'gray'});
-   * // -> 'Row Ids for catColors result table changed'
+   * // -> 'Sorted Row Ids for dogColors result table changed'
+   * // -> ['cujo', 'fido', 'rex']
    *
    * store.delListener(listenerId);
    * ```
    * @category Listener
    */
-  addResultRowIdsListener(
-    queryId: IdOrNull,
-    listener: ResultRowIdsListener,
-    trackReorder?: boolean,
+  addResultSortedRowIdsListener(
+    queryId: Id,
+    cellId: Id | undefined,
+    descending: boolean,
+    offset: number,
+    limit: number | undefined,
+    listener: ResultSortedRowIdsListener,
   ): Id;
 
   /**
@@ -2685,33 +2645,24 @@ export interface Queries {
    * called with a reference to the Queries object, the Id of the Table (which
    * is also the query Id), and the Id of the result Row that changed.
    *
-   * By default, such a listener is only called when a Cell is added to, or
-   * removed from, the result Row. To listen to all changes in the result Row,
-   * use the addResultRowListener method.
+   * Such a listener is only called when a Cell is added to, or removed from,
+   * the result Row. To listen to all changes in the result Row, use the
+   * addResultRowListener method.
    *
    * You can either listen to a single result Row (by specifying the query Id
    * and Row Id as the method's first two parameters) or changes to any Row (by
-   * providing `null`).
+   * providing `null` wildcards).
    *
    * Both, either, or neither of the `queryId` and `rowId` parameters can be
    * wildcarded with `null`. You can listen to a specific result Row in a
    * specific query, any result Row in a specific query, a specific result Row
    * in any query, or any result Row in any query.
    *
-   * Use the optional `trackReorder` parameter to additionally track when the
-   * set of Ids has not changed, but the order has - for example when a Cell
-   * from the middle of the Row is removed and then added back within the same
-   * transaction. This behavior is disabled by default due to the potential
-   * performance cost of detecting such changes.
-   *
    * @param queryId The Id of the query to listen to, or `null` as a wildcard.
    * @param rowId The Id of the result Row to listen to, or `null` as a
    * wildcard.
    * @param listener The function that will be called whenever the Cell Ids in
    * the result Row change.
-   * @param trackReorder An optional boolean that indicates that the listener
-   * should be called if the set of Ids remains the same but their order
-   * changes.
    * @returns A unique Id for the listener that can later be used to remove it.
    * @example
    * This example registers a listener that responds to any change to the Cell
@@ -2795,7 +2746,6 @@ export interface Queries {
     queryId: IdOrNull,
     rowId: IdOrNull,
     listener: ResultCellIdsListener,
-    trackReorder?: boolean,
   ): Id;
 
   /**