tinybase 2.0.0-beta.2 → 2.0.0-beta.3

package/lib/debug/store.d.ts

@@ -94,7 +94,7 @@ export type Cell = string | number | boolean;
  *
  * This is used when describing a Cell that is present _or_ that is not present
  * - such as when it has been deleted, or when describing a previous state where
- *   the Cell value has since been added.
+ * the Cell value has since been added.
  *
  * @category Store
  */
@@ -293,14 +293,17 @@ export type RowIdsListener = (store: Store, tableId: Id) => void;
  *
  * When called, a SortedRowIdsListener is given a reference to the Store, the Id
  * of the Table whose Row Ids sorting changed, the Cell Id being used to sort
- * them, and whether descending or not. 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.
+ * 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.
  *
  * @param store A reference to the Store that changed.
  * @param tableId The Id of the Table whose sorted Row Ids changed.
  * @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
@@ -310,6 +313,8 @@ export type SortedRowIdsListener = (
   tableId: Id,
   cellId: Id | undefined,
   descending: boolean,
+  offset: number,
+  limit: number | undefined,
   sortedRowIds: Ids,
 ) => void;
 
@@ -827,9 +832,7 @@ export interface Store {
    * The getTableIds method returns the Ids of every Table in the Store.
    *
    * Note that this returns a copy of, rather than a reference, to the list of
-   * Ids, so changes made to the list are not made to the Store itself. Since
-   * v2.0.0, the order is significant: this method will return the Ids in the
-   * order in which each Table was added.
+   * Ids, so changes made to the list are not made to the Store itself.
    *
    * @returns An array of the Ids of every Table in the Store.
    * @example
@@ -894,9 +897,7 @@ export interface Store {
    * The getRowIds method returns the Ids of every Row in a given Table.
    *
    * Note that this returns a copy of, rather than a reference, to the list of
-   * Ids, so changes made to the list are not made to the Store itself. Since
-   * v2.0.0, the order is significant: this method will return the Ids in the
-   * order in which each Row was added.
+   * Ids, so changes made to the list are not made to the Store itself.
    *
    * @param tableId The Id of the Table in the Store.
    * @returns An array of the Ids of every Row in the Table.
@@ -931,7 +932,9 @@ export interface Store {
    * sorted according to the values in a specified Cell.
    *
    * The sorting of the rows is alphanumeric, and you can indicate whether it
-   * should be in descending order.
+   * 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
@@ -945,6 +948,10 @@ export interface Store {
    * @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 Table.
    * @example
    * This example retrieves sorted Row Ids in a Table.
@@ -974,6 +981,25 @@ export interface Store {
    * // -> ['cujo', 'fido', 'felix']
    * ```
    * @example
+   * This example retrieves two pages of Row Ids in a Table.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {
+   *     fido: {price: 6},
+   *     felix: {price: 5},
+   *     mickey: {price: 2},
+   *     tom: {price: 4},
+   *     carnaby: {price: 3},
+   *     lowly: {price: 1},
+   *   },
+   * });
+   * console.log(store.getSortedRowIds('pets', 'price', false, 0, 2));
+   * // -> ['lowly', 'mickey']
+   * console.log(store.getSortedRowIds('pets', 'price', false, 2, 2));
+   * // -> ['carnaby', 'tom']
+   * ```
+   * @example
    * This example retrieves Row Ids sorted by their own value, since the
    * `cellId` parameter is undefined.
    *
@@ -1000,7 +1026,13 @@ export interface Store {
    * @category Getter
    * @since v2.0.0
    */
-  getSortedRowIds(tableId: Id, cellId?: Id, descending?: boolean): Ids;
+  getSortedRowIds(
+    tableId: Id,
+    cellId?: Id,
+    descending?: boolean,
+    offset?: number,
+    limit?: number,
+  ): Ids;
 
   /**
    * The getRow method returns an object containing the entire data of a single
@@ -1044,9 +1076,7 @@ export interface Store {
    * given Table.
    *
    * Note that this returns a copy of, rather than a reference, to the list of
-   * Ids, so changes made to the list are not made to the Store itself. Since
-   * v2.0.0, the order is significant: this method will return the Ids in the
-   * order in which each Cell was added.
+   * Ids, so changes made to the list are not made to the Store itself.
    *
    * @param tableId The Id of the Table in the Store.
    * @param rowId The Id of the Row in the Table.
@@ -2212,12 +2242,6 @@ export interface Store {
    * removed. To listen to all changes in the Store, use the addTablesListener
    * method.
    *
-   * Since v2.0.0, you can use the optional `trackReorder` parameter to
-   * additionally track when the set of Ids has not changed, but the order has -
-   * for example when a Table from the middle of the Store 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.
-   *
    * 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
@@ -2228,9 +2252,6 @@ export interface Store {
    *
    * @param listener The function that will be called whenever the Table Ids in
    * the Store 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.
    * @param mutator An optional boolean that indicates that the listener mutates
    * Store data.
    * @returns A unique Id for the listener that can later be used to call it
@@ -2260,7 +2281,6 @@ export interface Store {
    * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
    * const listenerId = store.addTableIdsListener(
    *   (store) => store.setCell('meta', 'update', 'store', true),
-   *   false, // track reorder
    *   true, // mutator
    * );
    *
@@ -2272,11 +2292,7 @@ export interface Store {
    * ```
    * @category Listener
    */
-  addTableIdsListener(
-    listener: TableIdsListener,
-    trackReorder?: boolean,
-    mutator?: boolean,
-  ): Id;
+  addTableIdsListener(listener: TableIdsListener, mutator?: boolean): Id;
 
   /**
    * The addTableListener method registers a listener function with the Store
@@ -2389,12 +2405,6 @@ export interface Store {
    * method's first parameter) or changes to any Table (by providing a `null`
    * wildcard).
    *
-   * Since v2.0.0, you can use the optional `trackReorder` parameter to
-   * additionally track when the set of Ids has not changed, but the order has -
-   * for example when a Row from the middle of the Table 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.
-   *
    * 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
@@ -2406,9 +2416,6 @@ export interface Store {
    * @param tableId The Id of the Table to listen to, or `null` as a wildcard.
    * @param listener The function that will be called whenever the Row Ids in
    * the 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.
    * @param mutator An optional boolean that indicates that the listener mutates
    * Store data.
    * @returns A unique Id for the listener that can later be used to call it
@@ -2431,36 +2438,6 @@ export interface Store {
    * store.delListener(listenerId);
    * ```
    * @example
-   * This example registers a listener that responds to a change of order in the
-   * rows of a specific Table, even though the set of Ids themselves has not
-   * changed.
-   *
-   * ```js
-   * const store = createStore().setTables({
-   *   pets: {
-   *     fido: {species: 'dog'},
-   *     felix: {species: 'cat'},
-   *   },
-   * });
-   * const listenerId = store.addRowIdsListener(
-   *   'pets',
-   *   (store) => {
-   *     console.log('Row Ids or order for pets table changed');
-   *     console.log(store.getRowIds('pets'));
-   *   },
-   *   true, // track reorder
-   * );
-   *
-   * store.transaction(() => {
-   *   store.delRow('pets', 'fido');
-   *   store.setRow('pets', 'fido', {species: 'dog'});
-   * });
-   * // -> 'Row Ids or order for pets table changed'
-   * // -> ['felix', 'fido']
-   *
-   * store.delListener(listenerId);
-   * ```
-   * @example
    * This example registers a listener that responds to any change to the Row
    * Ids of any Table.
    *
@@ -2489,7 +2466,6 @@ export interface Store {
    * const listenerId = store.addRowIdsListener(
    *   'pets',
    *   (store, tableId) => store.setCell('meta', 'update', tableId, true),
-   *   false, // track reorder
    *   true, // mutator
    * );
    *
@@ -2504,20 +2480,21 @@ export interface Store {
   addRowIdsListener(
     tableId: IdOrNull,
     listener: RowIdsListener,
-    trackReorder?: boolean,
     mutator?: boolean,
   ): Id;
 
   /**
    * The addSortedRowIdsListener method registers a listener function with the
-   * Store that will be called whenever sorted Row Ids in a Table change.
+   * Store that will be called whenever sorted (and optionally, paginated) Row
+   * Ids in a Table change.
    *
    * 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, and whether
-   * descending or not. 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.
+   * 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
@@ -2527,6 +2504,11 @@ export interface Store {
    * 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
@@ -2539,6 +2521,10 @@ export interface Store {
    * @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.
    * @param listener The function that will be called whenever the sorted Row
    * Ids in the Table change.
    * @param mutator An optional boolean that indicates that the listener mutates
@@ -2563,7 +2549,9 @@ export interface Store {
    *   'pets',
    *   'species',
    *   false,
-   *   (store, tableId, cellId, descending, sortedRowIds) => {
+   *   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
@@ -2577,6 +2565,43 @@ export interface Store {
    * store.delListener(listenerId);
    * ```
    * @example
+   * This 111example registers a listener that responds to any change to a
+   * paginated section of the sorted Row Ids of a specific Table.
+   *
+   * ```js
+   * 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);
+   * ```
+   * @example
    * 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.
@@ -2595,7 +2620,9 @@ export interface Store {
    *   'pets',
    *   undefined,
    *   false,
-   *   (store, tableId, cellId, descending, sortedRowIds) => {
+   *   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
@@ -2627,7 +2654,9 @@ export interface Store {
    *   'pets',
    *   'species',
    *   false,
-   *   (store, tableId, cellId, descending, sortedRowIds) => {
+   *   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
@@ -2655,6 +2684,8 @@ export interface Store {
    *   'pets',
    *   'species',
    *   false,
+   *   0,
+   *   undefined,
    *   (store, tableId) => store.setCell('meta', 'sorted', tableId, true),
    *   true, // mutator
    * );
@@ -2672,6 +2703,8 @@ export interface Store {
     tableId: Id,
     cellId: Id | undefined,
     descending: boolean,
+    offset: number,
+    limit: number | undefined,
     listener: SortedRowIdsListener,
     mutator?: boolean,
   ): Id;
@@ -2806,12 +2839,6 @@ export interface Store {
    * Table, any Row in a specific Table, a specific Row in any Table, or any Row
    * in any Table.
    *
-   * Since v2.0.0, you can 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.
-   *
    * 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
@@ -2824,9 +2851,6 @@ export interface Store {
    * @param rowId The Id of the Row to listen to, or `null` as a wildcard.
    * @param listener The function that will be called whenever the Cell Ids in
    * the 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.
    * @param mutator An optional boolean that indicates that the listener mutates
    * Store data.
    * @returns A unique Id for the listener that can later be used to call it
@@ -2883,7 +2907,6 @@ export interface Store {
    *   'fido',
    *   (store, tableId, rowId) =>
    *     store.setCell('meta', 'update', `${tableId}_${rowId}`, true),
-   *   false, // track reorder
    *   true, // mutator
    * );
    *
@@ -2899,7 +2922,6 @@ export interface Store {
     tableId: IdOrNull,
     rowId: IdOrNull,
     listener: CellIdsListener,
-    trackReorder?: boolean,
     mutator?: boolean,
   ): Id;