@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/featureTypes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Classification of a feature from its `type` string alone, for the plugins
+ * that decide something about a feature they did not parse. A type is the only
+ * thing a display, a menu or a widget can ask about a feature without knowing
+ * which adapter produced it, so these live in core rather than beside any one
+ * of their callers.
+ */
+/**
+ * Whether the type names a unit of transcription — a gene, a transcript, or an
+ * RNA, including the pseudogene and V(D)J segment spellings. This is the
+ * question "does this feature have exons", not "can this feature be spliced":
+ * an alignment splices too and is deliberately not gene-like, because a caller
+ * that means to launch a protein view or read a CDS would be wrong about it.
+ */
+export declare function isGeneLikeType(type: string | undefined): boolean;
+/**
+ * Whether the type names a sequence alignment — SO `match` and its subtypes
+ * (`cDNA_match`, `EST_match`, `nucleotide_match`, `protein_match`,
+ * `translated_nucleotide_match`), whose `match_part` children are the aligned
+ * blocks and whose gaps between them are introns when the aligned sequence was
+ * a transcript. Separate from `isGeneLikeType` on purpose: an EST alignment is
+ * evidence for a gene, not one.
+ */
+export declare function isSequenceMatchType(type: string | undefined): boolean;

package/esm/util/featureTypes.js

@@ -0,0 +1,35 @@
+/**
+ * Classification of a feature from its `type` string alone, for the plugins
+ * that decide something about a feature they did not parse. A type is the only
+ * thing a display, a menu or a widget can ask about a feature without knowing
+ * which adapter produced it, so these live in core rather than beside any one
+ * of their callers.
+ */
+// Anchored at the end so 'intergenic_region' is not a gene, 'rnapol_binding_site'
+// is not an RNA, and 'transcriptional_cis_regulatory_region' is not a
+// transcript.
+const GENE_LIKE_TYPE = /gene(_segment)?$|rna$|transcript$/;
+/**
+ * Whether the type names a unit of transcription — a gene, a transcript, or an
+ * RNA, including the pseudogene and V(D)J segment spellings. This is the
+ * question "does this feature have exons", not "can this feature be spliced":
+ * an alignment splices too and is deliberately not gene-like, because a caller
+ * that means to launch a protein view or read a CDS would be wrong about it.
+ */
+export function isGeneLikeType(type) {
+    return type !== undefined && GENE_LIKE_TYPE.test(type.toLowerCase());
+}
+// SO `match` and every subtype of it is spelled `<something>_match`, so the
+// suffix is the family. `match_part`, the child, is excluded by the anchor.
+const SEQUENCE_MATCH_TYPE = /(^|_)match$/;
+/**
+ * Whether the type names a sequence alignment — SO `match` and its subtypes
+ * (`cDNA_match`, `EST_match`, `nucleotide_match`, `protein_match`,
+ * `translated_nucleotide_match`), whose `match_part` children are the aligned
+ * blocks and whose gaps between them are introns when the aligned sequence was
+ * a transcript. Separate from `isGeneLikeType` on purpose: an EST alignment is
+ * evidence for a gene, not one.
+ */
+export function isSequenceMatchType(type) {
+    return type !== undefined && SEQUENCE_MATCH_TYPE.test(type.toLowerCase());
+}

package/esm/util/fetchAndMaybeUnzip.d.ts

@@ -0,0 +1,6 @@
+import type { BaseOptions } from '../data_adapters/BaseAdapter/index.ts';
+import type { StatusPhase } from './progress.ts';
+import type { GenericFilehandle } from 'generic-filehandle2';
+export declare function isGzip(buf: Uint8Array): boolean;
+export declare function fetchAndMaybeUnzip(loc: GenericFilehandle, opts?: BaseOptions, label?: string | StatusPhase): Promise<Uint8Array<ArrayBufferLike>>;
+export declare function fetchAndMaybeUnzipText(loc: GenericFilehandle, opts?: BaseOptions, label?: string | StatusPhase): Promise<string>;

package/esm/util/fetchAndMaybeUnzip.js

@@ -0,0 +1,71 @@
+import { redactSource } from './getLocationUri.js';
+import { downloadStatus, phaseOf, updateStatus } from './progress.js';
+function loadInflater() {
+    return import('@gmod/bgzf-filehandle');
+}
+export function isGzip(buf) {
+    return buf[0] === 31 && buf[1] === 139 && buf[2] === 8;
+}
+export async function fetchAndMaybeUnzip(loc, opts = {}, 
+// what is being downloaded, for the loading UI. Defaulted rather than
+// required because most callers are a track's one data file, where the track
+// name is already on screen; name it wherever several files load at once
+// behind a single indicator and "Downloading file" can't say which (the four
+// parallel assembly loads, say). The URL is not the caller's to supply — see
+// below
+label = 'Downloading file') {
+    // statusCallback is passed through as-is rather than defaulted to a no-op, so
+    // that "nobody is listening" reaches the reader: downloadStatus then hands it
+    // no onProgress and generic-filehandle2 takes `res.bytes()` rather than its
+    // getReader loop.
+    //
+    // **That is not the faster path, and this comment used to say it was.** In a
+    // Chrome worker the loop is ~1.8x faster up to 10MB and only ~1.1x slower past
+    // ~25MB — agent-docs/measurements/download-read-path.json. What withholding it
+    // buys is that a caller who asked for no reporting gets none, here and in the
+    // worker alike; the read speed is a wash at best and against us at the sizes a
+    // whole-file load usually is.
+    // Where a stalled load gets the URL it names, and the reason no call site
+    // passes one: `loc` knows. Every filehandle `openLocation` builds carries the
+    // address it was constructed with (generic-filehandle2 2.4.0), so this is true
+    // of every download in the tree rather than of the handful that remembered to
+    // say so. A Blob and a FileHandle report nothing, which is right — their bytes
+    // came from the user and there is no server to go and check.
+    //
+    // Redacted here rather than at the source, because the handle's `source` is
+    // verbatim what it fetches (a presigned URL keeps its signature) and this is
+    // the layer that hands it to a display.
+    const phase = loc.source === undefined
+        ? label
+        : { message: phaseOf(label), source: redactSource(loc.source) };
+    const { statusCallback, signal } = opts;
+    // the inflater is imported dynamically because this module is reachable from
+    // the core/util barrel, so a static import put bgzf-filehandle + pako
+    // (~180KB) on the startup path of every page load. A name ending .gz starts
+    // that import beside the download instead of after it; the bytes still decide
+    // whether to inflate.
+    const inflater = /\.gz($|[?#])/.test(loc.source ?? '')
+        ? loadInflater()
+        : undefined;
+    inflater?.catch(() => { });
+    // the signal reaches the read, so a cancelled whole-file load drops at the
+    // socket rather than downloading a multi-GB body to completion
+    const buf = await downloadStatus(phase, statusCallback, onProgress => loc.readFile({ ...opts, onProgress, signal }));
+    return isGzip(buf)
+        ? await updateStatus('Unzipping', statusCallback, async () => {
+            const { unzip } = await (inflater ?? loadInflater());
+            return unzip(buf);
+        }, 
+        // a cancel landing here is otherwise discovered only by whatever parses
+        // the result, after a whole-file inflate has run to completion
+        signal)
+        : buf;
+}
+export async function fetchAndMaybeUnzipText(loc, opts, label) {
+    const buffer = await fetchAndMaybeUnzip(loc, opts, label);
+    // 512MB  max chrome string length is 512MB
+    if (buffer.length > 536_870_888) {
+        throw new Error('Data exceeds maximum string length (512MB)');
+    }
+    return new TextDecoder('utf8', { fatal: true }).decode(buffer);
+}

package/esm/util/fetchContext.d.ts

@@ -0,0 +1,81 @@
+import type { RpcCallArgs, RpcCallReturn } from '../rpc/RpcRegistry.ts';
+import type { StatusCallback } from './progress.ts';
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
+export interface FetchContext {
+    signal: AbortSignal;
+    isStale: () => boolean;
+    /**
+     * The RPC `statusCallback` for the work this context describes: guarded to
+     * this fetch (a superseded one cannot repaint the overlay of the fetch that
+     * replaced it) and throttled through the display-wide window. `callRpc`
+     * injects it — read it directly only for a status write of your own
+     * (`updateStatus` phase labels).
+     *
+     * The fan-out helpers hand each region a context whose callback is that
+     * region's own slot (`callEachRegion`, and `fetchEachRegion` through it), so
+     * a `ctx.callRpc` aggregates N parallel regions into one bar in the fan-out
+     * case and reports the whole fetch in the batched one. Reading it off the
+     * model instead — or reusing the *outer* ctx's inside a fan-out — is what
+     * made parallel regions clobber each other's progress, and is now the thing
+     * you would have to go out of your way to do.
+     */
+    statusCallback: StatusCallback;
+    /**
+     * The one way a fetch calls an RPC: the registry-typed
+     * `rpcManager.call(rpcSessionId, method, args)` with this context's
+     * `signal` and `statusCallback` injected. Both used to be hand-threaded
+     * at every fetch site, and forgetting either was silent — no cancellation
+     * for that display, or no progress — which is exactly the failure class the
+     * envelope makes inexpressible: a fetch cannot issue an RPC the cancel and
+     * the status bar don't know about.
+     *
+     * Declared with a `this` parameter so it reads the *holding* context's
+     * signal and callback — the fan-out copies rebind it to their own status
+     * slot by construction — and so destructuring it off the context is a type
+     * error rather than a stale binding.
+     */
+    callRpc: <M extends string>(this: FetchContext, method: M, args: Omit<RpcCallArgs<M>, 'signal' | 'statusCallback'>) => Promise<RpcCallReturn<M>>;
+}
+/**
+ * Build a {@link FetchContext} over a live fetch's primitives. One
+ * constructor, so every context — `FetchMixin.runFetch`'s and `runFetchOnce`'s
+ * alike — carries the same `callRpc` envelope.
+ *
+ * **`self` has to be somewhere `getRpcSessionId` can find one, which in practice
+ * means a track or something under it.** `rpcSessionId` is declared by
+ * `BaseTrackModel` and by nothing above it, so the walk throws rather than
+ * falling back — and a fetch installed on a VIEW gets a context whose `callRpc`
+ * cannot be called at all. That is not a gap to fix here: the id names the track
+ * whose adapter is being read, and a view fetching for several tracks has a
+ * different one per call. The shape is to fan out and rebuild a context per
+ * track, which is what the breakpoint split view's overlay fetch does.
+ */
+export declare function makeFetchContext(self: IStateTreeNode, base: {
+    signal: AbortSignal;
+    isStale: () => boolean;
+    statusCallback: StatusCallback;
+}): FetchContext;
+/**
+ * One context per concurrent operation, each carrying its own status slot, so
+ * the N of them aggregate into a single Σcurrent/Σtotal bar rather than
+ * last-writer-wins on the owner's one status field.
+ *
+ * A copy of the ctx rather than a separate `slot()` on it because a caller
+ * should not have to know which kind of context it holds: the field is called
+ * `statusCallback` in both, and `statusCallback: ctx.statusCallback` at the RPC
+ * call site is correct in the fan-out and in the batched case alike — as is
+ * {@link makeFetchContext}'s `callRpc`, whose `this` parameter rebinds to the
+ * copy, so the envelope injects that operation's slot and not the batch's.
+ * Callers used to reach back to the model for `makeRegionStatusCallback(index)`,
+ * and the whole hazard was that forgetting to looked exactly like remembering
+ * to.
+ *
+ * Here beside `makeFetchContext` rather than in either fetch family, because
+ * both fan out inside one run: the per-region LGV helpers over N regions
+ * (`callEachRegion`), and the shared `installFetch` skeleton over whatever a
+ * display's `run` issues concurrently — the multi-way display's N lanes.
+ *
+ * The fan-out's lifetime is this batch's: slots are never reclaimed, and the
+ * batch is the thing that ends.
+ */
+export declare function fanOutStatus<C extends FetchContext>(ctx: C, count: number): C[];

package/esm/util/fetchContext.js

@@ -0,0 +1,59 @@
+import { getRpcSessionId } from './parentWalk.js';
+import { createStatusFanOut } from './progress.js';
+import { getRpcHost } from './sessionServices.js';
+/**
+ * Build a {@link FetchContext} over a live fetch's primitives. One
+ * constructor, so every context — `FetchMixin.runFetch`'s and `runFetchOnce`'s
+ * alike — carries the same `callRpc` envelope.
+ *
+ * **`self` has to be somewhere `getRpcSessionId` can find one, which in practice
+ * means a track or something under it.** `rpcSessionId` is declared by
+ * `BaseTrackModel` and by nothing above it, so the walk throws rather than
+ * falling back — and a fetch installed on a VIEW gets a context whose `callRpc`
+ * cannot be called at all. That is not a gap to fix here: the id names the track
+ * whose adapter is being read, and a view fetching for several tracks has a
+ * different one per call. The shape is to fan out and rebuild a context per
+ * track, which is what the breakpoint split view's overlay fetch does.
+ */
+export function makeFetchContext(self, base) {
+    return {
+        ...base,
+        callRpc(method, args) {
+            return getRpcHost(self).rpcManager.call(getRpcSessionId(self), method, {
+                ...args,
+                signal: this.signal,
+                statusCallback: this.statusCallback,
+            });
+        },
+    };
+}
+/**
+ * One context per concurrent operation, each carrying its own status slot, so
+ * the N of them aggregate into a single Σcurrent/Σtotal bar rather than
+ * last-writer-wins on the owner's one status field.
+ *
+ * A copy of the ctx rather than a separate `slot()` on it because a caller
+ * should not have to know which kind of context it holds: the field is called
+ * `statusCallback` in both, and `statusCallback: ctx.statusCallback` at the RPC
+ * call site is correct in the fan-out and in the batched case alike — as is
+ * {@link makeFetchContext}'s `callRpc`, whose `this` parameter rebinds to the
+ * copy, so the envelope injects that operation's slot and not the batch's.
+ * Callers used to reach back to the model for `makeRegionStatusCallback(index)`,
+ * and the whole hazard was that forgetting to looked exactly like remembering
+ * to.
+ *
+ * Here beside `makeFetchContext` rather than in either fetch family, because
+ * both fan out inside one run: the per-region LGV helpers over N regions
+ * (`callEachRegion`), and the shared `installFetch` skeleton over whatever a
+ * display's `run` issues concurrently — the multi-way display's N lanes.
+ *
+ * The fan-out's lifetime is this batch's: slots are never reclaimed, and the
+ * batch is the thing that ends.
+ */
+export function fanOutStatus(ctx, count) {
+    const slot = createStatusFanOut(ctx.statusCallback);
+    return Array.from({ length: count }, () => ({
+        ...ctx,
+        statusCallback: slot(),
+    }));
+}

package/esm/util/fetchHub.d.ts

@@ -0,0 +1,17 @@
+export interface HubConfig {
+    assemblies?: Record<string, unknown>[];
+    aggregateTextSearchAdapters?: (string | Record<string, unknown>)[];
+    tracks?: Record<string, unknown>[];
+    [key: string]: unknown;
+}
+export declare function hubUrl(hub: string): string;
+/**
+ * Fetch a hosted assembly config from jbrowse.org by UCSC database name (`hg38`,
+ * `mm10`, ...) or GenArk accession (`GCA_...`/`GCF_...`). Returns the full config
+ * — a self-contained assembly plus a catalog of CORS-enabled hosted tracks. Pass
+ * the name straight to `createLinearGenomeView({ assembly: 'hg38' })` for the
+ * common case; call this directly only to cherry-pick tracks from the catalog.
+ */
+export declare function fetchHub(hub: string, { signal }?: {
+    signal?: AbortSignal;
+}): Promise<HubConfig>;

package/esm/util/fetchHub.js

@@ -0,0 +1,31 @@
+import { addRelativeUris } from './addRelativeUris.js';
+const HUB_HOST = 'https://jbrowse.org';
+// A UCSC database name (hg38, mm10, ...) maps to /ucsc/<db>/; a GenArk accession
+// (GCA_/GCF_...) fans its 9 digits out into a 3-level directory tree.
+export function hubUrl(hub) {
+    const genark = /^(GC[AF])_(\d{3})(\d{3})(\d{3})/.exec(hub);
+    return genark
+        ? `${HUB_HOST}/hubs/genark/${genark[1]}/${genark[2]}/${genark[3]}/${genark[4]}/${hub}/config.json`
+        : `${HUB_HOST}/ucsc/${hub}/config.json`;
+}
+/**
+ * Fetch a hosted assembly config from jbrowse.org by UCSC database name (`hg38`,
+ * `mm10`, ...) or GenArk accession (`GCA_...`/`GCF_...`). Returns the full config
+ * — a self-contained assembly plus a catalog of CORS-enabled hosted tracks. Pass
+ * the name straight to `createLinearGenomeView({ assembly: 'hg38' })` for the
+ * common case; call this directly only to cherry-pick tracks from the catalog.
+ */
+export async function fetchHub(hub, { signal } = {}) {
+    const url = hubUrl(hub);
+    const response = await fetch(url, { signal });
+    if (response.ok) {
+        const config = (await response.json());
+        // hosted configs reference their data relative to the config's own location
+        addRelativeUris(config, new URL(url));
+        return config;
+    }
+    else {
+        throw new Error(`hub "${hub}" not found (${response.status} from ${url}). ` +
+            'See https://jbrowse.org for available assemblies.');
+    }
+}

package/esm/util/fetchJson.d.ts

@@ -0,0 +1 @@
+export declare function fetchJson<T = unknown>(url: string, init?: RequestInit): Promise<T>;

package/esm/util/fetchJson.js

@@ -0,0 +1,7 @@
+export async function fetchJson(url, init) {
+    const res = await fetch(url, init);
+    if (!res.ok) {
+        throw new Error(`HTTP ${res.status} fetching ${url}: ${await res.text().catch(() => '')}`);
+    }
+    return (await res.json());
+}

package/esm/util/fetchPhases.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The three phases a single-payload fetch is written in, so the rules that
+ * strand a display when any of them is got wrong are structural rather than
+ * remembered.
+ *
+ * The shared `installFetch` skeleton takes this shape, and so does the LGV
+ * global family (`installGlobalFetchAutorun`, a declaration over that same
+ * skeleton). It was the same contract declared twice, with the same three rules
+ * explained twice, which is a drift axis over rules whose whole value is being
+ * the same everywhere.
+ *
+ * `TCtx` is what a family hands its `run`: a `FetchContext` for most of them, a
+ * `ComparativeFetchContext` (that plus adapter config and refName rename) for
+ * the comparative displays, which wrap their own `run` rather than the skeleton
+ * growing an option. That is the one thing that genuinely differs, so it is the
+ * one parameter.
+ *
+ * **The per-region family is deliberately not this shape.** N regions stream and
+ * four displays decide something across them mid-fetch, so there is nowhere to
+ * put a single `commit` — it gets the same "never record what you did not
+ * receive" invariant from `RegionFetchContext.commitRegion` instead, and the
+ * note there is worth reading beside this one.
+ */
+export interface FetchPhases<TArgs, TResult, TCtx> {
+    /**
+     * Runs synchronously inside the autorun, so its reads — on top of the
+     * skeleton's own trigger list — are the dependency set. Returning `undefined`
+     * skips the run (minimized, an empty viewport, the display's own gate shut);
+     * the reads that decided that stay tracked, so the autorun rewakes. Everything
+     * the round trip has to be judged against is captured here and travels in
+     * `TArgs`: the viewport, the region set, the resolution.
+     *
+     * Prefer folding the fetch's inputs into one `currentFetchKey` computed over
+     * tracking them individually: a pan inside the buffered window then recomputes
+     * the same string and does not refire, and that same string tags the committed
+     * data so it cannot drift from what was fetched even if the view moves again
+     * mid-RPC.
+     *
+     * **Comparing that key against what is already committed does not belong
+     * here.** This gate is "is there anything to fetch", which a retry must not
+     * override; "do I already have exactly this" is `installFetch`'s `fetchKey` gate,
+     * which a retry must. Writing the second one into this one is how a display
+     * gets a dead Retry button — see there.
+     *
+     * What it must **not** do is move a trigger read of its own under a bail-out.
+     * See reference/FETCH_SKELETON.md §"The global-fetch trigger list must be read
+     * unconditionally".
+     */
+    prepare: () => TArgs | undefined;
+    /**
+     * Owns every await — the RPC, a byte-gate pre-flight, any post-RPC derivation
+     * the commit needs — and writes nothing to the model. Returns `undefined` for
+     * "nothing to commit", which is what a pre-flight that stopped this fetch
+     * says.
+     *
+     * **Nothing it reads is tracked**, so the payload it assembles cannot widen
+     * the autorun's dependency set the way calling `rpcProps()` in the body would.
+     * Being async is not what buys that — `run` is *called* synchronously, so its
+     * own prefix down to its first `await` runs wherever the caller was. The
+     * `installFetch` skeleton calls it inside `untracked`, which covers the
+     * global and comparative families with it; the per-region family reaches its
+     * work through `FetchMixin.runFetch`, an MST flow and so an action, which
+     * MobX runs untracked.
+     */
+    run: (args: TArgs, ctx: TCtx) => Promise<TResult | undefined>;
+    /**
+     * Synchronous, and reached only while this is still the latest fetch, so a
+     * superseded fetch resolving late cannot clobber fresher data. Async work here
+     * would reopen exactly that window, which is why it may not await. It takes
+     * `args` back, so what it stamps onto the committed data is what the fetch was
+     * issued for and not a live re-read.
+     *
+     * **Reached only when `run` produced a result**, which is what keeps a display
+     * from ever recording data it did not receive.
+     */
+    commit: (result: TResult, args: TArgs) => void;
+}

package/esm/util/fetchPhases.js

@@ -0,0 +1 @@
+export {};

package/esm/util/fetchSeq.d.ts

@@ -1,8 +1,11 @@
+import type { StatusCallback } from './progress.ts';
 import type { AbstractSessionModel } from './types/index.ts';
-export declare function fetchSeq({ start, end, refName, assemblyName, session, }: {
+export declare function fetchSeq({ start, end, refName, assemblyName, session, signal, statusCallback, }: {
     start: number;
     end: number;
     refName: string;
     assemblyName: string;
     session: AbstractSessionModel;
+    signal?: AbortSignal;
+    statusCallback?: StatusCallback;
 }): Promise<string>;

package/esm/util/fetchSeq.js

@@ -1,23 +1,35 @@
-import { getConf } from "../configuration/index.js";
-export async function fetchSeq({ start, end, refName, assemblyName, session, }) {
+import { getSequenceAdapterConfig } from '../assemblyManager/getSequenceAdapterConfig.js';
+export async function fetchSeq({ start, end, refName, assemblyName, session, signal, statusCallback, }) {
     const { rpcManager, assemblyManager } = session;
     const assembly = await assemblyManager.waitForAssembly(assemblyName);
     if (!assembly) {
         throw new Error('assembly not found');
     }
     const sessionId = 'getSequence';
-    const adapterConfig = getConf(assembly, ['sequence', 'adapter']);
+    // Undefined here means the assembly's `configuration` safeReference is
+    // unresolved — the assembly outlived the config entry it points at. NOT an
+    // assembly whose sequence carries no residues: a ChromSizesAdapter one still
+    // has a `sequence.adapter`, and fails later, inside the adapter. Say which
+    // this is; passing the undefined on fails in getAdapterPre as "could not
+    // determine adapter type", naming neither the assembly nor what was wanted.
+    const adapterConfig = getSequenceAdapterConfig(assembly);
+    if (!adapterConfig) {
+        throw new Error(`assembly ${assemblyName} has no resolved configuration, so its sequence adapter cannot be read`);
+    }
+    // Get the canonical refName, then translate to the sequence adapter refName
+    // (in FASTA). These may differ when refNameAliases override.
     const canonicalRefName = assembly.getCanonicalRefName2(refName);
     const seqAdapterRefName = assembly.getSeqAdapterRefName(canonicalRefName);
-    const seq = (await rpcManager.call(sessionId, 'CoreGetSequence', {
+    const seq = await rpcManager.call(sessionId, 'CoreGetSequence', {
         adapterConfig,
-        sessionId,
         region: {
             start,
             end,
             refName: seqAdapterRefName,
             assemblyName,
         },
-    }));
+        signal,
+        statusCallback,
+    });
     return seq ?? '';
 }

package/esm/util/fieldReader.d.ts

@@ -0,0 +1,17 @@
+import type { JexlInstance } from './jexlStrings.ts';
+import type { Feature } from './simpleFeature.ts';
+/**
+ * #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 declare function fieldReader(ref: string, jexl: JexlInstance | undefined): (feature: Feature) => unknown;
+/**
+ * #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 declare function isPlainFieldRef(ref: string): ref is never;

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

@@ -1,6 +1,23 @@
+declare global {
+    interface FileSystemFileHandle {
+        queryPermission(options: {
+            mode: 'read' | 'readwrite';
+        }): Promise<PermissionState>;
+        requestPermission(options: {
+            mode: 'read' | 'readwrite';
+        }): Promise<PermissionState>;
+    }
+}
 export declare function isFileSystemAccessSupported(): boolean;
+/**
+ * Which stored handles the pruner drops: everything past the
+ * MAX_STORED_HANDLES first-picked most recently.
+ *
+ * Split out and exported for the same reason staleSessionIds is — jsdom has no
+ * IndexedDB, so the transaction around it never runs under jest, and this is the
+ * one part of the decision that is testable at all.
+ */
+export declare function staleHandleIds(keys: string[]): string[];
 export declare function storeFileHandle(handle: FileSystemFileHandle): Promise<string>;
 export declare function getFileHandle(handleId: string): Promise<FileSystemFileHandle | undefined>;
-export declare function removeFileHandle(handleId: string): Promise<void>;
 export declare function verifyPermission(handle: FileSystemFileHandle, requestPermission?: boolean): Promise<boolean>;
-export declare function cleanupStaleHandles(maxAgeMs: number): Promise<void>;