@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/util/simpleFeature.js

@@ -1,73 +1,225 @@
+// brand carried by jexlFeatureProxy so the real feature can be recovered from a
+// proxy whose properties all resolve to data values
+const featureTarget = Symbol('featureTarget');
 export function isFeature(thing) {
     return (typeof thing === 'object' &&
         thing !== null &&
         typeof thing.get === 'function' &&
-        typeof thing.id === 'function');
+        (typeof thing.id === 'function' || featureTarget in thing));
+}
+/**
+ * Recover the underlying feature from a jexlFeatureProxy, or return a raw
+ * feature untouched. Needed by callers that want the feature's methods
+ * (`id()`, `parent()`) rather than the data value the proxy resolves a
+ * property to.
+ */
+export function unwrapFeature(feature) {
+    return feature[featureTarget] ?? feature;
+}
+/**
+ * Wrap a feature so jexl callbacks can read attributes as plain properties
+ * (`feature.score`) instead of `get(feature,'score')`. Since jexl has no
+ * member-call syntax, attributes resolve to values: any property (including
+ * `id`, i.e. a data field such as a GFF3 `ID=`) is forwarded to
+ * `feature.get(name)` where a SimpleFeature keeps its data. Exceptions:
+ * `parent` resolves to the parent feature (re-wrapped so `feature.parent.type`
+ * works), `uniqueId` to the feature's identity (`id()`) so it reads the same
+ * whether or not the feature happens to keep a uniqueId in its data, and
+ * `get`/`toJSON` stay callable methods so the legacy
+ * `get(feature,'x')`/`getTag(feature,'x')` forms and serialization still work.
+ * The `parent`/`id` jexl functions unwrap the proxy (see jexl.ts).
+ */
+export function jexlFeatureProxy(feature) {
+    return feature[featureTarget]
+        ? feature
+        : new Proxy(feature, {
+            has(target, prop) {
+                return prop === featureTarget || Reflect.has(target, prop);
+            },
+            get(target, prop) {
+                switch (prop) {
+                    case featureTarget: {
+                        return target;
+                    }
+                    case 'get': {
+                        return target.get.bind(target);
+                    }
+                    case 'toJSON': {
+                        return target.toJSON.bind(target);
+                    }
+                    case 'uniqueId': {
+                        return target.id();
+                    }
+                    case 'parent': {
+                        const p = target.parent?.();
+                        return p ? jexlFeatureProxy(p) : undefined;
+                    }
+                    default: {
+                        return typeof prop === 'string'
+                            ? target.get(prop)
+                            : Reflect.get(target, prop);
+                    }
+                }
+            },
+        });
+}
+/**
+ * Build the variable bindings a jexl callback evaluates against, wrapping any
+ * `Feature`-valued entry in `jexlFeatureProxy` (so `x.attr` reads directly while
+ * `get(x,'attr')` still works) and passing everything else through untouched.
+ *
+ * The single context-construction path shared by config-slot evaluation
+ * (`evaluateJexl`) and the filter chain (`SerializableFilterChain`), so which
+ * variables a callback can reference — and how a feature is exposed — never
+ * depends on which call site invoked it.
+ */
+export function buildJexlContext(args) {
+    const context = {};
+    for (const key in args) {
+        const value = args[key];
+        context[key] = isFeature(value) ? jexlFeatureProxy(value) : value;
+    }
+    return context;
 }
 function isSimpleFeatureSerialized(args) {
-    return 'uniqueId' in args && typeof args.data !== 'object';
+    return 'uniqueId' in args;
 }
+// a feature is valid if it has a non-inverted interval, or is a bare reference
+// sequence alias record: aliases and no coordinates at all (e.g. what
+// FromConfigAdapter yields when used as a refNameAliases adapter). A feature
+// that carries coordinates is still validated even if it also happens to have
+// an aliases attribute
+function validateFeatureData(data, uniqueId) {
+    const { aliases, start, end } = data;
+    const aliasRecord = !!aliases && start === undefined && end === undefined;
+    if (!aliasRecord) {
+        if (typeof start !== 'number' || typeof end !== 'number') {
+            throw new Error(`invalid feature data for "${uniqueId}", start and end must be numbers. start: ${start} end: ${end}`);
+        }
+        // written as a negated >= so NaN coordinates are rejected too
+        if (!(end >= start)) {
+            throw new Error(`invalid feature data for "${uniqueId}", end less than start. end: ${end} start: ${start}`);
+        }
+    }
+}
+/**
+ * Simple implementation of a feature object.
+ */
 export default class SimpleFeature {
     data;
     subfeatures;
     parentHandle;
     uniqueId;
+    /**
+     * @param args - SimpleFeature args
+     *
+     * Note: args.data.subfeatures can be an array of these same args,
+     * which will be inflated to more instances of this class.
+     */
     constructor(args) {
-        if (isSimpleFeatureSerialized(args)) {
+        const serialized = isSimpleFeatureSerialized(args);
+        if (serialized) {
             this.data = args;
         }
         else {
             this.data = args.data;
+            // load handle from args.parent (not args.data.parent): a plain args
+            // object likely carries a raw parent id rather than a Feature reference
             this.parentHandle = args.parent;
         }
-        const id = isSimpleFeatureSerialized(args) ? args.uniqueId : args.id;
+        const id = serialized ? args.uniqueId : args.id;
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
         if (id === undefined || id === null) {
-            throw new Error('SimpleFeature requires a unique `id` or `data.uniqueId` attribute');
+            throw new Error('SimpleFeature requires an `id` or `uniqueId` attribute');
         }
         this.uniqueId = String(id);
-        if (!(this.data.aliases || this.data.end - this.data.start >= 0)) {
-            throw new Error(`invalid feature data, end less than start. end: ${this.data.end} start: ${this.data.start}`);
-        }
-        if (this.data.subfeatures) {
-            this.subfeatures = this.data.subfeatures?.map((f, i) => typeof f.get !== 'function'
-                ? new SimpleFeature({
-                    id: f.uniqueId || `${id}-${i}`,
-                    data: {
-                        strand: this.data.strand,
-                        ...f,
-                    },
+        validateFeatureData(this.data, this.uniqueId);
+        this.subfeatures = this.inflateSubfeatures();
+    }
+    // raw subfeatures arrive as either plain arg objects or already-inflated
+    // features; inflate the former into SimpleFeature instances. The result is
+    // kept in a separate field so the caller's input data is never mutated
+    // (features are effectively immutable).
+    //
+    // The raw object is handed to the child as-is rather than copied. It used to
+    // be spread — `{...f, strand: f.strand ?? this.data.strand}` — which copied
+    // every attribute of every node in the subtree in order to set one field
+    // that is usually already set. On a GENCODE-shaped 1000-gene tree (26,870
+    // nodes, 18 keys each) that spread was 2.8 ms of the 3.8 ms this whole
+    // method cost. Strand inheritance now happens where it is read, in `get`,
+    // and is baked back into `toJSON` for the deserialized copy that has no
+    // parent to inherit from.
+    inflateSubfeatures() {
+        const raw = this.data.subfeatures;
+        return Array.isArray(raw)
+            ? raw.map((f, i) => isFeature(f)
+                ? f
+                : new SimpleFeature({
+                    id: f.uniqueId ?? `${this.uniqueId}-${i}`,
+                    data: f,
                     parent: this,
-                })
-                : f);
-        }
+                }))
+            : undefined;
     }
     get(name) {
-        return name === 'subfeatures'
-            ? this.subfeatures
-            : name === 'parent'
-                ? this.parent()
-                : this.data[name];
-    }
-    set(name, val) {
-        this.data[name] = val;
+        switch (name) {
+            case 'subfeatures': {
+                return this.subfeatures;
+            }
+            case 'parent': {
+                return this.parent();
+            }
+            case 'strand': {
+                // a subfeature with no strand of its own inherits its parent's,
+                // resolved here rather than copied onto it at construction
+                return this.data.strand ?? this.parentHandle?.get('strand');
+            }
+            default: {
+                return this.data[name];
+            }
+        }
     }
+    /**
+     * Get an array listing which data keys are present in this feature.
+     */
     tags() {
-        return Object.keys(this.data);
+        const keys = Object.keys(this.data);
+        // an inherited strand is a readable field of this feature without being a
+        // key of its data, so name it here too
+        return 'strand' in this.data || this.get('strand') === undefined
+            ? keys
+            : [...keys, 'strand'];
     }
+    /**
+     * Get the unique ID of this feature.
+     */
     id() {
         return this.uniqueId;
     }
+    /**
+     * Get this feature's parent feature, or undefined if none.
+     */
     parent() {
         return this.parentHandle;
     }
+    /**
+     * Get an array of child features, or undefined if none.
+     */
     children() {
-        return this.get('subfeatures');
+        return this.subfeatures;
     }
     toJSON() {
         const d = { ...this.data, uniqueId: this.id() };
         const p = this.parent();
         if (p) {
             d.parentId = p.id();
+            // bake the inherited strand in: the serialized form is what crosses the
+            // RPC boundary, and what comes back the other side is reconstructed with
+            // no parent handle to inherit from
+            const strand = this.get('strand');
+            if (strand !== undefined) {
+                d.strand = strand;
+            }
         }
         const c = this.children();
         if (c) {

package/esm/util/springAnimate.d.ts

@@ -0,0 +1,20 @@
+export interface SpringAnimateOptions {
+    from: number;
+    to: number;
+    /** applies one frame's value */
+    write: (value: number) => void;
+    /**
+     * The live value `write` drives. Supply it when that value is shared with
+     * anything else that can move it, and the spring stops as soon as it reads
+     * back something other than what it last wrote — an interrupted animation
+     * yields instead of overwriting the interruption on its next frame. Omit it for
+     * a value only this spring touches.
+     */
+    read?: () => number;
+    onFinish?: () => void;
+    precision?: number;
+    tension?: number;
+    friction?: number;
+    clamp?: boolean;
+}
+export declare function springAnimate({ from, to, write, read, onFinish, precision, tension, friction, clamp, }: SpringAnimateOptions): readonly [() => void, () => void];

package/esm/util/springAnimate.js

@@ -0,0 +1,80 @@
+// based on https://github.com/react-spring/react-spring/blob/cd5548a987383b8023efd620f3726a981f9e18ea/src/animated/FrameLoop.ts
+export function springAnimate({ from, to, write, read, onFinish = () => { }, precision, tension = 400, friction = 20, clamp = true, }) {
+    const mass = 1;
+    // ?? not ||, so an explicit precision of 0 (converge only on overshoot) is
+    // honored rather than silently replaced by the derived default
+    const eps = precision ?? Math.abs(to - from) / 1000;
+    let animationFrameId;
+    let lastWritten;
+    function apply(value) {
+        write(value);
+        lastWritten = read?.();
+    }
+    // Something other than this spring moved the value, so it owns it now (a wheel
+    // zoom, a nav, a drag). Compared against what the spring last WROTE rather
+    // than the value it asked for, because `write` may clamp: a spring pushing
+    // past a limit would otherwise read its own clamped result back as
+    // interference and stop one frame in.
+    function interrupted() {
+        return (read !== undefined && lastWritten !== undefined && read() !== lastWritten);
+    }
+    function update(animation) {
+        // checked before scheduling anything, so an interrupted spring simply stops
+        // requesting frames — no cancellation to sequence against the frame this
+        // update would have queued
+        if (interrupted()) {
+            return;
+        }
+        const time = performance.now();
+        let position = animation.lastPosition;
+        let lastTime = animation.lastTime ?? time;
+        let velocity = animation.lastVelocity ?? 0;
+        // Dropped frames (a background tab, a long task) are not replayed: the
+        // simulation resumes from now, so the spring finishes late rather than
+        // teleporting through 60 steps of physics in one frame.
+        if (time > lastTime + 64) {
+            lastTime = time;
+        }
+        // https://gafferongames.com/post/fix_your_timestep/
+        const numSteps = Math.floor(time - lastTime);
+        for (let i = 0; i < numSteps; ++i) {
+            const force = -tension * (position - to);
+            const damping = -friction * velocity;
+            const acceleration = (force + damping) / mass;
+            velocity += (acceleration * 1) / 1000;
+            position += (velocity * 1) / 1000;
+        }
+        const isVelocity = Math.abs(velocity) <= eps;
+        const isDisplacement = tension !== 0 ? Math.abs(to - position) <= eps : true;
+        const isOvershooting = clamp && tension !== 0
+            ? from < to
+                ? position > to
+                : position < to
+            : false;
+        const endOfAnimation = isOvershooting || (isVelocity && isDisplacement);
+        if (endOfAnimation) {
+            apply(to);
+            onFinish();
+        }
+        else {
+            apply(position);
+            animationFrameId = requestAnimationFrame(() => {
+                update({
+                    lastPosition: position,
+                    lastTime: time,
+                    lastVelocity: velocity,
+                });
+            });
+        }
+    }
+    return [
+        () => {
+            update({ lastPosition: from });
+        },
+        () => {
+            if (animationFrameId !== undefined) {
+                cancelAnimationFrame(animationFrameId);
+            }
+        },
+    ];
+}

package/esm/util/stats.d.ts

@@ -1,12 +1,12 @@
 import type { Feature } from './simpleFeature.ts';
-import type { NoAssemblyRegion } from './types/index.ts';
+import type { NoAssemblyRegion } from './types/data.ts';
 import type { Observable } from 'rxjs';
 export interface UnrectifiedQuantitativeStats {
     scoreMin: number;
     scoreMax: number;
     scoreSum: number;
     scoreSumSquares: number;
-    featureCount: number;
+    featureCount?: number;
     basesCovered: number;
     scoreMeanMin?: number;
     scoreMeanMax?: number;
@@ -19,7 +19,30 @@ export interface RectifiedQuantitativeStats extends UnrectifiedQuantitativeStats
 export interface QuantitativeStats extends RectifiedQuantitativeStats {
     currStatsBpPerPx: number;
 }
+/**
+ * calculate standard deviation using the 'shortcut method' that accepts
+ * the sum and the sum squares of the elements
+ *
+ * @param sum - sum(i, 1..n)
+ * @param sumSquares - sum(i^2, 1..n)
+ * @param n - number of elements
+ * @param population - boolean: use population instead of sample correction
+ * @returns - the estimated std deviation
+ */
 export declare function calcStdFromSums(sum: number, sumSquares: number, n: number, population?: boolean): number;
+/**
+ * @param stats - a summary stats object with scoreSum, featureCount,
+ * scoreSumSquares, and basesCovered
+ * @returns - a summary stats object with
+ * scoreMean, scoreStdDev, and featureDensity added
+ */
 export declare function rectifyStats(s: UnrectifiedQuantitativeStats): RectifiedQuantitativeStats;
+/**
+ * transform a list of scores to summary statistics
+ *
+ * @param region - object with start, end
+ * @param features - array of features which are possibly summary features
+ * @returns - object with scoreMax, scoreMin, scoreSum, scoreSumSquares, etc
+ */
 export declare function scoresToStats(region: NoAssemblyRegion, feats: Observable<Feature>): Promise<RectifiedQuantitativeStats>;
 export declare function blankStats(): RectifiedQuantitativeStats;

package/esm/util/stats.js

@@ -1,5 +1,15 @@
 import { firstValueFrom } from 'rxjs';
 import { reduce } from 'rxjs/operators';
+/**
+ * calculate standard deviation using the 'shortcut method' that accepts
+ * the sum and the sum squares of the elements
+ *
+ * @param sum - sum(i, 1..n)
+ * @param sumSquares - sum(i^2, 1..n)
+ * @param n - number of elements
+ * @param population - boolean: use population instead of sample correction
+ * @returns - the estimated std deviation
+ */
 export function calcStdFromSums(sum, sumSquares, n, population = false) {
     if (n === 0) {
         return 0;
@@ -9,6 +19,7 @@ export function calcStdFromSums(sum, sumSquares, n, population = false) {
         variance = sumSquares / n - (sum * sum) / (n * n);
     }
     else {
+        // sample correction is n-1
         variance = sumSquares - (sum * sum) / n;
         if (n > 1) {
             variance /= n - 1;
@@ -16,32 +27,51 @@ export function calcStdFromSums(sum, sumSquares, n, population = false) {
     }
     return variance < 0 ? 0 : Math.sqrt(variance);
 }
+/**
+ * @param stats - a summary stats object with scoreSum, featureCount,
+ * scoreSumSquares, and basesCovered
+ * @returns - a summary stats object with
+ * scoreMean, scoreStdDev, and featureDensity added
+ */
 export function rectifyStats(s) {
+    // Normalize undefined featureCount to 0 so || below operates on plain number
+    // (0 and undefined both mean "no per-feature count, fall back to basesCovered")
+    const n = s.featureCount ?? 0;
     return {
         ...s,
-        scoreMean: (s.scoreSum || 0) / (s.featureCount || s.basesCovered || 1),
-        scoreStdDev: calcStdFromSums(s.scoreSum, s.scoreSumSquares, s.featureCount || s.basesCovered),
-        featureDensity: (s.featureCount || 1) / s.basesCovered,
+        scoreMean: s.scoreSum / (n || s.basesCovered || 1),
+        scoreStdDev: calcStdFromSums(s.scoreSum, s.scoreSumSquares, n || s.basesCovered),
+        featureDensity: (s.featureCount ?? 1) / (s.basesCovered || 1),
     };
 }
+/**
+ * transform a list of scores to summary statistics
+ *
+ * @param region - object with start, end
+ * @param features - array of features which are possibly summary features
+ * @returns - object with scoreMax, scoreMin, scoreSum, scoreSumSquares, etc
+ */
 export async function scoresToStats(region, feats) {
     const { start, end } = region;
     const seed = {
+        // Number.MAX_VALUE not Infinity: precautionary, since Infinity serializes
+        // as null in JSON and these stats cross the RPC boundary. In practice the
+        // sentinels are always replaced before return (found===false → blankStats).
         scoreMin: Number.MAX_VALUE,
-        scoreMax: Number.MIN_VALUE,
+        scoreMax: -Number.MAX_VALUE,
         scoreMeanMin: Number.MAX_VALUE,
-        scoreMeanMax: Number.MIN_VALUE,
+        scoreMeanMax: -Number.MAX_VALUE,
         scoreSum: 0,
         scoreSumSquares: 0,
         featureCount: 0,
     };
     let found = false;
     const { scoreMin, scoreMax, scoreMeanMin, scoreMeanMax, scoreSum, scoreSumSquares, featureCount, } = await firstValueFrom(feats.pipe(reduce((acc, f) => {
-        const s = f.get('score');
+        const s = f.get('score') ?? 0;
         const summary = f.get('summary');
         const { scoreMax, scoreMin } = acc;
-        acc.scoreMax = Math.max(scoreMax, summary ? f.get('maxScore') : s);
-        acc.scoreMin = Math.min(scoreMin, summary ? f.get('minScore') : s);
+        acc.scoreMax = Math.max(scoreMax, summary ? (f.get('maxScore') ?? s) : s);
+        acc.scoreMin = Math.min(scoreMin, summary ? (f.get('minScore') ?? s) : s);
         acc.scoreMeanMin = Math.min(acc.scoreMeanMin, s);
         acc.scoreMeanMax = Math.max(acc.scoreMeanMax, s);
         acc.scoreSum += s;
@@ -50,6 +80,7 @@ export async function scoresToStats(region, feats) {
         found = true;
         return acc;
     }, seed)));
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     return found
         ? rectifyStats({
             scoreMax,