@genome-spy/core 0.43.3 → 0.45.0

package/dist/src/view/axisView.js

@@ -459,7 +459,7 @@ export function createGenomeAxis(axisProps, type) {
      * @return {import("../spec/view.js").UnitSpec}
      */
     const createChromosomeLabels = () => {
-        /** @type {Partial<import("../spec/mark.js").MarkConfig>} */
+        /** @type {Partial<import("../spec/mark.js").MarkProps>} */
         let chromLabelMarkProps;
         switch (ap.orient) {
             case "top":
@@ -594,7 +594,7 @@ export function createGenomeAxis(axisProps, type) {
         if (axisProps.chromLabels) {
             chromLayerSpec.layer.push(createChromosomeLabels());
 
-            /** @type {import("../spec/mark.js").MarkConfig} */
+            /** @type {import("../spec/mark.js").MarkProps} */
             let labelMarkSpec;
 
             // TODO: Simplify the following mess
@@ -608,7 +608,7 @@ export function createGenomeAxis(axisProps, type) {
                                 /** @type {import("../spec/view.js").UnitSpec} */ view
                             ) => {
                                 labelMarkSpec =
-                                    /** @type {import("../spec/mark.js").MarkConfig} */ (
+                                    /** @type {import("../spec/mark.js").MarkProps} */ (
                                         view.mark
                                     );
                             }

package/dist/src/view/paramMediator.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @param {any} x
+ * @returns {x is import("../spec/parameter.js").ExprRef}
+ */
+export function isExprRef(x: any): x is import("../spec/parameter.js").ExprRef;
+/**
+ * Removes ExprRef from the type and checks that the value is not an ExprRef.
+ * This is designed to be used with `activateExprRefProps`.
+ *
+ * @param {T | import("../spec/parameter.js").ExprRef} x
+ * @template T
+ * @returns {T}
+ */
+export function withoutExprRef<T>(x: T | import("../spec/parameter.js").ExprRef): T;
+/**
+ * Takes a record of properties that may have ExprRefs as values. Converts the
+ * ExprRefs to getters and setups a listener that is called when any of the
+ * expressions (upstream parameters) change.
+ *
+ * @param {ParamMediator} paramMediator
+ * @param {T} props The properties object
+ * @param {(props: (keyof T)[]) => void} [listener] Listener to be called when any of the expressions change
+ * @returns T
+ * @template {Record<string, any | import("../spec/parameter.js").ExprRef>} T
+ */
+export function activateExprRefProps<T extends Record<string, any>>(paramMediator: ParamMediator, props: T, listener?: (props: (keyof T)[]) => void): T;
+/**
+ * A class that manages parameters and expressions.
+ * Supports nesting and scoped parameters.
+ *
+ * @typedef {import("../utils/expression.js").ExpressionFunction & { addListener: (listener: () => void) => void, invalidate: () => void, identifier: () => string}} ExprRefFunction
+ */
+export default class ParamMediator {
+    /**
+     * @param {() => ParamMediator} [parentFinder]
+     *      An optional function that returns the parent mediator.
+     *      N.B. The function must always return the same mediator for the same parent,
+     *      i.e., the changing the structure of the hierarchy is NOT supported.
+     */
+    constructor(parentFinder?: () => ParamMediator);
+    /**
+     * @type {Map<string, Set<() => void>>}
+     * @protected
+     */
+    protected paramListeners: Map<string, Set<() => void>>;
+    /**
+     * @param {VariableParameter} param
+     * @returns {ParameterSetter}
+     */
+    registerParam(param: import("../spec/parameter.js").VariableParameter): (value: any) => void;
+    /**
+     *
+     * @param {string} paramName
+     * @param {T} initialValue
+     * @returns {(value: T) => void}
+     * @template T
+     */
+    allocateSetter<T>(paramName: string, initialValue: T): (value: T) => void;
+    /**
+     * Gets an existing setter for a parameter. Throws if the setter is not found.
+     * @param {string} paramName
+     */
+    getSetter(paramName: string): (value: any) => void;
+    /**
+     * Get the value of a parameter from this mediator.
+     * @param {string} paramName
+     */
+    getValue(paramName: string): any;
+    /**
+     * Get the value of a parameter from this mediator or the ancestors.
+     * @param {string} paramName
+     */
+    findValue(paramName: string): any;
+    /**
+     * Returns configs for all parameters that have been registered using `registerParam`.
+     */
+    get paramConfigs(): ReadonlyMap<string, import("../spec/parameter.js").VariableParameter>;
+    /**
+     *
+     * @param {string} paramName
+     * @returns {ParamMediator}
+     * @protected
+     */
+    protected findMediatorForParam(paramName: string): ParamMediator;
+    /**
+     * Parse expr and return a function that returns the value of the parameter.
+     *
+     * @param {string} expr
+     */
+    createExpression(expr: string): ExprRefFunction;
+    /**
+     * A convenience method for evaluating an expression.
+     *
+     * @param {string} expr
+     */
+    evaluateAndGet(expr: string): any;
+    #private;
+}
+/**
+ * A class that manages parameters and expressions.
+ * Supports nesting and scoped parameters.
+ */
+export type ExprRefFunction = ((datum?: object) => any) & import("../utils/expression.js").ExpressionProps & {
+    addListener: (listener: () => void) => void;
+    invalidate: () => void;
+    identifier: () => string;
+};
+//# sourceMappingURL=paramMediator.d.ts.map

package/dist/src/view/paramMediator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paramMediator.d.ts","sourceRoot":"","sources":["../../../src/view/paramMediator.js"],"names":[],"mappings":"AAsQA;;;GAGG;AACH,6BAHW,GAAG,+CAKb;AAED;;;;;;;GAOG;AACH,oFASC;AAED;;;;;;;;;;GAUG;AACH,mFANW,aAAa,+CAEW,IAAI,KAwCtC;AA7UD;;;;;GAKG;AACH;IA2BI;;;;;OAKG;IACH,2BALW,MAAM,aAAa,EAU7B;IA7BD;;;OAGG;IACH,0BAHU,IAAI,MAAM,EAAE,IAAI,MAAM,IAAI,CAAC,CAAC,CAGvB;IA2Bf;;;OAGG;IACH,gFAzCqB,GAAG,KAAK,IAAI,CAkEhC;IAED;;;;;;OAMG;IACH,6BALW,MAAM,kCAEU,IAAI,CA8B9B;IAED;;;OAGG;IACH,qBAFW,MAAM,WA9Fc,GAAG,KAAK,IAAI,CAsG1C;IAED;;;OAGG;IACH,oBAFW,MAAM,OAIhB;IAED;;;OAGG;IACH,qBAFW,MAAM,OAKhB;IAED;;OAEG;IACH,0FAIC;IAED;;;;;OAKG;IACH,0CAJW,MAAM,GACJ,aAAa,CASzB;IAID;;;;OAIG;IACH,uBAFW,MAAM,mBA4EhB;IAED;;;;OAIG;IACH,qBAFW,MAAM,OAKhB;;CACJ;;;;;;4BA7P4F,MAAM,IAAI,KAAK,IAAI;gBAAc,MAAM,IAAI;gBAAc,MAAM,MAAM"}

package/dist/src/view/paramMediator.js

@@ -0,0 +1,337 @@
+import { isString } from "vega-util";
+import createFunction from "../utils/expression.js";
+
+/**
+ * A class that manages parameters and expressions.
+ * Supports nesting and scoped parameters.
+ *
+ * @typedef {import("../utils/expression.js").ExpressionFunction & { addListener: (listener: () => void) => void, invalidate: () => void, identifier: () => string}} ExprRefFunction
+ */
+export default class ParamMediator {
+    /**
+     * @typedef {import("../spec/parameter.js").VariableParameter} VariableParameter
+     * @typedef {(value: any) => void} ParameterSetter
+     */
+
+    /** @type {Map<string, any>} */
+    #paramValues;
+
+    /**
+     * @type {Map<string, Set<() => void>>}
+     * @protected
+     */
+    paramListeners;
+
+    /** @type {Map<string, (value: any) => void>} */
+    #allocatedSetters = new Map();
+
+    /** @type {Map<string, ExprRefFunction>} */
+    #expressions = new Map();
+
+    /** @type {Map<string, VariableParameter>} */
+    #paramConfigs = new Map();
+
+    /** @type {() => ParamMediator} */
+    #parentFinder;
+
+    /**
+     * @param {() => ParamMediator} [parentFinder]
+     *      An optional function that returns the parent mediator.
+     *      N.B. The function must always return the same mediator for the same parent,
+     *      i.e., the changing the structure of the hierarchy is NOT supported.
+     */
+    constructor(parentFinder) {
+        this.#parentFinder = parentFinder ?? (() => undefined);
+
+        this.#paramValues = new Map();
+        this.paramListeners = new Map();
+    }
+
+    /**
+     * @param {VariableParameter} param
+     * @returns {ParameterSetter}
+     */
+    registerParam(param) {
+        if ("value" in param && "expr" in param) {
+            throw new Error(
+                "Parameter must not have both value and expr: " + param.name
+            );
+        }
+
+        /** @type {ParameterSetter} */
+        let setter;
+
+        if ("value" in param) {
+            setter = this.allocateSetter(param.name, param.value);
+        } else if ("expr" in param) {
+            const expr = this.createExpression(param.expr);
+            // TODO: getSetter(param) should return a setter that throws if
+            // modifying the value is attempted.
+            const realSetter = this.allocateSetter(param.name, expr(null));
+            expr.addListener(() => realSetter(expr(null)));
+            // NOP
+            setter = (_) => undefined;
+        }
+
+        this.#paramConfigs.set(param.name, param);
+
+        return setter;
+    }
+
+    /**
+     *
+     * @param {string} paramName
+     * @param {T} initialValue
+     * @returns {(value: T) => void}
+     * @template T
+     */
+    allocateSetter(paramName, initialValue) {
+        if (this.#allocatedSetters.has(paramName)) {
+            throw new Error(
+                "Setter already allocated for parameter: " + paramName
+            );
+        }
+
+        /** @type {(value: any) => void} */
+        const setter = (value) => {
+            const previous = this.#paramValues.get(paramName);
+            if (value !== previous) {
+                this.#paramValues.set(paramName, value);
+
+                const listeners = this.paramListeners.get(paramName);
+                if (listeners) {
+                    for (const listener of listeners) {
+                        listener();
+                    }
+                }
+            }
+        };
+
+        setter(initialValue);
+
+        this.#allocatedSetters.set(paramName, setter);
+
+        return setter;
+    }
+
+    /**
+     * Gets an existing setter for a parameter. Throws if the setter is not found.
+     * @param {string} paramName
+     */
+    getSetter(paramName) {
+        const setter = this.#allocatedSetters.get(paramName);
+        if (!setter) {
+            throw new Error("Setter not found for parameter: " + paramName);
+        }
+        return setter;
+    }
+
+    /**
+     * Get the value of a parameter from this mediator.
+     * @param {string} paramName
+     */
+    getValue(paramName) {
+        return this.#paramValues.get(paramName);
+    }
+
+    /**
+     * Get the value of a parameter from this mediator or the ancestors.
+     * @param {string} paramName
+     */
+    findValue(paramName) {
+        const mediator = this.findMediatorForParam(paramName);
+        return mediator?.getValue(paramName);
+    }
+
+    /**
+     * Returns configs for all parameters that have been registered using `registerParam`.
+     */
+    get paramConfigs() {
+        return /** @type {ReadonlyMap<string, VariableParameter>} */ (
+            this.#paramConfigs
+        );
+    }
+
+    /**
+     *
+     * @param {string} paramName
+     * @returns {ParamMediator}
+     * @protected
+     */
+    findMediatorForParam(paramName) {
+        if (this.#paramValues.has(paramName)) {
+            return this;
+        } else {
+            return this.#parentFinder()?.findMediatorForParam(paramName);
+        }
+    }
+
+    // TODO: deallocateSetter
+
+    /**
+     * Parse expr and return a function that returns the value of the parameter.
+     *
+     * @param {string} expr
+     */
+    createExpression(expr) {
+        if (this.#expressions.has(expr)) {
+            return this.#expressions.get(expr);
+        }
+
+        const globalObject = {};
+
+        /** @type {ExprRefFunction} */
+        const fn = /** @type {any} */ (createFunction(expr, globalObject));
+
+        /** @type {Map<string, ParamMediator>} */
+        const mediatorsForParams = new Map();
+
+        for (const param of fn.globals) {
+            const mediator = this.findMediatorForParam(param);
+            if (!mediator) {
+                throw new Error(
+                    `Unknown variable "${param}" in expression: ${expr}`
+                );
+            }
+
+            mediatorsForParams.set(param, mediator);
+
+            Object.defineProperty(globalObject, param, {
+                enumerable: true,
+                get() {
+                    return mediator.getValue(param);
+                },
+            });
+        }
+        // TODO: There should be a way to "materialize" the global object when
+        // it is used in expressions in transformation batches, i.e., when the same
+        // expression is applied to multiple data objects. In that case, the global
+        // object remains constant and the Map lookups cause unnecessary overhead.
+
+        // Keep track of them so that they can be detached later
+        const myListeners = new Set();
+
+        /**
+         *
+         * @param {() => void} listener
+         */
+        fn.addListener = (listener) => {
+            for (const [param, mediator] of mediatorsForParams) {
+                const listeners =
+                    mediator.paramListeners.get(param) ?? new Set();
+                mediator.paramListeners.set(param, listeners);
+
+                listeners.add(listener);
+                myListeners.add(listener);
+            }
+        };
+
+        /**
+         * Detach listeners. This must be called if the expression is no longer used.
+         * TODO: What if the expression is used in multiple places?
+         */
+        fn.invalidate = () => {
+            for (const [param, mediator] of mediatorsForParams) {
+                for (const listener of myListeners) {
+                    mediator.paramListeners.get(param)?.delete(listener);
+                }
+            }
+        };
+
+        // TODO: This should contain unique identifier for each parameter.
+        // As the same parameter name may be used in different branches of the
+        // hierarchy, they should be distinguished by a unique identifier, e.g.,
+        // a serial number of something similar.
+        fn.identifier = () => fn.code;
+
+        this.#expressions.set(expr, fn);
+
+        return fn;
+    }
+
+    /**
+     * A convenience method for evaluating an expression.
+     *
+     * @param {string} expr
+     */
+    evaluateAndGet(expr) {
+        const fn = this.createExpression(expr);
+        return fn();
+    }
+}
+
+/**
+ * @param {any} x
+ * @returns {x is import("../spec/parameter.js").ExprRef}
+ */
+export function isExprRef(x) {
+    return typeof x == "object" && x != null && "expr" in x && isString(x.expr);
+}
+
+/**
+ * Removes ExprRef from the type and checks that the value is not an ExprRef.
+ * This is designed to be used with `activateExprRefProps`.
+ *
+ * @param {T | import("../spec/parameter.js").ExprRef} x
+ * @template T
+ * @returns {T}
+ */
+export function withoutExprRef(x) {
+    if (isExprRef(x)) {
+        throw new Error(
+            `ExprRef ${JSON.stringify(
+                x
+            )} not allowed here. Expected a scalar value.`
+        );
+    }
+    return /** @type {T} */ (x);
+}
+
+/**
+ * Takes a record of properties that may have ExprRefs as values. Converts the
+ * ExprRefs to getters and setups a listener that is called when any of the
+ * expressions (upstream parameters) change.
+ *
+ * @param {ParamMediator} paramMediator
+ * @param {T} props The properties object
+ * @param {(props: (keyof T)[]) => void} [listener] Listener to be called when any of the expressions change
+ * @returns T
+ * @template {Record<string, any | import("../spec/parameter.js").ExprRef>} T
+ */
+export function activateExprRefProps(paramMediator, props, listener) {
+    /** @type {Record<string, any | import("../spec/parameter.js").ExprRef>} */
+    const activatedProps = { ...props };
+
+    /** @type {(keyof T)[]} */
+    const alteredProps = [];
+
+    const batchPropertyChange = (/** @type {keyof T} */ prop) => {
+        alteredProps.push(prop);
+        if (alteredProps.length === 1) {
+            queueMicrotask(() => {
+                listener(alteredProps.slice());
+                alteredProps.length = 0;
+            });
+        }
+    };
+
+    for (const [key, value] of Object.entries(props)) {
+        if (isExprRef(value)) {
+            const fn = paramMediator.createExpression(value.expr);
+            if (listener) {
+                fn.addListener(() => batchPropertyChange(key));
+            }
+
+            Object.defineProperty(activatedProps, key, {
+                enumerable: true,
+                get() {
+                    return fn();
+                },
+            });
+        } else {
+            activatedProps[key] = value;
+        }
+    }
+
+    return /** @type {T} */ (activatedProps);
+}

package/dist/src/view/paramMediator.test.js

@@ -0,0 +1,211 @@
+import { describe, expect, test } from "vitest";
+import ParamMediator, { activateExprRefProps } from "./paramMediator.js";
+
+describe("Single-level ParamMediator", () => {
+    test("Trivial case", () => {
+        const pm = new ParamMediator();
+        pm.registerParam({ name: "foo", value: 42 });
+        expect(pm.getValue("foo")).toBe(42);
+    });
+
+    test("Setter", () => {
+        const pm = new ParamMediator();
+        const setter = pm.allocateSetter("foo", 42);
+        expect(pm.getValue("foo")).toBe(42);
+
+        setter(43);
+        expect(pm.getValue("foo")).toBe(43);
+    });
+
+    test("Expressions have access to parameters", () => {
+        const pm = new ParamMediator();
+        pm.registerParam({ name: "foo", value: 42 });
+        const expr = pm.createExpression("foo + 1");
+        expect(expr()).toBe(43);
+    });
+
+    test("Throws on an unknown parameter", () => {
+        const pm = new ParamMediator();
+        expect(() => pm.createExpression("foo")).toThrow();
+    });
+
+    test("Listener on an expression gets called (only) when a parameter changes", () => {
+        const pm = new ParamMediator();
+        const setter = pm.allocateSetter("foo", 42);
+        const expr = pm.createExpression("foo + 1");
+
+        let result;
+        let calls = 0;
+
+        expr.addListener(() => {
+            result = expr();
+            calls++;
+        });
+
+        setter(50);
+        expect(result).toBe(51);
+        expect(calls).toBe(1);
+
+        setter(60);
+        expect(result).toBe(61);
+        expect(calls).toBe(2);
+
+        setter(60);
+        expect(result).toBe(61);
+        expect(calls).toBe(2);
+    });
+
+    test("Expression invalidation", () => {
+        const pm = new ParamMediator();
+        const setter = pm.allocateSetter("foo", 42);
+        const expr = pm.createExpression("foo + 1");
+
+        let result = expr();
+        expect(result).toBe(43);
+
+        expr.addListener(() => (result = expr()));
+
+        setter(50);
+        expect(result).toBe(51);
+
+        expr.invalidate();
+        // Listeners should be invalidated now: the result must remain the same.
+        setter(60);
+        expect(result).toBe(51);
+    });
+
+    test("Expression parameter handles dependencies", () => {
+        const pm = new ParamMediator();
+        const setter = pm.registerParam({ name: "foo", value: 42 });
+        pm.registerParam({ name: "bar", expr: "foo + 1" });
+        pm.registerParam({ name: "baz", expr: "bar + 2" });
+
+        const expr = pm.createExpression("baz");
+
+        let result = expr();
+        expect(result).toBe(45);
+
+        expr.addListener(() => (result = expr()));
+
+        setter(52);
+        expect(result).toBe(55);
+    });
+
+    test("Throws if both value and expr are provided", () => {
+        const pm = new ParamMediator();
+        expect(() =>
+            pm.registerParam({ name: "foo", value: 42, expr: "bar" })
+        ).toThrow();
+    });
+});
+
+describe("Nested ParamMediators", () => {
+    test("Value in parent", () => {
+        const parent = new ParamMediator();
+        const child = new ParamMediator(() => parent);
+
+        parent.registerParam({ name: "foo", value: 42 });
+        expect(parent.findValue("foo")).toBe(42);
+        expect(child.findValue("foo")).toBe(42);
+    });
+
+    test("Value in child", () => {
+        const parent = new ParamMediator();
+        const child = new ParamMediator(() => parent);
+
+        child.registerParam({ name: "foo", value: 42 });
+        expect(parent.findValue("foo")).toBeUndefined();
+        expect(child.findValue("foo")).toBe(42);
+    });
+
+    test("Child overrides parent", () => {
+        const parent = new ParamMediator();
+        const child = new ParamMediator(() => parent);
+
+        parent.registerParam({ name: "foo", value: 1 });
+        child.registerParam({ name: "foo", value: 2 });
+
+        expect(parent.findValue("foo")).toBe(1);
+        expect(child.findValue("foo")).toBe(2);
+    });
+
+    test("Expression", () => {
+        const parent = new ParamMediator();
+        const child = new ParamMediator(() => parent);
+
+        parent.registerParam({ name: "foo", value: 1 });
+        child.registerParam({ name: "bar", value: 2 });
+
+        const expr = child.createExpression("foo + bar");
+        expect(expr()).toBe(3);
+    });
+
+    test("Listener on an expression", () => {
+        const parent = new ParamMediator();
+        const child = new ParamMediator(() => parent);
+
+        const parentSetter = parent.allocateSetter("foo", 1);
+        const childSetter = parent.allocateSetter("bar", 2);
+
+        const expr = child.createExpression("foo + bar");
+
+        let result = expr();
+        expr.addListener(() => (result = expr()));
+
+        expect(result).toBe(3);
+
+        parentSetter(10);
+        expect(result).toBe(12);
+
+        childSetter(20);
+        expect(result).toBe(30);
+    });
+});
+
+test("activateExprRefProps", async () => {
+    const pm = new ParamMediator();
+
+    const fooSetter = pm.registerParam({ name: "foo", value: 7 });
+    const barSetter = pm.registerParam({ name: "bar", value: 11 });
+
+    /** @type {Record<string, any | import("../spec/parameter.js").ExprRef} */
+    const props = {
+        a: 42,
+        b: { expr: "foo" },
+        c: { expr: "bar" },
+    };
+
+    /** @type {string[]} */
+    let altered = [];
+
+    const activatedProps = activateExprRefProps(pm, props, (props) => {
+        altered = props;
+    });
+
+    expect(activatedProps).toEqual({
+        a: 42,
+        b: 7,
+        c: 11,
+    });
+
+    fooSetter(8);
+
+    // Let the scheduled microtask call the listener
+    await Promise.resolve();
+
+    expect(altered).toEqual(["b"]);
+
+    fooSetter(1);
+    barSetter(2);
+
+    // Let the scheduled microtask call the listener
+    await Promise.resolve();
+
+    expect(altered).toEqual(["b", "c"]);
+
+    expect(activatedProps).toEqual({
+        a: 42,
+        b: 1,
+        c: 2,
+    });
+});