@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/TextSearch/TextSearchManager.js

@@ -1,6 +1,26 @@
-import uFuzzy from '@leeoniya/ufuzzy';
-import { readConfObject } from "../configuration/index.js";
-import QuickLRU from "../util/QuickLRU/index.js";
+import { readConfObject } from '../configuration/index.js';
+import QuickLRU from '../util/QuickLRU/index.js';
+import { isAbortException } from '../util/aborting.js';
+import { checkStopToken } from '../util/stopToken.js';
+import { canonicalAssemblyNames } from '../util/tracks.js';
+// A misconfigured or unreachable index (a 404 .ix, a config missing
+// ixFilePath) must not take down search as a whole: the remaining indexes, and
+// the refName results the caller merges in afterwards, are still useful. Log
+// the failures and keep going rather than rejecting. An abort is not a failure
+// — every keystroke supersedes the previous query, so logging those would turn
+// normal typing into console spam.
+async function keepFulfilled(promises, message) {
+    const out = [];
+    for (const settled of await Promise.allSettled(promises)) {
+        if (settled.status === 'fulfilled') {
+            out.push(settled.value);
+        }
+        else if (!isAbortException(settled.reason)) {
+            console.error(message, settled.reason);
+        }
+    }
+    return out;
+}
 export default class TextSearchManager {
     pluginManager;
     adapterCache = new QuickLRU({
@@ -12,8 +32,8 @@ export default class TextSearchManager {
     clearCache() {
         this.adapterCache.clear();
     }
-    loadTextSearchAdapters(searchScope) {
-        return Promise.all(this.relevantAdapters(searchScope).map(async (conf) => {
+    loadTextSearchAdapters(assemblyName) {
+        return keepFulfilled(this.relevantAdapters(assemblyName).map(async (conf) => {
             const adapterId = readConfObject(conf, 'textSearchAdapterId');
             const r = this.adapterCache.get(adapterId);
             if (r) {
@@ -26,55 +46,88 @@ export default class TextSearchManager {
                 this.adapterCache.set(adapterId, adapterInstance);
                 return adapterInstance;
             }
-        }));
+        }), 'failed to load text search adapter');
     }
-    relevantAdapters(searchScope) {
-        const rootModel = this.pluginManager.rootModel;
-        const { aggregateTextSearchAdapters } = rootModel?.jbrowse;
-        const { tracks } = rootModel?.session;
-        const { assemblyName } = searchScope;
+    relevantAdapters(assemblyName) {
+        const { rootModel } = this.pluginManager;
+        // jbrowse is typed as a bare state tree node, so its config slots need a
+        // shape assertion; both it and the session are absent until a session is
+        // loaded, which is before anything can search
+        const { aggregateTextSearchAdapters = [] } = (rootModel?.jbrowse ?? {});
+        // The caller searches an assembly by the name the session knows it by,
+        // while an index names whatever the track it was built from named — so both
+        // sides go through the aliases, as every other "does this belong to this
+        // assembly" test in the app now does. Absent a session there is nothing to
+        // resolve against and the raw name is the best available answer.
+        const assemblyManager = rootModel?.session?.assemblyManager;
+        const canonical = (names) => assemblyManager
+            ? canonicalAssemblyNames(names, assemblyManager)
+            : names.filter(name => !!name);
+        const [wanted] = canonical([assemblyName]);
+        const matches = (names) => !!wanted && !!names && canonical(names).includes(wanted);
         return [
-            ...this.getAdaptersWithAssembly(assemblyName, aggregateTextSearchAdapters),
-            ...this.getTrackAdaptersWithAssembly(assemblyName, tracks),
+            ...this.getAdaptersWithAssembly(matches, aggregateTextSearchAdapters),
+            ...this.getTrackAdaptersWithAssembly(matches, rootModel?.session?.tracks ?? []),
         ];
     }
-    getAdaptersWithAssembly(assemblyName, confs) {
-        return confs.filter(c => readConfObject(c, 'assemblyNames')?.includes(assemblyName));
+    getAdaptersWithAssembly(matches, confs) {
+        return confs.filter(c => matches(readConfObject(c, 'assemblyNames')));
     }
-    getTrackAdaptersWithAssembly(assemblyName, confs) {
+    getTrackAdaptersWithAssembly(matches, confs) {
         return confs
-            .filter(conf => readConfObject(conf, [
+            .filter(conf => matches(readConfObject(conf, [
             'textSearching',
             'textSearchAdapter',
             'assemblyNames',
-        ])?.includes(assemblyName))
+        ])))
             .map(conf => conf.textSearching.textSearchAdapter);
     }
-    async search(args, searchScope, rankFn) {
-        return this.search2({ args, searchScope, rankFn });
-    }
-    async search2({ args, searchScope, rankFn, }) {
-        const adapters = await this.loadTextSearchAdapters(searchScope);
-        const results = await Promise.all(adapters.map(a => a.searchIndex(args)));
-        return this.sortResults2({
-            args,
-            results: results.flat(),
-            rankFn,
-        });
+    async search(args, assemblyName) {
+        const adapters = await this.loadTextSearchAdapters(assemblyName);
+        const results = await keepFulfilled(adapters.map(a => a.searchIndex(args)), 'text search adapter failed');
+        // the ranking below is the expensive half — a dynamic import plus a fuzzy
+        // sort over every hit — and a superseded keystroke has no use for it.
+        // Checked here rather than only inside the adapters because keepFulfilled
+        // deliberately drops a failing adapter and carries on, so an abort thrown
+        // by one of them would otherwise still land here as "no results from that
+        // index" and rank the rest
+        checkStopToken(args.stopToken);
+        return await this.sortResults({ args, results: results.flat() });
     }
-    sortResults2({ results, rankFn, args, }) {
+    // Ranks, never filters: the adapters have already decided what matches, and
+    // they match against attributes the display string does not always carry (a
+    // multi-word query hits e.g. the description while the display string is just
+    // the gene name). uFuzzy floats the results whose display string matches the
+    // query to the top and the rest keep their adapter order behind them.
+    //
+    // uFuzzy is imported here rather than at the top of the file so its 26KB stay
+    // out of the startup bundle: TextSearchManager is constructed by BaseRootModel
+    // on every page load, but nothing ranks results until the user searches.
+    async sortResults({ results, args, }) {
+        const { default: uFuzzy } = await import('@leeoniya/ufuzzy');
         const uf = new uFuzzy({});
+        // this code sample relatively unmodified from
+        // https://github.com/leeoniya/uFuzzy?tab=readme-ov-file#example
         const haystack = results.map(r => r.getDisplayString());
         const needle = args.queryString;
+        // false positive, this is not Array.prototype.filter
         const idxs = uf.filter(haystack, needle);
-        const res = [];
-        if (idxs != null && idxs.length > 0) {
+        const ranked = [];
+        const seen = new Set();
+        // idxs can be null when the needle is non-searchable (has no alpha-numeric chars)
+        if (idxs?.length) {
             const info = uf.info(idxs, haystack, needle);
+            // order is a double-indirection array (a re-order of the passed-in idxs)
+            // this allows corresponding info to be grabbed directly by idx, if needed
             const order = uf.sort(info, haystack, needle);
             for (const element of order) {
-                res.push(results[info.idx[element]]);
+                // using info.idx here instead of idxs because uf.info() may have
+                // further reduced the initial idxs based on prefix/suffix rules
+                const idx = info.idx[element];
+                seen.add(idx);
+                ranked.push(results[idx]);
             }
         }
-        return rankFn(res);
+        return [...ranked, ...results.filter((_, i) => !seen.has(i))];
     }
 }

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 {};