[relationships] Add forEachRelationship method

Author: jamesgpearce

src/relationships.d.ts

@@ -11,7 +11,7 @@
  * @module relationships
  */
 
-import {GetCell, Store} from './store.d';
+import {GetCell, RowCallback, Store} from './store.d';
 import {Id, IdOrNull, Ids} from './common.d';
 
 /**
@@ -39,6 +39,25 @@ export type Relationship = {
   linkedRowIds: {[firstRowId: Id]: Ids};
 };
 
+/**
+ * The RelationshipCallback type describes a function that takes an
+ * Relationship's Id and a callback to loop over each local Row within it.
+ *
+ * A RelationshipCallback is provided when using the forEachRelationship method,
+ * so that you can do something based on every Relationship in the Relationships
+ * object. See that method for specific examples.
+ *
+ * @param relationshipId The Id of the Relationship that the callback can
+ * operate on.
+ * @param forEachRow A function that will let you iterate over the local Row
+ * objects in this Relationship.
+ * @category Callback
+ */
+export type RelationshipCallback = (
+  relationshipId: Id,
+  forEachRow: (rowCallback: RowCallback) => void,
+) => void;
+
 /**
  * The RemoteRowIdListener type describes a function that is used to listen to
  * changes to the remote Row Id end of a Relationship.
@@ -405,6 +424,49 @@ export interface Relationships {
    */
   getRelationshipIds(): Ids;
 
+  /**
+   * The forEachRelationship method takes a function that it will then call for
+   * each Relationship in a specified Relationships object.
+   *
+   * This method is useful for iterating over the structure of the Relationships
+   * object in a functional style. The `relationshipCallback` parameter is a
+   * RelationshipCallback function that will be called with the Id of each
+   * Relationship, and with a function that can then be used to iterate over
+   * each local Row involved in the Relationship.
+   *
+   * @param relationshipCallback The function that should be called for every
+   * Relationship.
+   * @example
+   * This example iterates over each Relationship in a Relationships object, and
+   * lists each Row Id within them.
+   *
+   * ```js
+   * const store = createStore().setTable('pets', {
+   *   fido: {species: 'dog', next: 'felix'},
+   *   felix: {species: 'cat', next: 'cujo'},
+   *   cujo: {species: 'dog'},
+   * });
+   * const relationships = createRelationships(store)
+   *   .setRelationshipDefinition('petSpecies', 'pets', 'species', 'species')
+   *   .setRelationshipDefinition('petSequence', 'pets', 'pets', 'next');
+   *
+   * relationships.forEachRelationship((relationshipId, forEachRow) => {
+   *   console.log(relationshipId);
+   *   forEachRow((rowId) => console.log(`- ${rowId}`));
+   * });
+   * // -> 'petSpecies'
+   * // -> '- fido'
+   * // -> '- felix'
+   * // -> '- cujo'
+   * // -> 'petSequence'
+   * // -> '- fido'
+   * // -> '- felix'
+   * // -> '- cujo'
+   * ```
+   * @category Iterator
+   */
+  forEachRelationship(relationshipCallback: RelationshipCallback): void;
+
   /**
    * The hasRelationship method returns a boolean indicating whether a given
    * Relationship exists in the Relationships object.

src/relationships.ts

@@ -6,6 +6,7 @@ import {IdSet, IdSet3, setAdd, setNew} from './common/set';
 import {
   LinkedRowIdsListener,
   LocalRowIdsListener,
+  RelationshipCallback,
   Relationships,
   RelationshipsListenerStats,
   RemoteRowIdListener,
@@ -39,7 +40,7 @@ export const createRelationships: typeof createRelationshipsDecl =
     const [
       getStore,
       getRelationshipIds,
-      _forEachRelationship,
+      forEachRelationshipImpl,
       hasRelationship,
       getLocalTableId,
       getRelationship,
@@ -173,6 +174,13 @@ export const createRelationships: typeof createRelationshipsDecl =
       return relationships;
     };
 
+    const forEachRelationship = (relationshipCallback: RelationshipCallback) =>
+      forEachRelationshipImpl((relationshipId) =>
+        relationshipCallback(relationshipId, (rowCallback) =>
+          store.forEachRow(getLocalTableId(relationshipId), rowCallback),
+        ),
+      );
+
     const delRelationshipDefinition = (relationshipId: Id): Relationships => {
       mapSet(remoteTableIds, relationshipId);
       delDefinition(relationshipId);
@@ -250,6 +258,7 @@ export const createRelationships: typeof createRelationshipsDecl =
 
       getStore,
       getRelationshipIds,
+      forEachRelationship,
       hasRelationship,
       getLocalTableId,
       getRemoteTableId,

test/unit/common.ts

@@ -313,7 +313,7 @@ export const getRelationshipsObject = (
 ): IdMap<[IdMap<Id>, IdMap<Ids>]> => {
   const store = relationships.getStore();
   const relationshipsObject: IdMap<[IdMap<Id>, IdMap<Ids>]> = {};
-  relationships.getRelationshipIds().forEach((relationshipId) => {
+  relationships.forEachRelationship((relationshipId) => {
     relationshipsObject[relationshipId] = [{}, {}];
     store
       .getRowIds(relationships.getLocalTableId(relationshipId))

test/unit/relationships.test.ts

@@ -748,6 +748,27 @@ describe('Miscellaneous', () => {
     expectNoChanges(listener);
   });
 
+  test('forEachRelationship', () => {
+    relationships
+      .setRelationshipDefinition('r1', 't1', 'T1', 'c1')
+      .setRelationshipDefinition('r2', 't1', 'T1', 'c2');
+    setCells();
+    const eachRelationship: any = {};
+    relationships.forEachRelationship((relationshipsId, forEachRow) => {
+      const eachRow: any = {};
+      forEachRow((rowId, forEachCell) => {
+        const eachCell: any = {};
+        forEachCell((cellId, cell) => (eachCell[cellId] = cell));
+        eachRow[rowId] = eachCell;
+      });
+      eachRelationship[relationshipsId] = eachRow;
+    });
+    expect(eachRelationship).toEqual({
+      r1: {r1: {c1: 'R3', c2: 'R1'}, r2: {c1: 'R2', c2: 'R2'}},
+      r2: {r1: {c1: 'R3', c2: 'R1'}, r2: {c1: 'R2', c2: 'R2'}},
+    });
+  });
+
   test('are things present', () => {
     expect(relationships.hasRelationship('r1')).toEqual(false);
     relationships.setRelationshipDefinition('r1', 't1', 'T1', 'c1');