@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/tracks.d.ts

@@ -1,12 +1,90 @@
-import type { BlobLocation, FileHandleLocation, FileLocation, PreFileLocation } from './types/index.ts';
+export { getFileName } from './getFileName.ts';
+export { getRpcSessionId } from './parentWalk.ts';
+import type PluginManager from '../PluginManager.ts';
 import type { AnyConfigurationModel } from '../configuration/index.ts';
-import type { IAnyStateTreeNode, IAnyType, Instance, types } from '@jbrowse/mobx-state-tree';
-export declare function getTrackAssemblyNames(track: IAnyStateTreeNode & {
+import type { BlobLocation, FileHandleLocation, FileLocation, PreFileLocation } from './types/data.ts';
+import type { AbstractViewContainer } from './types/index.ts';
+import type { IAnyStateTreeNode, IAnyType, IStateTreeNode, Instance, types } from '@jbrowse/mobx-state-tree';
+export declare function getTrackAssemblyNames(track: IStateTreeNode & {
     configuration: AnyConfigurationModel;
 }): string[];
+/**
+ * What {@link canonicalAssemblyNames} needs of an assembly manager — the one
+ * method — so a picker that only resolves names says so in its signature and a
+ * test can stand in for it without building a session.
+ */
+export interface AssemblyNameResolver {
+    getCanonicalAssemblyName: (name: string) => string | undefined;
+}
+/**
+ * {@link AssemblyNameResolver} plus the presence test, for a picker that also
+ * has to screen out names the session cannot open at all.
+ *
+ * The screen is `has`, deliberately, and not
+ * `getCanonicalAssemblyName(name) !== undefined`: that reads `assemblyNameMap`,
+ * which is built from assembly *models*, so it answers no during the window
+ * where a config exists and the manager's afterAttach autorun hasn't built its
+ * model yet — which is exactly when an import form first renders. `has` also
+ * consults `confByName`, read off the configs, so it covers both. See
+ * assemblyManager's own note on the pair.
+ */
+export interface SessionAssemblies extends AssemblyNameResolver {
+    has: (assemblyName: string) => boolean;
+}
+/**
+ * Assembly names as the aliases resolve them, so a track configured against
+ * `hg38` compares equal to a view on `GRCh38`. Every "does this track belong to
+ * these assemblies" test should run both sides through this, or the same track
+ * is offered by one picker and hidden by another.
+ *
+ * A name the assembly manager doesn't know is kept **as written**, not dropped.
+ * Dropping it means "matches nothing" on the track side but "no constraint at
+ * all" on the list side, and those disagree; kept, both sides compare the same
+ * raw string and matching degrades to the exact name — which is also the right
+ * answer in the window before the assembly manager has built its models. Empty
+ * names are dropped: a half-initialized view pads its assembly list with them.
+ */
+export declare function canonicalAssemblyNames(names: string[], assemblyManager: AssemblyNameResolver): string[];
+/**
+ * Whether two names name the same assembly, resolving aliases on both sides.
+ *
+ * The pairwise counterpart to {@link canonicalAssemblyNames}, for the two
+ * places a list cannot be mapped: an index-aligned array, which that function's
+ * empty-name filter would desync, and a comparison where one side must come
+ * back in the caller's own spelling rather than the canonical one.
+ *
+ * **Both sides, or it buys nothing.** The names meeting at these comparisons
+ * come from different places — a view holds what the session opened it on, a
+ * track config holds what its author wrote, and a synteny mate holds whatever
+ * the adapter resolved a PanSN prefix to. Any two of those can be aliases of
+ * one assembly, and `===` says no.
+ *
+ * A name the assembly manager doesn't know compares as written, the same
+ * degradation {@link canonicalAssemblyNames} makes and for the same reason: an
+ * all-vs-all file carries sample names no config declares, and those still have
+ * to compare equal to themselves.
+ */
+export declare function isSameAssemblyName(a: string | undefined, b: string | undefined, assemblyManager: AssemblyNameResolver): boolean;
 export declare function getConfAssemblyNames(conf: AnyConfigurationModel): string[];
-export declare function getRpcSessionId(thisNode: IAnyStateTreeNode): string;
-export declare function getParentRenderProps(node: IAnyStateTreeNode): any;
+/**
+ * {@link getConfAssemblyNames} for a caller that cannot afford its throw — a
+ * config answering neither way leaves the question unanswered instead.
+ *
+ * `BaseTrackModel.refNameMismatch` is the caller: it runs on every render of
+ * every track label, so an unanswerable question must not become a thrown
+ * getter. It used to read the raw `assemblyNames` slot itself for that reason,
+ * which is a second, subtly different copy of the walk above — and one that
+ * answers `[]` for a ReferenceSequenceTrack whose assembly this already knows
+ * how to name.
+ */
+export declare function getConfAssemblyNamesOrNone(conf: AnyConfigurationModel): string[];
+/**
+ * The RPC session id a track's own requests go out under, from its config:
+ * what `BaseTrackModel.rpcSessionId` computes, for a caller holding no model.
+ * A call under any other id lands on another worker, which builds a second
+ * copy of the adapter that nothing frees.
+ */
+export declare function getConfRpcSessionId(conf: AnyConfigurationModel): string;
 export declare const UNKNOWN = "UNKNOWN";
 export declare const UNSUPPORTED = "UNSUPPORTED";
 export declare function getBlob(id: string): File | undefined;
@@ -16,60 +94,202 @@ export declare function storeBlobLocation(location: PreFileLocation): BlobLocati
 export declare function getFileFromCache(handleId: string): File | undefined;
 export declare function setFileInCache(handleId: string, file: File): void;
 export declare function clearFileFromCache(handleId: string): void;
-export declare function getFileHandleCache(): Record<string, File>;
-export declare function setFileHandleCache(cache: Record<string, File>): void;
+export declare function hasFileHandlesInCache(): boolean;
 export declare function ensureFileHandleReady(handleId: string, requestPermission?: boolean): Promise<File>;
 export declare function storeFileHandleLocation(handle: FileSystemFileHandle): Promise<FileHandleLocation>;
+/**
+ * Resolves a batch of stored file handles, one result per id.
+ *
+ * With `requestPermission` set these run ONE AT A TIME, and that is the whole
+ * point of the branch. `requestPermission()` needs transient user activation and
+ * the browser puts a single file-access prompt on screen at a time, so N of them
+ * fired off one "Restore access" click means the first call takes the prompt and
+ * the rest are refused without the user ever seeing a dialog — files reported
+ * back as permission failures that nobody was asked about. Taking turns, each
+ * prompt waits for the one before it to be answered, and whatever the activation
+ * window no longer covers is simply still pending for the next click instead of
+ * being spent.
+ *
+ * Without it nothing can prompt, so there is nothing to take turns over and the
+ * batch runs at once.
+ */
 export declare function restoreFileHandles(handleIds: string[], requestPermission?: boolean): Promise<({
     handleId: string;
-    success: boolean;
+    success: true;
     error?: undefined;
 } | {
     handleId: string;
-    success: boolean;
+    success: false;
     error: unknown;
 })[]>;
-export declare function findFileHandleIds(obj: unknown, handleIds?: Set<string>, seen?: WeakSet<object>): Set<string>;
+export declare function findFileHandleIds(obj: unknown): Set<string>;
 export declare function restoreFileHandlesFromSnapshot(sessionSnapshot: unknown, requestPermission?: boolean): Promise<({
     handleId: string;
-    success: boolean;
+    success: true;
     error?: undefined;
 } | {
     handleId: string;
-    success: boolean;
-    error: unknown;
-})[]>;
-export declare function getPendingFileHandleIds(): string[];
-export declare function setPendingFileHandleIds(ids: string[]): void;
-export declare function clearPendingFileHandleIds(): void;
-export declare function restorePendingFileHandles(): Promise<({
-    handleId: string;
-    success: boolean;
-    error?: undefined;
-} | {
-    handleId: string;
-    success: boolean;
+    success: false;
     error: unknown;
 })[]>;
+/**
+ * creates a new location from the provided location including the appropriate
+ * suffix and location type
+ *
+ * @param location - the FileLocation
+ * @param suffix - the file suffix (e.g. .bam)
+ * @returns the constructed location object from the provided parameters
+ */
 export declare function makeIndex(location: FileLocation, suffix: string): BlobLocation | FileHandleLocation | {
     uri: string;
     locationType: string;
+    baseUri?: string | undefined;
     localPath?: undefined;
 } | {
     localPath: string;
     locationType: string;
-    uri?: undefined;
 };
+/**
+ * constructs a potential index file (with suffix) from the provided file name
+ *
+ * @param name - the name of the index file
+ * @param typeA - one option of a potential two file suffix (e.g. CSI, BAI)
+ * @param typeB - the second option of a potential two file suffix (e.g. CSI, BAI)
+ * @returns a likely name of the index file for a given filename
+ */
 export declare function makeIndexType(name: string | undefined, typeA: string, typeB: string): string;
+/**
+ * The `index` block a tabix-indexed adapter's guess writes: where the index is,
+ * and which of the two kinds it is.
+ *
+ * Eight guessers spelled this pair out by hand, which is the crossed-pair hazard
+ * `tabixIndexSnapshot` was extracted for on the config side: a `.csi` location
+ * filed under `indexType: 'TBI'` is a valid-looking config that opens no index
+ * at all, and nothing downstream can tell it from a correct one.
+ *
+ * BAM is deliberately not here, for the reason `tabixIndexFields` gives: BAI/CSI
+ * is a different enumeration over a different default, and folding the two would
+ * mean a slot whose vocabulary depends on its adapter.
+ */
+export declare function guessTabixIndex(file: FileLocation, index: FileLocation | undefined): {
+    location: BlobLocation | FileHandleLocation | import("./index.ts").UriLocation | {
+        uri: string;
+        locationType: string;
+        baseUri?: string | undefined;
+        localPath?: undefined;
+    } | {
+        localPath: string;
+        locationType: string;
+    };
+    indexType: string;
+};
 export interface AdapterConfig {
     type: string;
     [key: string]: unknown;
 }
 export type AdapterGuesser = (file: FileLocation, index?: FileLocation, adapterHint?: string) => AdapterConfig | undefined;
 export type TrackTypeGuesser = (adapterName: string, file?: FileLocation) => string | undefined;
-export declare function getFileName(track: FileLocation): string;
+declare module '../PluginManager.ts' {
+    interface ExtensionPointRegistry {
+        'Core-guessAdapterForLocation': {
+            args: AdapterGuesser;
+            result: AdapterGuesser;
+        };
+        'Core-guessTrackTypeForLocation': {
+            args: TrackTypeGuesser;
+            result: TrackTypeGuesser;
+        };
+    }
+}
+/**
+ * Register a guess on `Core-guessAdapterForLocation`. Return an adapter config
+ * to claim the file, or `undefined` to defer to the plugins registered before
+ * this one.
+ *
+ * Prefer this over calling `addToExtensionPoint` directly: the chaining is done
+ * once here, so a plugin cannot break the chain by forgetting to delegate, nor
+ * drop an argument on the way through.
+ */
+export declare function addAdapterGuesser(pluginManager: PluginManager, guess: AdapterGuesser): void;
+/**
+ * Register a guess on `Core-guessTrackTypeForLocation`. Return a track type
+ * name to claim the adapter, or `undefined` to defer. See `addAdapterGuesser`
+ * for why this wrapper exists — hand-written delegates here used to drop the
+ * optional `file`, which hid it from every guesser registered earlier in the
+ * chain.
+ */
+export declare function addTrackTypeGuesser(pluginManager: PluginManager, guess: TrackTypeGuesser): void;
+/**
+ * Drop the format extension from a filename, plus any compression suffix, so
+ * `volvox.vcf.gz` becomes `volvox` rather than `volvox.vcf`. Names with no
+ * extension, and dotfiles, are returned unchanged.
+ */
+export declare function stripFileExtension(name: string): string;
 export declare function guessAdapter(file: FileLocation, index: FileLocation | undefined, adapterHint?: string, model?: IAnyStateTreeNode): AdapterConfig;
 export declare function guessTrackType(adapterType: string, model?: IAnyStateTreeNode, file?: FileLocation): string;
+export interface LooseTrackInput {
+    uri: string;
+    index?: string;
+    baseUri?: string;
+    [key: string]: unknown;
+}
+/**
+ * Expand a loose track description — a bare data-file URI, or an object with
+ * `uri` (and optional `index`) plus any extra config keys — into a full track
+ * config, the same inference the "Add track" flow does: the adapter and track
+ * type are guessed from the file via the format plugins, a stable `trackId` and
+ * a `name` are derived from the filename, and the assembly is stamped on. Extra
+ * keys on the input (`name`, `category`, `displays`, ...) override the inferred
+ * defaults. Takes a `pluginManager` (not a model) so it runs headlessly — in a
+ * worker/Node export as well as the browser. Throws when no format matches, so
+ * the caller can ask for a full config instead.
+ */
+export declare function guessTrackConf(input: string | LooseTrackInput, pluginManager: PluginManager, assemblyName?: string): {
+    trackId: string;
+    type: string;
+    name: string;
+    assemblyNames: string[];
+    adapter: AdapterConfig;
+};
+/**
+ * {@link guessTrackConf} over an already-built {@link FileLocation}, for a
+ * caller holding a location the loose `{ uri }` vocabulary cannot spell — a
+ * desktop local path. Kept separate so `LooseTrackInput` stays URI-only: it
+ * sits on the track-config union and the root config's `tracks`, where a
+ * local path would be a config a web deployment could not open.
+ *
+ * The `trackId` is a content hash of the adapter, not a timestamp, so adding
+ * the same file twice is idempotent — `addToSession` dedupes on it.
+ */
+export declare function guessTrackConfForLocation(file: FileLocation, index: FileLocation | undefined, pluginManager: PluginManager, assemblyName?: string): {
+    trackId: string;
+    type: string;
+    name: string;
+    assemblyNames: string[];
+    adapter: AdapterConfig;
+};
+/**
+ * Whether a track snapshot is the loose `{ uri, ... }` form — a data file with
+ * no `adapter` — that {@link expandLooseTrackConfig} expands.
+ */
+export declare function isLooseTrackConfig(snap: unknown): snap is LooseTrackInput & {
+    trackId?: string;
+};
+/**
+ * Expand a loose track config into a full one and leave any other snapshot
+ * untouched, so it can sit on every path a track snapshot enters the tree by:
+ * the track config union, the root config's frozen `tracks`, `addTrackConf`,
+ * and `showTrackGeneric`'s inline config.
+ *
+ * `{ "trackId": "reads", "uri": "reads.bam", "assemblyNames": ["hg38"] }` is a
+ * whole track: the adapter and track type come from the file's extension
+ * through the format plugins' guessers, the same inference the "Add track"
+ * flow runs, and `name` defaults to the file name. Any key written beside
+ * `uri` — `trackId`, `name`, `category`, `displayDefaults`, an explicit `type`
+ * — overrides what was inferred. `assemblyName` fills `assemblyNames` when the
+ * snapshot has none, for a config or embed that has exactly one assembly.
+ */
+export declare function expandLooseTrackConfig<T>(snap: T, pluginManager: PluginManager, assemblyName?: string): T;
 export declare function generateUnsupportedTrackConf(trackName: string, trackUrl: string, categories: string[] | undefined): {
     type: string;
     name: string;
@@ -87,6 +307,7 @@ export declare function generateUnknownTrackConf(trackName: string, trackUrl: st
 export declare function getTrackName(conf: AnyConfigurationModel | {
     name?: string;
     type?: string;
+    trackId?: string;
 }, session: {
     assemblies: AnyConfigurationModel[];
 }): string;
@@ -99,8 +320,188 @@ interface MinimalTrack extends IAnyType {
 interface GenericView {
     type: string;
     tracks: MSTArray<MinimalTrack>;
+    showTrack?: (trackId: string, initialSnapshot?: object, displayInitialSnapshot?: DisplayInitialSnapshot, inlineConf?: Record<string, unknown>) => unknown;
+}
+/**
+ * The display-snapshot argument of `showTrackGeneric`, exported so a view's own
+ * `showTrack` can annotate its parameter with it rather than approximate it.
+ * `Record<string, unknown>` is the approximation that reads as equivalent and is
+ * not: it rejects the precise snapshot interfaces callers legitimately pass,
+ * which have no index signature — the same hazard the `initialSnapshot`
+ * parameter's `object` annotation exists to avoid.
+ */
+export interface DisplayInitialSnapshot {
+    type?: string;
+    [key: string]: unknown;
+}
+interface DisplayConfSnapshot {
+    type: string;
+    displayId?: string;
+}
+/**
+ * The display type names a view can render, as a lookup set. Built once per
+ * view and handed to {@link viewCanDisplayTrack} for every track, rather than
+ * rebuilt per track.
+ */
+export declare function viewDisplayNames(pluginManager: PluginManager, viewType: string): Set<string>;
+/**
+ * Whether a view rendering `viewDisplays` can open a track at all: does the
+ * track's adapter feed a display the view draws. The coarse half of the
+ * question {@link pickDisplayForView} answers precisely, over the same
+ * candidates, so a picker never offers a track `showTrackGeneric` will refuse.
+ *
+ * Two answers that are easy to get wrong, and both have been:
+ *
+ * - A type **no plugin registered** answers false rather than throwing.
+ *   `getTrackType` throws on an unknown name, and a frozen track config never
+ *   passes the schema that would have rejected it at load — so a config naming
+ *   a plugin that failed to load put that throw inside whatever loop was
+ *   filtering tracks, and one unopenable track took out the entire list. The
+ *   track selector and jb2export's circular-view filter met this separately.
+ * - A view type registering **no displays at all** constrains nothing, so
+ *   every track passes. That is a policy rather than a fact, and it lives here
+ *   so the pickers agree on it.
+ */
+export declare function viewCanDisplayTrack(pluginManager: PluginManager, viewDisplays: Set<string>, track: {
+    type: string;
+    adapter?: {
+        type?: unknown;
+    };
+}): boolean;
+/**
+ * The tracks a view can be offered: those that support every assembly it
+ * displays, and that declare a display it can draw. The track selector's tree
+ * and every other picker that opens a track into a view read this one answer,
+ * or one of them offers a track the next hides.
+ */
+export declare function filterTracks(tracks: AnyConfigurationModel[], self: {
+    view?: IStateTreeNode & {
+        type: string;
+    };
+    assemblyNames: string[];
+}): AnyConfigurationModel[];
+/**
+ * Every track config a view can be offered, each assembly's sequence track
+ * first and then {@link filterTracks} over the list handed in.
+ */
+export declare function offeredTracks(tracks: AnyConfigurationModel[], self: {
+    view?: IStateTreeNode & {
+        type: string;
+    };
+    assemblyNames: string[];
+}): AnyConfigurationModel[];
+/**
+ * Which display a track opens with in a given view, and the declared entry
+ * that configures it: `{ type, conf }`, or undefined when the view draws none
+ * of the candidates or the requested type is not among them.
+ *
+ * The **type** is the requested one, checked rather than taken on faith (an
+ * unchecked one resolved its dangling `<trackId>-<type>` id back to the
+ * track's default display, and the caller was told it got what it asked for),
+ * else the first candidate among the view's own display types, else the first
+ * it draws at all. The **config** is then the declared entry of that type,
+ * never another one the view supports: `display.type ===
+ * display.configuration.type` is the invariant `DisplayConfigurationReference`
+ * assumes when it falls back to resolving by type.
+ */
+export declare function pickDisplayForView({ candidates, declaredDisplays, requestedType, viewDisplayTypes, preferredDisplayTypes, }: {
+    /** {@link displayCandidates}, canonical names in preference order */
+    candidates: string[];
+    /** the config's display entries, their types canonical */
+    declaredDisplays: DisplayConfSnapshot[];
+    requestedType: string | undefined;
+    viewDisplayTypes: string[];
+    /**
+     * The display types the view registered as its own, ahead of those it
+     * inherits through `extendedName`: a variant track on the circular view
+     * draws its chords, not the linear display the view also accepts as a
+     * ring, even where its config declares only the linear one.
+     */
+    preferredDisplayTypes?: Set<string>;
+}): {
+    type: string;
+    conf: DisplayConfSnapshot | undefined;
+} | undefined;
+export type TrackInit = string | {
+    trackId: string;
+    trackSnapshot?: Record<string, unknown>;
+    displaySnapshot?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+export declare function normalizeTrackInit(t: TrackInit): {
+    trackId: string;
+    trackSnapshot: Record<string, unknown>;
+    displaySnapshot: {
+        [x: string]: unknown;
+    };
+};
+export declare function showTrackGeneric(self: GenericView, trackId: string, initialSnapshot?: object, displayInitialSnapshot?: DisplayInitialSnapshot, inlineConf?: Record<string, unknown>): any;
+export interface DisplaySnapshot {
+    id: string;
+    [key: string]: unknown;
+}
+export interface TrackSnapshot {
+    id: string;
+    displays: DisplaySnapshot[];
+    [key: string]: unknown;
 }
-export declare function showTrackGeneric(self: GenericView, trackId: string, initialSnapshot?: {}, displayInitialSnapshot?: {}): any;
-export declare function hideTrackGeneric(self: GenericView, trackId: string): 0 | 1;
-export declare function toggleTrackGeneric(self: GenericView, trackId: string): void;
-export {};
+export declare function stripTrackIds(tracks: TrackSnapshot[]): {
+    displays: {
+        [key: string]: unknown;
+    }[];
+}[];
+export declare function hideTrackGeneric(self: GenericView, trackId: string): boolean;
+export declare function toggleTrackGeneric(self: GenericView, trackId: string): boolean;
+/**
+ * Start loading the state model and component of the display a track would
+ * open with, without opening it, for a caller that knows the track is coming.
+ * Anything that fails here is the launch's to report.
+ */
+export declare function warmTrackDisplayGeneric(self: GenericView, trackId: string, displayInitialSnapshot?: DisplayInitialSnapshot, assemblyName?: string): void;
+export declare function launchTrackGeneric(self: GenericView, trackId: string, initialSnapshot?: object, displayInitialSnapshot?: DisplayInitialSnapshot, inlineConf?: Record<string, unknown>): Promise<any>;
+export declare function launchToggleTrackGeneric(self: GenericView, trackId: string): Promise<boolean>;
+/**
+ * Every track config the session can show, connection-supplied ones included.
+ *
+ * `session.tracks` is only sessionTracks plus the admin config (see
+ * product-core's SessionTracks), so a track that arrived from a hub or registry
+ * connection is absent from it while still being toggleable from the track
+ * selector, which unions the same two sources. Anything answering "what tracks
+ * exist for X" wants this, or a feature silently can't see connection tracks.
+ *
+ * Note `session.tracks` already contains `sessionTracks` — unioning those two
+ * yields every session track twice.
+ */
+export declare function allSessionTracks(session: {
+    tracks: AnyConfigurationModel[];
+    connectionInstances?: {
+        tracks: AnyConfigurationModel[];
+    }[];
+}): AnyConfigurationModel[];
+/**
+ * The session's annotation for `assemblyName`, as trackIds: what a view opened
+ * on another genome starts with. Only FeatureTracks, not everything configured
+ * for the assembly — an alignments track turned on behind the user's back
+ * fetches data nobody asked for, and a FeatureTrack over a few kb is one tabix
+ * range query.
+ */
+export declare function annotationTrackIds(session: {
+    tracks: AnyConfigurationModel[];
+    connectionInstances?: {
+        tracks: AnyConfigurationModel[];
+    }[];
+    assemblyManager: AssemblyNameResolver;
+}, assemblyName: string): string[];
+/**
+ * One assembly on its own in a linear genome view, at `loc`. Keyed on `id`:
+ * following several alignments to one genome re-navigates the view rather than
+ * stacking a new one each time.
+ */
+export declare function openAssemblyInLinearView({ session, id, assemblyName, loc, tracks, }: {
+    session: AbstractViewContainer;
+    id: string;
+    assemblyName: string;
+    loc: string;
+    tracks: TrackInit[];
+}): Promise<void>;
+export declare function openMateLabel(assemblyName: string): string;