[store] addSortedRowIdsListener object arg

Author: jamesgpearce

src/@types/store/docs.js

@@ -5403,6 +5403,51 @@
    * @since v2.0.0
    */
   /// Store.addSortedRowIdsListener
+  /**
+   * When called with an object as the first argument, the
+   * addSortedRowIdsListener method destructures it to make it easier to skip
+   * optional parameters.
+   * @param args A SortedRowIdsArgs object containing the Id of the Table in the
+   * Store, and optional `cellId`, `descending`, `offset`, and `limit`
+   * parameters.
+   * @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
+   * Store data.
+   * @returns 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.
+   *
+   * ```js
+   * 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);
+   * ```
+   * @category Listener
+   * @since v6.1.0
+   */
+  /// Store.addSortedRowIdsListener.2
   /**
    * The addHasRowListener method registers a listener function with the Store
    * that will be called when a Row is added to or removed from the Store.

src/@types/store/index.d.ts

@@ -698,6 +698,13 @@ export interface Store {
     mutator?: boolean,
   ): Id;
 
+  /// Store.addSortedRowIdsListener.2
+  addSortedRowIdsListener(
+    args: SortedRowIdsArgs,
+    listener: SortedRowIdsListener<this>,
+    mutator?: boolean,
+  ): Id;
+
   /// Store.addHasRowListener
   addHasRowListener(
     tableId: IdOrNull,

src/@types/store/with-schemas/index.d.ts

@@ -1321,6 +1321,27 @@ export interface Store<in out Schemas extends OptionalSchemas> {
     mutator?: boolean,
   ): Id;
 
+  /// Store.addSortedRowIdsListener.2
+  addSortedRowIdsListener<
+    TableId extends TableIdFromSchema<Schemas[0]>,
+    CellIdOrUndefined extends CellIdFromSchema<Schemas[0], TableId> | undefined,
+    Descending extends boolean,
+    Offset extends number,
+    Limit extends number | undefined,
+  >(
+    args: SortedRowIdsArgs<Schemas[0], TableId>,
+    listener: SortedRowIdsListener<
+      Schemas,
+      TableId,
+      CellIdOrUndefined,
+      Descending,
+      Offset,
+      Limit,
+      this
+    >,
+    mutator?: boolean,
+  ): Id;
+
   /// Store.addHasRowListener
   addHasRowListener<
     TableIdOrNull extends TableIdFromSchema<Schemas[0]> | null,

src/store/index.ts

@@ -992,6 +992,28 @@ export const createStore: typeof createStoreDecl = (): Store => {
     return store;
   };
 
+  const addSortedRowIdsListenerImpl = (
+    tableId: Id,
+    cellId: Id | undefined,
+    otherArgs: [descending: boolean, offset: number, limit: number | undefined],
+    listener: SortedRowIdsListener,
+    mutator?: boolean,
+  ): Id => {
+    let sortedRowIds = getSortedRowIds(tableId, cellId, ...otherArgs);
+    return addListener(
+      () => {
+        const newSortedRowIds = getSortedRowIds(tableId, cellId, ...otherArgs);
+        if (!arrayIsEqual(newSortedRowIds, sortedRowIds)) {
+          sortedRowIds = newSortedRowIds;
+          listener(store, tableId, cellId, ...otherArgs, sortedRowIds);
+        }
+      },
+      sortedRowIdsListeners[mutator ? 1 : 0],
+      [tableId, cellId],
+      [getTableIds],
+    );
+  };
+
   // --
 
   const getContent = (): Content => [getTables(), getValues()];
@@ -1013,25 +1035,25 @@ export const createStore: typeof createStoreDecl = (): Store => {
     mapKeys(mapGet(tablesMap, id(tableId)));
 
   const getSortedRowIds = (
-    tableId: Id | SortedRowIdsArgs,
+    tableIdOrArgs: Id | SortedRowIdsArgs,
     cellId?: Id,
     descending?: boolean,
     offset = 0,
     limit?: number,
   ): Ids =>
-    isObject(tableId)
+    isObject(tableIdOrArgs)
       ? getSortedRowIds(
-          tableId.tableId,
-          tableId.cellId,
-          tableId.descending,
-          tableId.offset,
-          tableId.limit,
+          tableIdOrArgs.tableId,
+          tableIdOrArgs.cellId,
+          tableIdOrArgs.descending,
+          tableIdOrArgs.offset,
+          tableIdOrArgs.limit,
         )
       : arrayMap(
           slice(
             arraySort(
               mapMap<Id, RowMap, [Cell, Id]>(
-                mapGet(tablesMap, id(tableId)),
+                mapGet(tablesMap, id(tableIdOrArgs)),
                 (row, rowId) => [
                   isUndefined(cellId)
                     ? rowId
@@ -1520,48 +1542,33 @@ export const createStore: typeof createStoreDecl = (): Store => {
     mapForEach(valuesMap, valueCallback);
 
   const addSortedRowIdsListener = (
-    tableId: Id,
-    cellId: Id | undefined,
-    descending: boolean,
-    offset: number,
-    limit: number | undefined,
-    listener: SortedRowIdsListener,
+    tableIdOrArgs: Id | SortedRowIdsArgs,
+    cellIdOrListener: Id | undefined | SortedRowIdsListener,
+    descendingOrMutator?: boolean,
+    offset?: number,
+    limit?: number | undefined,
+    listener?: SortedRowIdsListener,
     mutator?: boolean,
-  ): Id => {
-    let sortedRowIds = getSortedRowIds(
-      tableId,
-      cellId,
-      descending,
-      offset,
-      limit,
-    );
-    return addListener(
-      () => {
-        const newSortedRowIds = getSortedRowIds(
-          tableId,
-          cellId,
-          descending,
-          offset,
-          limit,
+  ): Id =>
+    isObject(tableIdOrArgs)
+      ? addSortedRowIdsListenerImpl(
+          tableIdOrArgs.tableId,
+          tableIdOrArgs.cellId,
+          [
+            tableIdOrArgs.descending ?? false,
+            tableIdOrArgs.offset ?? 0,
+            tableIdOrArgs.limit,
+          ],
+          cellIdOrListener as SortedRowIdsListener,
+          descendingOrMutator,
+        )
+      : addSortedRowIdsListenerImpl(
+          tableIdOrArgs,
+          cellIdOrListener as Id | undefined,
+          [descendingOrMutator as boolean, offset as number, limit],
+          listener as SortedRowIdsListener,
+          mutator,
         );
-        if (!arrayIsEqual(newSortedRowIds, sortedRowIds)) {
-          sortedRowIds = newSortedRowIds;
-          listener(
-            store,
-            tableId,
-            cellId,
-            descending,
-            offset,
-            limit,
-            sortedRowIds,
-          );
-        }
-      },
-      sortedRowIdsListeners[mutator ? 1 : 0],
-      [tableId, cellId],
-      [getTableIds],
-    );
-  };
 
   const addStartTransactionListener = (listener: TransactionListener): Id =>
     addListener(listener, startTransactionListeners);

test/unit/core/store/store-advanced.test.ts

@@ -356,6 +356,39 @@ describe.each([
       store.setRow('t1', 'r7', {c1: 7, c2: 'seven'});
     });
 
+    test('Cell sort listener, add row with relevant cell, object arg', () => {
+      expect.assertions(7);
+      store.addSortedRowIdsListener(
+        {tableId: 't1', cellId: 'c2', limit: 8},
+        (_store, tableId, cellId, descending, offset, limit, sortedRowIds) => {
+          expect(tableId).toEqual('t1');
+          expect(cellId).toEqual('c2');
+          expect(descending).toEqual(false);
+          expect(offset).toEqual(0);
+          expect(limit).toEqual(8);
+          expect(sortedRowIds).toEqual([
+            'r5',
+            'r4',
+            'r1',
+            'r7',
+            'r6',
+            'r3',
+            'r2',
+          ]);
+          expect(store.getSortedRowIds('t1', 'c2')).toEqual([
+            'r5',
+            'r4',
+            'r1',
+            'r7',
+            'r6',
+            'r3',
+            'r2',
+          ]);
+        },
+      );
+      store.setRow('t1', 'r7', {c1: 7, c2: 'seven'});
+    });
+
     test('Cell sort listener, add row without relevant cell', () => {
       expect.assertions(1);
       store.addSortedRowIdsListener(