tinybase 6.1.0-beta.5 → 6.1.0

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

@@ -137,6 +137,7 @@ import type {
   RowCountListener,
   RowIdsListener,
   RowListener,
+  SortedRowIdsArgs,
   SortedRowIdsListener,
   Store,
   Table,
@@ -1723,7 +1724,8 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     storeOrStoreId?: StoreOrStoreId<Schemas>,
   ) => Ids;
 
-  /**
+  useSortedRowIds: {
+    /**
  * The useSortedRowIds hook returns the sorted (and optionally, paginated) Ids
  * of every Row in a given Table, and registers a listener so that any changes
  * to that result will cause a re-render.
@@ -1859,17 +1861,78 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * @category Store hooks
  * @since v2.0.0
  */
-  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;
+    <
+      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;
+
+    /**
+ * 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.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useSortedRowIds(
+ *   args: SortedRowIdsArgs,
+ *   storeOrStoreId?: StoreOrStoreId,
+ * ): Ids;
+ * ```
+ *
+ * ```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
+ */
+    <TableId extends TableIdFromSchema<Schemas[0]>>(
+      args: SortedRowIdsArgs<Schemas[0], TableId>,
+      storeOrStoreId?: StoreOrStoreId<Schemas>,
+    ): Ids;
+  };
 
   /**
  * The useHasRow hook returns a boolean indicating whether a given Row exists in
@@ -5329,7 +5392,8 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     storeOrStoreId?: StoreOrStoreId<Schemas>,
   ) => void;
 
-  /**
+  useSortedRowIdsListener: {
+    /**
  * The useSortedRowIdsListener hook registers a listener function with a Store
  * that will be called whenever sorted (and optionally, paginated) Row Ids in a
  * Table change.
@@ -5420,30 +5484,108 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * @category Store hooks
  * @since v2.0.0
  */
-  useSortedRowIdsListener: <
-    TableId extends TableIdFromSchema<Schemas[0]>,
-    CellIdOrUndefined extends CellIdFromSchema<Schemas[0], TableId> | undefined,
-    Descending extends boolean,
-    Offset extends number,
-    Limit extends number | undefined,
-  >(
-    tableId: TableId,
-    cellId: CellIdOrUndefined,
-    descending: Descending,
-    offset: Offset,
-    limit: Limit,
-    listener: SortedRowIdsListener<
-      Schemas,
-      TableId,
-      CellIdOrUndefined,
-      Descending,
-      Offset,
-      Limit
-    >,
-    listenerDeps?: React.DependencyList,
-    mutator?: boolean,
-    storeOrStoreId?: StoreOrStoreId<Schemas>,
-  ) => void;
+    <
+      TableId extends TableIdFromSchema<Schemas[0]>,
+      CellIdOrUndefined extends
+        | CellIdFromSchema<Schemas[0], TableId>
+        | undefined,
+    >(
+      tableId: TableId,
+      cellId: CellIdOrUndefined,
+      descending: boolean,
+      offset: number,
+      limit: number | undefined,
+      listener: SortedRowIdsListener<Schemas, TableId, CellIdOrUndefined>,
+      listenerDeps?: React.DependencyList,
+      mutator?: boolean,
+      storeOrStoreId?: StoreOrStoreId<Schemas>,
+    ): void;
+
+    /**
+ * 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 listener The function that will be called whenever the sorted Row Ids
+ * in the Table change.
+ * @param listenerDeps An optional array of dependencies for the `listener`
+ * function, which, if any change, result in the re-registration of the
+ * listener. This parameter defaults to an empty array.
+ * @param mutator An optional boolean that indicates that the listener mutates
+ * Store data.
+ * @param storeOrStoreId The Store to register the listener with: omit for the
+ * default context Store, provide an Id for a named context Store, or provide an
+ * explicit reference.
+ * @example
+ * This example uses the useSortedRowIdsListener hook to create a listener that
+ * is scoped to a single component. When the component is unmounted, the
+ * listener is removed from the Store.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useSortedRowIdsListener(
+ *   args: SortedRowIdsArgs,
+ *   listener: SortedRowIdsListener,
+ *   listenerDeps?: React.DependencyList,
+ *   mutator?: boolean,
+ *   storeOrStoreId?: StoreOrStoreId,
+ * ): void;
+ * ```
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createStore} from 'tinybase';
+ * import {Provider, useSortedRowIdsListener} from 'tinybase/ui-react';
+ *
+ * const App = ({store}) => (
+ *   <Provider store={store}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => {
+ *   useSortedRowIdsListener({tableId: 'pets', cellId: 'species'}, () =>
+ *     console.log('Sorted Row Ids changed'),
+ *   );
+ *   return <span>App</span>;
+ * };
+ *
+ * const store = createStore().setTables({
+ *   pets: {
+ *     fido: {species: 'dog'},
+ *     felix: {species: 'cat'},
+ *   },
+ * });
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App store={store} />); // !act
+ * console.log(store.getListenerStats().sortedRowIds);
+ * // -> 1
+ *
+ * store.setRow('pets', 'cujo', {species: 'wolf'}); // !act
+ * // -> 'Sorted Row Ids changed'
+ *
+ * root.unmount(); // !act
+ * console.log(store.getListenerStats().sortedRowIds);
+ * // -> 0
+ * ```
+ * @category Store hooks
+ * @since v6.1.0
+ */
+    <
+      TableId extends TableIdFromSchema<Schemas[0]>,
+      CellIdOrUndefined extends
+        | CellIdFromSchema<Schemas[0], TableId>
+        | undefined,
+    >(
+      args: SortedRowIdsArgs<Schemas[0], TableId>,
+      listener: SortedRowIdsListener<Schemas, TableId, CellIdOrUndefined>,
+      listenerDeps?: React.DependencyList,
+      mutator?: boolean,
+      storeOrStoreId?: StoreOrStoreId<Schemas>,
+    ): void;
+  };
 
   /**
  * The useHasRowListener hook registers a listener function with the Store that

package/index.js

@@ -1792,6 +1792,27 @@ const createStore = () => {
     transaction(() => actions(...arrayMap(args, id)));
     return store;
   };
+  const addSortedRowIdsListenerImpl = (
+    tableId,
+    cellId,
+    otherArgs,
+    listener,
+    mutator,
+  ) => {
+    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 = () => [getTables(), getValues()];
   const getTables = () => mapToObj3(tablesMap);
   const getTableIds = () => mapKeys(tablesMap);
@@ -1800,22 +1821,36 @@ const createStore = () => {
     mapKeys(mapGet(tableCellIds, id(tableId)));
   const getRowCount = (tableId) => collSize(mapGet(tablesMap, id(tableId)));
   const getRowIds = (tableId) => mapKeys(mapGet(tablesMap, id(tableId)));
-  const getSortedRowIds = (tableId, cellId, descending, offset = 0, limit) =>
-    arrayMap(
-      slice(
-        arraySort(
-          mapMap(mapGet(tablesMap, id(tableId)), (row, rowId) => [
-            isUndefined(cellId) ? rowId : mapGet(row, id(cellId)),
-            rowId,
-          ]),
-          ([cell1], [cell2]) =>
-            defaultSorter(cell1, cell2) * (descending ? -1 : 1),
-        ),
-        offset,
-        isUndefined(limit) ? limit : offset + limit,
-      ),
-      ([, rowId]) => rowId,
-    );
+  const getSortedRowIds = (
+    tableIdOrArgs,
+    cellId,
+    descending,
+    offset = 0,
+    limit,
+  ) =>
+    isObject(tableIdOrArgs)
+      ? getSortedRowIds(
+          tableIdOrArgs.tableId,
+          tableIdOrArgs.cellId,
+          tableIdOrArgs.descending,
+          tableIdOrArgs.offset,
+          tableIdOrArgs.limit,
+        )
+      : arrayMap(
+          slice(
+            arraySort(
+              mapMap(mapGet(tablesMap, id(tableIdOrArgs)), (row, rowId) => [
+                isUndefined(cellId) ? rowId : mapGet(row, id(cellId)),
+                rowId,
+              ]),
+              ([cell1], [cell2]) =>
+                defaultSorter(cell1, cell2) * (descending ? -1 : 1),
+            ),
+            offset,
+            isUndefined(limit) ? limit : offset + limit,
+          ),
+          ([, rowId]) => rowId,
+        );
   const getRow = (tableId, rowId) =>
     mapToObj(mapGet(mapGet(tablesMap, id(tableId)), id(rowId)));
   const getCellIds = (tableId, rowId) =>
@@ -2207,48 +2242,33 @@ const createStore = () => {
     mapForEach(mapGet(mapGet(tablesMap, id(tableId)), id(rowId)), cellCallback);
   const forEachValue = (valueCallback) => mapForEach(valuesMap, valueCallback);
   const addSortedRowIdsListener = (
-    tableId,
-    cellId,
-    descending,
+    tableIdOrArgs,
+    cellIdOrListener,
+    descendingOrMutator,
     offset,
     limit,
     listener,
     mutator,
-  ) => {
-    let sortedRowIds = getSortedRowIds(
-      tableId,
-      cellId,
-      descending,
-      offset,
-      limit,
-    );
-    return addListener(
-      () => {
-        const newSortedRowIds = getSortedRowIds(
-          tableId,
-          cellId,
-          descending,
-          offset,
-          limit,
+  ) =>
+    isObject(tableIdOrArgs)
+      ? addSortedRowIdsListenerImpl(
+          tableIdOrArgs.tableId,
+          tableIdOrArgs.cellId,
+          [
+            tableIdOrArgs.descending ?? false,
+            tableIdOrArgs.offset ?? 0,
+            tableIdOrArgs.limit,
+          ],
+          cellIdOrListener,
+          descendingOrMutator,
+        )
+      : addSortedRowIdsListenerImpl(
+          tableIdOrArgs,
+          cellIdOrListener,
+          [descendingOrMutator, offset, limit],
+          listener,
+          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) =>
     addListener(listener, startTransactionListeners);
   const addWillFinishTransactionListener = (listener) =>

package/mergeable-store/index.js

@@ -1140,6 +1140,27 @@ const createStore = () => {
     transaction(() => actions(...arrayMap(args, id)));
     return store;
   };
+  const addSortedRowIdsListenerImpl = (
+    tableId,
+    cellId,
+    otherArgs,
+    listener,
+    mutator,
+  ) => {
+    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 = () => [getTables(), getValues()];
   const getTables = () => mapToObj3(tablesMap);
   const getTableIds = () => mapKeys(tablesMap);
@@ -1148,22 +1169,36 @@ const createStore = () => {
     mapKeys(mapGet(tableCellIds, id(tableId)));
   const getRowCount = (tableId) => collSize(mapGet(tablesMap, id(tableId)));
   const getRowIds = (tableId) => mapKeys(mapGet(tablesMap, id(tableId)));
-  const getSortedRowIds = (tableId, cellId, descending, offset = 0, limit) =>
-    arrayMap(
-      slice(
-        arraySort(
-          mapMap(mapGet(tablesMap, id(tableId)), (row, rowId) => [
-            isUndefined(cellId) ? rowId : mapGet(row, id(cellId)),
-            rowId,
-          ]),
-          ([cell1], [cell2]) =>
-            defaultSorter(cell1, cell2) * (descending ? -1 : 1),
-        ),
-        offset,
-        isUndefined(limit) ? limit : offset + limit,
-      ),
-      ([, rowId]) => rowId,
-    );
+  const getSortedRowIds = (
+    tableIdOrArgs,
+    cellId,
+    descending,
+    offset = 0,
+    limit,
+  ) =>
+    isObject(tableIdOrArgs)
+      ? getSortedRowIds(
+          tableIdOrArgs.tableId,
+          tableIdOrArgs.cellId,
+          tableIdOrArgs.descending,
+          tableIdOrArgs.offset,
+          tableIdOrArgs.limit,
+        )
+      : arrayMap(
+          slice(
+            arraySort(
+              mapMap(mapGet(tablesMap, id(tableIdOrArgs)), (row, rowId) => [
+                isUndefined(cellId) ? rowId : mapGet(row, id(cellId)),
+                rowId,
+              ]),
+              ([cell1], [cell2]) =>
+                defaultSorter(cell1, cell2) * (descending ? -1 : 1),
+            ),
+            offset,
+            isUndefined(limit) ? limit : offset + limit,
+          ),
+          ([, rowId]) => rowId,
+        );
   const getRow = (tableId, rowId) =>
     mapToObj(mapGet(mapGet(tablesMap, id(tableId)), id(rowId)));
   const getCellIds = (tableId, rowId) =>
@@ -1555,48 +1590,33 @@ const createStore = () => {
     mapForEach(mapGet(mapGet(tablesMap, id(tableId)), id(rowId)), cellCallback);
   const forEachValue = (valueCallback) => mapForEach(valuesMap, valueCallback);
   const addSortedRowIdsListener = (
-    tableId,
-    cellId,
-    descending,
+    tableIdOrArgs,
+    cellIdOrListener,
+    descendingOrMutator,
     offset,
     limit,
     listener,
     mutator,
-  ) => {
-    let sortedRowIds = getSortedRowIds(
-      tableId,
-      cellId,
-      descending,
-      offset,
-      limit,
-    );
-    return addListener(
-      () => {
-        const newSortedRowIds = getSortedRowIds(
-          tableId,
-          cellId,
-          descending,
-          offset,
-          limit,
+  ) =>
+    isObject(tableIdOrArgs)
+      ? addSortedRowIdsListenerImpl(
+          tableIdOrArgs.tableId,
+          tableIdOrArgs.cellId,
+          [
+            tableIdOrArgs.descending ?? false,
+            tableIdOrArgs.offset ?? 0,
+            tableIdOrArgs.limit,
+          ],
+          cellIdOrListener,
+          descendingOrMutator,
+        )
+      : addSortedRowIdsListenerImpl(
+          tableIdOrArgs,
+          cellIdOrListener,
+          [descendingOrMutator, offset, limit],
+          listener,
+          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) =>
     addListener(listener, startTransactionListeners);
   const addWillFinishTransactionListener = (listener) =>