@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/tabix.js

@@ -0,0 +1,148 @@
+import { createStatusFanOut, downloadStatus } from './progress.js';
+import { calculateRedispatchRange } from './range.js';
+/**
+ * Read the feature type (column 3) from a raw GFF3/GTF line without a full
+ * split. Used only to classify a line for redispatch.
+ */
+function extractType(line) {
+    const t1 = line.indexOf('\t');
+    const t2 = t1 === -1 ? -1 : line.indexOf('\t', t1 + 1);
+    const t3 = t2 === -1 ? -1 : line.indexOf('\t', t2 + 1);
+    // a truncated line has no column 3 to read; a final column 3 (no trailing
+    // tab) runs to the end of the line rather than one character short of it
+    return t2 === -1 ? '' : line.slice(t2 + 1, t3 === -1 ? line.length : t3);
+}
+/**
+ * Fetch the tabix lines for a region under a "Downloading features" progress
+ * label, capturing each line's byte offset, indexed start/end, and feature type
+ * into a {@link TabixLine}. Shared by the GFF3 and GTF tabix adapters.
+ *
+ * The signal becomes the read's `AbortSignal`, so a cancelled fetch drops
+ * its block reads at the socket instead of downloading them and discarding the
+ * lines. @gmod/tabix aborts a block shared between callers only once every
+ * joined caller has aborted (`AggregateAbortController`), so this can't cancel a
+ * chunk another region still needs.
+ */
+export function readTabixLines(gff, refName, start, end, statusCallback, signal) {
+    const lines = [];
+    return downloadStatus('Downloading features', statusCallback, onProgress => gff.getLines(refName, start, end, {
+        lineCallback: (line, offset, s, e) => {
+            lines.push({
+                line,
+                offset,
+                start: s,
+                end: e,
+                type: extractType(line),
+            });
+        },
+        onProgress,
+        signal,
+    })).then(() => lines);
+}
+/**
+ * Read a region's tabix lines, then — if any feature found there extends past
+ * the query — read the overhang on either side, so a parent line's children (a
+ * gene's exons, a transcript's CDS) outside the original window are pulled in
+ * and the parent/child tree resolves fully. `expands` decides which lines widen
+ * the bound, so one chromosome-spanning record can't force a whole-chromosome
+ * refetch; {@link calculateRedispatchRange} says why that is a predicate.
+ *
+ * **There is one control, and skipping the expansion is a value of it**: an
+ * `expands` that admits nothing reads the query and stops. A caller that wants
+ * that says so to its adapter, which is the layer that knows whether its format
+ * can honour it — see `Gff3TabixAdapter`, and `GtfTabixAdapter` for a format
+ * that cannot.
+ *
+ * **The flanks, not the union.** Re-reading `[minStart, maxEnd]` returns
+ * everything the first read already had — a second full read of the query range
+ * to collect a gene's tail. At the window sizes a GFF3 track is browsed at that
+ * is most of the work done twice, and it is the reason the download bar halved:
+ * the expansion arrived as a second phase whose total was the whole region
+ * again, so a region that had just reported 100% dropped to 50% and climbed back
+ * (measured: two `65536/65536` phases for one query). Reading only what is
+ * missing leaves the second phase the size of the overhang.
+ *
+ * The line sequence is unchanged by that. Tabix returns the lines *overlapping*
+ * a range, so the three ranges' lines are the union range's lines, with the ones
+ * straddling a boundary appearing twice; `offset` is a line's position in the
+ * file, so deduplicating and sorting on it reconstructs file order — which for
+ * an indexed file is coordinate order — exactly.
+ *
+ * The two flanks are read concurrently and so need a status slot each, or they
+ * take turns overwriting one label. Exactly one expansion happens: a flank's own
+ * overhang is not chased, which bounds the work at three reads per query and
+ * usually two.
+ *
+ * Shared by the GFF3 and GTF tabix adapters, which differ only in how they
+ * parse the returned lines.
+ */
+export async function readTabixLinesRedispatched(file, 
+// the region's locus only — kept structural, like TabixLineSource above, so
+// this module stays free of the `types` barrel and its MST models
+query, expands, opts = {}) {
+    const { statusCallback, signal } = opts;
+    // `cb` is not optional: each read decides where it reports, and the flanks
+    // report somewhere the first read does not
+    const read = (start, end, cb) => readTabixLines(file, query.refName, start, end, cb, signal);
+    const lines = await read(query.start, query.end, statusCallback);
+    const redispatch = calculateRedispatchRange(lines, expands, query.start, query.end);
+    if (redispatch) {
+        const slot = createStatusFanOut(statusCallback);
+        const flanks = await Promise.all([
+            redispatch.start < query.start
+                ? read(redispatch.start, query.start, slot())
+                : [],
+            redispatch.end > query.end ? read(query.end, redispatch.end, slot()) : [],
+        ]);
+        return mergeTabixLines(lines, ...flanks);
+    }
+    return lines;
+}
+/**
+ * The lines of several overlapping reads as one file-ordered run, each line
+ * once. Keyed on `offset` because that is what a line *is* — its position in the
+ * file — so a line two ranges both returned collapses to one entry and the sort
+ * puts the whole set back in the order a single read over their union would have
+ * produced.
+ */
+function mergeTabixLines(...groups) {
+    const byOffset = new Map();
+    for (const group of groups) {
+        for (const line of group) {
+            byOffset.set(line.offset, line);
+        }
+    }
+    return [...byOffset.values()].sort((a, b) => a.offset - b.offset);
+}
+/**
+ * The header lines of a tabix-indexed file, however that file kept them.
+ *
+ * `getHeader()` alone is not that: it returns only lines beginning with the
+ * index's meta character (`#`). A header that is a plain row — which is what
+ * `tabix -S N` exists for, and what PLINK `.ld`, bedGraph and BED deflines
+ * routinely are — comes back as the empty string, even though the index records
+ * N in `skipLines`.
+ *
+ * Reading both is not backwards compatibility, and does not become unnecessary
+ * once our own files are written with commented headers. A bare header is the
+ * shape the data's publisher chose: Pan-UKB's TSVs and PLINK's `.ld` are
+ * distributed that way, and `-S N` is the only way to index one without
+ * rewriting a file the user did not write. Advice about how to generate a file
+ * reaches the files we generate; this reaches the rest.
+ *
+ * An adapter that stops at `getHeader()` therefore cannot tell "this file has
+ * no header" from "this file's header is not commented", and quietly falls back
+ * to an assumed column layout. That has cost real information more than once: a
+ * PLINK LD file lost its D' column, so `ldMetric: 'dprime'` silently served r²,
+ * and a bedGraph loses the names of its value columns. Nothing errors, because
+ * the assumed layout parses.
+ *
+ * That policy now lives in @gmod/tabix 3.5.4 as getHeaderLines, next to the
+ * index metadata that decides it, so this is a delegate. Deciding it there also
+ * costs one read of the file's leading blocks rather than two: asking for the
+ * commented block and then the counted rows used to fetch and decompress the
+ * same bytes twice, which every bare-header file did on every call.
+ */
+export function readTabixHeaderLines(file) {
+    return file.getHeaderLines();
+}

package/esm/util/tags.d.ts

@@ -0,0 +1,2 @@
+export declare const tagRegex: RegExp;
+export declare function isValidTag(tag: string): boolean;

package/esm/util/tags.js

@@ -0,0 +1,5 @@
+// A SAM tag is two characters: a letter followed by a letter or digit.
+export const tagRegex = /^[A-Za-z][A-Za-z0-9]$/;
+export function isValidTag(tag) {
+    return tagRegex.test(tag);
+}

package/esm/util/temporaryAssembly.d.ts

@@ -0,0 +1,21 @@
+import type { AnyConfigurationModel } from '../configuration/index.ts';
+/**
+ * Whether a track config names an assembly the session holds as **temporary** —
+ * the read-vs-ref pair a comparative view synthesizes, which goes away when that
+ * view closes (`releaseTemporaryAssemblies`).
+ *
+ * `some`, not `every`: a config half of whose assemblies survive is still one
+ * nothing can draw once the other half is gone, and unlike a sweep that DELETES
+ * a config this question never has to decide whose it is. The `every`/`some`
+ * distinction is what made the session-track sweep ADR-084 removed a judgment
+ * call; a question asked at the moment of the write has no such problem.
+ *
+ * Down here rather than beside the contract check that started it
+ * (`product-core/Session/temporaryAssemblyTracks.ts`) because two callers now
+ * ask it and they are on opposite sides of the dependency: the check and the
+ * track menu's copy guard in product-core, and `addTrackFromWidget` in this
+ * package, which routes a track around the session lists entirely when the
+ * answer is yes. A second copy of the predicate is the thing to avoid — a copied
+ * guard is where the escape clause gets added to only one of them.
+ */
+export declare function namesTemporaryAssembly(session: unknown, trackConf: AnyConfigurationModel | Record<string, unknown>): boolean;

package/esm/util/temporaryAssembly.js

@@ -0,0 +1,29 @@
+import { readConfObject } from '../configuration/index.js';
+/**
+ * Whether a track config names an assembly the session holds as **temporary** —
+ * the read-vs-ref pair a comparative view synthesizes, which goes away when that
+ * view closes (`releaseTemporaryAssemblies`).
+ *
+ * `some`, not `every`: a config half of whose assemblies survive is still one
+ * nothing can draw once the other half is gone, and unlike a sweep that DELETES
+ * a config this question never has to decide whose it is. The `every`/`some`
+ * distinction is what made the session-track sweep ADR-084 removed a judgment
+ * call; a question asked at the moment of the write has no such problem.
+ *
+ * Down here rather than beside the contract check that started it
+ * (`product-core/Session/temporaryAssemblyTracks.ts`) because two callers now
+ * ask it and they are on opposite sides of the dependency: the check and the
+ * track menu's copy guard in product-core, and `addTrackFromWidget` in this
+ * package, which routes a track around the session lists entirely when the
+ * answer is yes. A second copy of the predicate is the thing to avoid — a copied
+ * guard is where the escape clause gets added to only one of them.
+ */
+export function namesTemporaryAssembly(session, trackConf) {
+    const temporary = session
+        .temporaryAssemblies;
+    if (!temporary?.length) {
+        return false;
+    }
+    const names = readConfObject(trackConf, 'assemblyNames');
+    return !!names?.some(name => temporary.some(a => a.name === name));
+}

package/esm/util/thresholdScale.d.ts

@@ -0,0 +1,91 @@
+import type { CategoricalScale } from '../ui/colorScale.ts';
+import type { CategoricalField } from './categoricalField.ts';
+/**
+ * #api
+ * A domain written as strings — the shared `domain` slot is a `stringArray` —
+ * read back as the numbers it names. A member that is not a number reads NaN,
+ * which every comparison against it declines.
+ */
+export declare function numericDomain(domain: readonly (string | number)[]): number[];
+/**
+ * #api
+ * A threshold scale's cut points as {@link thresholdIndex} walks them: the
+ * numbers the domain names, ascending. Cuts written high to low, as p-value
+ * thresholds often are, left the middle interval unreachable, the walk stopping
+ * at the first cut a value is under.
+ */
+export declare function thresholdCuts(domain: readonly (string | number)[]): number[];
+/**
+ * #api
+ * The bin a value falls in: how many of the ascending cut points it is at or
+ * past, so a palette with one more entry than the domain paints it as
+ * `palette[thresholdIndex(value, domain)]`. A value that is not a number is
+ * in no bin and answers -1; an infinite one takes the end bin on its side, as
+ * d3's threshold scale places it, so a `-log10` of a zero p-value lands in
+ * the top bin.
+ */
+export declare function thresholdIndex(value: unknown, domain: readonly number[]): number;
+/**
+ * #api
+ * The colour of each interval, in order: the declared palette, and the
+ * default categorical palette where it runs out.
+ */
+export declare function thresholdPalette(bins: number, palette?: readonly string[]): string[];
+/**
+ * #api
+ * What a threshold scale's bins are called in a key, one label per palette
+ * entry: `< a` below the first cut, `a – b` between two, `≥ b` past the last.
+ */
+export declare function thresholdLabels(domain: readonly number[]): string[];
+/**
+ * #api
+ * The key a value holding text that is no number files under on a threshold
+ * scale, painted the misconfiguration grey rather than passing for a missing
+ * value.
+ */
+export declare const NOT_A_NUMBER_LABEL = "(not a number)";
+/**
+ * #api
+ * A threshold key's rows: every interval, painted or not, since the bins are
+ * the whole domain, then the not-a-number and no-value rows where a feature
+ * took one, in the order `thresholdField` sorts them.
+ */
+export declare function thresholdKeyEntries(cuts: readonly number[], range: readonly string[] | undefined, met: {
+    missing?: boolean;
+    notNumber?: boolean;
+}, names?: readonly string[]): {
+    value: string;
+    label: string;
+    color: string;
+    missing?: true;
+}[];
+/**
+ * #api
+ * The rows a ramp's key lists beside its bar once a feature painted one: the
+ * not-a-number and no-value rows a threshold's key ends with. Empty while
+ * neither painted.
+ */
+export declare function rampGapScales(id: string, met: {
+    missing?: boolean;
+    notNumber?: boolean;
+}): CategoricalScale[];
+/**
+ * #api
+ * Whether a field holds no value at all, as against text that fails to parse:
+ * absent, empty, or a VCF's `AF=.`, which arrives as `[undefined]`.
+ */
+export declare function isMissing(value: unknown): boolean;
+/**
+ * #api
+ * A threshold scale read the way every categorical channel reads its field: a
+ * value files under the label of the bin it falls in, a feature with no value
+ * under `''`, and text that is no number under {@link NOT_A_NUMBER_LABEL}.
+ * The bins are the whole domain, so a key lists each one. `labels` names the
+ * bins in a key, one each from the lowest, where a config spells them for a
+ * reader; a bin's key stays its interval.
+ */
+export declare function thresholdField(field: string, { domain, range, labels: names, }?: {
+    domain?: readonly string[];
+    range?: readonly string[];
+    labels?: readonly string[];
+}): CategoricalField;

package/esm/util/thresholdScale.js

@@ -0,0 +1,166 @@
+import { categoricalPalette } from '../ui/colors.js';
+import { NO_VALUE_LABEL, keyNames } from './categoricalField.js';
+import { MISCONFIGURED_COLOR, NO_CATEGORY_COLOR } from './color/index.js';
+import { groupKeyComparator, valueText } from './groupKeys.js';
+import { numericValue } from './numericValue.js';
+/**
+ * #api
+ * A domain written as strings — the shared `domain` slot is a `stringArray` —
+ * read back as the numbers it names. A member that is not a number reads NaN,
+ * which every comparison against it declines.
+ */
+export function numericDomain(domain) {
+    return domain.map(Number);
+}
+/**
+ * #api
+ * A threshold scale's cut points as {@link thresholdIndex} walks them: the
+ * numbers the domain names, ascending. Cuts written high to low, as p-value
+ * thresholds often are, left the middle interval unreachable, the walk stopping
+ * at the first cut a value is under.
+ */
+export function thresholdCuts(domain) {
+    return numericDomain(domain)
+        .filter(cut => Number.isFinite(cut))
+        .sort((a, b) => a - b);
+}
+/**
+ * #api
+ * The bin a value falls in: how many of the ascending cut points it is at or
+ * past, so a palette with one more entry than the domain paints it as
+ * `palette[thresholdIndex(value, domain)]`. A value that is not a number is
+ * in no bin and answers -1; an infinite one takes the end bin on its side, as
+ * d3's threshold scale places it, so a `-log10` of a zero p-value lands in
+ * the top bin.
+ */
+export function thresholdIndex(value, domain) {
+    const v = numericValue(value);
+    if (Number.isNaN(v)) {
+        return -1;
+    }
+    let i = 0;
+    while (i < domain.length && v >= domain[i]) {
+        i++;
+    }
+    return i;
+}
+/**
+ * #api
+ * The colour of each interval, in order: the declared palette, and the
+ * default categorical palette where it runs out.
+ */
+export function thresholdPalette(bins, palette = []) {
+    return Array.from({ length: bins }, (_, i) => palette[i] ?? categoricalPalette[i % categoricalPalette.length]);
+}
+/**
+ * #api
+ * What a threshold scale's bins are called in a key, one label per palette
+ * entry: `< a` below the first cut, `a – b` between two, `≥ b` past the last.
+ */
+export function thresholdLabels(domain) {
+    if (domain.length === 0) {
+        return ['any value'];
+    }
+    return [
+        `< ${domain[0]}`,
+        ...domain.slice(1).map((cut, i) => `${domain[i]} – ${cut}`),
+        `≥ ${domain.at(-1)}`,
+    ];
+}
+/**
+ * #api
+ * The key a value holding text that is no number files under on a threshold
+ * scale, painted the misconfiguration grey rather than passing for a missing
+ * value.
+ */
+export const NOT_A_NUMBER_LABEL = '(not a number)';
+/**
+ * #api
+ * A threshold key's rows: every interval, painted or not, since the bins are
+ * the whole domain, then the not-a-number and no-value rows where a feature
+ * took one, in the order `thresholdField` sorts them.
+ */
+export function thresholdKeyEntries(cuts, range, met, names = []) {
+    const labels = thresholdLabels(cuts);
+    const colors = thresholdPalette(labels.length, range);
+    return [
+        ...labels.map((label, i) => ({
+            value: label,
+            label: names[i] ?? label,
+            color: colors[i],
+        })),
+        ...(met.notNumber
+            ? [
+                {
+                    value: NOT_A_NUMBER_LABEL,
+                    label: NOT_A_NUMBER_LABEL,
+                    color: MISCONFIGURED_COLOR,
+                },
+            ]
+            : []),
+        ...(met.missing
+            ? [
+                {
+                    value: '',
+                    label: NO_VALUE_LABEL,
+                    color: NO_CATEGORY_COLOR,
+                    missing: true,
+                },
+            ]
+            : []),
+    ];
+}
+/**
+ * #api
+ * The rows a ramp's key lists beside its bar once a feature painted one: the
+ * not-a-number and no-value rows a threshold's key ends with. Empty while
+ * neither painted.
+ */
+export function rampGapScales(id, met) {
+    const entries = thresholdKeyEntries([], undefined, met).slice(1);
+    return entries.length > 0 ? [{ kind: 'categorical', id, entries }] : [];
+}
+/**
+ * #api
+ * Whether a field holds no value at all, as against text that fails to parse:
+ * absent, empty, or a VCF's `AF=.`, which arrives as `[undefined]`.
+ */
+export function isMissing(value) {
+    return Array.isArray(value)
+        ? value.every(v => v === undefined || v === null)
+        : valueText(value) === '';
+}
+/**
+ * #api
+ * A threshold scale read the way every categorical channel reads its field: a
+ * value files under the label of the bin it falls in, a feature with no value
+ * under `''`, and text that is no number under {@link NOT_A_NUMBER_LABEL}.
+ * The bins are the whole domain, so a key lists each one. `labels` names the
+ * bins in a key, one each from the lowest, where a config spells them for a
+ * reader; a bin's key stays its interval.
+ */
+export function thresholdField(field, { domain = [], range = [], labels: names = [], } = {}) {
+    const cuts = thresholdCuts(domain);
+    const labels = thresholdLabels(cuts);
+    const named = keyNames(labels, names);
+    const palette = thresholdPalette(labels.length, range);
+    const colorOf = new Map(labels.map((label, i) => [label, palette[i]]));
+    return {
+        field,
+        domain: labels,
+        closed: true,
+        key: value => {
+            if (isMissing(value)) {
+                return '';
+            }
+            const bin = thresholdIndex(value, cuts);
+            return bin < 0 ? NOT_A_NUMBER_LABEL : labels[bin];
+        },
+        compare: groupKeyComparator([...labels, NOT_A_NUMBER_LABEL]),
+        label: key => (key === '' ? NO_VALUE_LABEL : (named.get(key) ?? key)),
+        sectionLabel: key => `${field}: ${key === '' ? 'none' : key}`,
+        color: key => key === ''
+            ? NO_CATEGORY_COLOR
+            : (colorOf.get(key) ?? MISCONFIGURED_COLOR),
+    };
+}

package/esm/util/tickLabels.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A region needs at least this many coordinate labels to be worth numbering.
+ *
+ * Tick pitch comes from the bpPerPx of the whole displayed-region set, so a
+ * region much narrower than that pitch still catches a tick or two. With every
+ * chromosome displayed at once — a whole-genome overview scalebar, a
+ * whole-genome dotplot axis — each one then ends up with a single lone number
+ * jammed against the next chromosome's refName, and the axis reads as scattered
+ * repeats of the same "500M".
+ *
+ * One coordinate conveys no scale on its own: it gives a reader no spacing to
+ * read a distance off, and sitting alone in a chromosome's span it reads as
+ * marking that span rather than a position inside it. Needing two means narrow
+ * regions show just their refName, and only regions with room for a real ruler
+ * get numbers.
+ */
+export declare const MIN_TICK_LABELS_PER_BLOCK = 2;
+/** Whether a run of `count` coordinate labels in one region is worth drawing. */
+export declare function tickLabelsWorthDrawing(count: number): boolean;
+/**
+ * Drop the labels of every region left with too few of them to read, keeping
+ * those of regions that have a real ruler.
+ *
+ * For a caller holding one flat list across several regions, where the count
+ * has to be taken per region before anything can be decided. A caller that
+ * already works a region at a time wants `tickLabelsWorthDrawing` on its own
+ * length instead.
+ *
+ * `regionOf` returns whatever identifies a region to the caller — an index, a
+ * refName, a block key. A group's labels are dropped together, so that identity
+ * has to separate two regions that can sit side by side on one axis: an axis
+ * may carry the same refName twice (a read-vs-ref dotplot builds one from
+ * gatherOverlaps, so a read aligned twice to a chromosome yields two regions on
+ * it), and keying those together would let one lend the other its quorum.
+ */
+export declare function dropLoneTickLabels<T>(labels: T[], regionOf: (label: T) => unknown): T[];

package/esm/util/tickLabels.js

@@ -0,0 +1,45 @@
+/**
+ * A region needs at least this many coordinate labels to be worth numbering.
+ *
+ * Tick pitch comes from the bpPerPx of the whole displayed-region set, so a
+ * region much narrower than that pitch still catches a tick or two. With every
+ * chromosome displayed at once — a whole-genome overview scalebar, a
+ * whole-genome dotplot axis — each one then ends up with a single lone number
+ * jammed against the next chromosome's refName, and the axis reads as scattered
+ * repeats of the same "500M".
+ *
+ * One coordinate conveys no scale on its own: it gives a reader no spacing to
+ * read a distance off, and sitting alone in a chromosome's span it reads as
+ * marking that span rather than a position inside it. Needing two means narrow
+ * regions show just their refName, and only regions with room for a real ruler
+ * get numbers.
+ */
+export const MIN_TICK_LABELS_PER_BLOCK = 2;
+/** Whether a run of `count` coordinate labels in one region is worth drawing. */
+export function tickLabelsWorthDrawing(count) {
+    return count >= MIN_TICK_LABELS_PER_BLOCK;
+}
+/**
+ * Drop the labels of every region left with too few of them to read, keeping
+ * those of regions that have a real ruler.
+ *
+ * For a caller holding one flat list across several regions, where the count
+ * has to be taken per region before anything can be decided. A caller that
+ * already works a region at a time wants `tickLabelsWorthDrawing` on its own
+ * length instead.
+ *
+ * `regionOf` returns whatever identifies a region to the caller — an index, a
+ * refName, a block key. A group's labels are dropped together, so that identity
+ * has to separate two regions that can sit side by side on one axis: an axis
+ * may carry the same refName twice (a read-vs-ref dotplot builds one from
+ * gatherOverlaps, so a read aligned twice to a chromosome yields two regions on
+ * it), and keying those together would let one lend the other its quorum.
+ */
+export function dropLoneTickLabels(labels, regionOf) {
+    const counts = new Map();
+    for (const label of labels) {
+        const region = regionOf(label);
+        counts.set(region, (counts.get(region) ?? 0) + 1);
+    }
+    return labels.filter(label => tickLabelsWorthDrawing(counts.get(regionOf(label))));
+}

package/esm/util/timeGate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A wall-clock gate for a callback invoked once per item in a long synchronous
+ * loop: `due(intervalMs)` returns true at most once per `intervalMs`, without
+ * calling `Date.now()` on every invocation.
+ *
+ * `Date.now()` costs ~40ns, invisible until the loop is a 666k-read pileup —
+ * there it measured ~28ms per gated callsite, and the alignments worker has two
+ * of them (the progress emit in `createProgressReporter` and the yield in
+ * `createAbortBreakpoint`). Both previously read the clock per call, on the
+ * documented reasoning that it was negligible next to the per-item work; at
+ * this item count it measurably isn't.
+ *
+ * The stride between clock reads is **learned from the observed call rate**,
+ * never fixed. A fixed stride is what regressed this before: a phase with few
+ * but heavy items (a multi-sample VCF region — a few hundred sites, thousands
+ * of samples each) never reached the count, so its progress bar froze at 0% and
+ * its cancellation never fired. A learned stride makes exactly those loops
+ * measure a low rate and hold a stride of 1, gating on time alone as before,
+ * while a millions-of-calls loop thins itself out.
+ *
+ * `intervalMs` is per call rather than fixed at construction; both current
+ * callers pass a constant.
+ */
+export declare function createTimeGate(): (intervalMs: number) => boolean;
+export type TimeGate = ReturnType<typeof createTimeGate>;

package/esm/util/timeGate.js

@@ -0,0 +1,78 @@
+// Target number of `Date.now()` reads per interval. Above 1 so the fire itself
+// doesn't drift late when the call rate rises between two fires: the gate
+// notices the interval has elapsed within ~1/this of it.
+const CLOCK_READS_PER_INTERVAL = 8;
+// Ceiling on the learned stride. The stride is only ever an extrapolation from
+// the last observed call rate, and the gate is blind between clock reads — if
+// per-item cost jumps mid-loop the next read arrives late in wall-clock terms.
+// This caps how blind it can get: a 10x mid-loop slowdown at a stride this size
+// costs about one extra interval, which for a progress emit or a cancellation
+// check is immaterial. At the rates that motivate a gate at all (hundreds of
+// calls per ms) it is never the binding constraint.
+const MAX_STRIDE = 8192;
+// The stride is re-aimed on every clock read, including ones taken part-way
+// through an interval — otherwise the whole first interval runs at stride 1,
+// which for a 666k-call loop is 33k clock reads before the gate learns
+// anything. Those early samples span a short window, so cap how fast the stride
+// may grow: the ramp still reaches MAX_STRIDE in five reads, but one
+// unrepresentatively fast millisecond can't launch the gate straight to blind.
+const STRIDE_GROWTH_LIMIT = 8;
+/**
+ * A wall-clock gate for a callback invoked once per item in a long synchronous
+ * loop: `due(intervalMs)` returns true at most once per `intervalMs`, without
+ * calling `Date.now()` on every invocation.
+ *
+ * `Date.now()` costs ~40ns, invisible until the loop is a 666k-read pileup —
+ * there it measured ~28ms per gated callsite, and the alignments worker has two
+ * of them (the progress emit in `createProgressReporter` and the yield in
+ * `createAbortBreakpoint`). Both previously read the clock per call, on the
+ * documented reasoning that it was negligible next to the per-item work; at
+ * this item count it measurably isn't.
+ *
+ * The stride between clock reads is **learned from the observed call rate**,
+ * never fixed. A fixed stride is what regressed this before: a phase with few
+ * but heavy items (a multi-sample VCF region — a few hundred sites, thousands
+ * of samples each) never reached the count, so its progress bar froze at 0% and
+ * its cancellation never fired. A learned stride makes exactly those loops
+ * measure a low rate and hold a stride of 1, gating on time alone as before,
+ * while a millions-of-calls loop thins itself out.
+ *
+ * `intervalMs` is per call rather than fixed at construction; both current
+ * callers pass a constant.
+ */
+export function createTimeGate() {
+    let stride = 1;
+    let sinceClockRead = 0;
+    let callsSinceFire = 0;
+    let lastFire = 0;
+    return (intervalMs) => {
+        callsSinceFire++;
+        if (++sinceClockRead < stride) {
+            return false;
+        }
+        sinceClockRead = 0;
+        const now = Date.now();
+        // lastFire 0 is the first call ever — `now - 0` is the epoch, not an
+        // elapsed time, and there is no rate to measure yet. Fire (so an initial
+        // 0% tick is never swallowed) and start the window here.
+        if (lastFire === 0) {
+            lastFire = now;
+            callsSinceFire = 0;
+            return true;
+        }
+        const elapsed = now - lastFire;
+        // elapsed 0 means the window fell inside one clock tick, which measures
+        // nothing. Shrinking is unbounded (an estimate below the current stride
+        // takes effect at once) so a slowdown is corrected on the next read.
+        if (elapsed > 0) {
+            stride = Math.min(MAX_STRIDE, stride * STRIDE_GROWTH_LIMIT, Math.max(1, Math.floor((callsSinceFire * intervalMs) /
+                (elapsed * CLOCK_READS_PER_INTERVAL))));
+        }
+        if (elapsed < intervalMs) {
+            return false;
+        }
+        lastFire = now;
+        callsSinceFire = 0;
+        return true;
+    };
+}