@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/assemblyManager/assembly.d.ts

@@ -1,75 +1,348 @@
+import QuickLRU from '../util/QuickLRU/index.ts';
 import type PluginManager from '../PluginManager.ts';
 import type { BaseOptions } from '../data_adapters/BaseAdapter/index.ts';
 import type RpcManager from '../rpc/RpcManager.ts';
 import type { Feature, Region } from '../util/index.ts';
+import type { RpcStatus } from '../util/progress.ts';
+import type { RefNameAliases, RefNameMaps } from './refNameMaps.ts';
+import type { RefNameMismatch } from './refNameMismatch.ts';
 import type { IAnyType, Instance } from '@jbrowse/mobx-state-tree';
+export { getSequenceAdapterConfig } from './getSequenceAdapterConfig.ts';
+export { buildRefNameMaps } from './refNameMaps.ts';
+export { lookupGeneticCodeId } from './geneticCodes.ts';
+export { refNameMismatchMessage } from './refNameMismatch.ts';
+export type { RefNameAliases, RefNameMaps } from './refNameMaps.ts';
+export type { RefNameMismatch } from './refNameMismatch.ts';
 type AdapterConf = Record<string, unknown>;
-type RefNameAliases = Record<string, string>;
-export interface RefNameMap {
-    forwardMap: RefNameAliases;
-    reverseMap: RefNameAliases;
-}
 export interface BasicRegion {
     start: number;
     end: number;
     refName: string;
     assemblyName: string;
 }
+/**
+ * #stateModel Assembly
+ */
 export default function assemblyFactory(assemblyConfigType: IAnyType, pluginManager: PluginManager): import("@jbrowse/mobx-state-tree").IModelType<{
+    /**
+     * #property
+     */
     configuration: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").IReferenceType<IAnyType>>;
 }, {
+    /**
+     * #volatile
+     */
     error: unknown;
+    /**
+     * #volatile
+     */
     loadingP: Promise<void> | undefined;
+    adapterLoads: QuickLRU<string, Promise<RefNameAliases>>;
+    /**
+     * #volatile
+     */
     volatileRegions: BasicRegion[] | undefined;
+    /**
+     * #volatile
+     */
     refNameAliases: RefNameAliases | undefined;
+    /**
+     * #volatile
+     * Maps canonical refName -> sequence adapter refName (in FASTA).
+     * These may differ when refNameAliases with override:true remap names.
+     */
     canonicalToSeqAdapterRefNames: Record<string, string> | undefined;
+    /**
+     * #volatile
+     */
     cytobands: Feature[] | undefined;
+    /**
+     * #volatile
+     * refName -> NCBI genetic-code id loaded from `geneticCodesLocation`;
+     * merged with (and overridden by) the inline `geneticCodes` config slot
+     */
+    loadedGeneticCodes: Record<string, number> | undefined;
+    /**
+     * #volatile
+     * Precomputed in loadPre to avoid expensive synchronous computation
+     * when MobX triggers the autorun after setLoaded
+     */
+    lowerCaseRefNameAliases: RefNameAliases | undefined;
+    /**
+     * #volatile
+     * What the in-flight load is doing ("Downloading chromosome sizes"), for a
+     * view that is showing a spinner while it waits. Same split as
+     * BaseDisplayModel's status fields, so the same LoadingProgress UI
+     * renders both.
+     */
+    statusMessage: string | undefined;
+    /**
+     * #volatile
+     * Fraction in [0,1] when the load reports determinate progress
+     */
+    statusProgress: number | undefined;
+    /**
+     * #volatile
+     * The URL the in-flight phase is fetching, when it named one. A load
+     * that hangs shows this and not the label: "Downloading chromosome
+     * aliases" forever says nothing a user can act on, and the address of
+     * the server that stopped answering does.
+     */
+    statusSource: string | undefined;
+    /**
+     * #volatile
+     * adapter cache key -> the empty-intersection verdict `loadRefNameMap`
+     * reached for that adapter under this assembly. Sits beside
+     * `adapterLoads` and is keyed the same way, so it inherits that cache's
+     * once-per-(assembly, adapter config) property: the diagnostic is
+     * recorded exactly as often as the map is built, which is once.
+     *
+     * Written by replacing the Map rather than mutating it — a Map inside a
+     * volatile is one observable, not a deeply observable collection, so a
+     * `.set()` would leave every reader stale.
+     */
+    refNameMismatches: Map<string, RefNameMismatch>;
 } & {
+    /**
+     * #method
+     */
     getConf(arg: string): any;
-    readonly lowerCaseRefNameAliases: {
-        [k: string]: string;
-    } | undefined;
 } & {
-    readonly initialized: boolean;
+    /**
+     * #getter
+     */
     readonly name: string;
-    readonly regions: BasicRegion[] | undefined;
+    /**
+     * #getter
+     */
     readonly aliases: string[];
+    /**
+     * #getter
+     */
     readonly displayName: string;
-    hasName(name: string): boolean;
-    readonly allAliases: string[];
-    readonly allRefNames: string[] | undefined;
-    readonly lowerCaseRefNames: string[] | undefined;
-    readonly allRefNamesWithLowerCase: string[] | undefined;
-    readonly rpcManager: RpcManager;
+    /**
+     * #getter
+     */
     readonly refNameColors: string[];
 } & {
-    readonly refNames: string[] | undefined;
+    /**
+     * #getter
+     */
+    readonly allAliases: string[];
+    /**
+     * #method
+     */
+    hasName(name: string): boolean;
 } & {
-    getCanonicalRefName(refName: string): string | undefined;
-    getCanonicalRefName2(refName: string): string;
-    getRefNameColor(refName: string): string | undefined;
-    isValidRefName(refName: string): boolean;
-    getSeqAdapterRefName(canonicalRefName: string): string;
+    /**
+     * #action
+     * Records what the in-flight load is doing. Its own actions block (rather
+     * than sitting next to setLoaded) so loadPre can hand `self.setStatus` to
+     * the adapters as a plain callback: it fires after awaits, outside the
+     * action that started the load, and a volatile write there has to go
+     * through an action of its own.
+     */
+    setStatus(status?: RpcStatus): void;
+    /**
+     * #action
+     * Record that an adapter's reference names and this assembly's have
+     * nothing in common. Diagnostic only: `loadRefNameMap` still returns its
+     * map and the track still loads, because a wrong guess here must not take
+     * a working track away from anyone.
+     */
+    setRefNameMismatch(adapterCacheKey: string, mismatch: RefNameMismatch): void;
 } & {
-    setLoaded({ regions, refNameAliases, cytobands, }: {
+    /**
+     * #action
+     * Applies all load-time state in a single transaction so dependent
+     * autoruns fire once, with the precomputed lowercase/name lookups already
+     * in place by the time refNameAliases becomes observable.
+     */
+    setLoaded({ regions, refNameAliases, lowerCaseRefNameAliases, canonicalToSeqAdapterRefNames, cytobands, geneticCodes, }: RefNameMaps & {
         regions: Region[];
-        refNameAliases: RefNameAliases;
         cytobands: Feature[];
+        geneticCodes: Record<string, number>;
     }): void;
+    /**
+     * #action
+     */
     setError(e: unknown): void;
-    setRegions(regions: Region[]): void;
-    setRefNameAliases(aliases: RefNameAliases): void;
-    setCytobands(cytobands: Feature[]): void;
-    setCanonicalToSeqAdapterRefNames(map: Record<string, string>): void;
+    /**
+     * #action
+     */
     setLoadingP(p?: Promise<void>): void;
-    load(): Promise<void>;
+    /**
+     * #action
+     */
     loadPre(): Promise<void>;
 } & {
-    getAdapterMapEntry(adapterConf: AdapterConf, options: BaseOptions): Promise<RefNameMap>;
-    getRefNameMapForAdapter(adapterConf: AdapterConf, opts: BaseOptions): Promise<RefNameAliases>;
-    getReverseRefNameMapForAdapter(adapterConf: AdapterConf, opts: BaseOptions): Promise<RefNameAliases>;
-    afterCreate(): void;
+    /**
+     * #action
+     * Resolves once regions + refNameAliases are set, and rejects with the
+     * load failure. Idempotent: concurrent callers share one attempt, and a
+     * failed attempt is discarded so the next call retries.
+     *
+     * The rejection is the authoritative signal for a caller that awaits it.
+     * `self.error` mirrors it for reactive consumers only (the UI renders it),
+     * and must not be consulted after an await: a concurrent retry clears it,
+     * so an awaiter reading it can see a cleared error and mistake a failed
+     * load for a successful one.
+     */
+    load(): Promise<void>;
+} & {
+    afterAttach(): void;
+} & {
+    /**
+     * #getter
+     */
+    readonly initialized: boolean;
+    /**
+     * #getter
+     */
+    readonly regions: BasicRegion[] | undefined;
+    /**
+     * #getter
+     * note: lowerCaseRefNameAliases not included here: this allows the list
+     * of refnames to be just the "normal casing", but things like
+     * getCanonicalRefName can resolve a lower-case name if needed
+     */
+    readonly allRefNames: string[] | undefined;
+    /**
+     * #getter
+     * canonical refName -> every name this assembly has for that sequence,
+     * canonical first. The inverse of `refNameAliases`, memoized here because
+     * the readers that want it want the whole table (the About dialog's alias
+     * listing) rather than one row. Undefined until the aliases load.
+     */
+    readonly namesByCanonicalRefName: Map<string, string[]> | undefined;
+    /**
+     * #getter
+     */
+    readonly rpcManager: RpcManager;
+} & {
+    /**
+     * #getter
+     */
+    readonly refNames: string[] | undefined;
+} & {
+    /**
+     * #getter
+     * memoized refName -> first region index, so getRefNameColor is O(1)
+     * instead of an O(n) indexOf per call (matters for assemblies with many
+     * contigs rendered in overview scalebars/rulers)
+     */
+    readonly refNameToIndex: Map<string, number> | undefined;
+} & {
+    /**
+     * #method
+     * Returns the canonical refName for a given alias or refName.
+     * Note: The canonical name may differ from what's in the FASTA file when
+     * refNameAliases with override:true are configured. To get the name that
+     * matches the FASTA file, use getSeqAdapterRefName().
+     */
+    getCanonicalRefName(refName: string): string | undefined;
+    /**
+     * #method
+     */
+    getRefNameColor(refName: string): string | undefined;
+    /**
+     * #method
+     * The whole-contig region for a CANONICAL refName — its extents, and so
+     * the bounds anything placing a span on it has to clamp into. Undefined
+     * before `regions` loads, and for a refName this assembly doesn't have.
+     *
+     * Reads the `refNameToIndex` memo, which is why this exists rather than
+     * each caller writing `assembly.regions?.find(r => r.refName === name)`:
+     * five of them did, and that scan is O(contigs) per call on an assembly
+     * whose whole point is that it may have thousands.
+     */
+    getRegionForRefName(refName: string): BasicRegion | undefined;
+    /**
+     * #method
+     * NCBI genetic-code (translation table) id for a refName, from the
+     * assembly's `geneticCodes` config map (e.g. a mitochondrial contig = 2).
+     * Falls back to the standard code (1) for unlisted refNames.
+     */
+    getGeneticCodeId(refName: string): number;
+    /**
+     * #method
+     * Given a canonical refName, returns the refName used by the sequence
+     * adapter (what's in the FASTA file). Falls back to the input if no
+     * mapping exists.
+     */
+    getSeqAdapterRefName(canonicalRefName: string): string;
+} & {
+    /**
+     * #method
+     * The total canonical-refName resolver, for any name arriving from
+     * outside — off a feature, out of an RPC result, out of a session spec.
+     * A name the assembly does not know comes back unchanged, and so does one
+     * asked for before the aliases load, where `getCanonicalRefName` answers
+     * `undefined` for the first and THROWS for the second.
+     *
+     * The throw is the reason to call this rather than hand-roll
+     * `getCanonicalRefName(x) ?? x`: that idiom looks total and is not, and
+     * these resolutions sit in getters and render paths that run from the
+     * first frame, before the alias file has landed. Answering with the input
+     * there means the comparison downstream may miss, but it misses for one
+     * frame and re-runs, where a throw out of a getter takes the view down.
+     * `initialized` is the gate for a caller that needs to know which answer
+     * it got.
+     *
+     * See getCanonicalRefName() for what canonical means when
+     * `refNameAliases` carries an `override`.
+     */
+    getCanonicalRefName2(refName: string): string;
+    /**
+     * #method
+     */
+    isValidRefName(refName: string): boolean;
+} & {
+    /**
+     * #method
+     * The other names this assembly has for the same sequence as `refName` —
+     * its aliases, whether the name handed in is an alias or the canonical
+     * name. `chr1`, `1` and `NC_000001.11` each answer with the other two.
+     *
+     * Empty for a name this assembly does not have, and also before the
+     * aliases load: this resolves through `getCanonicalRefName2` so it can be
+     * called from a render, and `initialized` is what distinguishes the two.
+     */
+    getAliasesForRefName(refName: string): string[];
+    /**
+     * #method
+     * get Map of `canonical-name -> adapter-specific-name`, memoized per
+     * adapter config so concurrent callers share one load
+     *
+     * The load reports progress (the adapter's index download, or for an
+     * in-memory adapter the whole file) through the `statusCallback` of
+     * whichever caller started it. The others await it silently, and that is
+     * deliberate rather than a gap worth plumbing around: the callers sharing
+     * an entry are almost always the N displayed regions of ONE display, so
+     * their callbacks all write into that display's aggregated status bar and
+     * the first one is already reporting on behalf of the rest. The costs of
+     * getting this "right" — a listener set per key, registration, and
+     * deregistration on settle — buy visibility only for a second display on
+     * the same file, and for a first caller torn down mid-load, which is a
+     * no-op rather than a hazard because the callbacks are `isAlive`-guarded
+     * at the display end.
+     *
+     * If that ever stops being enough, the fix is not a subscription list
+     * bolted on here: it is for the assembly to hold the in-flight status as
+     * observable state that consumers read, which is what this model is
+     * already made of.
+     */
+    getRefNameMapForAdapter(adapterConf: AdapterConf, options: BaseOptions): Promise<RefNameAliases>;
+    /**
+     * #method
+     * The empty-intersection verdict for an adapter under this assembly, if
+     * the map load reached one. Keyed by `adapterConfigCacheKey`, which is
+     * what a track already computes as its `rpcSessionId` — so a track looks
+     * up its own diagnostic with no plumbing between here and it. Undefined
+     * until the map has loaded, which is the same instant the track's first
+     * fetch resolves.
+     */
+    getRefNameMismatch(adapterCacheKey: string): RefNameMismatch | undefined;
 }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>;
 export type AssemblyModel = ReturnType<typeof assemblyFactory>;
 export type Assembly = Instance<AssemblyModel>;
-export {};