Add RowArrayAdapter

src/c2mChart.ts

@@ -48,6 +48,16 @@ import { launchOptionDialog } from "./optionDialog";
 import { launchInfoDialog } from "./infoDialog";
 import { AudioNotificationType } from "./audio/AudioEngine";
 import { DEFAULT_LANGUAGE, translate, AVAILABLE_LANGUAGES } from "./translator";
+import type { RowArrayAdapter } from "./rowArrayAdapter";
+
+/**
+ * ValidUserInputRows are the types the user can submit as data rows.
+ * Note that number will be converted to SimpleDataPoint[],
+ * so the effective types we accept is more restrictive.
+ */
+type ValidUserInputRows =
+    | RowArrayAdapter<SupportedDataPointType>
+    | (number | SupportedDataPointType)[];
 
 /**
  * Metadata about previous levels. Used to quickly return to parents.
@@ -1385,14 +1395,14 @@ export class c2m {
                 (value, index) => index
             );
             this._data = Object.values(userData).map((row) =>
-                convertDataRow(row)
+                convertDataRow(row as ValidUserInputRows)
             );
             return;
         }
 
         this._groups = [""];
         this._visible_group_indices = [0];
-        this._data = [convertDataRow(userData)];
+        this._data = [convertDataRow(userData as ValidUserInputRows)];
     }
 
     /**

src/rowArrayAdapter.ts

@@ -0,0 +1,230 @@
+// The point of rowArrayAdapter is that we don't have to copy data into c2m if a library
+// we're integrating with already stores it differently.
+// TODO: supporting sort/continuous might be a little verbose
+// author: Andrew Pikul ([email protected])
+
+import type { SupportedDataPointType } from "./dataPoint";
+import { isHighLowDataPoint, isOHLCDataPoint } from "./dataPoint";
+
+/**
+ * An interface that imitates an array to give c2m read-access to chart data stored elsewhere.
+ */
+export interface RowArrayAdapter<T extends SupportedDataPointType> {
+    length: number;
+    min: (prop: string) => number;
+    minWithIndex: (prop: string) => [number, number];
+    max: (prop: string) => number;
+    maxWithIndex: (prop: string) => [number, number];
+    at: (index: number) => T;
+    findIndex(test: (T) => boolean): number;
+    forEach(
+        callbackFn: (value: T, index: number, array: ArrayAsAdapter<T>) => void,
+        thisArg?: unknown
+    ): void;
+}
+
+/**
+ * Check if an object implements the RowArrayAdapter interface. Used where we use Array.isArray().
+ * @param obj - the object to check
+ * @returns true if the object implements the interface
+ */
+export function isRowArrayAdapter(
+    obj: unknown
+): obj is RowArrayAdapter<SupportedDataPointType> {
+    return (
+        obj &&
+        typeof obj === "object" &&
+        "length" in obj && // TODO: Could, if they give us "length()" instead of "length", we fix it for them?
+        "min" in obj &&
+        "max" in obj &&
+        "at" in obj
+    );
+}
+
+/**
+ * Create a RowArrayAdapter from an actual array.
+ */
+export class ArrayAsAdapter<T extends number | SupportedDataPointType> {
+    _array: T[];
+
+    /**
+     * Construct adapter from supplied array
+     * @param array - the underlying array from the adapter
+     */
+    constructor(array: (T | SupportedDataPointType)[]) {
+        // NOTE: If you give us a SupportedDataPointType, we will attempt to cast it for you to type T
+        if (!array) {
+            this._array = [] as T[];
+            return; // (Should throw error? don't think c2m allows empty data)
+        }
+        this._array = array as T[]; // Don't inherit array, we want to fail Array.isArray()
+    }
+
+    /**
+     * Shims the Array.length property
+     * @returns the length of the array
+     */
+    get length(): number {
+        return this._array.length;
+    }
+
+    /**
+     * Implements a min() function, in this case a shim over Math.min()
+     * @param prop - a string indicating the property that is assessed for min
+     * @returns the minimum value of the array
+     */
+    min(prop: string): number {
+        return this.minWithIndex(prop)[1];
+    }
+
+    /**
+     * Implements a function like min() but returns an array of [index, value]
+     * @param prop - a string indicating the property that is assessed for min
+     * @returns [index, value] corresponding to the minimum of the row
+     */
+    minWithIndex(prop: string): [number, number] {
+        if (!this._array) return [-1, NaN];
+        return this._array.reduce(
+            (
+                localMinimum: [number, number],
+                point: T,
+                currentIndex: number
+            ): [number, number] => {
+                let val: number = NaN;
+                if (typeof point === "number") {
+                    if (prop) return [-1, NaN];
+                    val = point;
+                    // eslint and tsc disagree about whether or not the above condition
+                    // is sufficient to guarantee type exclusion, tsc says no. the argument
+                    // gets rather abstract wrt `extends`, but this is just a test implementation
+                    // and real implementations should not support numbers anyway
+                    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+                } else if (prop in (point as SupportedDataPointType)) {
+                    // online linter wants me to specify [index: string]:number to use `in`
+                    val = point[prop] as number;
+                } else if (isOHLCDataPoint(point) && prop === "y") {
+                    val = Math.min(
+                        point.high,
+                        point.low,
+                        point.open,
+                        point.close
+                    );
+                } else if (isHighLowDataPoint(point) && prop === "y") {
+                    val = Math.min(point.high, point.low);
+                } else return localMinimum;
+                if (isNaN(val) || val === null) {
+                    return localMinimum;
+                }
+                if (isNaN(localMinimum[1])) {
+                    return [currentIndex, val];
+                }
+                return val < localMinimum[1]
+                    ? [currentIndex, val]
+                    : localMinimum;
+            },
+            [-1, NaN] // Initial value of reduce()
+        );
+    }
+
+    /**
+     * Implements a max() function, in this case a shim over Math.max()
+     * @param prop - a string indicating the property that is assessed for min
+     * @returns the maximum value of the array
+     */
+    max(prop: string): number {
+        return this.maxWithIndex(prop)[1];
+    }
+
+    /**
+     * Implements a function like max(), but returns an array of [index, value]
+     * @param prop - a string indicating the property that is assessed for min
+     * @returns [index, value] coresponding to the maximum of the row
+     */
+    maxWithIndex(prop: string): [number, number] {
+        if (!this._array) return [-1, NaN];
+        return this._array.reduce(
+            (
+                localMaximum: [number, number],
+                point: T,
+                currentIndex: number
+            ): [number, number] => {
+                let val: number = NaN;
+                if (typeof point === "number") {
+                    if (prop) return [-1, NaN];
+                    val = point;
+                    // eslint and tsc disagree about whether or not the above condition
+                    // is sufficient to guarantee type exclusion, tsc says no. the argument
+                    // gets rather abstract wrt `extends`, but this is just a test implementation
+                    // and real implementations should not support numbers anyway
+                    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+                } else if (prop in (point as SupportedDataPointType)) {
+                    // online linter wants me to specify [index: string]:number to use `in`
+                    val = point[prop] as number;
+                } else if (isOHLCDataPoint(point) && prop === "y") {
+                    val = Math.max(
+                        point.high,
+                        point.low,
+                        point.open,
+                        point.close
+                    );
+                } else if (isHighLowDataPoint(point) && prop === "y") {
+                    val = Math.max(point.high, point.low);
+                } else return localMaximum;
+                if (isNaN(val) || val === null) {
+                    return localMaximum;
+                }
+                if (isNaN(localMaximum[1])) {
+                    return [currentIndex, val];
+                }
+                return val > localMaximum[1]
+                    ? [currentIndex, val]
+                    : localMaximum;
+            },
+            [-1, NaN] // Initial value of reduce()
+        );
+    }
+
+    /**
+     * Shims the Array.at() function
+     * @param index - the index of the value you'd like to access
+     * @returns the value at the supplied index
+     */
+    at(index: number): T {
+        return this._array.at(index);
+    }
+
+    /**
+     * Shims the Array.findIndex() function, finds index of first element which satisfies the test function
+     * @param test - then function by which we test
+     * @returns index of first element
+     */
+    findIndex(test: (T) => boolean): number {
+        return this._array.findIndex(test);
+    }
+
+    /**
+     * forEach imitates an arrays forEach():
+     * @param callbackFn - a function to execute for each element in the "array".
+     * It accepts three arguments:
+     * value: T
+     * index: number
+     * array: the current ArrayAsAdapter<T>
+     *
+     * and returns nothing.
+     * @param thisArg - an optional argument to set as "this" in your callbackFn.
+     * As in Array.prototype.forEach(), if the callbackFn is defined by arrow syntax,
+     * the arrow syntax will lexically bind its own this and ignore thisArg.
+     */
+    forEach(
+        callbackFn: (value: T, index: number, array: ArrayAsAdapter<T>) => void,
+        thisArg?: unknown
+    ): void {
+        this._array.forEach((innerValue: T, innerIndex: number) => {
+            // typescript doesn't like us binding thisArg which is `unknown` type
+            // but we're shimming a javascript function and the user has the right
+            // to assign legitimately any value they'd like as `this`
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+            callbackFn.bind(thisArg)(innerValue, innerIndex, this);
+        }); // purposely use => because we need our lexically-scoped this
+    }
+}

src/types.ts

@@ -2,6 +2,7 @@
 import type { AudioEngine } from "./audio/";
 import type { c2m } from "./c2mChart";
 import type { SupportedDataPointType } from "./dataPoint";
+import type { RowArrayAdapter } from "./rowArrayAdapter";
 
 /**
  * Details for a given hotkey
@@ -71,7 +72,10 @@ export type SonifyTypes = {
      * The data that should be presented in this chart.
      * This key is required for all charts.
      */
-    data: dataSet | SupportedInputType[];
+    data:
+        | dataSet
+        | SupportedInputType[]
+        | RowArrayAdapter<SupportedDataPointType>;
     /**
      * The HTML element in the DOM that represents this chart.
      * This will be used to handle keyboard events to enable the user to interact with the chart.
@@ -111,7 +115,10 @@ export type SonifyTypes = {
  * A dictionary of data, where the key is the group name, and the value is the array of data points
  */
 export type dataSet = {
-    [groupName: string]: SupportedInputType[] | null;
+    [groupName: string]:
+        | SupportedInputType[]
+        | RowArrayAdapter<SupportedDataPointType>
+        | null;
 };
 
 /**