@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/layouts/placeRect.js

@@ -0,0 +1,97 @@
+/**
+ * Minimal row-packing primitive for integer-indexed 1D layouts.
+ *
+ * `rows[y]` is a flat `[s1,e1,s2,e2,...]` sorted ascending by start, where
+ * intervals within a row never overlap. `placeRect` finds the first row
+ * with no collision (or appends a new row), inserts `[start, end+2]`,
+ * and returns the row INDEX (0, 1, 2, ...).
+ *
+ * How this differs from `GranularRectLayout` in this same folder, and
+ * why this exists as a separate primitive:
+ *
+ * - **Keys:** GranularRectLayout keys rectangles by string ID in a
+ *   `Map`, so re-adding an id returns the row it already holds;
+ *   `placeRect` has no ID and no rectangle object. Callers with numeric
+ *   indices (e.g. BAM read indices) don't pay the cost of allocating
+ *   string IDs, Rectangle objects, or the outer Map — they use a
+ *   `Uint16Array` of row indices instead.
+ *
+ * - **Scaling / height:** GranularRectLayout has `pitchX`, `pitchY`,
+ *   multi-row rectangle heights, `maxHeight` / `hardRowLimit`, and
+ *   returns pixel `top` values. `placeRect` is unit-agnostic (bp or
+ *   px), one-row-per-rect, no limits, and returns a row index.
+ *
+ * - **State ownership:** GranularRectLayout is a class with internal
+ *   state; `placeRect` is a pure function operating on a caller-owned
+ *   `number[][]` array, so memory lifetime matches the caller's scope.
+ *
+ * Neither hit-tests: both are packing only, and consumers that need
+ * hit-testing build a Flatbush over the result.
+ *
+ * Use `placeRect` for tight per-call layouts over typed-array data
+ * (alignments pileup and chain rendering). Use `GranularRectLayout`
+ * when rects have variable heights or the layout needs a row limit
+ * (feature/gene tracks).
+ *
+ * Per-row complexity:
+ *   - O(1) append when the row's last end ≤ new start (start-sorted
+ *     input — the common case)
+ *   - O(log M) collision + insertion-point lookup for wide rows via
+ *     binary search on ends. Ends are monotone within a row because
+ *     intervals are non-overlapping and sorted by start.
+ *   - O(M) for the splice shift when inserting mid-row; only taken
+ *     once per placement, and only when the fast-path misses.
+ *
+ * @param rows  mutable `number[][]` — each row is `[s1,e1,s2,e2,...]`
+ * @param start rect start (any numeric unit — bp, px, etc.)
+ * @param end   rect end (exclusive)
+ * @returns     the row index the rect was placed in
+ */
+export function placeRect(rows, start, end) {
+    const paddedEnd = end + 2;
+    let y = rows.length;
+    for (let r = 0; r < rows.length; r++) {
+        const row = rows[r];
+        const len = row.length;
+        // Fast path: entire row ends before new start → O(1) append.
+        if (row[len - 1] <= start) {
+            row.push(start, paddedEnd);
+            y = r;
+            break;
+        }
+        // Find j = first index where interval end > start. Only intervals
+        // at/after j can possibly collide with [start, paddedEnd).
+        let j;
+        if (len < 32) {
+            j = 0;
+            while (row[j + 1] <= start) {
+                j += 2;
+            }
+        }
+        else {
+            let lo = 0;
+            let hi = len >>> 1;
+            while (lo < hi) {
+                const mid = (lo + hi) >>> 1;
+                if (row[(mid << 1) + 1] <= start) {
+                    lo = mid + 1;
+                }
+                else {
+                    hi = mid;
+                }
+            }
+            j = lo << 1;
+        }
+        // Only interval j can collide — if its start is past paddedEnd there
+        // is a gap and we insert at j; otherwise we collide and try next row.
+        if (row[j] >= paddedEnd) {
+            row.splice(j, 0, start, paddedEnd);
+            y = r;
+            break;
+        }
+    }
+    if (y === rows.length) {
+        rows.push([start, paddedEnd]);
+    }
+    return y;
+}

package/esm/util/lazyAfterAttach.d.ts

@@ -0,0 +1,13 @@
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * #api core/util
+ * Run a display's `afterAttach` body from a module loaded on demand, so the
+ * autorun installers stay out of the display's eager bundle.
+ *
+ * One policy for the gap the `await` opens: a node torn down before the module
+ * lands installs nothing, and a module that fails to load is reported where the
+ * user can see it rather than onto the display's own error slot — that slot is
+ * what `reload()` clears, and nothing would re-run the install behind it.
+ * Three displays hand-rolled this IIFE and each drew the lines differently.
+ */
+export declare function runLazyAfterAttach<Self extends IStateTreeNode>(self: Self, load: () => Promise<(self: Self) => void>): void;

package/esm/util/lazyAfterAttach.js

@@ -0,0 +1,31 @@
+import { isAlive } from '@jbrowse/mobx-state-tree';
+import { getNotificationSink } from './sessionServices.js';
+/**
+ * #api core/util
+ * Run a display's `afterAttach` body from a module loaded on demand, so the
+ * autorun installers stay out of the display's eager bundle.
+ *
+ * One policy for the gap the `await` opens: a node torn down before the module
+ * lands installs nothing, and a module that fails to load is reported where the
+ * user can see it rather than onto the display's own error slot — that slot is
+ * what `reload()` clears, and nothing would re-run the install behind it.
+ * Three displays hand-rolled this IIFE and each drew the lines differently.
+ */
+export function runLazyAfterAttach(self, load) {
+    // eslint-disable-next-line @typescript-eslint/no-floating-promises
+    ;
+    (async () => {
+        try {
+            const install = await load();
+            if (isAlive(self)) {
+                install(self);
+            }
+        }
+        catch (e) {
+            if (isAlive(self)) {
+                console.error(e);
+                getNotificationSink(self).notifyError(`${e}`, e);
+            }
+        }
+    })();
+}

package/esm/util/leadingEdgeAutorun.d.ts

@@ -0,0 +1,40 @@
+import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
+export interface LeadingEdgeAutorunOptions {
+    /** autorun name, for the MobX devtools/spy stream */
+    name: string;
+    /** how long to coalesce reruns once the body has started work once */
+    delay: number;
+}
+/**
+ * An autorun that runs on the leading edge until its body reports having
+ * started work, and debounces every run after that.
+ *
+ * MobX's own `autorun(fn, { delay })` is trailing-edge only: it schedules the
+ * *first* run through `setTimeout` too, so a cold open waits the whole delay
+ * for no interaction to coalesce, and that latency lands directly on first
+ * paint. Measured on the per-region fetch autorun, display creation to first
+ * `fetchNeeded`: 683 ms under `{ delay: 600 }`, 112 ms under this.
+ *
+ * **The body returns `true` when it started the work the delay exists to
+ * coalesce**, and that is what arms the debounce. Runs that bail on a guard —
+ * a view not measured yet, a minimized track, a prerequisite that has not
+ * landed — return nothing and stay on the leading edge, so the timer is never
+ * armed by work that did not happen. Priming off the body's return rather than
+ * an imperative `prime()` call is what makes a bail-out path unable to arm it
+ * by accident: there is nothing to forget and nothing to misplace.
+ *
+ * **The leading edge is a microtask, not the install call itself**, and that
+ * one hop is what keeps the debounce's whole point. A model is routinely built
+ * and then configured in the same synchronous block — a session applying a
+ * display setting, a caller flipping a mode right after `create` — and a fetch
+ * issued between those two lines is issued against the un-configured state,
+ * invalidated by the setting that follows, and reissued. Yielding once collapses
+ * every such pair back into one run, while still starting three orders of
+ * magnitude sooner than the timer did. What it deliberately does not coalesce is
+ * a change that arrives after an await: that is a later decision, and it costs
+ * the refetch it should.
+ *
+ * The debounce is per-installation, so two autoruns on one model coalesce
+ * independently.
+ */
+export declare function leadingEdgeAutorun(self: IAnyStateTreeNode, body: () => boolean | void, { name, delay }: LeadingEdgeAutorunOptions): import("mobx").IReactionDisposer;

package/esm/util/leadingEdgeAutorun.js

@@ -0,0 +1,51 @@
+import { namedAutorun } from '@jbrowse/render-core/namedReactions';
+/**
+ * An autorun that runs on the leading edge until its body reports having
+ * started work, and debounces every run after that.
+ *
+ * MobX's own `autorun(fn, { delay })` is trailing-edge only: it schedules the
+ * *first* run through `setTimeout` too, so a cold open waits the whole delay
+ * for no interaction to coalesce, and that latency lands directly on first
+ * paint. Measured on the per-region fetch autorun, display creation to first
+ * `fetchNeeded`: 683 ms under `{ delay: 600 }`, 112 ms under this.
+ *
+ * **The body returns `true` when it started the work the delay exists to
+ * coalesce**, and that is what arms the debounce. Runs that bail on a guard —
+ * a view not measured yet, a minimized track, a prerequisite that has not
+ * landed — return nothing and stay on the leading edge, so the timer is never
+ * armed by work that did not happen. Priming off the body's return rather than
+ * an imperative `prime()` call is what makes a bail-out path unable to arm it
+ * by accident: there is nothing to forget and nothing to misplace.
+ *
+ * **The leading edge is a microtask, not the install call itself**, and that
+ * one hop is what keeps the debounce's whole point. A model is routinely built
+ * and then configured in the same synchronous block — a session applying a
+ * display setting, a caller flipping a mode right after `create` — and a fetch
+ * issued between those two lines is issued against the un-configured state,
+ * invalidated by the setting that follows, and reissued. Yielding once collapses
+ * every such pair back into one run, while still starting three orders of
+ * magnitude sooner than the timer did. What it deliberately does not coalesce is
+ * a change that arrives after an await: that is a later decision, and it costs
+ * the refetch it should.
+ *
+ * The debounce is per-installation, so two autoruns on one model coalesce
+ * independently.
+ */
+export function leadingEdgeAutorun(self, body, { name, delay }) {
+    let primed = false;
+    return namedAutorun(self, () => {
+        if (body()) {
+            primed = true;
+        }
+    }, {
+        name,
+        scheduler: run => {
+            if (primed) {
+                setTimeout(run, delay);
+            }
+            else {
+                queueMicrotask(run);
+            }
+        },
+    });
+}

package/esm/util/legendCandidates.d.ts

@@ -0,0 +1,50 @@
+export interface LegendCandidate {
+    rowIndex: number;
+    label: string;
+    color: number;
+}
+export interface LegendEntry {
+    label: string;
+    color: number;
+}
+export declare const MAX_LEGEND_ENTRIES = 30;
+export declare const MAX_LEGEND_CANDIDATES = 1024;
+/**
+ * Accumulator for the distinct (row, name, color) combinations a packer walks
+ * past, in first-seen order and bounded — the small list `unionLegendCandidates`
+ * derives a key from, so the main thread never re-walks the features. Fed scalar
+ * by scalar, from the loop that already holds the three values.
+ *
+ * Deduped on the whole triple rather than on (row, color): the union takes the
+ * first NAME it sees for a color, so where that name is already spoken for, the
+ * second name on that color has to still be in the list to carry it.
+ *
+ * A nameless feature contributes nothing, which is the union's rule too — so a
+ * track whose features have no names ships an empty list rather than one entry
+ * per feature.
+ */
+export declare function createLegendCandidateCollector(maxCandidates?: number): {
+    candidates: LegendCandidate[];
+    add(rowIndex: number, label: string, color: number): void;
+};
+export interface LegendCandidateSource {
+    candidates: readonly LegendCandidate[];
+    rowPaintsCandidateColor: (rowIndex: number) => boolean;
+}
+/**
+ * The categorical color key over any number of packed regions: one entry per
+ * distinct color, labeled by the first name seen in that color, in first-seen
+ * order.
+ *
+ * Keyed by color rather than by name, so each key row is 1:1 with a color — a
+ * row is normally a toggle and hiding a category hides features BY color, so two
+ * names sharing one color must collapse to a single row. A name reused across
+ * two colors keeps its first-seen color.
+ *
+ * `[]` when the data carries no categorical signal: nothing named, or more than
+ * `maxEntries` distinct colors.
+ *
+ * `regions` is consumed lazily, so a caller able to answer without reading any
+ * of them can pass a generator and have none of them touched.
+ */
+export declare function unionLegendCandidates<T>(regions: Iterable<T>, resolve: (region: T) => LegendCandidateSource, maxEntries?: number): LegendEntry[];

package/esm/util/legendCandidates.js

@@ -0,0 +1,87 @@
+// How many distinct colors a derived key may name and still BE a key. Past this
+// the data is not a categorical vocabulary (a track keyed by unique per-feature
+// names), and a list of every feature is the thing a key exists instead of.
+//
+// A different question from `legendIsReadable`'s lower bar, which asks whether a
+// key a display already has is worth the rows it costs.
+export const MAX_LEGEND_ENTRIES = 30;
+// Bound on the candidate list one region ships. Far above MAX_LEGEND_ENTRIES, so
+// a vocabulary that is categorical at all crosses whole, and a track with a name
+// per feature ships a prefix that reads the same way it would have.
+export const MAX_LEGEND_CANDIDATES = 1024;
+/**
+ * Accumulator for the distinct (row, name, color) combinations a packer walks
+ * past, in first-seen order and bounded — the small list `unionLegendCandidates`
+ * derives a key from, so the main thread never re-walks the features. Fed scalar
+ * by scalar, from the loop that already holds the three values.
+ *
+ * Deduped on the whole triple rather than on (row, color): the union takes the
+ * first NAME it sees for a color, so where that name is already spoken for, the
+ * second name on that color has to still be in the list to carry it.
+ *
+ * A nameless feature contributes nothing, which is the union's rule too — so a
+ * track whose features have no names ships an empty list rather than one entry
+ * per feature.
+ */
+export function createLegendCandidateCollector(maxCandidates = MAX_LEGEND_CANDIDATES) {
+    const candidates = [];
+    const colorsSeen = new Map();
+    return {
+        candidates,
+        add(rowIndex, label, color) {
+            if (label !== '' && candidates.length < maxCandidates) {
+                let byLabel = colorsSeen.get(rowIndex);
+                if (byLabel === undefined) {
+                    byLabel = new Map();
+                    colorsSeen.set(rowIndex, byLabel);
+                }
+                let colors = byLabel.get(label);
+                if (colors === undefined) {
+                    colors = new Set();
+                    byLabel.set(label, colors);
+                }
+                if (!colors.has(color)) {
+                    colors.add(color);
+                    candidates.push({ rowIndex, label, color });
+                }
+            }
+        },
+    };
+}
+/**
+ * The categorical color key over any number of packed regions: one entry per
+ * distinct color, labeled by the first name seen in that color, in first-seen
+ * order.
+ *
+ * Keyed by color rather than by name, so each key row is 1:1 with a color — a
+ * row is normally a toggle and hiding a category hides features BY color, so two
+ * names sharing one color must collapse to a single row. A name reused across
+ * two colors keeps its first-seen color.
+ *
+ * `[]` when the data carries no categorical signal: nothing named, or more than
+ * `maxEntries` distinct colors.
+ *
+ * `regions` is consumed lazily, so a caller able to answer without reading any
+ * of them can pass a generator and have none of them touched.
+ */
+export function unionLegendCandidates(regions, resolve, maxEntries = MAX_LEGEND_ENTRIES) {
+    const entries = [];
+    const seenColors = new Set();
+    const seenLabels = new Set();
+    for (const region of regions) {
+        const { candidates, rowPaintsCandidateColor } = resolve(region);
+        for (const { rowIndex, label, color } of candidates) {
+            if (rowPaintsCandidateColor(rowIndex) &&
+                !seenLabels.has(label) &&
+                !seenColors.has(color)) {
+                seenLabels.add(label);
+                seenColors.add(color);
+                entries.push({ label, color });
+                if (entries.length > maxEntries) {
+                    return [];
+                }
+            }
+        }
+    }
+    return entries;
+}

package/esm/util/librpc.d.ts

@@ -1,2 +1,5 @@
-export { RpcClient, RpcServer, deserializeError, rpcResult, serializeError, } from 'librpc-web-mod';
-export type { RpcResult } from 'librpc-web-mod';
+export { default as RpcClient } from '../rpc/RpcClient.ts';
+export { default as RpcServer, rpcResult, rpcResultWithArrayBuffers, } from '../rpc/RpcServer.ts';
+export type { RpcResult } from '../rpc/RpcServer.ts';
+export { isRpcResult, unwrapRpcResult } from './rpc.ts';
+export { deserializeError, serializeError, } from '../rpc/serializeError/index.ts';

package/esm/util/librpc.js

@@ -1 +1,6 @@
-export { RpcClient, RpcServer, deserializeError, rpcResult, serializeError, } from 'librpc-web-mod';
+export { default as RpcClient } from '../rpc/RpcClient.js';
+export { default as RpcServer, rpcResult, rpcResultWithArrayBuffers, } from '../rpc/RpcServer.js';
+// the inverse of rpcResult, for a deserializeReturn rebuilding the caller's
+// value out of what the worker sent
+export { isRpcResult, unwrapRpcResult } from './rpc.js';
+export { deserializeError, serializeError, } from '../rpc/serializeError/index.js';

package/esm/util/linkify.js

@@ -1,3 +1,5 @@
+// based on autolink-js, license MIT
+// https://github.com/bryanwoods/autolink-js/blob/1418049970152c56ced73d43dcc62d80b320fb71/autolink.js#L9
 const URL_PATTERN = /(^|[\s\n]|<[A-Za-z]*\/?>)((?:https?|ftp):\/\/[-A-Z0-9+\u0026\u2019@#/%?=()~_|!:,.;]*[-A-Z0-9+\u0026@#/%=~()_|])/gi;
 export function linkify(s) {
     URL_PATTERN.lastIndex = 0;

package/esm/util/locString.d.ts

@@ -5,5 +5,77 @@ export interface ParsedLocString {
     end?: number;
     reversed?: boolean;
 }
+export declare class UnknownRefNameError extends Error {
+    name: string;
+}
 export declare function parseLocStringOneBased(locString: string, isValidRefName: (refName: string, assemblyName?: string) => boolean): ParsedLocString;
 export declare function parseLocString(locString: string, isValidRefName: (refName: string, assemblyName?: string) => boolean): ParsedLocString;
+/**
+ * Assemble a 1-based "locString" from an interbase genomic location
+ * @param region - Region
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1', start: 0, end: 100 })
+ * // ↳ 'chr1:1..100'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ assemblyName: 'hg19', refName: 'chr1', start: 0, end: 100 })
+ * // ↳ '{hg19}chr1:1..100'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1' })
+ * // ↳ 'chr1'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1', start: 0 })
+ * // ↳ 'chr1:1..'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1', end: 100 })
+ * // ↳ 'chr1:1..100'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1', start: 0, end: 1 })
+ * // ↳ 'chr1:1'
+ * ```
+ */
+export declare function assembleLocString(region: ParsedLocString): string;
+/**
+ * Same as {@link assembleLocString}, but with the coordinates left unformatted:
+ * no thousand separators, and never affected by the `numberGrouping` display
+ * preference. Use this wherever the result is compared, keyed on, or parsed
+ * rather than read — block keys, dedup buckets, locStrings handed back to
+ * `parseLocString` — both because it is faster (block calculations assemble a
+ * great many of these) and because a display convention shifting under an
+ * identity string is a correctness bug, not a cosmetic one.
+ */
+export declare function assembleLocStringRaw(region: ParsedLocString): string;
+/**
+ * One space-separated string for a set of regions — what the header of a
+ * multi-region view says it is showing, and what an export of those regions
+ * labels itself with.
+ *
+ * The assembly name appears only when the regions disagree about it: naming it
+ * on every one of a dozen same-assembly blocks is noise, and dropping it where
+ * they differ loses the only thing telling them apart.
+ */
+export declare function assembleLocStrings(regions: ParsedLocString[]): string;
+export declare function compareLocs(locA: ParsedLocString, locB: ParsedLocString): number;
+export declare function compareLocStrings(a: string, b: string, isValidRefName: (refName: string, assemblyName?: string) => boolean): number;
+/**
+ * A cursor/coordinate readout: `{assembly}chr1:1,234`, with the refName
+ * shortened and the coordinate locale-grouped. The *display* counterpart to
+ * {@link assembleLocString} — this one is for showing a single position to a
+ * user, never for a location string that will be parsed back.
+ */
+export declare function stringify({ refName, coord, assemblyName, oob, }: {
+    assemblyName?: string;
+    coord: number;
+    refName?: string;
+    oob?: boolean;
+}, useAssemblyName?: boolean): string;