@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/createStopTokenRotation.d.ts

@@ -0,0 +1,118 @@
+import type { RpcStatus, StatusWindow } from './progress.ts';
+import type { StopToken } from './stopToken.ts';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * Where a rotation reports, in the one of two modes the host is actually in.
+ *
+ * A union rather than one shape with an optional window, because the two modes
+ * do not use the same member and the optional version required the one that is
+ * dead in the lending mode: when a host lends its `statusWindow` the rotation
+ * writes through the window and never calls `setStatusMessage`, so a caller
+ * supplying both got silence from the half it thought it was wiring up.
+ * `FetchMixin` was that caller.
+ */
+export type StatusReporter = {
+    /**
+     * The host's own window, present on any display composing the LGV fetch
+     * mixins. The rotation reports through it rather than opening a SECOND on
+     * the same status field — which is what one-window-per-owner exists to
+     * prevent.
+     */
+    statusWindow: StatusWindow;
+    setStatusMessage?: never;
+} | {
+    /**
+     * The sink for the window the rotation opens for itself. This is the mode
+     * the displays this helper was written for are in (dotplot, synteny),
+     * which compose no fetch mixin, along with every
+     * {@link createStatusChannel} holder.
+     */
+    setStatusMessage: (status?: RpcStatus) => void;
+    statusWindow?: never;
+};
+/**
+ * A {@link StatusReporter} a model can hold in **one** volatile, for something
+ * that has one operation to narrate and no reason to grow a status vocabulary
+ * of its own. `ProgressChip` takes `message`/`fraction` straight off it.
+ *
+ * The alternative is what every display does: two volatiles and an action
+ * calling {@link statusMessageText} and {@link statusFraction}. That is the
+ * right shape where the fields are part of the model's own surface —
+ * `BaseDisplay` and `FetchMixin` declare them because half the display API reads
+ * them — and a lot of declaration for a view that wants a corner chip while one
+ * fetch runs. A plain function rather than a mixin because a compose layer is
+ * what the model chains here cannot afford (ADR-041).
+ */
+export interface StatusChannel {
+    setStatusMessage: (status?: RpcStatus) => void;
+    readonly message: string | undefined;
+    readonly fraction: number | undefined;
+}
+export declare function createStatusChannel(): StatusChannel;
+export interface ActiveFetch {
+    /** stop token to forward to the RPC call */
+    stopToken: StopToken;
+    /**
+     * True only while this is still the most recent fetch AND `self` is alive.
+     * Gate every post-await write — result commit, error set — on it so a
+     * superseded or torn-down fetch never writes back.
+     */
+    isCurrent: () => boolean;
+    /**
+     * RPC `statusCallback` pre-gated by `isCurrent`: forwards progress to
+     * `setStatusMessage` only while this is still the latest fetch, so a
+     * superseded fetch's late status update can't flicker the overlay, and
+     * throttled to the same leading edge as `FetchMixin`'s callbacks. Pass it
+     * straight as the RPC `statusCallback` arg.
+     */
+    statusCallback: (status: RpcStatus) => void;
+    /**
+     * Call in the `finally` of the run that owns this fetch: closes `isCurrent`
+     * and retires this fetch's status slot, which blanks the field only if no
+     * other operation on the host is still reporting.
+     *
+     * Both together, because a caller doing it by hand gets a subset.
+     * `isCurrent` is `token === current && isAlive`, and a run that *completes*
+     * never rotates its own token — so without this the guard stays open past the
+     * work and a trailing write lands on top of a hand-written
+     * `setStatusMessage(undefined)` up to a window later.
+     *
+     * A **superseded** run calls it too, and must: its slot goes on voting for a
+     * phase that is over until it does. The run that replaced it has already
+     * opened its own slot by then, so the label the user is looking at survives.
+     */
+    end: () => void;
+}
+/**
+ * Latest-wins stop-token rotation for a fetch that runs in a bare `autorun`
+ * rather than through `FetchMixin.runFetch` (which welds the same mechanics to
+ * `fetchGeneration`, so it's only for viewport-driven LGV fetches). Each
+ * `begin()` aborts the prior fetch's token and returns a fresh one plus an
+ * `isCurrent()` guard that captures this run's token — gate every post-await
+ * write on it and a superseded or torn-down fetch can never clobber fresher
+ * data. The guard is the return value, so a caller can't forget to compare a
+ * token by hand.
+ *
+ * `end()` in the run's `finally` is the other half, and for the same reason —
+ * see {@link ActiveFetch.end} for the two things it does together.
+ *
+ * Owns the token mechanics and the status channel; the caller keeps its own
+ * loading/error/commit side-effects. Three holders: `FetchMixin` as a member
+ * (so `cancelFetch` can reach it), `installFetch` one per installation (every
+ * other fetch in the tree runs on that skeleton), and the synteny diagonalize
+ * progress wrapper (`withDiagonalizeProgress`) directly.
+ *
+ * `report` is passed rather than read off `self`, so where the status lands is
+ * the caller's decision and not a shape this imposes. A display passes itself —
+ * its status fields are part of its own API, and one composing `FetchMixin`
+ * passes the model-wide window along with them (see `StatusReporter`).
+ * Anything with one operation to narrate and no status vocabulary of its own
+ * passes a {@link createStatusChannel}, which is one volatile instead of two
+ * fields and an action.
+ */
+export type StopTokenRotation = ReturnType<typeof createStopTokenRotation>;
+export declare function createStopTokenRotation(self: IStateTreeNode, report: StatusReporter): {
+    begin(): ActiveFetch;
+    cancel: () => void;
+    dispose(): void;
+};

package/esm/util/createStopTokenRotation.js

@@ -0,0 +1,127 @@
+import { isAlive } from '@jbrowse/mobx-state-tree';
+import { observable, runInAction } from 'mobx';
+import { createStatusWindow, statusFraction, statusMessageText, } from './progress.js';
+import { createStopToken, stopStopToken } from './stopToken.js';
+export function createStatusChannel() {
+    // MobX rather than MST, so this is a value a model can hold rather than a
+    // node it has to parent. A volatile is `observable.ref`, so the fields have
+    // to be observable in their own right for a component to see them move.
+    const state = observable({
+        message: undefined,
+        fraction: undefined,
+    }, {}, { deep: false });
+    return {
+        get message() {
+            return state.message;
+        },
+        get fraction() {
+            return state.fraction;
+        },
+        setStatusMessage(status) {
+            // its own action: the rotation calls this from a status callback, which
+            // fires after an await and so outside whatever MST action started the
+            // fetch
+            runInAction(() => {
+                state.message = statusMessageText(status);
+                state.fraction = statusFraction(status);
+            });
+        },
+    };
+}
+export function createStopTokenRotation(self, report) {
+    let currentStopToken;
+    // The host's window when it has one, so a display composing `FetchMixin` has
+    // one window rather than two writing one field; our own otherwise. Lent means
+    // this fetch is one slot beside the host's others rather than a second writer
+    // (ADR-081), which is why `end()` no longer has to ask whether it owns the
+    // field.
+    const lent = report.statusWindow !== undefined;
+    const statusWindow = report.statusWindow
+        ? report.statusWindow
+        : // the one place the field is touched, so the liveness check covers a
+            // stream's statuses and the clear that ends it alike
+            createStatusWindow((status) => {
+                if (isAlive(self)) {
+                    report.setStatusMessage(status);
+                }
+            });
+    let openStream;
+    /**
+     * Stop the in-flight fetch without starting one, and retire its slot.
+     *
+     * Dropping `currentStopToken` rather than only stopping it is what closes
+     * every outstanding guard: `isCurrent` compares against this field, so one
+     * assignment makes a fetch already past its await stale, whether it is the one
+     * being cancelled or a superseded predecessor still unwinding.
+     *
+     * Retiring, not blanking — the field goes blank only if this was the last
+     * operation reporting on it (ADR-081).
+     *
+     * Named rather than reached through `this`, so a destructured `dispose` still
+     * works: `addDisposer(self, rotation.dispose)` is a shape callers reach for.
+     */
+    const cancel = () => {
+        if (currentStopToken) {
+            stopStopToken(currentStopToken);
+            currentStopToken = undefined;
+        }
+        // a fetch in flight when this is called never reaches its `finally`, and a
+        // slot nobody retires goes on voting
+        openStream?.clear();
+        openStream = undefined;
+    };
+    return {
+        begin() {
+            if (currentStopToken) {
+                stopStopToken(currentStopToken);
+            }
+            const stopToken = createStopToken();
+            currentStopToken = stopToken;
+            // `ended` is the term a completed fetch has no other way to express: the
+            // token comparison catches a SUPERSEDED one, but a fetch that simply
+            // finished still holds the current token. The stream reads it as well as
+            // the caller's commit guard, which is why both go through this closure.
+            let ended = false;
+            const isCurrent = () => !ended && stopToken === currentStopToken && isAlive(self);
+            // Opened BEFORE the superseded run reaches its `finally`, which is what
+            // keeps the label the user is looking at from blanking between the two:
+            // the run being replaced is suspended at an await and resumes a microtask
+            // from now, by which point this slot is already voting. A fetch being
+            // SUPERSEDED is the one case where the display does not stop loading, so
+            // a gap there reads as the overlay's `'Loading'` fallback (ADR-080).
+            const stream = statusWindow.open({ isCurrent });
+            openStream = stream;
+            return {
+                stopToken,
+                isCurrent,
+                statusCallback: stream.statusCallback,
+                end() {
+                    ended = true;
+                    // A completed fetch's token is released here, not only on supersede
+                    // or cancel — otherwise it pins its AbortSignal controllers (and blob
+                    // URL) until the next `begin()`, forever for a one-shot fetch that
+                    // succeeds and never reruns. `stopStopToken` is guarded, so the
+                    // superseded and cancelled runs that arrive here already-stopped cost
+                    // nothing.
+                    stopStopToken(stopToken);
+                    if (openStream === stream) {
+                        openStream = undefined;
+                    }
+                    stream.clear();
+                },
+            };
+        },
+        cancel,
+        dispose() {
+            cancel();
+            // the window outlives the token: a trailing write is queued on a timer,
+            // and while the sink's `isCurrent` makes it a no-op rather than a write to
+            // a dead node, the timer itself still stands for up to a window past
+            // teardown. Only ours — resetting a lent one drops a write the host's
+            // other operations are still owed.
+            if (!lent) {
+                statusWindow.reset();
+            }
+        },
+    };
+}

package/esm/util/createSvgRasterCanvas.d.ts

@@ -0,0 +1,7 @@
+export interface SvgRasterCanvasOpts {
+    createCanvas?: (width: number, height: number) => HTMLCanvasElement;
+}
+export declare function createSvgRasterCanvas(width: number, height: number, opts: SvgRasterCanvasOpts | undefined): {
+    canvas: HTMLCanvasElement;
+    ctx: CanvasRenderingContext2D;
+};

package/esm/util/createSvgRasterCanvas.js

@@ -0,0 +1,22 @@
+// SVG export's "rasterize a layer to PNG" idiom: a 2× DPR canvas drawn into,
+// then embedded as <image xlinkHref={dataURL}/>. Used by every renderSvg.tsx
+// that has heavy fill paths (alignments pileup, wiggle bins, hic matrix, LD
+// matrix, etc.) where vector output would be unreasonably large.
+//
+// Fixed at 2× — exports go to print/file, not screen, so devicePixelRatio is
+// not the right scale factor.
+const SVG_RASTER_DPR = 2;
+export function createSvgRasterCanvas(width, height, opts) {
+    const dpr = SVG_RASTER_DPR;
+    const canvas = opts?.createCanvas
+        ? opts.createCanvas(width * dpr, height * dpr)
+        : document.createElement('canvas');
+    canvas.width = width * dpr;
+    canvas.height = height * dpr;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+        throw new Error('createSvgRasterCanvas: 2D context unavailable');
+    }
+    ctx.scale(dpr, dpr);
+    return { canvas, ctx };
+}

package/esm/util/crypto.d.ts

@@ -1,7 +1,31 @@
+/**
+ * AES encrypt compatible with crypto-js OpenSSL format
+ * Uses Web Crypto API when available, falls back to pure JS in non-secure contexts
+ */
 export declare function aesEncrypt(plaintext: string, password: string): Promise<string>;
+/**
+ * AES decrypt compatible with crypto-js OpenSSL format
+ * Uses Web Crypto API when available, falls back to pure JS in non-secure contexts
+ */
 export declare function aesDecrypt(ciphertext: string, password: string): Promise<string>;
+/**
+ * SHA256 hash
+ * Uses Web Crypto API when available, falls back to pure JS in non-secure contexts
+ */
 export declare function sha256(data: string): Promise<Uint8Array>;
+/**
+ * Base64 encode a Uint8Array
+ */
 export declare function toBase64(data: Uint8Array): string;
+/**
+ * URL-safe Base64 encode (for OAuth PKCE)
+ */
 export declare function toBase64Url(data: Uint8Array): string;
+/**
+ * SHA256 hash and return as Base64 (for OAuth PKCE code challenge)
+ */
 export declare function sha256Base64(data: string): Promise<string>;
+/**
+ * SHA256 hash and return as URL-safe Base64 (for OAuth PKCE code challenge)
+ */
 export declare function sha256Base64Url(data: string): Promise<string>;