[checkpoints] Add forEachCheckpoints method

Author: jamesgpearce

src/checkpoints.d.ts

@@ -33,6 +33,20 @@ import {Store} from './store.d';
  */
 export type CheckpointIds = [Ids, Id | undefined, Ids];
 
+/**
+ * The CheckpointCallback type describes a function that takes a Checkpoint's
+ * Id.
+ *
+ * A CheckpointCallback is provided when using the forEachCheckpoint method,
+ * so that you can do something based on every Checkpoint in the Checkpoints
+ * object. See that method for specific examples.
+ *
+ * @param checkpointId The Id of the Checkpoint that the callback can operate
+ * on.
+ * @category Callback
+ */
+export type CheckpointCallback = (checkpointId: Id, label?: string) => void;
+
 /**
  * The CheckpointIdsListener type describes a function that is used to listen to
  * changes to the checkpoint Ids in a Checkpoints object.
@@ -353,6 +367,36 @@ export interface Checkpoints {
    */
   getCheckpointIds(): CheckpointIds;
 
+  /**
+   * The forEachCheckpoint method takes a function that it will then call for
+   * each Checkpoint in a specified Checkpoints object.
+   *
+   * This method is useful for iterating over the structure of the Checkpoints
+   * object in a functional style. The `checkpointCallback` parameter is a
+   * CheckpointCallback function that will be called with the Id of each
+   * Checkpoint.
+   *
+   * @param checkpointCallback The function that should be called for every
+   * Checkpoint.
+   * @example
+   * This example iterates over each Checkpoint in a Checkpoints object.
+   *
+   * ```js
+   * const store = createStore().setTables({pets: {fido: {sold: false}}});
+   * const checkpoints = createCheckpoints(store);
+   * store.setCell('pets', 'fido', 'sold', true);
+   * checkpoints.addCheckpoint('sale');
+   *
+   * checkpoints.forEachCheckpoint((checkpointId, label) => {
+   *   console.log(`${checkpointId}:${label}`);
+   * });
+   * // -> '0:'
+   * // -> '1:sale'
+   * ```
+   * @category Iterator
+   */
+  forEachCheckpoint(checkpointCallback: CheckpointCallback): void;
+
   /**
    * The hasCheckpoint method returns a boolean indicating whether a given
    * Checkpoint exists in the Checkpoints object.

src/checkpoints.ts

@@ -1,5 +1,6 @@
 import {Cell, Store} from './store.d';
 import {
+  CheckpointCallback,
   CheckpointIds,
   CheckpointIdsListener,
   CheckpointListener,
@@ -9,7 +10,14 @@ import {
 } from './checkpoints.d';
 import {DEBUG, ifNotUndefined, isUndefined} from './common/other';
 import {Id, IdOrNull, Ids} from './common.d';
-import {IdMap, mapEnsure, mapGet, mapNew, mapSet} from './common/map';
+import {
+  IdMap,
+  mapEnsure,
+  mapForEach,
+  mapGet,
+  mapNew,
+  mapSet,
+} from './common/map';
 import {IdSet, IdSet2, setNew} from './common/set';
 import {
   arrayClear,
@@ -193,6 +201,9 @@ export const createCheckpoints: typeof createCheckpointsDecl =
       [...forwardIds],
     ];
 
+    const forEachCheckpoint = (checkpointCallback: CheckpointCallback) =>
+      mapForEach(labels, checkpointCallback);
+
     const hasCheckpoint = (checkpointId: Id) => collHas(deltas, checkpointId);
 
     const getCheckpoint = (checkpointId: Id): string | undefined =>
@@ -267,6 +278,7 @@ export const createCheckpoints: typeof createCheckpointsDecl =
 
       getStore,
       getCheckpointIds,
+      forEachCheckpoint,
       hasCheckpoint,
       getCheckpoint,
 

test/unit/checkpoints.test.ts

@@ -500,6 +500,23 @@ describe('Miscellaneous', () => {
     expectNoChanges(listener);
   });
 
+  test('forEachCheckpoint', () => {
+    setCells();
+    checkpoints.setCheckpoint('2', 'two');
+    checkpoints.setCheckpoint('3', 'three');
+    const eachCheckpoint: any = {};
+    checkpoints.forEachCheckpoint(
+      (checkpointId, label) => (eachCheckpoint[checkpointId] = label),
+    );
+    expect(eachCheckpoint).toEqual({
+      '0': '',
+      '1': '',
+      '2': 'two',
+      '3': 'three',
+      '4': '',
+    });
+  });
+
   test('getStore', () => {
     expect(checkpoints.getStore()).toEqual(store);
   });