tinybase 2.0.0-beta.1 → 2.0.0-beta.4

package/lib/debug/queries.d.ts

@@ -9,7 +9,7 @@
  *
  * @packageDocumentation
  * @module queries
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 
 import {
@@ -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
@@ -38,7 +38,7 @@ import {Id, IdOrNull, Ids, SortKey} from './common.d';
  * @param length The length of the array of Cell values to be aggregated.
  * @returns The value of the aggregation.
  * @category Aggregators
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type Aggregate = (cells: Cell[], length: number) => Cell;
 
@@ -64,7 +64,7 @@ export type Aggregate = (cells: Cell[], length: number) => Cell;
  * @param length The length of the array of Cell values in the aggregation.
  * @returns The new value of the aggregation.
  * @category Aggregators
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type AggregateAdd = (
   current: Cell,
@@ -97,7 +97,7 @@ export type AggregateAdd = (
  * @param length The length of the array of Cell values in the aggregation.
  * @returns The new value of the aggregation.
  * @category Aggregators
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type AggregateRemove = (
   current: Cell,
@@ -129,7 +129,7 @@ export type AggregateRemove = (
  * @param length The length of the array of Cell values in the aggregation.
  * @returns The new value of the aggregation.
  * @category Aggregators
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type AggregateReplace = (
   current: Cell,
@@ -147,7 +147,7 @@ export type AggregateReplace = (
  *
  * @param queryId The Id of the query that the callback can operate on.
  * @category Callback
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type QueryCallback = (queryId: Id) => void;
 
@@ -168,7 +168,7 @@ export type QueryCallback = (queryId: Id) => void;
  * @param getCellChange A function that returns information about any Cell's
  * changes.
  * @category Listener
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type ResultTableListener = (
   queries: Queries,
@@ -190,10 +190,45 @@ export type ResultTableListener = (
  * @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.
  * @category Listener
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 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
+ */
+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.
@@ -212,7 +247,7 @@ export type ResultRowIdsListener = (queries: Queries, tableId: Id) => void;
  * @param getCellChange A function that returns information about any Cell's
  * changes.
  * @category Listener
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type ResultRowListener = (
   queries: Queries,
@@ -236,7 +271,7 @@ export type ResultRowListener = (
  * @param tableId The Id of the Table that changed, which is also the query Id.
  * @param rowId The Id of the Row that changed.
  * @category Listener
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type ResultCellIdsListener = (
   queries: Queries,
@@ -266,7 +301,7 @@ export type ResultCellIdsListener = (
  * @param getCellChange A function that returns information about any Cell's
  * changes.
  * @category Listener
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type ResultCellListener = (
   queries: Queries,
@@ -286,27 +321,27 @@ export type ResultCellListener = (
  * and is only populated in a debug build.
  *
  * @category Development
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 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;
 };
@@ -320,7 +355,7 @@ export type QueriesListenerStats = {
  * calculated values. See those methods for specific examples.
  *
  * @category Callback
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type GetTableCell = {
   /**
@@ -441,7 +476,7 @@ export type GetTableCell = {
  * // -> {cujo: {description: 'dog for Carol'}}
  * ```
  * @category Definition
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type Select = {
   /**
@@ -526,7 +561,7 @@ export type Select = {
  * // -> {cujo: {petSpecies: 'dog', ownerName: 'Carol'}}
  * ```
  * @category Definition
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type SelectedAs = {
   /**
@@ -699,7 +734,7 @@ export type SelectedAs = {
  * // -> {cujo: {description: 'dog in Washington'}}
  * ```
  * @category Definition
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type Join = {
   /**
@@ -813,7 +848,7 @@ export type Join = {
  * // -> {cujo: {buyer: 'Carol', seller: 'Alice'}}
  * ```
  * @category Definition
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type JoinedAs = {as: (joinedTableId: Id) => void};
 
@@ -931,7 +966,7 @@ export type JoinedAs = {as: (joinedTableId: Id) => void};
  * // -> {cujo: {species: 'dog', state: 'WA'}}
  * ```
  * @category Definition
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type Where = {
   /**
@@ -1136,6 +1171,8 @@ export type Where = {
  * // -> {1: {owner: 'bob', lowestPriceOver2: 3}}
  * // Both have a parrot at 3. Alice's worm at 1 is excluded from aggregation.
  * ```
+ * @category Definition
+ * @since v2.0.0
  */
 export type Group = (
   selectedCellId: Id,
@@ -1180,7 +1217,7 @@ export type Group = (
  * // -> {1: {species: 'cat', minPrice: 3, maxPrice: 4}}
  * ```
  * @category Definition
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type GroupedAs = {as: (groupedCellId: Id) => void};
 
@@ -1270,7 +1307,7 @@ export type GroupedAs = {as: (groupedCellId: Id) => void};
  * // Parrots are filtered out because they have zero range in price.
  * ```
  * @category Definition
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export type Having = {
   /**
@@ -1293,212 +1330,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.
- *
- * @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.
@@ -1560,40 +1391,39 @@ 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();
  * ```
  * @see Queries guides
  * @category Queries
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export interface Queries {
   /**
@@ -1609,7 +1439,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
@@ -1623,13 +1453,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.
@@ -1658,7 +1487,7 @@ export interface Queries {
    * // -> {fido: {color: 'brown'}, cujo: {color: 'black'}}
    * ```
    * @category Configuration
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   setQueryDefinition(
     queryId: Id,
@@ -1669,8 +1498,6 @@ export interface Queries {
       where: Where;
       group: Group;
       having: Having;
-      order: Order;
-      limit: Limit;
     }) => void,
   ): Queries;
 
@@ -1703,7 +1530,7 @@ export interface Queries {
    * // -> []
    * ```
    * @category Configuration
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   delQueryDefinition(queryId: Id): Queries;
 
@@ -1729,7 +1556,7 @@ export interface Queries {
    * // -> {fido: {color: 'brown'}}
    * ```
    * @category Getter
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   getStore(): Store;
 
@@ -1757,7 +1584,7 @@ export interface Queries {
    * // -> ['dogColors', 'catColors']
    * ```
    * @category Getter
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   getQueryIds(): Ids;
 
@@ -1791,7 +1618,7 @@ export interface Queries {
    * // -> 'catColors'
    * ```
    * @category Iterator
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   forEachQuery(queryCallback: QueryCallback): void;
 
@@ -1820,7 +1647,7 @@ export interface Queries {
    * // -> false
    * ```
    * @category Getter
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   hasQuery(queryId: Id): boolean;
 
@@ -1853,7 +1680,7 @@ export interface Queries {
    * // -> undefined
    * ```
    * @category Getter
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   getTableId(queryId: Id): Id | undefined;
 
@@ -1899,7 +1726,7 @@ export interface Queries {
    * // -> {}
    * ```
    * @category Result
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   getResultTable(queryId: Id): Table;
 
@@ -1912,9 +1739,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
@@ -1945,10 +1769,76 @@ export interface Queries {
    * // -> []
    * ```
    * @category Result
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   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
+   */
+  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.
@@ -1991,7 +1881,7 @@ export interface Queries {
    * // -> {}
    * ```
    * @category Result
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   getResultRow(queryId: Id, rowId: Id): Row;
 
@@ -2037,7 +1927,7 @@ export interface Queries {
    * // -> []
    * ```
    * @category Result
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   getResultCellIds(queryId: Id, rowId: Id): Ids;
 
@@ -2080,7 +1970,7 @@ export interface Queries {
    * // -> undefined
    * ```
    * @category Result
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   getResultCell(queryId: Id, rowId: Id, cellId: Id): CellOrUndefined;
 
@@ -2115,13 +2005,13 @@ export interface Queries {
    * // -> false
    * ```
    * @category Result
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   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.
@@ -2151,7 +2041,7 @@ export interface Queries {
    * // -> false
    * ```
    * @category Result
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   hasResultRow(queryId: Id, rowId: Id): boolean;
 
@@ -2188,7 +2078,7 @@ export interface Queries {
    * // -> false
    * ```
    * @category Result
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   hasResultCell(queryId: Id, rowId: Id, cellId: Id): boolean;
 
@@ -2235,7 +2125,7 @@ export interface Queries {
    * // -> '- felix'
    * ```
    * @category Iterator
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   forEachResultTable(tableCallback: TableCallback): void;
 
@@ -2281,7 +2171,7 @@ export interface Queries {
    * // -> '- color'
    * ```
    * @category Iterator
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   forEachResultRow(queryId: Id, rowCallback: RowCallback): void;
 
@@ -2324,7 +2214,7 @@ export interface Queries {
    * // -> 'color: brown'
    * ```
    * @category Iterator
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   forEachResultCell(queryId: Id, rowId: Id, cellCallback: CellCallback): void;
 
@@ -2415,6 +2305,7 @@ export interface Queries {
    * store.delListener(listenerId);
    * ```
    * @category Listener
+   * @since v2.0.0
    */
   addResultTableListener(queryId: IdOrNull, listener: ResultTableListener): Id;
 
@@ -2435,22 +2326,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 - specifically 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', {
@@ -2462,16 +2344,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'));
    *   },
@@ -2479,18 +2360,94 @@ 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
+   * @since v2.0.0
+   */
+  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', {
@@ -2502,35 +2459,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', {
@@ -2539,36 +2496,46 @@ 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
+   * @since v2.0.0
    */
-  addResultRowIdsListener(
-    queryId: IdOrNull,
-    listener: ResultRowIdsListener,
-    trackReorder?: boolean,
+  addResultSortedRowIdsListener(
+    queryId: Id,
+    cellId: Id | undefined,
+    descending: boolean,
+    offset: number,
+    limit: number | undefined,
+    listener: ResultSortedRowIdsListener,
   ): Id;
 
   /**
@@ -2667,6 +2634,7 @@ export interface Queries {
    * store.delListener(listenerId);
    * ```
    * @category Listener
+   * @since v2.0.0
    */
   addResultRowListener(
     queryId: IdOrNull,
@@ -2779,6 +2747,7 @@ export interface Queries {
    * store.delListener(listenerId);
    * ```
    * @category Listener
+   * @since v2.0.0
    */
   addResultCellIdsListener(
     queryId: IdOrNull,
@@ -2895,6 +2864,7 @@ export interface Queries {
    * store.delListener(listenerId);
    * ```
    * @category Listener
+   * @since v2.0.0
    */
   addResultCellListener(
     queryId: IdOrNull,
@@ -2945,7 +2915,7 @@ export interface Queries {
    * // The listener is not called.
    * ```
    * @category Listener
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   delListener(listenerId: Id): Queries;
 
@@ -2981,7 +2951,7 @@ export interface Queries {
    * // -> 0
    * ```
    * @category Lifecycle
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   destroy(): void;
 
@@ -3011,7 +2981,7 @@ export interface Queries {
    * // -> 0
    * ```
    * @category Development
-   * @since v2.0.0-beta
+   * @since v2.0.0
    */
   getListenerStats(): QueriesListenerStats;
 }
@@ -3049,6 +3019,6 @@ export interface Queries {
  * // -> true
  * ```
  * @category Creation
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export function createQueries(store: Store): Queries;