[metrics] Add forEachMetric method

Author: jamesgpearce

src/common/definable.ts

@@ -29,6 +29,7 @@ export const getDefinableFunctions = <Thing, RowValue>(
 ): [
   () => Store,
   () => Ids,
+  (cb: (id: Id, value: Thing) => void) => void,
   (id: Id) => boolean,
   (id: Id) => Id,
   (id: Id) => Thing | undefined,
@@ -54,6 +55,9 @@ export const getDefinableFunctions = <Thing, RowValue>(
 
   const getThingIds = (): Ids => mapKeys(tableIds);
 
+  const forEachThing = (cb: (id: Id, value: Thing) => void): void =>
+    mapForEach(things, cb);
+
   const hasThing = (id: Id): boolean => collHas(things, id);
 
   const getTableId = (id: Id): Id => mapGet(tableIds, id) as Id;
@@ -169,6 +173,7 @@ export const getDefinableFunctions = <Thing, RowValue>(
   return [
     getStore,
     getThingIds,
+    forEachThing,
     hasThing,
     getTableId,
     getThing,

src/indexes.ts

@@ -37,6 +37,7 @@ export const createIndexes: typeof createIndexesDecl = getCreateFunction(
     const [
       getStore,
       getIndexIds,
+      _forEachIndex,
       hasIndex,
       getTableId,
       getIndex,

src/metrics.d.ts

@@ -22,6 +22,20 @@ import {Id, IdOrNull, Ids} from './common.d';
  */
 export type Metric = number;
 
+/**
+ * The MetricCallback type describes a function that takes a Metric's Id and a
+ * callback to loop over each Row within it.
+ *
+ * A MetricCallback is provided when using the forEachMetric method, so that you
+ * can do something based on every Metric in the Metrics object. See that method
+ * for specific examples.
+ *
+ * @param metricId The Id of the Metric that the callback can operate on.
+ * @param metric The value of the Metric.
+ * @category Callback
+ */
+export type MetricCallback = (metricId: Id, metric?: Metric) => void;
+
 /**
  * The Aggregate type describes a custom function that takes an array or numbers
  * and returns an aggregate that is used as a Metric.
@@ -478,6 +492,38 @@ export interface Metrics {
    */
   getMetricIds(): Ids;
 
+  /**
+   * The forEachMetric method takes a function that it will then call for each
+   * Metric in the Metrics object.
+   *
+   * This method is useful for iterating over all the Metrics in a functional
+   * style. The `metricCallback` parameter is a MetricCallback function that
+   * will called with the Id of each Metric and its value.
+   *
+   * @param metricCallback The function that should be called for every Metric.
+   * @example
+   * This example iterates over each Metric in a Metrics object.
+   *
+   * ```js
+   * const store = createStore().setTable('species', {
+   *   dog: {price: 5},
+   *   cat: {price: 4},
+   *   worm: {price: 1},
+   * });
+   * const metrics = createMetrics(store)
+   *   .setMetricDefinition('highestPrice', 'species', 'max', 'price')
+   *   .setMetricDefinition('lowestPrice', 'species', 'min', 'price');
+   *
+   * metrics.forEachMetric((metricId, metric) => {
+   *   console.log([metricId, metric]);
+   * });
+   * // -> ['highestPrice', 5]
+   * // -> ['lowestPrice', 1]
+   * ```
+   * @category Iterator
+   */
+  forEachMetric(metricCallback: MetricCallback): void;
+
   /**
    * The hasMetric method returns a boolean indicating whether a given Metric
    * exists in the Metrics object, and has a value.

src/metrics.ts

@@ -98,6 +98,7 @@ export const createMetrics: typeof createMetricsDecl = getCreateFunction(
     const [
       getStore,
       getMetricIds,
+      forEachMetric,
       hasMetric,
       getTableId,
       getMetric,
@@ -222,6 +223,7 @@ export const createMetrics: typeof createMetricsDecl = getCreateFunction(
 
       getStore,
       getMetricIds,
+      forEachMetric,
       hasMetric,
       getTableId,
       getMetric,

src/relationships.ts

@@ -39,6 +39,7 @@ export const createRelationships: typeof createRelationshipsDecl =
     const [
       getStore,
       getRelationshipIds,
+      _forEachRelationship,
       hasRelationship,
       getLocalTableId,
       getRelationship,

test/unit/common.ts

@@ -285,9 +285,9 @@ export const getMetricsObject = (
   metrics: Metrics,
 ): IdMap<number | undefined> => {
   const metricsObject: IdMap<number | undefined> = {};
-  metrics.getMetricIds().forEach((metricId) => {
-    metricsObject[metricId] = metrics.getMetric(metricId);
-  });
+  metrics.forEachMetric(
+    (metricId) => (metricsObject[metricId] = metrics.getMetric(metricId)),
+  );
   return metricsObject;
 };
 

test/unit/metrics.test.ts

@@ -612,6 +612,17 @@ describe('Miscellaneous', () => {
     expectNoChanges(listener);
   });
 
+  test('forEachMetric', () => {
+    metrics.setMetricDefinition('m1', 't1', 'max', 'c1');
+    metrics.setMetricDefinition('m2', 't1', 'min', 'c1');
+    setCells();
+    const eachMetric: any = {};
+    metrics.forEachMetric(
+      (metricId, metric) => (eachMetric[metricId] = metric),
+    );
+    expect(eachMetric).toEqual({m1: 5, m2: 1});
+  });
+
   test('are things present', () => {
     expect(metrics.hasMetric('m1')).toEqual(false);
     metrics.setMetricDefinition('m1', 't1');