@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/util/progress.d.ts

@@ -0,0 +1,459 @@
+import type { StopToken, StopTokenChecker } from './stopToken.ts';
+/**
+ * Indeterminate phase: set `label` on the status channel, run `fn`, then restore
+ * whatever phase encloses it — `''` when there is none. Pass `stopToken` and the
+ * phase becomes a cancellation boundary too: this is the labelled form of
+ * {@link withStopTokenCheck}, so `fn` is checked on both sides of its await and
+ * neither check has to be remembered at the call site. The determinate
+ * counterpart is {@link withProgress}.
+ *
+ * Nests — see {@link openPhase}. An inner phase's close restores the enclosing
+ * label and not its bar; the enclosing phase's next `report()` re-establishes
+ * it, and one with none to send was indeterminate anyway.
+ *
+ * `msg` is a {@link StatusPhase} where the caller knows which file the phase is
+ * fetching — `downloadPhase(label, location)` builds one — and a plain string
+ * everywhere else. It nests and retires identically either way.
+ */
+export declare function updateStatus<U>(msg: string | StatusPhase, cb: StatusCallback | undefined, fn: () => U | Promise<U>, stopToken?: StopToken): Promise<U>;
+/**
+ * A determinate reading on the status channel: a phase label plus how far
+ * through it the operation is. The loading UI renders the message and a bar.
+ */
+export interface StatusWithProgress {
+    message: string;
+    current: number;
+    total: number;
+    /** see {@link StatusPhase} */
+    source?: string;
+}
+/**
+ * A phase label that also names what it is waiting on — the URL of the file
+ * being fetched, so a load that hangs can say which server stopped answering
+ * rather than leaving "Downloading chromosome aliases" on screen forever.
+ *
+ * A shape of its own rather than a `source` on a bare string, and deliberately
+ * NOT a {@link StatusWithProgress} with a zero total: the aggregate's tie-break
+ * turns on whether a phase has anything to measure (see `measurable`), and a
+ * label that carries a URL has no more measurement than a plain label does.
+ * Given its own shape it votes exactly as the bare string it replaces —
+ * {@link statusReading} skips it, so `live` stays 0 — and a phase downloading
+ * with a real bar still wins the label over one that is only waiting.
+ *
+ * The field is additive on the wire: {@link statusMessageText} and
+ * {@link statusFraction} answer for it exactly as they do for the plain label,
+ * so every existing indicator renders it unchanged and only a consumer that
+ * asks for {@link statusSource} sees the difference.
+ */
+export interface StatusPhase {
+    message: string;
+    source: string;
+}
+/**
+ * The last word of a phase that did not finish: the label its retire leaves on
+ * the channel — the enclosing phase's, or `''` when there was none — plus the
+ * one thing no reading can carry, that the work under it stopped short.
+ *
+ * **The aggregate cannot infer this from the readings**, which is why it is on
+ * the wire. A phase clear and a phase that threw arrive as the same `''`, and on
+ * the per-region fetch path a clear *is* a completion — charging it less than
+ * its total is what made the shared bar run backwards as a batch landed
+ * (ADR-072, and `FetchMixin.test.ts` pins it by name). So the outcome travels as
+ * a value the `finally` writes, and the credit follows the value.
+ *
+ * **A value rather than a second callback argument**, because it has to survive
+ * every `status => cb(status)` forwarder in the tree and the worker's
+ * postMessage: `wrapForRpc` posts one status, and an extra argument would be
+ * dropped in silence at each of those seams.
+ *
+ * A consumer that only understands the falsy-message retire keeps working:
+ * `message` is the same string it would have been handed, so
+ * {@link statusMessageText} and {@link statusFraction} answer exactly as they do
+ * for a bare `''`. The marker is read by the first {@link createStatusAggregate}
+ * it reaches, which credits the retiring phase what it transferred and then
+ * stores the plain message — so it never reaches a display's status field.
+ */
+export interface PhaseFailure {
+    message: string;
+    failed: true;
+}
+export type RpcStatus = string | StatusWithProgress | StatusPhase | PhaseFailure;
+/**
+ * The single out-of-band status transport carried across the RPC boundary. A
+ * plain string is an indeterminate phase label; a {@link StatusWithProgress}
+ * adds a determinate fraction. Adapters wrap raw byte/block/feature counts into
+ * this; the loading UI renders the message and (when present) a progress bar.
+ */
+export type StatusCallback = (status: RpcStatus) => void;
+/**
+ * The determinate reading in `status`, or undefined when there is none — a bare
+ * label, a {@link StatusPhase}, or the last word of a phase that threw. The one
+ * place the transport's union is narrowed to a `current`/`total`, so a consumer
+ * reading the numbers cannot mistake a label or a {@link PhaseFailure} for a
+ * measurement. It tests for the numbers themselves rather than excluding the
+ * shapes that lack them, so a shape added later is out until it opts in.
+ */
+export declare function statusReading(status: RpcStatus | undefined): StatusWithProgress | undefined;
+/**
+ * What `status` says it is waiting on, or undefined when it names nothing — a
+ * label with no {@link StatusPhase} source, and every reading that arrived
+ * before one was attached. The URL is what a stalled phase has to show; see
+ * {@link StatusPhase}.
+ */
+export declare function statusSource(status: RpcStatus | undefined): string | undefined;
+/**
+ * The phase a status names, verbatim — its label, whichever shape it arrived in.
+ * The raw form, `''` and all, for the few places that have to reason about the
+ * sentinel itself, or that are rebuilding a phase around the label they were
+ * handed. Everywhere else wants {@link statusMessageText}.
+ */
+export declare function phaseOf(status: RpcStatus): string;
+/**
+ * Extract the human-readable text from any status value, or `undefined` when
+ * there is none.
+ *
+ * `''` is none: it is the phase-over sentinel, not a label. Normalizing it here
+ * leaves one spelling of "nothing to show" for the three models that store a
+ * `statusMessage` (`assembly`, `BaseDisplayModel`, `FetchMixin`) — otherwise a
+ * reset's `undefined` and a phase's `''` read the same on screen
+ * (`message || 'Loading'`) and differently to everything else.
+ *
+ * The corollary binds anything that *transforms* a status: rewriting `''` into
+ * any other string — a prefix, a default — makes a phase that never ends, since
+ * a slot's last word is what {@link aggregateStatus} weighs. `levelStatusCallback`
+ * in `runDiagonalize.ts` is the one transformer in the tree.
+ */
+export declare function statusMessageText(status: RpcStatus | undefined): string | undefined;
+/**
+ * Fraction complete in [0,1], or undefined when the status is indeterminate
+ * (a plain string, or a zero total).
+ */
+export declare function statusFraction(status: RpcStatus | undefined): number | undefined;
+/**
+ * One operation's stream through a {@link StatusWindow}, and the last word that
+ * ends it. They come back together because **every operation must retire its
+ * own slot when its work ends**: neither a window nor a fan-out can see the end
+ * of a batch and neither guesses at one (ADR-080), so a stream nobody closes
+ * goes on voting for a phase that is over.
+ */
+export interface StatusStream {
+    /** The RPC `statusCallback` for this operation. */
+    statusCallback: StatusCallback;
+    /**
+     * This operation's last word: retires its slot, re-derives the field from the
+     * operations still running, and blanks it when this was the last of them.
+     * Call it once, in the `finally` of the operation this stream describes.
+     *
+     * **Retiring, not blanking**, which is the difference a display with two
+     * concurrent operations turns on (ADR-081). The blank still lands unthrottled
+     * and drops what was queued behind it, because nothing is coming to displace
+     * the last label of a fetch that is over.
+     *
+     * It is not guarded by `isCurrent`: a run that has just finished is no longer
+     * current, and a superseded run must retire its slot too or it votes forever.
+     */
+    clear: () => void;
+}
+/**
+ * One owner's status field: the throttle window in front of it, the slot each
+ * concurrent operation writes into, and the aggregate that arbitrates between
+ * them.
+ *
+ * All three are one object so the cardinality rule has only one spelling: **one
+ * window per owner, N streams on it, one field**. That is what makes a
+ * display's parallel per-region fetches thin to one flow between them rather
+ * than to N, and what stops its viewport fetch and its bare-autorun fetch
+ * clobbering each other (ADR-081).
+ */
+export interface StatusWindow {
+    /**
+     * Open a stream for one operation: a {@link StatusCallback} recording into
+     * this operation's own slot, skipped entirely once `isCurrent()` goes false —
+     * a superseded fetch, or a torn-down model — plus the `clear` that retires it.
+     *
+     * `isCurrent` is read twice on purpose. Once before the window, so a
+     * superseded fetch's late status can't consume the slot a live one is waiting
+     * on; once inside, because a trailing write fires on a timer and the
+     * operation it belongs to can be gone by then.
+     *
+     * Opening on an idle window reopens the throttle, so the first operation to
+     * start after a lull reports at once rather than being charged a window it
+     * did nothing to earn. An owner therefore never resets by hand around a
+     * fetch; `reset` is for teardown.
+     *
+     * **Every status goes through the window, the `''` closing a phase
+     * included** (ADR-071), so a phase that opens and closes inside one paints
+     * nothing. The window holds a single pending write, so that `''` still
+     * displaces the percentage queued behind it and a finished phase's progress
+     * cannot reappear.
+     */
+    open: (args: {
+        isCurrent: () => boolean;
+    }) => StatusStream;
+    /**
+     * Drop the queued trailing write and reopen the throttle. For the owner's
+     * teardown, where the timer outlives everything that could make it a no-op —
+     * jest reports the surviving timer as a worker that will not exit.
+     */
+    reset: () => void;
+}
+/**
+ * Thin one channel's status emits at the *source*, for a transport that pays
+ * per message.
+ *
+ * {@link createStatusWindow} already throttles what reaches a display's status
+ * field, but it runs on the main thread: every emit the worker made still cost
+ * a postMessage, a task and a structured clone to get there and be dropped. A
+ * scroll-zoom measured 9,668 of those in ten seconds — 23% of the main thread's
+ * busy time — for the ~100 statuses the window let through.
+ *
+ * What it drops is only ever an intermediate reading of a phase a later reading
+ * of the same phase supersedes, so {@link createStatusAggregate} is unaffected:
+ * it takes the latest reading per slot, and credits a phase its total only when
+ * the *label* changes. A change of label — including the `''` retire — and a
+ * {@link PhaseFailure} therefore go through untouched, and a reading queued
+ * behind the window is flushed ahead of the label that supersedes it so the
+ * transition still carries the phase's own last numbers.
+ */
+export declare function throttleStatusEmits(emit: StatusCallback): (status: RpcStatus) => void;
+/**
+ * Open a {@link StatusWindow} over one status field. `write` is that field's
+ * **only** writer, statuses and the closing blank alike, so whatever guards it
+ * — `isAlive(self)`, a React `alive` flag — guards every one of them by
+ * construction rather than by a copy of the check at each `finally`.
+ *
+ * Leading-edge, so sparse updates pass straight through and dense bursts are
+ * thinned; trailing as well, so the last write of a phase always lands — it is
+ * the one that matters most and exactly the one a leading-edge-only gate drops.
+ *
+ * Create **one per owner** — a display, a dialog run, an assembly load — and
+ * take every one of that owner's status callbacks off it as a stream. The
+ * streams are slots in one aggregate, so the owner's two concurrent operations
+ * arbitrate for the field the same way one fetch's parallel regions do, and
+ * neither ends the other's label (ADR-081).
+ *
+ * Deliberately wraps only the *callback* path, never `setStatusMessage` itself
+ * — a display writing a phase label by hand ("Downloading" → "Parsing") is a
+ * sequence of distinct labels, and a trailing edge only guarantees the *last*
+ * of a burst, not each one in turn.
+ *
+ * Both fetch families own one: `FetchMixin` for the LGV displays, and
+ * `createStopTokenRotation` for the bare-autorun fetches (dotplot, synteny)
+ * that compose no fetch mixin — and a display that has both lends the mixin's
+ * to the rotation rather than opening a second on one field. A plain function
+ * rather than shared model state because the two families declare their status
+ * fields separately and one set shadows the other — see ADR-041.
+ */
+export declare function createStatusWindow(write: (status: RpcStatus | undefined) => void): StatusWindow;
+/**
+ * Format a phase label with a rounded percentage appended when a determinate
+ * `fraction` is present (e.g. `progressLabel('Downloading', 0.45)` →
+ * `"Downloading 45%"`). The single place the `X%` suffix is formatted: both
+ * {@link statusProgressLabel} (RpcStatus callers) and the loading
+ * overlays/indicators — which hold the message and fraction already split apart
+ * onto the model — route through it, so no caller hand-rolls `Math.round`.
+ */
+export declare function progressLabel(message: string | undefined, fraction: number | undefined): string;
+/**
+ * {@link progressLabel} for an {@link RpcStatus}: the message, with a rounded
+ * percentage appended when the status is determinate (e.g. `"Downloading 45%"`).
+ * The form the loading dialogs use, holding the raw status object.
+ */
+export declare function statusProgressLabel(status: RpcStatus | undefined): string;
+/**
+ * Adapt the byte-granularity download callback exposed by the readers
+ * (generic-filehandle2 `readFile`, @gmod/tabix `getLines`, @gmod/bam /
+ * @gmod/cram `getRecordsForRange`) to the structured {@link StatusCallback}
+ * transport, labelling each tick with `message`. Returns undefined when there's
+ * no `statusCallback`, so the reader can skip its progress bookkeeping entirely.
+ *
+ * **That skip is not a saving**, which is the opposite of what the shape
+ * suggests. Handed an `onProgress`, generic-filehandle2 streams the body into
+ * one pre-sized buffer; handed none it calls `res.bytes()` — and in a Chrome
+ * worker the streaming read is roughly 1.8x *faster* up to 10MB, giving that
+ * back only past ~25MB. So withholding this reporter honors a caller who asked
+ * for no reporting; it is never about speed. Numbers and the bench that retakes
+ * them:
+ * agent-docs/measurements/download-read-path.json.
+ *
+ * `total` is optional because not every reader knows the size up front
+ * (generic-filehandle2 omits it when the response has no Content-Length): with a
+ * total we emit a determinate bar, without one we emit just the label so the UI
+ * still shows the phase as an indeterminate spinner.
+ *
+ * Internal to this module — the only caller is {@link downloadStatus}, which is
+ * the API adapters use. Kept separate purely so the reporter logic reads on its
+ * own line.
+ */
+declare function downloadStatusReporter(statusCallback: StatusCallback | undefined, label: string | StatusPhase): ((current: number, total?: number) => void) | undefined;
+/**
+ * Run a download phase whose reader counts its own progress. Shows `label`,
+ * hands `fn` the {@link downloadStatusReporter} to pass straight to the
+ * reader's `onProgress` (its ticks upgrade the same label to a determinate
+ * bar), then clears the status. Combines {@link updateStatus} with the reporter
+ * so the label is written in exactly one place — the phase label and the
+ * progress label can't drift apart.
+ *
+ * The unit is whatever the reader counts, and the caller does not have to know
+ * which: bytes for the index readers, blocks and expected-value chunks for
+ * `@gmod/hic`. All of them report `(current, total?)`.
+ *
+ * `stopToken` makes the phase a cancellation boundary, exactly as it does on
+ * {@link updateStatus} — `fn` is checked on both sides of its await.
+ *
+ * A {@link StatusPhase} `label` carries its source onto the readings too, so a
+ * download that stalls part-way through still names the file it was reading.
+ */
+export declare function downloadStatus<T>(label: string | StatusPhase, statusCallback: StatusCallback | undefined, fn: (onProgress: ReturnType<typeof downloadStatusReporter>) => T | Promise<T>, stopToken?: StopToken): Promise<T>;
+/**
+ * One concurrent operation's contribution to a fan-out's shared status: what it
+ * is reporting right now, plus how much of each phase it has already finished
+ * (see {@link createStatusFanOut}, which is what records them).
+ *
+ * `completed` is a total per phase, not the phases themselves: a finished phase
+ * is charged to both halves of the fraction, so its own `current` was only ever
+ * its `total` written twice.
+ */
+export interface StatusSlot {
+    status: RpcStatus | undefined;
+    completed: Map<string, number>;
+}
+/**
+ * Combine the in-flight statuses of several concurrent operations (one RPC per
+ * visible region, say) into the single status the loading UI shows, so N regions
+ * read as one bar instead of each clobbering the shared field. Returns undefined
+ * when nothing is in flight.
+ *
+ * **Only operations in the same phase are summed.** `current`/`total` are
+ * additive within a phase — bytes with bytes, features with features — and
+ * incommensurable across one, so one phase wins and the rest are charged below
+ * (ADR-072). A fan-out whose slots share one phase, the common case, is a plain
+ * Σcurrent/Σtotal.
+ *
+ * **The phase that wins is the earliest one the batch is still in** (ADR-080). A
+ * batch is in every phase any of its operations is in — the phase that operation
+ * last *reported*, not the one it happens to be measuring this instant — and it
+ * leaves one when its LAST operation does. So the label moves forward once per
+ * phase, in order, and the bar under it is that phase's own.
+ *
+ * Rank alone would hand the label to a phase with nothing to say, so a phase the
+ * batch has anything to measure in — a reading now, or work already finished —
+ * beats one it does not. `phaseRank` is the fan-out's record of first
+ * appearance; with none, every phase ranks the same and the choice falls back to
+ * slot order.
+ *
+ * Each slot is then priced against the winning phase on its own, which is why
+ * this cannot be a Σ over two flat lists:
+ *
+ * - measuring it: its own `current`/`total`, plus whatever it already finished
+ *   of that phase, in both halves.
+ * - not measuring it but having finished some: that finished work in both halves
+ *   and **nothing more** — never the mean as well, or the bar falls every time a
+ *   region moves on.
+ * - neither: in flight with nothing comparable to measure, so charged the mean
+ *   of the totals we do know with nothing completed against it. That covers a
+ *   response with no Content-Length and a slot in another phase alike; dropping
+ *   either outright reads 100% while it is still downloading.
+ *
+ * A winning phase nothing is measuring right now comes back as its label alone —
+ * summing what its slots retired at reads 100% for a batch that is still
+ * working, and every slot being between reads is exactly when that happens.
+ * {@link createStatusFanOut} re-sends the phase's last real reading instead.
+ *
+ * A retired slot (`''` or nothing yet) never votes and is never charged the
+ * mean; charging it at zero is a bar that runs *backwards* as regions finish.
+ * Its finished work still counts, which is what keeps the fraction rising as the
+ * batch lands.
+ */
+export declare function aggregateStatus(slots: StatusSlot[], phaseRank?: Map<string, number>): RpcStatus | undefined;
+/**
+ * Fan one status field out to several concurrent operations that would
+ * otherwise fight over it. Each `slot()` returns a {@link StatusCallback}
+ * remembering its own latest value and how much of each phase it has been
+ * through; every write re-derives the shared status from all slots through
+ * {@link aggregateStatus}, so N concurrent downloads read as one bar instead of
+ * last-writer-wins — and the first one to finish (which writes the `''` every
+ * phase helper clears with) can't blank the label while the others are still
+ * running.
+ *
+ * Use it wherever several operations are handed one `statusCallback` at once —
+ * a `Promise.all`, an rxjs `merge`, or the per-region fan-out the LGV displays'
+ * `callEachRegion` builds over a fetch context. One fan-out per batch: slots are
+ * taken for the batch's lifetime and it is the batch that ends, so a long-lived
+ * one accumulates slots for work that is over.
+ *
+ * **A slot's finished phases are recorded here**, because only a slot's own
+ * channel ever sees the total it retired at, and they are what keep a landing
+ * batch's bar from walking backwards. A phase is over the moment the slot stops
+ * reporting it forward — see {@link continuesPhase}; the `''` it ends on is only
+ * one of the ways it can say so.
+ *
+ * **It never writes `''`.** A slot between two phases and a slot that is done
+ * both read as idle from here, so an empty aggregate means "no slot is reporting
+ * this instant", not "the batch is over". What goes out is the last label alone,
+ * with no bar — which is what that state is. The end of a batch is the owner's
+ * to declare (ADR-080): every one of them clears its field when its work ends.
+ *
+ * Something rather than nothing, because a write that lands is also how a
+ * phase's last progress value is *displaced* — statuses are throttled, so a
+ * percentage queued behind the window would otherwise fire after the work it
+ * measured had ended (ADR-071).
+ *
+ * **A phase does not lose its bar because nothing is measuring it this
+ * instant.** Between reads a slot reports the label alone, and when every slot
+ * is between reads at once the aggregate has no measurement — a determinate bar
+ * would drop to an indeterminate spinner and return a tick later. The phase's
+ * last reading is held and re-sent instead, and dropped the moment the phase
+ * changes.
+ */
+export declare function createStatusFanOut(statusCallback: StatusCallback | undefined): () => StatusCallback;
+/**
+ * Call once per outer-loop iteration. With no argument it auto-increments an
+ * internal counter (the elegant default — `for (…) report()`); pass an explicit
+ * `current` when the caller tracks its own position, e.g. a running offset that
+ * spans several batches.
+ */
+export type ProgressReporter = (current?: number) => void;
+/**
+ * The single per-iteration callback for long synchronous worker loops. The
+ * returned `report(current)` is called once per outer-loop iteration and does
+ * two throttled jobs on each call:
+ *
+ * - checks the stop token via the existing throttled {@link checkStopTokenThrottled}
+ *   machinery, so cancellation interrupts the loop within milliseconds instead
+ *   of only at phase boundaries, and
+ * - emits a {@link StatusWithProgress} through `statusCallback` at most once per
+ *   `throttleMs`, so the main thread gets a live percentage without flooding
+ *   the postMessage channel.
+ *
+ * Both jobs are optional: with no `statusCallback`/`total` this is purely a
+ * throttled cancellation tick, so a loop has exactly one inner callback whether
+ * or not it drives the progress UI.
+ *
+ * Emission is gated on wall-clock time (`throttleMs`) through {@link
+ * createTimeGate}, which thins the `Date.now()` reads as well as the emits —
+ * see there for why its stride is learned rather than fixed. Keep the loop a
+ * plain `for` and call `report()` once per item (it owns the counter), or
+ * `report(n)` for an explicit position.
+ */
+export declare function createProgressReporter({ label, total, statusCallback, stopToken, stopTokenCheck, throttleMs, }: {
+    label?: string;
+    total?: number;
+    statusCallback?: (status: RpcStatus) => void;
+    stopToken?: StopToken;
+    stopTokenCheck?: StopTokenChecker;
+    throttleMs?: number;
+}): ProgressReporter;
+/**
+ * Run a measurable phase: shows `label` at 0%, hands `fn` a {@link
+ * ProgressReporter} to drive during the work, then checks the stop token once
+ * more and restores the enclosing phase. The determinate counterpart to
+ * `updateStatus`, and it nests the same way — see {@link openPhase}.
+ */
+export declare function withProgress<T>({ label, total, statusCallback, stopToken, }: {
+    label: string;
+    total: number;
+    statusCallback?: (status: RpcStatus) => void;
+    stopToken?: StopToken;
+}, fn: (report: ProgressReporter) => T | Promise<T>): Promise<T>;
+export {};