@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/configuration/types.d.ts

@@ -1,14 +1,316 @@
-import type { ConfigurationSchemaOptions, ConfigurationSchemaType } from './configurationSchema.ts';
-import type ConfigSlot from './configurationSlot.ts';
-import type { IStateTreeNode, Instance, SnapshotOut } from '@jbrowse/mobx-state-tree';
-export type GetOptions<SCHEMA> = SCHEMA extends ConfigurationSchemaType<any, infer OPTIONS> ? OPTIONS : never;
-export type GetBase<SCHEMA> = SCHEMA extends undefined ? never : GetOptions<SCHEMA> extends ConfigurationSchemaOptions<undefined, any> ? undefined : GetOptions<SCHEMA> extends ConfigurationSchemaOptions<infer BASE extends AnyConfigurationSchemaType, any> ? BASE : never;
-export type GetExplicitIdentifier<SCHEMA> = GetOptions<SCHEMA> extends ConfigurationSchemaOptions<any, infer EXPLICIT_IDENTIFIER extends string> ? EXPLICIT_IDENTIFIER : never;
-export type ConfigurationSchemaForModel<MODEL> = MODEL extends IStateTreeNode<infer SCHEMA extends AnyConfigurationSchemaType> ? SCHEMA : never;
-export type ConfigurationSlotName<SCHEMA> = SCHEMA extends undefined ? never : SCHEMA extends ConfigurationSchemaType<infer D, any> ? (keyof D & string) | GetExplicitIdentifier<SCHEMA> | (GetBase<SCHEMA> extends ConfigurationSchemaType<any, any> ? ConfigurationSlotName<GetBase<SCHEMA>> : never) : never;
+import type { FileLocation } from '../util/types/index.ts';
+import type { IsAny } from '../util/types/isAny.ts';
+import type { ConfigurationSchemaDefinition, ConfigurationSchemaOptions, ConfigurationSchemaType } from './configurationSchema.ts';
+import type { BuiltinSlotTypeName } from './configurationSlot.ts';
+import type { IAnyType, IArrayType, IOptionalIType, ISimpleType, IStateTreeNode, Instance, SnapshotOut } from '@jbrowse/mobx-state-tree';
+export type ConfigurationSchemaForModel<MODEL> = IsAny<MODEL> extends true ? AnyConfigurationSchemaType : MODEL extends IStateTreeNode<infer T> ? T extends AnyConfigurationSchemaType ? T : T extends IOptionalIType<infer INNER extends AnyConfigurationSchemaType, any> ? INNER : AnyConfigurationSchemaType : never;
+/**
+ * A schema's definition as **stored**: the author's own entries over the ones
+ * its `baseConfiguration` contributed, the type-level twin of
+ * `mergeSchemaDefinition`. The base arrives already merged with its own base,
+ * so one level here covers a chain of any depth.
+ *
+ * A flat mapped type over the union of both key sets, not
+ * `Omit<BASE, keyof D> & D`: an intersection's `keyof` is a union of key sets,
+ * and mapping over a union that includes `string` — which
+ * `ConfigurationSchemaDefinition`'s index signature contributes — collapses
+ * back to an index signature, which is the thing `ConfigNodeProps` exists to
+ * get rid of.
+ */
+export type MergeConfigDef<D, BASE> = BASE extends ConfigurationSchemaType<infer BD, any> ? {
+    [K in keyof BD | keyof D]: NormalizeSlotDef<K extends keyof D ? K extends keyof BD ? MergeSlotDef<BD[K], D[K]> : D[K] : K extends keyof BD ? BD[K] : never>;
+} : {
+    [K in keyof D]: NormalizeSlotDef<D[K]>;
+};
+/**
+ * A redeclared slot merges field-by-field over the base's; a sub-schema or a
+ * constant keeps replace semantics, matching `mergeSchemaDefinition`'s
+ * `isSlotDefinitionEntry` guard.
+ */
+type MergeSlotDef<BASE_ENTRY, ENTRY> = BASE_ENTRY extends {
+    type: string;
+} ? ENTRY extends {
+    type: string;
+} ? Omit<BASE_ENTRY, keyof ENTRY> & ENTRY : ENTRY : ENTRY;
+/**
+ * What the type level reads off a slot definition: the slot's `type`, a
+ * `stringEnum`'s `model`, and whether a `defaultValue` is there at all — widened
+ * off its literal. The description, `advanced`, `contextVariable` and the
+ * literal default are documentation and runtime, and carrying them makes two
+ * schemas that differ only in one of them mutually unassignable: a subclass
+ * raising `height` from 100 to 250 stopped satisfying a parameter pinned to its
+ * base. `SlotValueRawFromDef` re-widens a scalar default anyway, and reaches
+ * `any` for everything else, so nothing downstream loses precision.
+ */
+type NormalizeSlotDef<E> = E extends AnyConfigurationSchemaType ? E : E extends {
+    type: infer T;
+} ? {
+    type: T;
+} & (E extends {
+    model: infer M;
+} ? {
+    model: M;
+} : unknown) & (E extends {
+    defaultValue: infer V;
+} ? {
+    defaultValue: WidenDefaultValue<V>;
+} : unknown) : E;
+type WidenDefaultValue<V> = [V] extends [boolean] ? boolean : [V] extends [string] ? string : [V] extends [number] ? number : unknown;
+type ConfigNodeValue<DEF> = IsAny<DEF> extends true ? any : DEF extends AnyConfigurationSchemaType ? DEF['Type'] : DEF extends IArrayType<any> | IOptionalIType<IArrayType<any>, any> ? DEF['Type'] : DEF extends string ? string : DEF extends number ? number : SlotValueRawFromDef<DEF>;
+/**
+ * The slots a config node presents, read off the schema's own DEFINITION rather
+ * than the `Record<string, any>` `makeConfigurationSchemaModel` assembles its
+ * MST props from. Those props carry an index signature, so every
+ * `node.anything` resolves to `any`; mapping the definition instead is what
+ * makes `node.colorr` a compile error.
+ *
+ * A plain mapped type, and it has to stay one. Wrapping it in a conditional —
+ * to answer early for a widened definition, say — makes TypeScript measure
+ * DEFINITION as covariant instead of invariant, and it refuses a failed
+ * covariant check on a type argument outright where a failed invariant one
+ * falls back to comparing the two schemas structurally. Structural is the
+ * comparison that matters: a subclass schema's node has every slot the base's
+ * does, while its *definition* restates `defaultValue` and `description` and so
+ * matches nothing. The widened case belongs on `AnyConfigurationModel`.
+ */
+export type ConfigNodeProps<DEFINITION> = {
+    [K in keyof DEFINITION]: ConfigNodeValue<DEFINITION[K]>;
+};
+/**
+ * The two write actions every config node carries, which `setConf` is the
+ * spelling of. A type alias rather than an interface because it annotates the
+ * `.actions` block: MST constrains that to `ModelActions`, an index signature
+ * of functions, and only a type alias of an object literal gets the implicit
+ * index signature that satisfies it.
+ */
+export type ConfigNodeActions = {
+    setSubschema: (slotName: string, data: unknown) => unknown;
+    setSlot: (slotName: string, value: unknown) => void;
+};
+/**
+ * MST's node brand, restated. A config node carries its own schema here by
+ * polymorphic `this`, and `ConfigurationSchemaForModel` walks it back out —
+ * which is what every `getConf` / `readConfObject` / `setConf` slot-name
+ * constraint hangs off, so losing it switches the read-side check off with no
+ * error anywhere. `scripts/audit-config-read-types.ts` is the only thing that
+ * reports that; run it after touching this.
+ *
+ * Structurally identical to `IStateTreeNode<IT>`, but an alias rather than an
+ * interface: TypeScript infers an implicit index signature for an intersection
+ * only when every constituent is an alias or a mapped type, and that is what
+ * leaves a concrete config node — whose props are a mapped type with no index
+ * signature of its own — assignable to `AnyConfigurationModel`.
+ */
+export type ConfigNodeBrand<IT extends IAnyType> = {
+    readonly $treenode?: any;
+    readonly $__mstStateTreeNodeType__?: [IT] | [any];
+};
+/**
+ * The identifier a schema's `explicitIdentifier` installs, folded into the
+ * definition as if it were a declared string slot — which is what it is at
+ * runtime, `makeConfigurationSchemaModel` just builds it from the options rather
+ * than from the table. Folding it in rather than intersecting it onto `Type`
+ * keeps it out of `ConfigurationSchemaType`'s parameter list: as a parameter it
+ * reads as invariant (it lands in a `Record<K, …>` key position), which stops a
+ * concrete schema widening to `AnyConfigurationSchemaType`. Inheritance comes
+ * free, since `MergeConfigDef` already folds the base's whole definition in.
+ */
+export interface IdentifierSlotDef {
+    type: 'string';
+    defaultValue: '';
+}
+/**
+ * The `type` prop an `explicitlyTyped` schema installs, folded into the
+ * definition the same way and for the same reasons. Separate from
+ * `IdentifierSlotDef` despite the identical shape, because the runtime prop is
+ * `types.literal(modelName)` and this is where that would be said if the model
+ * name ever became a type parameter.
+ */
+export interface TypeSlotDef {
+    type: 'string';
+    defaultValue: '';
+}
+export type ConfigurationSlotName<SCHEMA> = IsAny<SCHEMA> extends true ? string : SCHEMA extends ConfigurationSchemaType<infer D, any> ? keyof D & string : never;
+/**
+ * The names a config snapshot for `SCHEMA` may use — its own slots, its
+ * sub-schemas recursively, its identifier and everything it inherits — with
+ * every value left `unknown`.
+ *
+ * Names are the whole point of it. A slot value can be its own type, a `jexl:`
+ * callback string, or (for a `maybe*` slot) absent, and nothing here tries to
+ * check that; a *name* the schema does not declare is dropped on the way in
+ * without a word, so `preferance` is a setting that reads as applied and never
+ * applies. Against an object literal — which is how an embedder writes one —
+ * TypeScript's excess-property check turns that into a compile error.
+ */
+export type ConfigurationSnapshot<SCHEMA> = SCHEMA extends undefined ? never : SCHEMA extends ConfigurationSchemaType<infer D, any> ? {
+    [K in keyof D]?: D[K] extends ConfigurationSchemaType<any, any> ? ConfigurationSnapshot<D[K]> : unknown;
+} : unknown;
+/**
+ * The value each builtin slot `type` reads as — the type-level twin of
+ * `slotTypes` in `configurationSlot.ts`, which is the same list as MST models.
+ * A table rather than the fourteen-deep conditional staircase this used to be:
+ * adding a slot type is now one row here and one there, and the two tables sit
+ * side by side where a name present in one and missing from the other is
+ * visible. Missing a row is not silent either — it drops the slot to the
+ * `defaultValue` fallback below, which is what `SlotValueRawFromDef` documents.
+ *
+ * `stringEnum`/`maybeStringEnum` are deliberately absent: their value type comes
+ * from the author's own `types.enumeration`, read off `model` before this table
+ * is consulted.
+ */
+interface SlotValueByType {
+    stringArray: string[];
+    expressionArray: string[];
+    stringArrayMap: Record<string, string[]>;
+    numberMap: Record<string, number>;
+    stringMap: Record<string, string>;
+    fileLocation: FileLocation;
+    maybeFileLocation: FileLocation | undefined;
+    maybeNumber: number | undefined;
+    maybeBoolean: boolean | undefined;
+    maybeColor: string | undefined;
+    maybeString: string | undefined;
+    /**
+     * `frozen` and its `maybe*` form are `any` deliberately — arbitrary dynamic
+     * JSON whose shape the caller asserts at the read boundary. `unknown` would
+     * only add cast ceremony on values that are legitimately dynamic.
+     *
+     * Stated here rather than left to the `defaultValue` fallback, which reaches
+     * `any` for these only by accident: no `frozen` slot in the repo happens to
+     * default to a scalar.
+     */
+    frozen: any;
+    maybeFrozen: any;
+    number: number;
+    integer: number;
+    boolean: boolean;
+    string: string;
+    text: string;
+    featureField: string;
+    color: string;
+    colorArray: string[];
+}
+/**
+ * The two tables name the same builtin slot types, checked rather than
+ * remembered.
+ *
+ * A row present in one and missing from the other is otherwise **not** an
+ * error: the slot drops through to `SlotValueRawFromDef`'s `defaultValue`
+ * fallback, which re-widens a scalar default but reaches `any` for everything
+ * else — so a new `stringArray`-shaped type would silently read as `any` at
+ * every call site. The "every builtin slot type reads as its declared value
+ * type" case in `configTypeNarrowing.test.ts` lists the rows by hand, so it
+ * only catches the drift if whoever adds the type also edits the test; this
+ * catches it either way.
+ */
+type MutuallyExtends<A, B> = [A] extends [B] ? [B] extends [A] ? true : false : false;
+type Assert<T extends true> = T;
+export type SlotValueTableCoversBuiltinSlotTypes = Assert<MutuallyExtends<BuiltinSlotTypeName, keyof SlotValueByType>>;
+type SlotValueRawFromDef<DEF> = DEF extends AnyConfigurationSchemaType ? AnyConfigurationSnapshot : DEF extends {
+    model: ISimpleType<infer T extends string>;
+} ? DEF extends {
+    type: 'maybeStringEnum';
+} ? T | undefined : DEF extends {
+    type: 'stringEnumArray';
+} ? T[] : T : DEF extends {
+    type: infer T extends keyof SlotValueByType;
+} ? SlotValueByType[T] : DEF extends {
+    defaultValue: infer V;
+} ? [V] extends [boolean] ? boolean : [V] extends [string] ? string : [V] extends [number] ? number : any : any;
+type SubSchemaOf<SCHEMA, K> = IsAny<SCHEMA> extends true ? any : SCHEMA extends ConfigurationSchemaType<infer D, any> ? K extends keyof D ? D[K] : never : never;
+type SubSchemaSlotPath<SCHEMA> = SCHEMA extends ConfigurationSchemaType<infer D, any> ? IsAny<D> extends true ? readonly string[] : {
+    [K in keyof D & string]: D[K] extends AnyConfigurationSchemaType ? readonly [K, ConfigurationSlotName<D[K]>] | readonly [K, ...SubSchemaSlotPath<D[K]>] : D[K] extends IAnyType | {
+        type: 'frozen' | 'maybeFrozen';
+    } ? readonly [K, ...string[]] : never;
+}[keyof D & string] : readonly string[];
+/**
+ * The array paths a read may take into `SCHEMA`. Past one segment each is
+ * checked: a sub-schema's name, then one of its slot names or a deeper path. A
+ * head naming something other than a sub-schema — a pluggable adapter union, an
+ * array or map of sub-schemas, a `frozen` slot — keeps an unchecked tail, and a
+ * widened schema admits any `string[]`.
+ *
+ * A one-segment path stays unchecked: it is how a generic class body, where
+ * `SCHEMA` is unresolved, reads a slot at all (`FastaAdapterBase`).
+ */
+export type ConfigurationSlotPath<SCHEMA> = readonly [] | readonly [string] | SubSchemaSlotPath<SCHEMA>;
+/** what a read of `PATH` into `SCHEMA` yields */
+export type ConfigurationSlotPathValue<SCHEMA, PATH> = PATH extends readonly [
+    infer HEAD,
+    ...infer REST
+] ? SubSchemaOf<SCHEMA, HEAD> extends infer SUB extends AnyConfigurationSchemaType ? REST extends readonly [infer SLOT extends string] ? ConfigurationSlotValue<SUB, SLOT> : ConfigurationSlotPathValue<SUB, REST> : any : any;
+/** what a raw read (`getConf` / `readConfObject`) of this slot yields */
+export type ConfigurationSlotValue<SCHEMA, K extends string> = SCHEMA extends ConfigurationSchemaType<infer D, any> ? K extends keyof D ? SlotValueRawFromDef<D[K]> : any : any;
+/**
+ * Naming convention for config types, paired per schema:
+ * - `XConfigSchema` is the MST IType (the schema itself). Use it for
+ *   `getConf`, `ConfigurationReference`, and factory params — anywhere a schema
+ *   is expected.
+ * - `XConfigModel` is `Instance<XConfigSchema>` (a resolved config node). Use it
+ *   for `readConfObject` results, model fields, and values read off a session.
+ *
+ * Prefer a named `XConfigModel` alias over inlining `Instance<XConfigSchema>` at
+ * call sites. Two historical names predate this convention and stay as-is:
+ * `BaseTrackConfig` (the track instance type) and `AnyConfiguration` (a
+ * model-or-snapshot union, not a plain instance).
+ */
 export type AnyConfigurationSchemaType = ConfigurationSchemaType<any, any>;
-export type AnyConfigurationModel = Instance<AnyConfigurationSchemaType>;
-export type AnyConfigurationSlotType = ReturnType<typeof ConfigSlot>;
-export type AnyConfigurationSlot = Instance<AnyConfigurationSlotType>;
-export type AnyConfiguration = AnyConfigurationModel | SnapshotOut<AnyConfigurationModel>;
-export type ConfigurationModel<SCHEMA extends AnyConfigurationSchemaType> = Instance<SCHEMA>;
+export type AnyConfigurationModel = Instance<AnyConfigurationSchemaType> & Record<string, any>;
+/**
+ * A node of a pluggable element union — a track's, a display's, an adapter's —
+ * whichever member it is, naming its `type`. An interface rather than an
+ * intersection so a generated doc prints the name.
+ */
+export interface PluggableConfigNode extends AnyConfigurationModel {
+    type: string;
+}
+/**
+ * The `XConfigModel` for a **field table** — a `*ConfigSchemaFields` export —
+ * rather than for a whole assembled schema. What it is for is the cast a
+ * cross-cutting mixin uses to reach the `configuration` its composing display
+ * supplies but its own `self` cannot see: cast to `AnyConfigurationModel` there
+ * and `getConf`/`setConf` derive their slot-name constraint from a schema
+ * widened to `any`, so every name typechecks and a misspelled *read* returns
+ * `undefined` with no diagnostic at any layer. Name the mixin's own field table
+ * instead and the check comes back, scoped to exactly the slots that mixin owns.
+ *
+ * `BASE` is for the mixin that also reads a slot off the schema its displays
+ * inherit from — `ConfigurationSlotName` walks the base chain, so passing it
+ * admits those names too and nothing else (`HeightModeMixin` and `height`).
+ *
+ * The pairing this depends on is a mixin and its field table living together:
+ * `RowHeightMixin` + `rowHeightConfigSchemaFields` is the worked example, and
+ * `packages/tree-sidebar/CLAUDE.md` has the reasoning.
+ */
+export type ConfigModelForFields<FIELDS extends ConfigurationSchemaDefinition, BASE extends AnyConfigurationSchemaType | undefined = undefined> = Instance<ConfigurationSchemaType<MergeConfigDef<FIELDS, BASE>, ConfigurationSchemaOptions<BASE, undefined>>>;
+/**
+ * `true` when HOST's `configuration` still narrows slot names, `false` when it
+ * has widened them back to `string`. One line per mixin pins it:
+ *
+ * ```ts
+ * const pin: HostChecksSlotNames<HeightModeHost> = true
+ * ```
+ *
+ * Worth a named type because the widened form has **no symptom** — a mixin host
+ * cast to `AnyConfigurationModel` compiles and runs and checks nothing. Every
+ * misspelled slot name below it typechecks, and a misspelled *read* returns
+ * `undefined` with no diagnostic at any layer, so only a sabotage or this
+ * assertion tells the two apart.
+ */
+export type HostChecksSlotNames<HOST extends {
+    configuration: AnyConfigurationModel;
+}> = string extends ConfigurationSlotName<ConfigurationSchemaForModel<HOST['configuration']>> ? false : true;
+/** a plain-object snapshot of a configuration model (not a live MST node) */
+export type AnyConfigurationSnapshot = SnapshotOut<AnyConfigurationModel>;
+/**
+ * A value readable as configuration: either a live configuration model or a
+ * plain snapshot of one. `session.tracks` holds plain base or merged configs
+ * that hydrate to MST only on first reference access, `getTrackById` also
+ * answers live assembly-sequence and connection nodes, and `readConfObject`
+ * reads both — so this is the honest type at those boundaries. Reserve
+ * `AnyConfigurationModel` for values that must be live (actions, identity,
+ * reference resolution).
+ */
+export type AnyConfiguration = AnyConfigurationModel | AnyConfigurationSnapshot;
+export {};

package/esm/configuration/uriShorthand.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Expand a one-file adapter's `{ uri }` shorthand into the single location slot
+ * it declares, or pass a snapshot already in full form through untouched.
+ *
+ * `locationKey` is the only thing that differs between the twenty-odd adapters
+ * reading one file (`bedLocation`, `bigWigLocation`, `hicLocation`,
+ * `pafLocation`, …). `expandTabixShorthand` is the indexed families' version.
+ */
+export declare function expandUriShorthand(snap: Record<string, unknown>, locationKey: string): Record<string, unknown>;

package/esm/configuration/uriShorthand.js

@@ -0,0 +1,16 @@
+import { fillLocations } from './fillLocations.js';
+/**
+ * Expand a one-file adapter's `{ uri }` shorthand into the single location slot
+ * it declares, or pass a snapshot already in full form through untouched.
+ *
+ * `locationKey` is the only thing that differs between the twenty-odd adapters
+ * reading one file (`bedLocation`, `bigWigLocation`, `hicLocation`,
+ * `pafLocation`, …). `expandTabixShorthand` is the indexed families' version.
+ */
+export function expandUriShorthand(snap, locationKey) {
+    return snap.uri
+        ? fillLocations(snap, {
+            [locationKey]: { uri: snap.uri, baseUri: snap.baseUri },
+        })
+        : snap;
+}

package/esm/data_adapters/BaseAdapter/BaseAdapter.d.ts

@@ -1,16 +1,24 @@
 import type PluginManager from '../../PluginManager.ts';
-import type { AnyConfigurationModel } from '../../configuration/index.ts';
-import type { AugmentedRegion as Region } from '../../util/types/index.ts';
+import type { AnyConfigurationModel, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotPath, ConfigurationSlotPathValue, ConfigurationSlotValue } from '../../configuration/index.ts';
 import type { getSubAdapterType } from '../dataAdapterCache.ts';
-export declare class BaseAdapter {
-    config: AnyConfigurationModel;
-    getSubAdapter?: getSubAdapterType | undefined;
-    pluginManager?: PluginManager | undefined;
+export declare class BaseAdapter<CONF extends AnyConfigurationModel = AnyConfigurationModel> {
     id: string;
-    sequenceAdapterConfig?: Record<string, unknown>;
+    config: CONF;
+    getSubAdapter?: getSubAdapterType;
+    pluginManager?: PluginManager;
+    /**
+     * The reference sequence this instance reads, as the adapter config of the
+     * assembly the request that built it named. Part of the instance's identity:
+     * dataAdapterCache keys a {@link READS_REFERENCE} adapter on its config AND
+     * this, so one BAM shown on two genomes is two instances, each reading its
+     * own. Undefined when the building request named no genome, and a reference
+     * read then throws rather than guessing. Instance state rather than a
+     * per-call argument because `CramAdapter` binds its reference fetch into the
+     * `IndexedCramFile` at construction, inside @gmod/cram's slice cache.
+     */
+    readonly sequenceAdapterConfig?: Record<string, unknown>;
     static capabilities: string[];
-    constructor(config?: AnyConfigurationModel, getSubAdapter?: getSubAdapterType | undefined, pluginManager?: PluginManager | undefined);
-    setSequenceAdapterConfig(config: Record<string, unknown>): void;
-    getConf(arg: string | string[]): any;
-    freeResources(_region: Region): void;
+    constructor(config?: CONF, getSubAdapter?: getSubAdapterType, pluginManager?: PluginManager, sequenceAdapterConfig?: Record<string, unknown>);
+    /** shorthand for `readConfObject(this.config, arg)` */
+    getConf<const SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONF>> | ConfigurationSlotPath<ConfigurationSchemaForModel<CONF>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONF>>>(arg: SLOT, args?: Record<string, unknown>): SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONF>, SLOT> : ConfigurationSlotPathValue<ConfigurationSchemaForModel<CONF>, SLOT>;
 }

package/esm/data_adapters/BaseAdapter/BaseAdapter.js

@@ -1,31 +1,32 @@
-import { getSnapshot, isStateTreeNode } from '@jbrowse/mobx-state-tree';
-import { ConfigurationSchema, readConfObject, } from "../../configuration/index.js";
-import idMaker from "../../util/idMaker.js";
+import { ConfigurationSchema, readConfObject, } from '../../configuration/index.js';
+import { getAdapterId } from './getAdapterId.js';
 const EmptyConfig = ConfigurationSchema('empty', {});
 export class BaseAdapter {
+    id;
     config;
     getSubAdapter;
     pluginManager;
-    id;
+    /**
+     * The reference sequence this instance reads, as the adapter config of the
+     * assembly the request that built it named. Part of the instance's identity:
+     * dataAdapterCache keys a {@link READS_REFERENCE} adapter on its config AND
+     * this, so one BAM shown on two genomes is two instances, each reading its
+     * own. Undefined when the building request named no genome, and a reference
+     * read then throws rather than guessing. Instance state rather than a
+     * per-call argument because `CramAdapter` binds its reference fetch into the
+     * `IndexedCramFile` at construction, inside @gmod/cram's slice cache.
+     */
     sequenceAdapterConfig;
     static capabilities = [];
-    constructor(config = EmptyConfig.create(), getSubAdapter, pluginManager) {
+    constructor(config = EmptyConfig.create(), getSubAdapter, pluginManager, sequenceAdapterConfig) {
         this.config = config;
         this.getSubAdapter = getSubAdapter;
         this.pluginManager = pluginManager;
-        if (typeof jest === 'undefined') {
-            const data = isStateTreeNode(config) ? getSnapshot(config) : config;
-            this.id = `${idMaker(data)}`;
-        }
-        else {
-            this.id = 'test';
-        }
-    }
-    setSequenceAdapterConfig(config) {
-        this.sequenceAdapterConfig = config;
+        this.sequenceAdapterConfig = sequenceAdapterConfig;
+        this.id = getAdapterId(config);
     }
-    getConf(arg) {
-        return readConfObject(this.config, arg);
+    /** shorthand for `readConfObject(this.config, arg)` */
+    getConf(arg, args) {
+        return readConfObject(this.config, arg, args);
     }
-    freeResources(_region) { }
 }

package/esm/data_adapters/BaseAdapter/BaseFeatureDataAdapter.d.ts

@@ -1,24 +1,175 @@
-import { type Observable } from 'rxjs';
 import { BaseAdapter } from './BaseAdapter.ts';
-import type { BaseOptions } from './BaseOptions.ts';
+import type { AnyConfigurationModel } from '../../configuration/index.ts';
+import type { FeatureTable } from '../../util/featureTable.ts';
 import type { Feature } from '../../util/simpleFeature.ts';
 import type { AugmentedRegion as Region } from '../../util/types/index.ts';
-export declare abstract class BaseFeatureDataAdapter extends BaseAdapter {
+import type { FeatureDensity } from './featureDensity.ts';
+import type { BaseOptions, ZoomRange } from './types.ts';
+import type { Observable } from 'rxjs';
+/**
+ * Base class for feature adapters to extend. Defines some methods that
+ * subclasses must implement.
+ */
+/** #adapterBase BaseFeatureDataAdapter | features overlapping a region — genes, reads, variants. The common case */
+export declare abstract class BaseFeatureDataAdapter<CONF extends AnyConfigurationModel = AnyConfigurationModel> extends BaseAdapter<CONF> {
+    /**
+     * Get all reference sequence names used in the data source
+     * Example:
+     * public async getRefNames(opts?: BaseOptions): Promise\<string[]\> \}
+     *   await this.setup()
+     *   const \{ refNames \} = this.metadata
+     *   return refNames
+     * \}
+     *
+     *
+     * NOTE: If an adapter is unable to determine the reference sequence names,
+     * the array will be empty
+     * @param opts - Feature adapter options
+     */
     abstract getRefNames(opts?: BaseOptions): Promise<string[]>;
+    /**
+     * Get features from the data source that overlap a region
+     * Example:
+     * public getFeatures(
+     *   region: Region,
+     *   opts: BaseOptions,
+     * ): Observable<Feature> \{
+     *   return ObservableCreate(observer =\> \{
+     *     const records = getRecords(assembly, refName, start, end)
+     *     records.forEach(record =\> \{
+     *       observer.next(this.recordToFeature(record))
+     *     \})
+     *     observer.complete()
+     *   \})
+     * \}
+     * @param region - Region
+     * @param opts - Feature adapter options
+     * @returns Observable of Feature objects in the region
+     */
     abstract getFeatures(region: Region, opts?: BaseOptions): Observable<Feature>;
+    /**
+     * Return "header info" that is fetched from the data file, or other info
+     * that would not simply be in the config of the file. The return value can
+     * be `{tag:string, data: any}[]` e.g. list of tags with their values which
+     * is how VCF,BAM,CRAM return values for getInfo or it can be a nested JSON
+     * object
+     */
     getHeader(_opts?: BaseOptions): Promise<unknown>;
+    /**
+     * Return info that is primarily used for interpreting the data that is there,
+     * primarily in reference to being used for augmenting feature details panels
+     */
     getMetadata(_opts?: BaseOptions): Promise<unknown>;
-    getFeaturesInRegion(region: Region, opts?: BaseOptions): Observable<Feature>;
+    /**
+     * Adapters that are frequently called on multiple regions simultaneously
+     * may want to implement a more efficient custom version of this method.
+     *
+     * The regions are fetched concurrently, so each gets its own
+     * {@link createStatusFanOut} slot rather than the caller's raw
+     * `statusCallback`: they all report the same phases ("Downloading
+     * features"), and sharing one status field meant the last writer won and the
+     * first region to finish cleared the label while the rest were still
+     * downloading. Aggregated, N regions read as one Σbytes bar — the same helper
+     * `callEachRegion` uses to give the per-region RPCs on the main thread a slot
+     * apiece.
+     */
     getFeaturesInMultipleRegions(regions: Region[], opts?: BaseOptions): Observable<Feature>;
+    /**
+     * Convenience wrapper that collects {@link getFeatures} for a region into an
+     * array — the common shape across RPC methods (RenderFeatureData, Manhattan,
+     * Wiggle, etc.). Pass `opts` so `statusCallback`/`signal` reach the
+     * adapter; omitting them means no download progress and a fetch that can't be
+     * interrupted mid-flight.
+     */
+    getFeaturesArray(region: Region, opts?: BaseOptions): Promise<Feature[]>;
+    /**
+     * The features overlapping a region as the table a mark's declaration runs
+     * over: by default a table over {@link getFeaturesArray}. An adapter that
+     * already holds its rows as typed arrays answers a `ColumnTable` over them
+     * instead, and makes no object per row.
+     */
+    getFeatureTable(region: Region, opts?: BaseOptions): Promise<FeatureTable>;
+    /**
+     * {@link getFeaturesArray} across multiple regions — collects
+     * {@link getFeaturesInMultipleRegions} into an array. The common shape in
+     * matrix/comparative RPC methods (variants, synteny, dotplot, breakpoint).
+     */
+    getFeaturesInMultipleRegionsArray(regions: Region[], opts?: BaseOptions): Promise<Feature[]>;
+    /**
+     * Check if the store has data for the given reference name.
+     * @param refName - Name of the reference sequence
+     * @returns Whether data source has data for the given reference name
+     */
     hasDataForRefName(refName: string, opts?: BaseOptions): Promise<boolean>;
+    /**
+     * Calculates the minimum score, maximum score, and other statistics from
+     * features over a region, primarily used for quantitative tracks
+     */
     getRegionQuantitativeStats(region: Region, opts?: BaseOptions): Promise<import("../../util/stats.ts").RectifiedQuantitativeStats>;
+    /**
+     * Calculates the minimum score, maximum score, and other statistics from
+     * features over multiple regions, primarily used for quantitative tracks
+     */
     getMultiRegionQuantitativeStats(regions?: Region[], opts?: BaseOptions): Promise<import("../../util/stats.ts").RectifiedQuantitativeStats>;
-    getRegionFeatureDensityStats(region: Region, opts?: BaseOptions): Promise<import("./types.ts").FeatureDensityStats>;
-    getMultiRegionFeatureDensityStats(regions: Region[], opts?: BaseOptions): Promise<import("./types.ts").FeatureDensityStats>;
-    getSources(regions: Region[]): Promise<{
+    /**
+     * Cheap upper bound on the compressed bytes a fetch of `regions` would pull,
+     * derived from an index without downloading or parsing any features. The
+     * default returns `undefined` ("no cheap estimate"); indexed adapters (tabix)
+     * override it, and an adapter that caps what it returns at screen resolution
+     * (BigWig, HiC, sequence) simply doesn't — no estimate means no byte gate.
+     *
+     * The one byte-estimate entry point, used by both halves of the region-too-large
+     * gate: the pre-flight `CoreGetRegionByteEstimate` RPC and the in-fetch
+     * short-circuit in `executeRenderFeatureData`. The byte *budget* it is compared
+     * against is read on the main thread from the adapter's `fetchSizeLimit` config
+     * slot, so it never crosses the worker boundary — see
+     * agent-docs/reference/REGION_TOO_LARGE.md.
+     */
+    getRegionByteSize(_regions: Region[], _opts?: BaseOptions): Promise<number | undefined>;
+    /**
+     * The bp/px interval over which this adapter answers a fetch from the same
+     * zoom level it answers `opts.bpPerPx` from, so a display holding the answer
+     * refetches only when the view leaves it. The default, `undefined`, is an
+     * answer that does not depend on the zoom, which a display never refetches
+     * for a zoom. An adapter that reads `bpPerPx` declares its range here
+     * (`BigWigAdapter` from its header's zoom levels).
+     */
+    getZoomRange(_opts?: BaseOptions): Promise<ZoomRange | undefined>;
+    /**
+     * The interval every value this adapter answers lies in by definition, as a
+     * fraction lies in [0, 1], which a value scale's unpinned ends stand at
+     * rather than following the loaded data, so the axis reads alike at every
+     * locus. The default, `undefined`, is a quantity with no such bounds, whose
+     * axis autoscales. `GCContentAdapter` declares [0, 1] for GC content and none
+     * for skew.
+     */
+    getValueDomain(_opts?: BaseOptions): Promise<[number, number] | undefined>;
+    /**
+     * Features per bin over each region, at the view's `bpPerPx`, for the density
+     * tier the display draws where the region-too-large gate refused the
+     * features. The default reads the `densityAdapter` sidecar slot
+     * (`densityAdapterConfigSchemaFields`) through `getSubAdapter`; `undefined`
+     * means no tier, and the banner stands. ADR-102 records why no index
+     * estimate stands in for a missing sidecar.
+     */
+    getFeatureDensity(regions: Region[], opts: BaseOptions & {
+        bpPerPx: number;
+    }): Promise<FeatureDensity[] | undefined>;
+    getSources(regions: Region[], opts?: BaseOptions): Promise<{
         name: string;
         color?: string;
         [key: string]: unknown;
     }[]>;
+    /**
+     * Export data from the adapter in a specified format for given regions.
+     * Some adapters (like VcfAdapter) can efficiently export raw data directly
+     * from the file without parsing to features.
+     *
+     * @param regions - Regions to export data from
+     * @param formatType - The format to export to (e.g. 'vcf', 'sam', 'bedgraph')
+     * @param opts - Feature adapter options
+     * @returns Promise resolving to the exported data as a string, or undefined
+     *          if the adapter does not support direct export for this format
+     */
     getExportData(_regions: Region[], _formatType: string, _opts?: BaseOptions): Promise<string | undefined>;
 }