[hooks] useSortedRowIds object arg

Fixes #214

Author: jamesgpearce

src/@types/ui-react/docs.js

@@ -1523,6 +1523,55 @@
  * @since v2.0.0
  */
 /// useSortedRowIds
+
+/**
+ * When called with an object as the first argument, the useSortedRowIds 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 storeOrStoreId The Store to be accessed: omit for the default context
+ * Store, provide an Id for a named context Store, or provide an explicit
+ * reference.
+ * @returns An array of the sorted Ids of every Row in the Table.
+ * @example
+ * This example creates a Store outside the application, which is used in the
+ * useSortedRowIds hook by reference. A change to the data in the Store
+ * re-renders the component.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createStore} from 'tinybase';
+ * import {useSortedRowIds} from 'tinybase/ui-react';
+ *
+ * const store = createStore().setTables({
+ *   pets: {
+ *     fido: {species: 'dog'},
+ *     felix: {species: 'cat'},
+ *   },
+ * });
+ * const App = () => (
+ *   <span>
+ *     {JSON.stringify(
+ *       useSortedRowIds({tableId: 'pets', cellId: 'species'}, store),
+ *     )}
+ *   </span>
+ * );
+ *
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["felix","fido"]</span>'
+ *
+ * store.setRow('pets', 'cujo', {species: 'wolf'}); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["felix","fido","cujo"]</span>'
+ * ```
+ * @category Store hooks
+ * @since v6.1.0
+ */
+/// useSortedRowIds.2
+
 /**
  * The useHasRow hook returns a boolean indicating whether a given Row exists in
  * the Store, and registers a listener so that any changes to that result will

src/@types/ui-react/index.d.ts

@@ -63,6 +63,7 @@ import type {
   RowCountListener,
   RowIdsListener,
   RowListener,
+  SortedRowIdsArgs,
   SortedRowIdsListener,
   Store,
   Table,
@@ -190,6 +191,12 @@ export function useSortedRowIds(
   storeOrStoreId?: StoreOrStoreId,
 ): Ids;
 
+/// useSortedRowIds.2
+export function useSortedRowIds(
+  args: SortedRowIdsArgs,
+  storeOrStoreId?: StoreOrStoreId,
+): Ids;
+
 /// useHasRow
 export function useHasRow(
   tableId: Id,

src/@types/ui-react/with-schemas/index.d.ts

@@ -114,6 +114,7 @@ import type {
   RowCountListener,
   RowIdsListener,
   RowListener,
+  SortedRowIdsArgs,
   SortedRowIdsListener,
   Store,
   Table,
@@ -236,18 +237,26 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     storeOrStoreId?: StoreOrStoreId<Schemas>,
   ) => Ids;
 
-  /// useSortedRowIds
-  useSortedRowIds: <
-    TableId extends TableIdFromSchema<Schemas[0]>,
-    CellId extends CellIdFromSchema<Schemas[0], TableId>,
-  >(
-    tableId: TableId,
-    cellId?: CellId,
-    descending?: boolean,
-    offset?: number,
-    limit?: number,
-    storeOrStoreId?: StoreOrStoreId<Schemas>,
-  ) => Ids;
+  useSortedRowIds: {
+    /// useSortedRowIds
+    <
+      TableId extends TableIdFromSchema<Schemas[0]>,
+      CellId extends CellIdFromSchema<Schemas[0], TableId>,
+    >(
+      tableId: TableId,
+      cellId?: CellId,
+      descending?: boolean,
+      offset?: number,
+      limit?: number,
+      storeOrStoreId?: StoreOrStoreId<Schemas>,
+    ): Ids;
+
+    /// useSortedRowIds.2
+    <TableId extends TableIdFromSchema<Schemas[0]>>(
+      args: SortedRowIdsArgs<Schemas[0], TableId>,
+      storeOrStoreId?: StoreOrStoreId<Schemas>,
+    ): Ids;
+  };
 
   /// useHasRow
   useHasRow: <TableId extends TableIdFromSchema<Schemas[0]>>(
@@ -627,14 +636,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     descending: Descending,
     offset: Offset,
     limit: Limit,
-    listener: SortedRowIdsListener<
-      Schemas,
-      TableId,
-      CellIdOrUndefined,
-      Descending,
-      Offset,
-      Limit
-    >,
+    listener: SortedRowIdsListener<Schemas, TableId, CellIdOrUndefined>,
     listenerDeps?: React.DependencyList,
     mutator?: boolean,
     storeOrStoreId?: StoreOrStoreId<Schemas>,

src/ui-react/hooks.ts

@@ -61,6 +61,7 @@ import type {
   RowCountListener,
   RowIdsListener,
   RowListener,
+  SortedRowIdsArgs,
   SortedRowIdsListener,
   Store,
   Table,
@@ -242,7 +243,7 @@ import {
   arrayMap,
 } from '../common/array.ts';
 import {ListenerArgument} from '../common/listeners.ts';
-import {IdObj, objIsEqual} from '../common/obj.ts';
+import {IdObj, isObject, objIsEqual} from '../common/obj.ts';
 import {
   getUndefined,
   ifNotUndefined,
@@ -480,6 +481,23 @@ const useCheckpointAction = (
   );
 };
 
+const useSortedRowIdsImpl = (
+  tableId: Id,
+  cellId?: Id,
+  descending?: boolean,
+  offset?: number,
+  limit?: number | undefined,
+  storeOrStoreId?: StoreOrStoreId,
+): Ids =>
+  useListenable(
+    SORTED_ROW_IDS,
+    useStoreOrStoreById(storeOrStoreId),
+    ReturnType.Array,
+    [tableId, cellId, descending, offset, limit],
+  );
+
+// ---
+
 export const useCreateStore: typeof useCreateStoreDecl = (
   create: () => Store,
   createDeps: DependencyList = EMPTY_ARRAY,
@@ -599,18 +617,31 @@ export const useRowIds: typeof useRowIdsDecl = (
   );
 
 export const useSortedRowIds: typeof useSortedRowIdsDecl = (
-  tableId: Id,
-  cellId?: Id,
+  tableIdOrArgs: Id | SortedRowIdsArgs,
+  cellIdOrStoreOrStoreId?: Id | StoreOrStoreId,
   descending?: boolean,
-  offset = 0,
-  limit?: number,
+  offset?: number,
+  limit?: number | undefined,
   storeOrStoreId?: StoreOrStoreId,
 ): Ids =>
-  useListenable(
-    SORTED_ROW_IDS,
-    useStoreOrStoreById(storeOrStoreId),
-    ReturnType.Array,
-    [tableId, cellId, descending, offset, limit],
+  (useSortedRowIdsImpl as any)(
+    ...(isObject(tableIdOrArgs)
+      ? [
+          tableIdOrArgs.tableId,
+          tableIdOrArgs.cellId,
+          tableIdOrArgs.descending ?? false,
+          tableIdOrArgs.offset ?? 0,
+          tableIdOrArgs.limit,
+          cellIdOrStoreOrStoreId,
+        ]
+      : [
+          tableIdOrArgs,
+          cellIdOrStoreOrStoreId,
+          descending,
+          offset,
+          limit,
+          storeOrStoreId,
+        ]),
   );
 
 export const useHasRow: typeof useHasRowDecl = (