@jbrowse/core 5.0.0-beta.8 → 5.0.0-beta.9

package/esm/util/fieldReader.js

@@ -0,0 +1,62 @@
+import { isJexl, stringToJexlExpression } from './jexlStrings.js';
+import { buildJexlContext } from './simpleFeature.js';
+/**
+ * #api
+ * What a channel reads off a feature: a field by name, a dotted path into a
+ * structured field where no field carries the whole name (`INFO.SVTYPE` on a
+ * VCF record), or a `jexl:` expression over `feature`. A jexl expression that
+ * does not compile throws here, once, rather than on every feature.
+ */
+export function fieldReader(ref, jexl) {
+    const path = ref.includes('.') ? ref.split('.') : undefined;
+    const rests = path?.map((_, i) => path.slice(i).join('.'));
+    if (isJexl(ref)) {
+        if (!jexl) {
+            throw new Error(`a jexl: field needs a jexl instance (${ref})`);
+        }
+        const expr = stringToJexlExpression(ref, jexl);
+        return feature => expr.eval(buildJexlContext({ feature }));
+    }
+    return feature => {
+        const value = feature.get(ref);
+        return value === undefined && path && rests
+            ? readPath(feature.get(path[0]), path, rests)
+            : value;
+    };
+}
+/**
+ * #api
+ * Whether a field ref is a bare name: what `feature.get` answers on its own,
+ * with no path to walk and no expression to evaluate. A loop over a plain name
+ * keeps the direct call, and only a config that writes a path pays for one.
+ */
+export function isPlainFieldRef(ref) {
+    return !ref.includes('.') && !isJexl(ref);
+}
+function readPath(root, path, rests) {
+    let value = root;
+    for (let i = 1; i < path.length; i++) {
+        value =
+            typeof value === 'object' && value !== null
+                ? Reflect.get(value, path[i])
+                : undefined;
+    }
+    return value ?? readWholeRest(root, path, rests);
+}
+// A path that read nothing by descending tries each level's rest as one key,
+// so `INFO.AF.EAS` reaches a key named `AF.EAS`, which VCF 4.3 allows. Only a
+// miss pays for it: a path that resolves is the plain walk above.
+function readWholeRest(root, path, rests) {
+    let value = root;
+    for (let i = 1; i < path.length - 1; i++) {
+        if (typeof value !== 'object' || value === null) {
+            return undefined;
+        }
+        const whole = Reflect.get(value, rests[i]);
+        if (whole !== undefined) {
+            return whole ?? undefined;
+        }
+        value = Reflect.get(value, path[i]);
+    }
+    return undefined;
+}

package/esm/util/groupKeys.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The ordering every in-track group-by shares, whatever partitioned the
+ * features: named groups first, then the `''` catch-all a dimension files its
+ * unanswerable features under, then the overflow bucket a capped partition
+ * merged its tail into.
+ */
+export declare const OVERFLOW_GROUP_KEY = "\0overflow";
+export declare const MAX_GROUPS = 40;
+/**
+ * The text a field value groups, colors and labels by: a missing value is the
+ * `''` catch-all, and a multi-valued attribute joins, so two features carrying
+ * the same list land together.
+ */
+export declare function valueText(value: unknown): string;
+/**
+ * Numbers first by value, then every other key run by run with digit runs by
+ * magnitude, so -1 before 1 and chr2 before chr10. The two classes never
+ * interleave: a signed or decimal number read run by run orders differently
+ * than by value, and letting them mix made the order intransitive.
+ */
+export declare function compareGroupKeys(a: string, b: string): number;
+/**
+ * The order a facet stacks its sections in. `domain` is the channel's
+ * declared order: the keys it lists come first, in that order, and the rest
+ * follow under `compareGroupKeys`. Every categorical channel in the tree
+ * reads its domain this way, so a listed value is a placement and an
+ * unlisted one is not an error.
+ */
+export declare function groupKeyComparator(domain?: readonly string[]): typeof compareGroupKeys;
+/**
+ * The domain a re-pick keeps: a facet set from a menu or dialog names no
+ * domain, so one naming the field the current facet already reads carries
+ * the current order along. A reorder names its own domain and passes
+ * through, an empty one included.
+ */
+export declare function carryGroupDomain<T extends {
+    field: string;
+    domain?: readonly string[];
+}>(next: T | undefined, current: T | undefined): T | undefined;
+/**
+ * The overflow bucket's chip. Says MERGED because that lane is the one entry
+ * in a stack that is not a value, and this label is the only place a reader
+ * is told the cap fired at all.
+ */
+export declare function overflowLabel(count: number): string;
+/**
+ * Which section each key stacks into once the cap applies: the first
+ * `MAX_GROUPS` keys in natural order keep their own and the rest fold into
+ * the overflow section. The catch-all `''` is held out of the merge, since
+ * "lacking the value" is an answer users look for. A domain orders the
+ * sections and never decides which exist, so reordering them changes no
+ * key's section.
+ */
+export declare function capGroupKeys(keys: Iterable<string>): {
+    mergedCount: number;
+    sectionOf: (key: string) => string;
+};
+/**
+ * A group's stable identity: its sort key and the label its chip shows.
+ */
+export interface GroupId {
+    key: string;
+    label: string;
+}
+/**
+ * Identity of the key space a facet hands out keys in: its field. A key means
+ * nothing on its own, since `''` is both the ungrouped section and every
+ * field's catch-all, so anything keyed by group key is dropped when this
+ * moves. The `domain` only orders the keys and is no part of the space, so a
+ * reorder keeps what a reader hid.
+ */
+export declare function groupKeySpaceOf(facet: {
+    field: string;
+    domain?: readonly string[];
+} | undefined): string;

package/esm/util/groupKeys.js

@@ -0,0 +1,152 @@
+/**
+ * The ordering every in-track group-by shares, whatever partitioned the
+ * features: named groups first, then the `''` catch-all a dimension files its
+ * unanswerable features under, then the overflow bucket a capped partition
+ * merged its tail into.
+ */
+// '\0' cannot collide with a real tag value or refName, and the rank below
+// pins it dead last so a merged tail never displaces a named group.
+export const OVERFLOW_GROUP_KEY = '\u0000overflow';
+// Hard ceiling on the sections one grouping may stack; the tail past it merges
+// into the overflow section. A backstop for the dimensions that are not a
+// closed set, a tag or an attribute, whose value space is the file's.
+export const MAX_GROUPS = 40;
+/**
+ * The text a field value groups, colors and labels by: a missing value is the
+ * `''` catch-all, and a multi-valued attribute joins, so two features carrying
+ * the same list land together.
+ */
+export function valueText(value) {
+    return value === undefined || value === null
+        ? ''
+        : Array.isArray(value)
+            ? value.map(String).join(',')
+            : String(value);
+}
+function groupKeyRank(key) {
+    return key === '' ? 1 : key === OVERFLOW_GROUP_KEY ? 2 : 0;
+}
+const NUMERIC = /^-?\d+(\.\d+)?$/;
+const DIGIT_RUNS = /\d+|\D+/g;
+function compareRuns(a, b) {
+    const runsA = a.match(DIGIT_RUNS) ?? [];
+    const runsB = b.match(DIGIT_RUNS) ?? [];
+    const shared = Math.min(runsA.length, runsB.length);
+    for (let i = 0; i < shared; i++) {
+        const x = runsA[i];
+        const y = runsB[i];
+        if (x === y) {
+            continue;
+        }
+        if (/^\d/.test(x) && /^\d/.test(y)) {
+            const nx = Number(x);
+            const ny = Number(y);
+            if (nx !== ny) {
+                return nx < ny ? -1 : 1;
+            }
+            return x.length < y.length ? -1 : 1;
+        }
+        return x < y ? -1 : 1;
+    }
+    return runsA.length - runsB.length;
+}
+/**
+ * Numbers first by value, then every other key run by run with digit runs by
+ * magnitude, so -1 before 1 and chr2 before chr10. The two classes never
+ * interleave: a signed or decimal number read run by run orders differently
+ * than by value, and letting them mix made the order intransitive.
+ */
+export function compareGroupKeys(a, b) {
+    const rankDiff = groupKeyRank(a) - groupKeyRank(b);
+    if (rankDiff !== 0 || a === b) {
+        return rankDiff;
+    }
+    const numA = NUMERIC.test(a);
+    const numB = NUMERIC.test(b);
+    if (numA !== numB) {
+        return numA ? -1 : 1;
+    }
+    if (numA) {
+        const diff = Number(a) - Number(b);
+        if (diff !== 0) {
+            return diff < 0 ? -1 : 1;
+        }
+    }
+    return compareRuns(a, b);
+}
+/**
+ * The order a facet stacks its sections in. `domain` is the channel's
+ * declared order: the keys it lists come first, in that order, and the rest
+ * follow under `compareGroupKeys`. Every categorical channel in the tree
+ * reads its domain this way, so a listed value is a placement and an
+ * unlisted one is not an error.
+ */
+export function groupKeyComparator(domain) {
+    if (!domain?.length) {
+        return compareGroupKeys;
+    }
+    const rank = new Map();
+    domain.forEach((key, i) => {
+        if (!rank.has(key)) {
+            rank.set(key, i);
+        }
+    });
+    return (a, b) => {
+        const ra = rank.get(a) ?? Infinity;
+        const rb = rank.get(b) ?? Infinity;
+        return ra !== rb ? (ra < rb ? -1 : 1) : compareGroupKeys(a, b);
+    };
+}
+/**
+ * The domain a re-pick keeps: a facet set from a menu or dialog names no
+ * domain, so one naming the field the current facet already reads carries
+ * the current order along. A reorder names its own domain and passes
+ * through, an empty one included.
+ */
+export function carryGroupDomain(next, current) {
+    return next !== undefined &&
+        next.domain === undefined &&
+        current?.domain !== undefined &&
+        next.field === current.field
+        ? { ...next, domain: current.domain }
+        : next;
+}
+/**
+ * The overflow bucket's chip. Says MERGED because that lane is the one entry
+ * in a stack that is not a value, and this label is the only place a reader
+ * is told the cap fired at all.
+ */
+export function overflowLabel(count) {
+    return `${count} merged values`;
+}
+/**
+ * Which section each key stacks into once the cap applies: the first
+ * `MAX_GROUPS` keys in natural order keep their own and the rest fold into
+ * the overflow section. The catch-all `''` is held out of the merge, since
+ * "lacking the value" is an answer users look for. A domain orders the
+ * sections and never decides which exist, so reordering them changes no
+ * key's section.
+ */
+export function capGroupKeys(keys) {
+    const ordered = [...new Set(keys)].sort(compareGroupKeys);
+    const hasUntagged = ordered.includes('');
+    const named = ordered.filter(key => key !== '');
+    const merged = ordered.length > MAX_GROUPS
+        ? named.slice(MAX_GROUPS - (hasUntagged ? 2 : 1))
+        : [];
+    const mergedSet = new Set(merged);
+    return {
+        mergedCount: merged.length,
+        sectionOf: (key) => (mergedSet.has(key) ? OVERFLOW_GROUP_KEY : key),
+    };
+}
+/**
+ * Identity of the key space a facet hands out keys in: its field. A key means
+ * nothing on its own, since `''` is both the ungrouped section and every
+ * field's catch-all, so anything keyed by group key is dropped when this
+ * moves. The `domain` only orders the keys and is no part of the space, so a
+ * reorder keeps what a reader hid.
+ */
+export function groupKeySpaceOf(facet) {
+    return facet?.field ?? '';
+}

package/esm/util/highlights.d.ts

@@ -1,14 +1,16 @@
-import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
 import type { Theme } from '@mui/material';
 export interface HighlightType {
     start: number;
     end: number;
-    assemblyName?: string;
+    assemblyName: string;
     refName: string;
     color?: string;
     label?: string;
 }
-export declare function revealHighlightsOnGrowth(node: IAnyStateTreeNode, count: () => number): void;
+export type HighlightInput = Omit<HighlightType, 'assemblyName'> & {
+    assemblyName?: string;
+};
+export declare function isSameHighlight(a: HighlightType, b: HighlightType): boolean;
 export declare function highlightKey(h: {
     assemblyName?: string;
     refName: string;
@@ -18,4 +20,4 @@ export declare function highlightKey(h: {
 export declare function getHighlightColor(highlight: {
     color?: string;
 }, theme: Theme, alpha?: number): import("./colord.ts").Colord;
-export declare function coerceHighlight(h: string | HighlightType, defaultAssembly: string, isValidRefName: (refName: string, assemblyName?: string) => boolean): HighlightType | undefined;
+export declare function coerceHighlight(h: string | HighlightInput, defaultAssembly: string, isValidRefName: (refName: string, assemblyName?: string) => boolean): HighlightType | undefined;

package/esm/util/highlights.js

@@ -1,25 +1,12 @@
-import { addDisposer } from '@jbrowse/mobx-state-tree';
-import { autorun } from 'mobx';
 import { colord } from './colord.js';
 import { parseLocString } from './locString.js';
-import { getSession } from './mstUtils.js';
-// Bands and bookmark overlays both render only while the session-wide
-// `highlightsVisible` flag is on, so anything added while it is off draws
-// nothing at all, which reads as "it didn't work". Watching the collection
-// grow reveals for every path that adds to it rather than asking each call
-// site to remember. `count` is seeded before the autorun so restoring a
-// session that deliberately persisted bands-off doesn't flip it back on, and
-// removals only lower the baseline — they never re-reveal, or the toggle could
-// never be turned off.
-export function revealHighlightsOnGrowth(node, count) {
-    let prevCount = count();
-    addDisposer(node, autorun(function highlightRevealAutorun() {
-        const newCount = count();
-        if (newCount > prevCount) {
-            getSession(node).revealHighlights();
-        }
-        prevCount = newCount;
-    }));
+export function isSameHighlight(a, b) {
+    return (a.assemblyName === b.assemblyName &&
+        a.refName === b.refName &&
+        a.start === b.start &&
+        a.end === b.end &&
+        a.color === b.color &&
+        a.label === b.label);
 }
 // Highlight regions have no id and can duplicate, so the trailing index only
 // breaks ties between otherwise-identical regions. Wrapping the array index in
@@ -84,11 +71,11 @@ function parseLocHighlight(s, defaultAssembly, isValidRefName) {
         ? { refName, start, end, assemblyName: assemblyName ?? defaultAssembly }
         : undefined;
 }
-// Normalize an `init.highlight` entry (HighlightType object, JSON string, or
-// loc string) into a HighlightType, defaulting the assemblyName. Shared by
-// LinearGenomeView and DotplotView, whose `init.highlight` accept the same
-// three forms — the JSON shape-check in particular has to stay identical or a
-// highlight that works in one view silently drops in the other.
+// Normalize a launch spec's `highlight` entry (object, JSON string, or loc
+// string) into a HighlightType, defaulting the assemblyName. Shared by
+// LinearGenomeView and DotplotView, whose `highlight` launch keys accept the
+// same three forms — the JSON shape-check in particular has to stay identical or
+// a highlight that works in one view silently drops in the other.
 export function coerceHighlight(h, defaultAssembly, 
 // takes the assembly a `{...}` prefix named, so a caller with more than one
 // assembly in play validates the refName against the one the entry asked for

package/esm/util/hooks.d.ts

@@ -66,8 +66,7 @@ export declare function useFinalUnmount(cleanup: () => void): void;
  * components on the same key each kept their own copy of it, so toggling a
  * setting in one BreakpointSplitView header left a second one open beside it
  * showing the old value until it remounted. Instances on a key now subscribe to
- * each other's writes, and to other tabs' — `subscribeToLocalStorageKey`, which
- * the grid-bookmark widget shares from its state model.
+ * each other's writes, and to other tabs' — `subscribeToLocalStorageKey`.
  *
  * The store is read on every notify rather than cached, so nothing here can go
  * stale against a `localStorage.clear()`. Which also means a functional update

package/esm/util/hooks.js

@@ -204,8 +204,7 @@ function resolveUpdate(value, prev) {
  * components on the same key each kept their own copy of it, so toggling a
  * setting in one BreakpointSplitView header left a second one open beside it
  * showing the old value until it remounted. Instances on a key now subscribe to
- * each other's writes, and to other tabs' — `subscribeToLocalStorageKey`, which
- * the grid-bookmark widget shares from its state model.
+ * each other's writes, and to other tabs' — `subscribeToLocalStorageKey`.
  *
  * The store is read on every notify rather than cached, so nothing here can go
  * stale against a `localStorage.clear()`. Which also means a functional update

package/esm/util/index.d.ts

@@ -23,7 +23,7 @@ export { avg, clamp, getDisplayStr, getNumberGrouping, max, maxFinite, min, minm
 export { type MinimalRegion, bpSpanPx, bpToPx, bytesForRegions, featureSpanPx, getBpDisplayStr, getTickDisplayStr, parseBpString, } from './bpUtils.ts';
 export { type BasicFeature, gatherOverlaps, mergeIntervals, } from './intervals.ts';
 export { clampToContig, clampToListedContig } from './clampToContig.ts';
-export { animationAllowed } from './animationAllowed.ts';
+export { MORPH_DURATION_MS, animationAllowed, easeInOutCubic, morphClockMs, } from './animationAllowed.ts';
 export { springAnimate } from './springAnimate.ts';
 export { localStorageAvailable, localStorageGetBoolean, localStorageGetItem, localStorageGetJSON, localStorageGetNumber, localStorageGetStringArray, localStorageRemoveItem, localStorageSetBoolean, localStorageSetItem, localStorageSetJSON, localStorageSetNumber, notifyLocalStorageKey, subscribeToLocalStorageKey, } from './localStorage.ts';
 export { renameRegionIfNeeded, renameRegionsIfNeeded } from './renameRegions.ts';
@@ -65,7 +65,7 @@ export declare function testAdapter(fileName: string, regex: RegExp, adapterHint
 export { type Feature, type SimpleFeatureSerialized, type SimpleFeatureSerializedNoId, default as SimpleFeature, isFeature, } from './simpleFeature.ts';
 export { saveAs } from './FileSaver/index.ts';
 export { type SaveSvgAsImageOptions, saveSvgAsImage, svgHtmlToPngBlob, } from '../svg/saveSvgAsImage.ts';
-export { type ActiveFetch, type StatusChannel, type StatusReporter, createStatusChannel, createStopTokenRotation, } from './createStopTokenRotation.ts';
+export { type ActiveFetch, type StatusChannel, type StatusReporter, createStatusChannel, createAbortRotation, } from './createAbortRotation.ts';
 export { createSharedSetup } from './cachedSetup.ts';
 export { scheduleDetachedDestroy } from './scheduleDetachedDestroy.ts';
 export { isDataCurrent } from './isDataCurrent.ts';
@@ -75,7 +75,7 @@ export { isGeneLikeType, isSequenceMatchType } from './featureTypes.ts';
 export { locStringsToRegions } from './locStringsToRegions.ts';
 export type { RefNameSource } from './locStringsToRegions.ts';
 export { type ParsedLocString, UnknownRefNameError, assembleLocString, assembleLocStringRaw, assembleLocStrings, compareLocStrings, compareLocs, parseLocString, parseLocStringOneBased, stringify, } from './locString.ts';
-export { type LastStopTokenCheck, type StopToken, type StopTokenChecker, type StopTokenSignal, checkStopToken, checkStopTokenThrottled, createStopToken, createStopTokenChecker, hasSharedArrayBuffer, isStopToken, isStopped, markStopTokenStopped, registerStopTokenBroadcaster, stopStopToken, stopTokenSignal, withStopTokenCheck, withStopTokenSignal, } from './stopToken.ts';
+export { type AbortBreakpoint, checkAbortSignal, createAbortBreakpoint, withAbortCheck, } from './aborting.ts';
 export { type AddTrackComponentModel, type AddTrackComponentProps, adapterNeedsAddTrackComponent, addAddTrackComponent, } from './addTrackComponent.ts';
 export { adapterConfigFromSpec } from './formatGuessers.ts';
 export { type AdapterConfig, type AdapterGuesser, type LooseTrackInput, type TrackTypeGuesser, UNKNOWN, UNSUPPORTED, addAdapterGuesser, addTrackTypeGuesser, clearFileFromCache, ensureFileHandleReady, expandLooseTrackConfig, findFileHandleIds, generateUnknownTrackConf, generateUnsupportedTrackConf, getBlob, getBlobMap, getConfAssemblyNames, getFileFromCache, getFileName, getRpcSessionId, getTrackAssemblyNames, getTrackName, guessAdapter, guessTrackConf, guessTrackType, hasFileHandlesInCache, hideTrackGeneric, isLooseTrackConfig, makeIndex, makeIndexType, restoreFileHandles, restoreFileHandlesFromSnapshot, setBlobMap, setFileInCache, showTrackGeneric, storeBlobLocation, storeFileHandleLocation, stripFileExtension, stripTrackIds, toggleTrackGeneric, } from './tracks.ts';

package/esm/util/index.js

@@ -30,7 +30,7 @@ export { avg, clamp, getDisplayStr, getNumberGrouping, max, maxFinite, min, minm
 export { bpSpanPx, bpToPx, bytesForRegions, featureSpanPx, getBpDisplayStr, getTickDisplayStr, parseBpString, } from './bpUtils.js';
 export { gatherOverlaps, mergeIntervals, } from './intervals.js';
 export { clampToContig, clampToListedContig } from './clampToContig.js';
-export { animationAllowed } from './animationAllowed.js';
+export { MORPH_DURATION_MS, animationAllowed, easeInOutCubic, morphClockMs, } from './animationAllowed.js';
 export { springAnimate } from './springAnimate.js';
 export { localStorageAvailable, localStorageGetBoolean, localStorageGetItem, localStorageGetJSON, localStorageGetNumber, localStorageGetStringArray, localStorageRemoveItem, localStorageSetBoolean, localStorageSetItem, localStorageSetJSON, localStorageSetNumber, notifyLocalStorageKey, subscribeToLocalStorageKey, } from './localStorage.js';
 export { renameRegionIfNeeded, renameRegionsIfNeeded } from './renameRegions.js';
@@ -119,6 +119,7 @@ export function isSupportedIndexingAdapter(type = '') {
 // needing insertion order builds its own Map (see tree-sidebar's CLAUDE.md).
 export function groupBy(array, predicate) {
     const result = Object.create(null);
+    // eslint-disable-next-line unicorn/prefer-group-by -- Object.groupBy types its result Partial, which would widen every caller's Object.values to `T[] | undefined`
     for (const value of array) {
         const t = predicate(value);
         result[t] ??= [];
@@ -135,7 +136,7 @@ export function testAdapter(fileName, regex, adapterHint, expected) {
 export { default as SimpleFeature, isFeature, } from './simpleFeature.js';
 export { saveAs } from './FileSaver/index.js';
 export { saveSvgAsImage, svgHtmlToPngBlob, } from '../svg/saveSvgAsImage.js';
-export { createStatusChannel, createStopTokenRotation, } from './createStopTokenRotation.js';
+export { createStatusChannel, createAbortRotation, } from './createAbortRotation.js';
 // `installFetch` is deliberately NOT re-exported here: it reaches `getSession`
 // through `fetchContext.ts`, which imports this barrel, so exporting it makes
 // the barrel initialize itself. Import it from `@jbrowse/core/util/installFetch`.
@@ -147,7 +148,7 @@ export { linkify } from './linkify.js';
 export { isGeneLikeType, isSequenceMatchType } from './featureTypes.js';
 export { locStringsToRegions } from './locStringsToRegions.js';
 export { UnknownRefNameError, assembleLocString, assembleLocStringRaw, assembleLocStrings, compareLocStrings, compareLocs, parseLocString, parseLocStringOneBased, stringify, } from './locString.js';
-export { checkStopToken, checkStopTokenThrottled, createStopToken, createStopTokenChecker, hasSharedArrayBuffer, isStopToken, isStopped, markStopTokenStopped, registerStopTokenBroadcaster, stopStopToken, stopTokenSignal, withStopTokenCheck, withStopTokenSignal, } from './stopToken.js';
+export { checkAbortSignal, createAbortBreakpoint, withAbortCheck, } from './aborting.js';
 export { adapterNeedsAddTrackComponent, addAddTrackComponent, } from './addTrackComponent.js';
 export { adapterConfigFromSpec } from './formatGuessers.js';
 export { UNKNOWN, UNSUPPORTED, addAdapterGuesser, addTrackTypeGuesser, clearFileFromCache, ensureFileHandleReady, expandLooseTrackConfig, findFileHandleIds, generateUnknownTrackConf, generateUnsupportedTrackConf, getBlob, getBlobMap, getConfAssemblyNames, getFileFromCache, getFileName, getRpcSessionId, getTrackAssemblyNames, getTrackName, guessAdapter, guessTrackConf, guessTrackType, hasFileHandlesInCache, hideTrackGeneric, isLooseTrackConfig, makeIndex, makeIndexType, restoreFileHandles, restoreFileHandlesFromSnapshot, setBlobMap, setFileInCache, showTrackGeneric, storeBlobLocation, storeFileHandleLocation, stripFileExtension, stripTrackIds, toggleTrackGeneric, } from './tracks.js';

package/esm/util/indexCandidates.js

@@ -73,7 +73,7 @@ export function siblingLocation(location, fileName) {
     const replaceLast = (path) => 
     // the separator is kept: a Windows local path uses backslashes and a URI
     // never does, so rebuilding with '/' would corrupt one of them
-    path.replace(/[^/\\]*$/, fileName);
+    path.replace(/[^/\\]*$/, () => fileName);
     if (location.locationType === 'UriLocation') {
         return { ...location, uri: replaceLast(location.uri) };
     }

package/esm/util/installFetch.d.ts

@@ -1,7 +1,6 @@
-import type { ActiveFetch, StatusReporter, StopTokenRotation } from './createStopTokenRotation.ts';
+import type { ActiveFetch, StatusReporter, AbortRotation } from './createAbortRotation.ts';
 import type { FetchContext } from './fetchContext.ts';
 import type { FetchPhases } from './fetchPhases.ts';
-import type { StopToken } from './stopToken.ts';
 import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
 /**
  * The bookkeeping a family hangs off one fetch, beside the phases. Each of the
@@ -24,17 +23,17 @@ export interface FetchLifecycle {
     setError: (error?: unknown) => void;
     /**
      * Runs synchronously as the fetch starts, after the rotation has superseded
-     * whatever it replaced: the loading flag (`FetchMixin`'s `activeStopToken`,
+     * whatever it replaced: the loading flag (`FetchMixin`'s `activeSignal`,
      * through `fetchMixinLifecycle`), and anything a display blanks
      * because it has no freshness signature to keep stale data honest with
      * (chord's refName map).
      *
-     * Takes the token rather than the whole {@link ActiveFetch}: publishing it is
+     * Takes the signal rather than the whole {@link ActiveFetch}: publishing it is
      * the only thing any implementation does with the fetch, and the guard and
      * the status slot are the skeleton's to hand out — through `ctx`, where a
      * `run` gets them pre-wired.
      */
-    onBegin?: (stopToken: StopToken) => void;
+    onBegin?: (signal: AbortSignal) => void;
     /**
      * Runs in the `finally`, before the rotation's `end()`. `current` is this
      * run's own guard, already evaluated: a **superseded** run must not clear the
@@ -56,7 +55,7 @@ export interface FetchLifecycle {
  * the loading flag on an abort. The rules only pay for themselves by being the
  * same everywhere, so they live here and the differences are parameters.
  *
- * `active` comes from a {@link createStopTokenRotation} `begin()` the caller
+ * `active` comes from a {@link createAbortRotation} `begin()` the caller
  * already made, because who owns the rotation is one of the real differences: a
  * display's *primary* fetch rotates through `FetchMixin`, so `cancelFetch` can
  * reach it, while every other fetch's rotation lives in its installer's closure
@@ -143,8 +142,12 @@ interface InstallFetchOptionsBase<TArgs, TResult> extends FetchPhases<TArgs, TRe
      *
      * Omit it where the fetch holds no committed state to compare against — most
      * of them, whose `prepare` returns args unconditionally.
+     *
+     * A value, compared by `isDataCurrent`: the settings a fetch was issued
+     * under go in as the object the worker receives, never as a serialized
+     * spelling of it.
      */
-    fetchKey?: (args: TArgs) => string;
+    fetchKey?: (args: TArgs) => unknown;
     /**
      * The key of the data already committed, when the host keeps one —
      * `KeyedFetchMixin` stamps `loadedFetchKey`, which its `dataCurrent` reads
@@ -157,10 +160,10 @@ interface InstallFetchOptionsBase<TArgs, TResult> extends FetchPhases<TArgs, TRe
      * write is what wakes the autorun to fetch A again. A closure variable would
      * leave data B under viewport A until the next input moved.
      */
-    loadedKey?: () => string | undefined;
+    loadedKey?: () => unknown;
     /**
      * The predicate form of the freshness gate, for a fetch whose "I have exactly
-     * this already" is not string equality: the density tier holds bins over a
+     * this already" is not key equality: the density tier holds bins over a
      * buffered read and answers a viewport those bins *contain*, which no key can
      * spell. Same rules as `fetchKey` — declined runs report `declined`, and a
      * `reloadCounter` advanced since the last issued fetch overrides it — so the
@@ -203,7 +206,7 @@ export type InstallFetchOptions<TArgs, TResult> = InstallFetchOptionsBase<TArgs,
     rotation?: never;
 } | {
     /** the host's own latest-wins rotation, lent whole — see above */
-    rotation: StopTokenRotation;
+    rotation: AbortRotation;
     report?: never;
 });
 /**

package/esm/util/installFetch.js

@@ -2,7 +2,7 @@ import { addDisposer, isAlive } from '@jbrowse/mobx-state-tree';
 import { observable, runInAction, untracked } from 'mobx';
 import { assertDisplayContract, makeRetryContractCheck, } from '../pluggableElementTypes/models/assertDisplayContract.js';
 import { handleFetchError } from './aborting.js';
-import { createStopTokenRotation } from './createStopTokenRotation.js';
+import { createAbortRotation } from './createAbortRotation.js';
 import { makeFetchContext } from './fetchContext.js';
 import { isDataCurrent } from './isDataCurrent.js';
 import { leadingEdgeAutorun } from './leadingEdgeAutorun.js';
@@ -18,7 +18,7 @@ import { leadingEdgeAutorun } from './leadingEdgeAutorun.js';
  * the loading flag on an abort. The rules only pay for themselves by being the
  * same everywhere, so they live here and the differences are parameters.
  *
- * `active` comes from a {@link createStopTokenRotation} `begin()` the caller
+ * `active` comes from a {@link createAbortRotation} `begin()` the caller
  * already made, because who owns the rotation is one of the real differences: a
  * display's *primary* fetch rotates through `FetchMixin`, so `cancelFetch` can
  * reach it, while every other fetch's rotation lives in its installer's closure
@@ -30,13 +30,13 @@ import { leadingEdgeAutorun } from './leadingEdgeAutorun.js';
  * flow, and so an action, which MobX runs untracked already.
  */
 export async function runFetchOnce(self, active, args, { run, commit, setError, onBegin, onEnd, }) {
-    const { stopToken, isCurrent, statusCallback, end } = active;
+    const { signal, isCurrent, statusCallback, end } = active;
     // synchronous, so it lands while this run is by construction the current one
     setError(undefined);
-    onBegin?.(stopToken);
+    onBegin?.(signal);
     try {
         const result = await run(args, makeFetchContext(self, {
-            stopToken,
+            signal,
             isStale: () => !isCurrent(),
             statusCallback,
         }));
@@ -52,8 +52,8 @@ export async function runFetchOnce(self, active, args, { run, commit, setError,
     finally {
         // Both `onEnd` implementations are MST actions on `self`, and a display
         // destroyed mid-fetch — a track closed, a display type switched out from
-        // under a load — still resumes here. `beforeDestroy` already stopped the
-        // token, so the bookkeeping is moot on a dead node; calling the action
+        // under a load — still resumes here. `beforeDestroy` already aborted the
+        // signal, so the bookkeeping is moot on a dead node; calling the action
         // anyway only warns.
         if (isAlive(self)) {
             onEnd?.(isCurrent());
@@ -79,7 +79,7 @@ function installContractChecks(self, contract) {
  * would drop a write the host's other operations are still owed.
  */
 function ownRotation(self, report) {
-    const rotation = createStopTokenRotation(self, report);
+    const rotation = createAbortRotation(self, report);
     addDisposer(self, () => {
         rotation.dispose();
     });
@@ -118,9 +118,10 @@ export function installFetch(self, opts) {
     let issuedEpoch;
     // The skeleton's own stamp exists only where there is a key to stamp — a
     // fetch with no `fetchKey` never reads it, so allocating one would only feed
-    // it `undefined` on every commit.
+    // it `undefined` on every commit. Shallow, because the deep enhancer would
+    // swap a stamped key object for an observable copy of it.
     const stamp = loadedKey === undefined && fetchKey !== undefined
-        ? observable.box()
+        ? observable.box(undefined, { deep: false })
         : undefined;
     const heldKey = loadedKey ?? (() => stamp?.get());
     // the freshness gate in whichever form the caller declared it

package/esm/util/installPrerequisiteFetch.d.ts

@@ -1,4 +1,4 @@
-import type { StatusReporter } from './createStopTokenRotation.ts';
+import type { StatusReporter } from './createAbortRotation.ts';
 import type { FetchContext } from './fetchContext.ts';
 import type { FetchSkeletonHost } from './installFetch.ts';
 /**
@@ -12,6 +12,8 @@ export interface PrerequisiteFetchHost extends FetchSkeletonHost {
     /**
      * Read in `prepare`, so it is **tracked**: an adapter edited in the config
      * editor has to re-read, and `run`'s own reads are untracked by contract.
+     * The key stamps it by reference, which is safe because nothing mutates an
+     * adapter config in place: it is a config snapshot or built fresh from one.
      */
     adapterConfig: Record<string, unknown>;
     isMinimized: boolean;
@@ -52,7 +54,7 @@ export interface PrerequisiteFetchHost extends FetchSkeletonHost {
  *   nothing; a header is not a load.
  *
  * `createAdapterMetadataFetch` keys on the same adapter config and is
- * deliberately NOT one of these: no trigger, no stop token and no status,
+ * deliberately NOT one of these: no trigger, no signal and no status,
  * because it is fetched lazily when a details widget opens and the widget opens
  * on the result. A prerequisite read is the one a display's own fetch waits on.
  *
@@ -69,7 +71,7 @@ export interface PrerequisiteFetchHost extends FetchSkeletonHost {
  * Everything the skeleton gives it is the point of going through the skeleton:
  * the latest-wins rotation (so a superseding read aborts the one it replaced,
  * and only a superseding read does — a user cancel of the primary fetch cannot
- * strand the display the way sharing its token would), the clear at the start,
+ * strand the display the way sharing its signal would), the clear at the start,
  * the currency-guarded error rule, the unconditional `reloadCounter` read that
  * makes the chrome's Retry re-run this, and the retired status slot that keeps a
  * failed read from leaving a progress chip up for good.