[store] forEachTableCell

Author: jamesgpearce

src/store.ts

@@ -33,6 +33,7 @@ import {
   StoreListenerStats,
   Table,
   TableCallback,
+  TableCellCallback,
   Tables,
   TablesSchema,
   TransactionListener,
@@ -1329,6 +1330,11 @@ export const createStore: typeof createStoreDecl = (): Store => {
       ),
     );
 
+  const forEachTableCell = (
+    tableId: Id,
+    tableCellCallback: TableCellCallback,
+  ): void => mapForEach(mapGet(tableCellIds, id(tableId)), tableCellCallback);
+
   const forEachRow = (tableId: Id, rowCallback: RowCallback): void =>
     collForEach(mapGet(tablesMap, id(tableId)), (rowMap, rowId) =>
       rowCallback(rowId, (cellCallback) => mapForEach(rowMap, cellCallback)),
@@ -1491,6 +1497,7 @@ export const createStore: typeof createStoreDecl = (): Store => {
     finishTransaction,
 
     forEachTable,
+    forEachTableCell,
     forEachRow,
     forEachCell,
     forEachValue,

src/types/docs/store.js

@@ -289,6 +289,19 @@
  * @category Callback
  */
 /// TableCallback
+/**
+ * The TableCellCallback type describes a function that takes a Cell's Id and
+ * the count of times it appears across a whole Table.
+ *
+ * A TableCellCallback is provided when using the forEachTableCell method, so
+ * that you can do something based on every Cell used across a Table. See that
+ * method for specific examples.
+ *
+ * @param cellId The Id of the Cell that the callback can operate on.
+ * @param count The number of times this Cell is used across a whole Table.
+ * @category Callback
+ */
+/// TableCellCallback
 /**
  * The RowCallback type describes a function that takes a Row's Id and a
  * callback to loop over each Cell within it.
@@ -3189,6 +3202,35 @@
    * @category Iterator
    */
   /// Store.forEachTable
+  /**
+   * The forEachTableCell method takes a function that it will then call for
+   * each Cell used across the whole Table.
+   *
+   * This method is useful for iterating over the Cell structure of the Table in
+   * a functional style. The `tableCellCallback` parameter is a
+   * TableCellCallback function that will be called with the Id of each Cell and
+   * the count of Rows in the Table in which it appears.
+   *
+   * @param tableId The Id of the Table containing the Cells to iterate over.
+   * @param tableCellCallback The function that should be called for every Cell
+   * Id used across the whole Table.
+   * @example
+   * This example iterates over each Cell Id used across the whole Table.
+   *
+   * ```js
+   * const store = createStore().setTables({
+   *   pets: {fido: {species: 'dog'}, felix: {species: 'cat', legs: 4}},
+   * });
+   * store.forEachTableCell('pets', (cellId, count) => {
+   *   console.log(`${cellId}: ${count}`);
+   * });
+   * // -> 'species: 2'
+   * // -> 'legs: 1'
+   * ```
+   * @category Iterator
+   * @since v3.3
+   */
+  /// Store.forEachTableCell
   /**
    * The forEachRow method takes a function that it will then call for each Row
    * in a specified Table.

src/types/store.d.ts

@@ -68,6 +68,9 @@ export type TableCallback = (
   forEachRow: (rowCallback: RowCallback) => void,
 ) => void;
 
+/// TableCellCallback
+export type TableCellCallback = (cellId: Id, count: number) => void;
+
 /// RowCallback
 export type RowCallback = (
   rowId: Id,
@@ -456,6 +459,9 @@ export interface Store {
   /// Store.forEachTable
   forEachTable(tableCallback: TableCallback): void;
 
+  /// Store.forEachTableCell
+  forEachTableCell(tableId: Id, tableCellCallback: TableCellCallback): void;
+
   /// Store.forEachRow
   forEachRow(tableId: Id, rowCallback: RowCallback): void;
 

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

@@ -173,6 +173,12 @@ export type TableCallback<
   Params1 extends any[] = Truncate<Params2>,
 > = ((...params: Params2) => void) | ((...params: Params1) => void);
 
+/// TableCellCallback
+export type TableCellCallback<
+  Schema extends OptionalTablesSchema,
+  TableId extends TableIdFromSchema<Schema>,
+> = (cellId: CellIdFromSchema<Schema, TableId>, count: number) => void;
+
 /// RowCallback
 export type RowCallback<
   Schema extends OptionalTablesSchema,
@@ -838,6 +844,12 @@ export interface Store<in out Schemas extends OptionalSchemas> {
   /// Store.forEachTable
   forEachTable(tableCallback: TableCallback<Schemas[0]>): void;
 
+  /// Store.forEachTableCell
+  forEachTableCell<TableId extends TableIdFromSchema<Schemas[0]>>(
+    tableId: TableId,
+    tableCellCallback: TableCellCallback<Schemas[0], TableId>,
+  ): void;
+
   /// Store.forEachRow
   forEachRow<TableId extends TableIdFromSchema<Schemas[0]>>(
     tableId: TableId,

test/unit/store-advanced.test.ts

@@ -389,6 +389,13 @@ describe('Miscellaneous', () => {
       expect(row).toEqual({c1: 1, c2: 2});
     });
 
+    test('forEachTableCell', () => {
+      store.setTables({t1: {r1: {c1: 1, c2: 2}, r2: {c2: 2, c3: 3}}});
+      const cells: Row = {};
+      store.forEachTableCell('t1', (cellId, count) => (cells[cellId] = count));
+      expect(cells).toEqual({c1: 1, c2: 2, c3: 1});
+    });
+
     test('forEachValue', () => {
       store.setValues({v1: 1, v2: 2});
       const values: Values = {};