[indexes] Add forEachIndex and forEachSlice methods

Author: jamesgpearce

src/indexes.d.ts

@@ -11,7 +11,7 @@
  * @module indexes
  */
 
-import {GetCell, Store} from './store.d';
+import {GetCell, RowCallback, Store} from './store.d';
 import {Id, IdOrNull, Ids, SortKey} from './common.d';
 
 /**
@@ -43,6 +43,42 @@ export type Index = {[sliceId: Id]: Slice};
  */
 export type Slice = Ids;
 
+/**
+ * The IndexCallback type describes a function that takes an Index's Id and a
+ * callback to loop over each Slice within it.
+ *
+ * A IndexCallback is provided when using the forEachIndex method, so that you
+ * can do something based on every Index in the Indexes object. See that method
+ * for specific examples.
+ *
+ * @param indexId The Id of the Index that the callback can operate on.
+ * @param forEachRow A function that will let you iterate over the Slice objects
+ * in this Index.
+ * @category Callback
+ */
+export type IndexCallback = (
+  indexId: Id,
+  forEachSlice: (sliceCallback: SliceCallback) => void,
+) => void;
+
+/**
+ * The SliceCallback type describes a function that takes a Slice's Id and a
+ * callback to loop over each Row within it.
+ *
+ * A SliceCallback is provided when using the forEachSlice method, so that you
+ * can do something based on every Slice in an Index. See that method for
+ * specific examples.
+ *
+ * @param sliceId The Id of the Slice that the callback can operate on.
+ * @param forEachRow A function that will let you iterate over the Row objects
+ * in this Slice.
+ * @category Callback
+ */
+export type SliceCallback = (
+  sliceId: Id,
+  forEachRow: (rowCallback: RowCallback) => void,
+) => void;
+
 /**
  * The SliceIdsListener type describes a function that is used to listen to
  * changes to the Slice Ids in an Index.
@@ -362,6 +398,82 @@ export interface Indexes {
    */
   getIndexIds(): Ids;
 
+  /**
+   * The forEachIndex method takes a function that it will then call for each
+   * Index in a specified Indexes object.
+   *
+   * This method is useful for iterating over the structure of the Indexes
+   * object in a functional style. The `indexCallback` parameter is a
+   * IndexCallback function that will called with the Id of each Index, and with
+   * a function that can then be used to iterate over each Slice of the Index,
+   * should you wish.
+   *
+   * @param indexCallback The function that should be called for every Index.
+   * @example
+   * This example iterates over each Index in a Indexes object, and lists each
+   * Slice Id within them.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog', color: 'brown'},
+   *   felix: {species: 'cat', color: 'black'},
+   *   cujo: {species: 'dog', color: 'black'},
+   * });
+   * const indexes = createIndexes(store)
+   *   .setIndexDefinition('bySpecies', 'pets', 'species')
+   *   .setIndexDefinition('byColor', 'pets', 'color');
+   *
+   * indexes.forEachIndex((indexId, forEachSlice) => {
+   *   console.log(indexId);
+   *   forEachSlice((sliceId) => console.log(`- ${sliceId}`));
+   * });
+   * // -> 'bySpecies'
+   * // -> '- dog'
+   * // -> '- cat'
+   * // -> 'byColor'
+   * // -> '- brown'
+   * // -> '- black'
+   * ```
+   * @category Iterator
+   */
+  forEachIndex(indexCallback: IndexCallback): void;
+
+  /**
+   * The forEachSlice method takes a function that it will then call for each
+   * Slice in a specified Index.
+   *
+   * This method is useful for iterating over the Slice structure of the Index
+   * in a functional style. The `rowCallback` parameter is a RowCallback
+   * function that will called with the Id and value of each Row in the Slice.
+   *
+   * @param indexId The Id of the Index to iterate over.
+   * @param sliceCallback The function that should be called for every Slice.
+   * @example
+   * This example iterates over each Row in a Slice, and lists its Id.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog'},
+   *   felix: {species: 'cat'},
+   *   cujo: {species: 'dog'},
+   * });
+   * const indexes = createIndexes(store);
+   * indexes.setIndexDefinition('bySpecies', 'pets', 'species');
+   *
+   * indexes.forEachSlice('bySpecies', (sliceId, forEachRow) => {
+   *   console.log(sliceId);
+   *   forEachRow((rowId) => console.log(`- ${rowId}`));
+   * });
+   * // -> 'dog'
+   * // -> '- fido'
+   * // -> '- cujo'
+   * // -> 'cat'
+   * // -> '- felix'
+   * ```
+   * @category Iterator
+   */
+  forEachSlice(indexId: Id, sliceCallback: SliceCallback): void;
+
   /**
    * The hasIndex method returns a boolean indicating whether a given Index
    * exists in the Indexes object.

src/indexes.ts

@@ -4,8 +4,10 @@ import {Id, IdOrNull, Ids, SortKey} from './common.d';
 import {IdMap, mapForEach, mapGet, mapKeys, mapNew, mapSet} from './common/map';
 import {IdSet, IdSet2, IdSet3, setAdd, setNew} from './common/set';
 import {
+  IndexCallback,
   Indexes,
   IndexesListenerStats,
+  SliceCallback,
   SliceIdsListener,
   SliceRowIdsListener,
   createIndexes as createIndexesDecl,
@@ -37,7 +39,7 @@ export const createIndexes: typeof createIndexesDecl = getCreateFunction(
     const [
       getStore,
       getIndexIds,
-      _forEachIndex,
+      forEachIndexImpl,
       hasIndex,
       getTableId,
       getIndex,
@@ -178,6 +180,33 @@ export const createIndexes: typeof createIndexesDecl = getCreateFunction(
       return indexes;
     };
 
+    const forEachIndex = (indexCallback: IndexCallback) =>
+      forEachIndexImpl((indexId, slices) =>
+        indexCallback(indexId, (sliceCallback) =>
+          forEachSliceImpl(indexId, sliceCallback, slices),
+        ),
+      );
+
+    const forEachSlice = (indexId: Id, sliceCallback: SliceCallback) =>
+      forEachSliceImpl(indexId, sliceCallback, getIndex(indexId) as IdSet2);
+
+    const forEachSliceImpl = (
+      indexId: Id,
+      sliceCallback: SliceCallback,
+      slices: IdSet2,
+    ) => {
+      const tableId = getTableId(indexId);
+      collForEach(slices, (rowIds, sliceId) =>
+        sliceCallback(sliceId, (rowCallback) =>
+          collForEach(rowIds, (rowId) =>
+            rowCallback(rowId, (cellCallback) =>
+              store.forEachCell(tableId, rowId, cellCallback),
+            ),
+          ),
+        ),
+      );
+    };
+
     const delIndexDefinition = (indexId: Id): Indexes => {
       delDefinition(indexId);
       return indexes;
@@ -218,6 +247,8 @@ export const createIndexes: typeof createIndexesDecl = getCreateFunction(
 
       getStore,
       getIndexIds,
+      forEachIndex,
+      forEachSlice,
       hasIndex,
       hasSlice,
       getTableId,

test/unit/common.ts

@@ -293,14 +293,17 @@ export const getMetricsObject = (
 
 export const getIndexesObject = (indexes: Indexes): IdMap<IdMap<Ids>> => {
   const indexesObject: IdMap<IdMap<Ids>> = {};
-  indexes.getIndexIds().forEach((indexId) => {
+  indexes.forEachIndex((indexId) => {
     indexesObject[indexId] = {};
-    indexes.getSliceIds(indexId).forEach((sliceId) => {
-      indexesObject[indexId][sliceId] = indexes.getSliceRowIds(
-        indexId,
-        sliceId,
+    indexes
+      .getSliceIds(indexId)
+      .forEach(
+        (sliceId) =>
+          (indexesObject[indexId][sliceId] = indexes.getSliceRowIds(
+            indexId,
+            sliceId,
+          )),
       );
-    });
   });
   return indexesObject;
 };

test/unit/indexes.test.ts

@@ -1555,6 +1555,62 @@ describe('Miscellaneous', () => {
     expectNoChanges(listener);
   });
 
+  describe('forEach', () => {
+    test('forEachIndex', () => {
+      indexes
+        .setIndexDefinition('i1', 't1')
+        .setIndexDefinition('i2', 't1', 'c2');
+      setCells();
+      const eachIndex: any = {};
+      indexes.forEachIndex((indexId, forEachSlice) => {
+        const eachSlice: any = {};
+        forEachSlice((sliceId, forEachRow) => {
+          const eachRow: any = {};
+          forEachRow((rowId, forEachCell) => {
+            const eachCell: any = {};
+            forEachCell((cellId, cell) => (eachCell[cellId] = cell));
+            eachRow[rowId] = eachCell;
+          });
+          eachSlice[sliceId] = eachRow;
+        });
+        eachIndex[indexId] = eachSlice;
+      });
+      expect(eachIndex).toEqual({
+        i1: {
+          '': {
+            r1: {c1: 'one', c2: 'odd'},
+            r2: {c1: 'two', c2: 'even'},
+            r3: {c1: 'three', c2: 'odd'},
+            r4: {c1: 'four', c2: 'even'},
+          },
+        },
+        i2: {
+          even: {r2: {c1: 'two', c2: 'even'}, r4: {c1: 'four', c2: 'even'}},
+          odd: {r1: {c1: 'one', c2: 'odd'}, r3: {c1: 'three', c2: 'odd'}},
+        },
+      });
+    });
+
+    test('forEachSlice', () => {
+      indexes.setIndexDefinition('i2', 't1', 'c2');
+      setCells();
+      const eachSlice: any = {};
+      indexes.forEachSlice('i2', (sliceId, forEachRow) => {
+        const eachRow: any = {};
+        forEachRow((rowId, forEachCell) => {
+          const eachCell: any = {};
+          forEachCell((cellId, cell) => (eachCell[cellId] = cell));
+          eachRow[rowId] = eachCell;
+        });
+        eachSlice[sliceId] = eachRow;
+      });
+      expect(eachSlice).toEqual({
+        even: {r2: {c1: 'two', c2: 'even'}, r4: {c1: 'four', c2: 'even'}},
+        odd: {r1: {c1: 'one', c2: 'odd'}, r3: {c1: 'three', c2: 'odd'}},
+      });
+    });
+  });
+
   test('are things present', () => {
     expect(indexes.hasIndex('i1')).toEqual(false);
     indexes.setIndexDefinition('i1', 't1', 'c2');