@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/layouts/placeRect.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 declare function placeRect(rows: number[][], start: number, end: number): number;

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/lazyWithPreload.d.ts

@@ -0,0 +1,19 @@
+import type { AnyReactComponentType } from './types/util.ts';
+/**
+ * `React.lazy` that also exposes the import it wraps, so code that knows a
+ * component is about to render (a session naming a view, a track being shown)
+ * can start the download instead of waiting for React to reach it. A failed
+ * load is not kept, so the render that follows tries again.
+ *
+ * Once the import has landed, the first render gets the module synchronously.
+ * React.lazy suspends on any promise, settled or not, and React holds a
+ * suspended boundary's reveal for 300 ms after its fallback commits, so a
+ * preloaded component nested under another cost that 300 ms per level.
+ */
+export declare function lazyWithPreload<T extends AnyReactComponentType>(factory: () => Promise<{
+    default: T;
+}>): import("react").LazyExoticComponent<T> & {
+    preload: () => Promise<{
+        default: T;
+    }>;
+};

package/esm/util/lazyWithPreload.js

@@ -0,0 +1,27 @@
+import { lazy } from 'react';
+/**
+ * `React.lazy` that also exposes the import it wraps, so code that knows a
+ * component is about to render (a session naming a view, a track being shown)
+ * can start the download instead of waiting for React to reach it. A failed
+ * load is not kept, so the render that follows tries again.
+ *
+ * Once the import has landed, the first render gets the module synchronously.
+ * React.lazy suspends on any promise, settled or not, and React holds a
+ * suspended boundary's reveal for 300 ms after its fallback commits, so a
+ * preloaded component nested under another cost that 300 ms per level.
+ */
+export function lazyWithPreload(factory) {
+    let loaded;
+    let loading;
+    const load = () => (loading ??= factory().then(module => (loaded = module), (error) => {
+        loading = undefined;
+        throw error;
+    }));
+    const settled = (module) => ({
+        // eslint-disable-next-line unicorn/no-thenable -- React.lazy takes a module synchronously only from a then that calls back at once
+        then: (resolve) => {
+            resolve(module);
+        },
+    });
+    return Object.assign(lazy(() => (loaded ? settled(loaded) : load())), { preload: load });
+}

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,72 @@
+import type { CategoricalEntry, CategoricalScale } from '../ui/colorScale.ts';
+import type { LegendSwatch } from '../ui/legendSpec.ts';
+import type { CategoricalField } from './categoricalField.ts';
+export interface LegendCandidate {
+    rowIndex: number;
+    value: string;
+    color: number;
+}
+export interface LegendEntry {
+    values: string[];
+    color: number;
+}
+export declare const MAX_LEGEND_ENTRIES = 30;
+export declare const MAX_LEGEND_CANDIDATES = 1024;
+/**
+ * Accumulator for the distinct (row, value, color) combinations a packer walks
+ * past, in first-seen order and bounded, so the main thread never re-walks the
+ * features. Deduped on the whole triple: a row of the union lists every value
+ * painted in its color, so a second value on that color has to still be in the
+ * list to reach it.
+ */
+export declare function createLegendCandidateCollector(maxCandidates?: number): {
+    candidates: LegendCandidate[];
+    add(rowIndex: number, value: 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 listing every value painted in it, colors in first-seen
+ * order. Keyed by color rather than by value because hiding a category hides
+ * features BY color, so two values sharing one color are one row that names
+ * both; a value met in two colors stays with the first.
+ *
+ * `[]` when there are more than `maxEntries` distinct colors, where the data is
+ * not a categorical vocabulary. `regions` is consumed lazily.
+ */
+export declare function unionLegendCandidates<T>(regions: Iterable<T>, resolve: (region: T) => LegendCandidateSource, maxEntries?: number): LegendEntry[];
+/**
+ * A source whose every entry is a candidate its one row paints: the entries of
+ * a scale table `encodeFeatures` resolved, or any walk that met each value in
+ * one color.
+ */
+export declare function everyRowPaints(entries: readonly {
+    value: string;
+    color: number;
+}[]): LegendCandidateSource;
+/**
+ * The one categorical key a color channel derives from what a worker painted:
+ * the union above over the loaded regions, each row a painted color naming
+ * every value in it through `field` and ordered by it, and nothing where the
+ * rows would say nothing (`legendIsReadable`). A display resolving its own colors hands the
+ * candidates its packer recorded; one resolved by `encodeFeatures` hands the
+ * entries of the scale tables that came back. Either way the key lists what
+ * the painting holds, and a `closed` field's domain besides once anything
+ * painted. `title` heads it in place of the field's name, `''` heading
+ * nothing, and `swatches` draws a row as something other than its color's box.
+ * `besides` are the colors of rows a display lists beside these, which the
+ * one-color test counts and the length test does not.
+ */
+export declare function derivedColorScale<T>(regions: Iterable<T>, resolve: (region: T) => LegendCandidateSource, { id, field, title, maxItems, swatches, besides, }: {
+    id: string;
+    field: CategoricalField;
+    title?: string;
+    maxItems?: number;
+    swatches?: (row: CategoricalEntry & {
+        color: string;
+    }) => LegendSwatch[];
+    besides?: readonly string[];
+}): CategoricalScale[];

package/esm/util/legendCandidates.js

@@ -0,0 +1,138 @@
+import { MAX_LEGEND_ITEMS, legendIsReadable } from '../ui/legendSpec.js';
+import { abgrToCssRgba, cssColorToABGR } from './colorBits.js';
+// 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, value, color) combinations a packer walks
+ * past, in first-seen order and bounded, so the main thread never re-walks the
+ * features. Deduped on the whole triple: a row of the union lists every value
+ * painted in its color, so a second value on that color has to still be in the
+ * list to reach it.
+ */
+export function createLegendCandidateCollector(maxCandidates = MAX_LEGEND_CANDIDATES) {
+    const candidates = [];
+    const seen = new Set();
+    return {
+        candidates,
+        add(rowIndex, value, color) {
+            const id = `${rowIndex}\u0000${color}\u0000${value}`;
+            if (candidates.length < maxCandidates && !seen.has(id)) {
+                seen.add(id);
+                candidates.push({ rowIndex, value, color });
+            }
+        },
+    };
+}
+/**
+ * The categorical color key over any number of packed regions: one entry per
+ * distinct color listing every value painted in it, colors in first-seen
+ * order. Keyed by color rather than by value because hiding a category hides
+ * features BY color, so two values sharing one color are one row that names
+ * both; a value met in two colors stays with the first.
+ *
+ * `[]` when there are more than `maxEntries` distinct colors, where the data is
+ * not a categorical vocabulary. `regions` is consumed lazily.
+ */
+export function unionLegendCandidates(regions, resolve, maxEntries = MAX_LEGEND_ENTRIES) {
+    const rows = new Map();
+    const seenValues = new Set();
+    for (const region of regions) {
+        const { candidates, rowPaintsCandidateColor } = resolve(region);
+        for (const { rowIndex, value, color } of candidates) {
+            if (!rowPaintsCandidateColor(rowIndex) || seenValues.has(value)) {
+                continue;
+            }
+            seenValues.add(value);
+            const row = rows.get(color);
+            if (row) {
+                row.values.push(value);
+            }
+            else {
+                rows.set(color, { values: [value], color });
+                if (rows.size > maxEntries) {
+                    return [];
+                }
+            }
+        }
+    }
+    return [...rows.values()];
+}
+/**
+ * A source whose every entry is a candidate its one row paints: the entries of
+ * a scale table `encodeFeatures` resolved, or any walk that met each value in
+ * one color.
+ */
+export function everyRowPaints(entries) {
+    return {
+        candidates: entries.map(({ value, color }) => ({
+            rowIndex: 0,
+            value,
+            color,
+        })),
+        rowPaintsCandidateColor: () => true,
+    };
+}
+/**
+ * The one categorical key a color channel derives from what a worker painted:
+ * the union above over the loaded regions, each row a painted color naming
+ * every value in it through `field` and ordered by it, and nothing where the
+ * rows would say nothing (`legendIsReadable`). A display resolving its own colors hands the
+ * candidates its packer recorded; one resolved by `encodeFeatures` hands the
+ * entries of the scale tables that came back. Either way the key lists what
+ * the painting holds, and a `closed` field's domain besides once anything
+ * painted. `title` heads it in place of the field's name, `''` heading
+ * nothing, and `swatches` draws a row as something other than its color's box.
+ * `besides` are the colors of rows a display lists beside these, which the
+ * one-color test counts and the length test does not.
+ */
+export function derivedColorScale(regions, resolve, { id, field, title = field.field, maxItems, swatches, besides = [], }) {
+    const painted = unionLegendCandidates(regions, resolve).map(({ values, color }) => {
+        const sorted = values.toSorted(field.compare);
+        const value = sorted[0];
+        return {
+            value,
+            values: sorted,
+            label: sorted.map(v => field.label(v)).join(', '),
+            color: abgrToCssRgba(color),
+            ...(value === '' ? { missing: true } : {}),
+        };
+    });
+    const named = new Set(painted.flatMap(e => e.values));
+    const unpainted = field.closed && painted.length > 0
+        ? field.domain
+            .filter(value => !named.has(value))
+            .map(value => ({
+            value,
+            label: field.label(value),
+            color: abgrToCssRgba(cssColorToABGR(field.color(value))),
+        }))
+        : [];
+    const entries = [...painted, ...unpainted].sort((a, b) => field.compare(a.value, b.value));
+    const beside = besides.map(color => ({
+        label: '',
+        color: abgrToCssRgba(cssColorToABGR(color)),
+    }));
+    return painted.length > 0 &&
+        legendIsReadable([...entries, ...beside], (maxItems ?? MAX_LEGEND_ITEMS) + beside.length)
+        ? [
+            {
+                kind: 'categorical',
+                id,
+                ...(title ? { title } : {}),
+                ...(field.domain.length > 0 ? { domain: field.domain } : {}),
+                entries: swatches
+                    ? entries.map(row => ({ ...row, swatches: swatches(row) }))
+                    : 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;