@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/configuration/bamIndexFields.d.ts

@@ -0,0 +1,49 @@
+/**
+ * BAM's `index`, which is the tabix pair over a different enumeration: BAI/CSI
+ * rather than TBI/CSI, with its own default and its own placeholder name.
+ * Folding the two would mean a slot whose vocabulary depends on its adapter,
+ * which is why `tabixIndexFields` says BAM is deliberately not there.
+ *
+ * Only the enumeration differs. `fillIndexType` is the same function, since a
+ * `.csi` names itself the same way whichever sibling format it stands in for.
+ */
+export declare const bamIndexFields: {
+    readonly indexType: {
+        readonly model: import("@jbrowse/mobx-state-tree").ISimpleType<"BAI" | "CSI">;
+        readonly type: 'stringEnum';
+        readonly defaultValue: 'BAI';
+        readonly description: '`BAI` is the usual `samtools index` output. `CSI` is required for a reference longer than 512 Mb, which BAI cannot address. Derived from the index file name where the config names a `.csi` and leaves this unset.';
+    };
+    readonly location: {
+        readonly type: 'fileLocation';
+        readonly defaultValue: {
+            readonly uri: '/path/to/my.bam.bai';
+            readonly locationType: 'UriLocation';
+        };
+        readonly description: 'location of the index. Only needed when it is not named `<file>.bam.bai` (or `.bam.csi`), the names the `uri` shorthand assumes.';
+    };
+};
+/**
+ * #config BamIndex
+ * #category adapter
+ * Where a BAM's index is and which of the two kinds it is. `indexType` is
+ * derived from the index file's own name where the config names a `.csi` and
+ * leaves it unset, so the usual config states neither — the `uri` shorthand
+ * derives both, and `csi: true` beside it switches the pair together. Spell
+ * `location` out for an index that does not sit beside its BAM; a `.csi` named
+ * there is read as a CSI without `indexType` as well.
+ */
+export declare function bamIndexSchema(): import("./configurationSchema.ts").ConfigurationSchemaType<{
+    readonly indexType: {
+        type: "stringEnum";
+    } & {
+        model: import("@jbrowse/mobx-state-tree").ISimpleType<"BAI" | "CSI">;
+    } & {
+        defaultValue: string;
+    };
+    readonly location: {
+        type: "fileLocation";
+    } & {
+        defaultValue: unknown;
+    };
+}, import("./configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined, undefined, import("./requirements.ts").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>, any>>;

package/esm/configuration/bamIndexFields.js

@@ -0,0 +1,41 @@
+import { types } from '@jbrowse/mobx-state-tree';
+import { ConfigurationSchema } from './configurationSchema.js';
+import { fillIndexType } from './indexType.js';
+/**
+ * BAM's `index`, which is the tabix pair over a different enumeration: BAI/CSI
+ * rather than TBI/CSI, with its own default and its own placeholder name.
+ * Folding the two would mean a slot whose vocabulary depends on its adapter,
+ * which is why `tabixIndexFields` says BAM is deliberately not there.
+ *
+ * Only the enumeration differs. `fillIndexType` is the same function, since a
+ * `.csi` names itself the same way whichever sibling format it stands in for.
+ */
+export const bamIndexFields = {
+    indexType: {
+        model: types.enumeration('IndexType', ['BAI', 'CSI']),
+        type: 'stringEnum',
+        defaultValue: 'BAI',
+        description: '`BAI` is the usual `samtools index` output. `CSI` is required for a reference longer than 512 Mb, which BAI cannot address. Derived from the index file name where the config names a `.csi` and leaves this unset.',
+    },
+    location: {
+        type: 'fileLocation',
+        defaultValue: {
+            uri: '/path/to/my.bam.bai',
+            locationType: 'UriLocation',
+        },
+        description: 'location of the index. Only needed when it is not named `<file>.bam.bai` (or `.bam.csi`), the names the `uri` shorthand assumes.',
+    },
+};
+/**
+ * #config BamIndex
+ * #category adapter
+ * Where a BAM's index is and which of the two kinds it is. `indexType` is
+ * derived from the index file's own name where the config names a `.csi` and
+ * leaves it unset, so the usual config states neither — the `uri` shorthand
+ * derives both, and `csi: true` beside it switches the pair together. Spell
+ * `location` out for an index that does not sit beside its BAM; a `.csi` named
+ * there is read as a CSI without `indexType` as well.
+ */
+export function bamIndexSchema() {
+    return ConfigurationSchema('BamIndex', { ...bamIndexFields }, { preProcessSnapshot: fillIndexType });
+}

package/esm/configuration/configurationSchema.d.ts

@@ -1,37 +1,202 @@
+import type PluginManager from '../PluginManager.ts';
+import type { IsAny } from '../util/types/isAny.ts';
 import type { ConfigSlotDefinition } from './configurationSlot.ts';
-import type { AnyConfigurationSchemaType } from './types.ts';
-import type { IAnyType } from '@jbrowse/mobx-state-tree';
-export type { AnyConfigurationModel, AnyConfigurationSchemaType, AnyConfigurationSlot, AnyConfigurationSlotType, } from './types.ts';
+import type { ConfigurationSchemaRequirement } from './requirements.ts';
+import type { AnyConfigurationModel, AnyConfigurationSchemaType, ConfigNodeActions, ConfigNodeBrand, ConfigNodeProps, IdentifierSlotDef, MergeConfigDef, TypeSlotDef } from './types.ts';
+import type { IAnyType, ISimpleType, IType, ReferenceIdentifier, SnapshotIn, SnapshotOut } from '@jbrowse/mobx-state-tree';
+export type { AnyConfigurationModel, AnyConfigurationSchemaType, } from './types.ts';
+/**
+ * The three entry kinds `makeConfigurationSchemaModel` classifies: a slot
+ * definition, a constant (bare string/number), or a nested sub-schema — which
+ * is the **MST type** `ConfigurationSchema()` returned, hence `IAnyType`.
+ *
+ * A raw nested `ConfigurationSchemaDefinition` used to be a fourth member here,
+ * and it was both dead and load-bearing in the wrong direction: nothing
+ * constructs a sub-schema from one (the loop has no branch for it, so it throws
+ * "no type set for config slot"), while a plain object of strings and numbers is
+ * exactly what a *slot definition* is — so every slot in the repo matched that
+ * member instead and was never checked against `ConfigSlotDefinition` at all.
+ * `type: 'enum'`, a name this system has never had, compiled for years that way.
+ */
 export interface ConfigurationSchemaDefinition {
-    [n: string]: ConfigSlotDefinition | ConfigurationSchemaDefinition | string | number | IAnyType;
+    [n: string]: ConfigSlotDefinition | string | number | IAnyType;
 }
-export interface ConfigurationSchemaOptions<BASE_SCHEMA extends AnyConfigurationSchemaType | undefined, EXPLICIT_IDENTIFIER extends string | undefined> {
-    explicitlyTyped?: boolean;
+export type RetiredSpelling = (value: unknown) => Record<string, unknown>;
+export interface ConfigurationSchemaOptions<BASE_SCHEMA extends AnyConfigurationSchemaType | undefined, EXPLICIT_IDENTIFIER extends string | undefined, EXPLICITLY_TYPED extends boolean | undefined = boolean | undefined, REQUIREMENT extends ConfigurationSchemaRequirement = ConfigurationSchemaRequirement, SELF = any> {
+    explicitlyTyped?: EXPLICITLY_TYPED;
     explicitIdentifier?: EXPLICIT_IDENTIFIER;
-    implicitIdentifier?: string | boolean;
     baseConfiguration?: BASE_SCHEMA;
-    actions?: (self: unknown) => any;
-    views?: (self: unknown) => any;
-    extend?: (self: unknown) => any;
+    actions?: (self: SELF) => any;
+    views?: (self: SELF) => any;
+    extend?: (self: SELF) => any;
+    /**
+     * The slot a bare string or number snapshot lifts into, as that slot's type
+     * takes it, so `color: "red"` and `color: { value: "red" }` are one config,
+     * and `rules: [5]` is `rules: [{ value: 5 }]`; or two slots, one taking a
+     * number and one a string, so a width's `size: 3` is `{ value: 3 }` and
+     * `size: "score"` is `{ field: "score" }`. Applied before
+     * `preProcessSnapshot`, on every path a snapshot arrives by; the JSON schema,
+     * `describeSlots` and the config editor read it here.
+     */
+    shorthand?: string | readonly string[];
+    /**
+     * Slots a bare value sets beside `shorthand`, for a schema whose defaults
+     * would hide it: LGVSyntenyColor's `field` defaults to `strand`, so its
+     * `color: "steelblue"` is `{ value: "steelblue", scale: "none" }`.
+     */
+    shorthandWith?: Record<string, unknown>;
+    /**
+     * Refuse a snapshot key the schema does not declare, where MST would drop
+     * it in silence. Checked after the `shorthand` lift and before
+     * `preProcessSnapshot`, on the same paths.
+     */
+    closed?: boolean;
+    /**
+     * The spellings an older release used, by the name it used, each answering
+     * the members that name's value becomes. Lifted
+     * before the `closed` check and `preProcessSnapshot`, on every path a
+     * snapshot or a settings bag arrives by, and read by the `displayDefaults`
+     * router, so one declaration serves a config entry, the shorthand object, a
+     * share link and an agent's bag alike. A spelling the snapshot already
+     * carries wins over the one a lift produces.
+     */
+    retired?: Record<string, RetiredSpelling>;
+    /**
+     * A colour object's defaults by `field`, `*` for any other: the scale while
+     * `scale` is unset, and the members that scale reads while unwritten.
+     */
+    fieldPresets?: Readonly<Record<string, {
+        readonly scale: string;
+    }>>;
     preProcessSnapshot?: (snapshot: Record<string, unknown>) => Record<string, unknown>;
+    requires?: REQUIREMENT[];
 }
-declare function makeConfigurationSchemaModel<DEFINITION extends ConfigurationSchemaDefinition, OPTIONS extends ConfigurationSchemaOptions<any, any>>(modelName: string, schemaDefinition: DEFINITION, options: OPTIONS): import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IModelType<Record<string, any>, {
-    setSubschema(slotName: string, data: Record<string, unknown>): Record<string, unknown> | ({
-        [x: string]: any;
-    } & import("@jbrowse/mobx-state-tree/dist/internal").NonEmptyObject & {
-        setSubschema(slotName: string, data: Record<string, unknown>): Record<string, unknown> | ({
-            [x: string]: any;
-        } & import("@jbrowse/mobx-state-tree/dist/internal").NonEmptyObject & any & import("@jbrowse/mobx-state-tree").IStateTreeNode<AnyConfigurationSchemaType>);
-    } & import("@jbrowse/mobx-state-tree").IStateTreeNode<AnyConfigurationSchemaType>);
-}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>, [undefined]>;
-export interface ConfigurationSchemaType<DEFINITION extends ConfigurationSchemaDefinition, OPTIONS extends ConfigurationSchemaOptions<any, any>> extends ReturnType<typeof makeConfigurationSchemaModel<DEFINITION, OPTIONS>> {
-    isJBrowseConfigurationSchema: boolean;
-    jbrowseSchemaDefinition: DEFINITION;
-    jbrowseSchemaOptions: OPTIONS;
-    type: string;
-    [key: string]: unknown;
+type SchemaHook = (self: any) => any;
+/**
+ * Options as **stored**: what a caller passes, except that the three
+ * MST-chained hooks may have accumulated a chain by merging in a
+ * `baseConfiguration`. A caller's single function is a valid chain of one, so
+ * `ConfigurationSchemaOptions` is assignable to this and no call site changes.
+ *
+ * They stay a chain rather than being folded into one function because MST is
+ * what does the chaining: `.actions()` is called once per entry, which is what
+ * puts the base's members on `self` by the time the subclass's function runs,
+ * and what lets the subclass override one by redeclaring its name. Folding to
+ * `self => ({...base(self), ...child(self)})` would give neither, and would
+ * corrupt `extend` outright (it returns `{actions, views, state}`, so a spread
+ * merge drops whichever side declared fewer of the three).
+ *
+ * `preProcessSnapshot` is the exception and composes into a single function,
+ * `child(base(snapshot))`: the base normalizes and migrates first, the subclass
+ * refines. It has to stay one function because `preProcessSnapshotWith` runs it
+ * straight off the registry, over a partial settings bag as well as a snapshot.
+ */
+export interface MergedConfigurationSchemaOptions<BASE_SCHEMA extends AnyConfigurationSchemaType | undefined, EXPLICIT_IDENTIFIER extends string | undefined> extends Omit<ConfigurationSchemaOptions<BASE_SCHEMA, EXPLICIT_IDENTIFIER>, 'actions' | 'views' | 'extend'> {
+    actions?: SchemaHook | SchemaHook[];
+    views?: SchemaHook | SchemaHook[];
+    extend?: SchemaHook | SchemaHook[];
 }
-export declare function ConfigurationSchema<DEFINITION extends ConfigurationSchemaDefinition, OPTIONS extends ConfigurationSchemaOptions<BASE_SCHEMA, EXPLICIT_IDENTIFIER>, BASE_SCHEMA extends AnyConfigurationSchemaType | undefined = undefined, EXPLICIT_IDENTIFIER extends string | undefined = undefined>(modelName: string, inputSchemaDefinition: DEFINITION, inputOptions?: ConfigurationSchemaOptions<BASE_SCHEMA, EXPLICIT_IDENTIFIER>): ConfigurationSchemaType<DEFINITION, OPTIONS>;
-export declare function TrackConfigurationReference(schemaType: IAnyType): import("@jbrowse/mobx-state-tree").ISnapshotProcessor<import("@jbrowse/mobx-state-tree").ITypeUnion<any, any, any>, import("@jbrowse/mobx-state-tree")._NotCustomized, any>;
-export declare function DisplayConfigurationReference(schemaType: IAnyType): import("@jbrowse/mobx-state-tree").ITypeUnion<any, any, any>;
-export declare function ConfigurationReference<SCHEMATYPE extends AnyConfigurationSchemaType>(schemaType: SCHEMATYPE): SCHEMATYPE;
+declare function makeConfigurationSchemaModel<DEFINITION extends ConfigurationSchemaDefinition, OPTIONS extends MergedConfigurationSchemaOptions<any, any>>(modelName: string, schemaDefinition: DEFINITION, options: OPTIONS): import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IModelType<Record<string, any>, ConfigNodeActions, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>, [undefined]>;
+/**
+ * DEFINITION is unconstrained on purpose. It carries the *merged* definition —
+ * `MergeConfigDef`, an unresolved conditional that cannot be checked against a
+ * constraint — and intersecting it with `ConfigurationSchemaDefinition` to
+ * satisfy one would put an index signature straight back into
+ * `keyof DEFINITION`. The authoring check lives on `ConfigurationSchema`'s own
+ * parameter, where the literal arrives, and on the `extends` clause below.
+ */
+export interface ConfigurationSchemaType<out DEFINITION, OPTIONS extends ConfigurationSchemaOptions<any, any>> extends ReturnType<typeof makeConfigurationSchemaModel<DEFINITION & ConfigurationSchemaDefinition, OPTIONS>> {
+    /**
+     * Overrides the factory's, whose props come off a `Record<string, any>` and
+     * so admit every name. Slots come from the definition — the identifier and
+     * an `explicitlyTyped` schema's `type` ride in as two of them — and the brand
+     * names this schema, which is what `ConfigurationSchemaForModel` infers back
+     * out. `TypeWithoutSTN` too, since a wrapper — `types.optional`,
+     * `types.stripDefault` — builds its instance from that one.
+     */
+    readonly Type: ConfigNodeProps<DEFINITION> & ConfigNodeActions & ConfigNodeBrand<this>;
+    readonly TypeWithoutSTN: ConfigNodeProps<DEFINITION> & ConfigNodeActions;
+}
+type RequirementPath<D> = {
+    [K in keyof D & string]: K | (D[K] extends ConfigurationSchemaType<infer SUB, any> ? `${K}.${RequirementPath<SUB>}` : never);
+}[keyof D & string];
+type RequirementWhen<D> = {
+    [K in keyof D & string as D[K] extends {
+        type: string;
+    } ? K : never]?: (D[K] extends {
+        model: ISimpleType<infer V extends string>;
+    } ? V : string)[];
+};
+type RequirementOf<D, BASE> = BASE extends ConfigurationSchemaType<infer BD, any> ? ConfigurationSchemaRequirement<RequirementWhen<D> & RequirementWhen<BD>, RequirementPath<D> | RequirementPath<BD>> : ConfigurationSchemaRequirement<RequirementWhen<D>, RequirementPath<D>>;
+export declare function ConfigurationSchema<const DEFINITION extends ConfigurationSchemaDefinition, BASE_SCHEMA extends AnyConfigurationSchemaType | undefined = undefined, EXPLICIT_IDENTIFIER extends string | undefined = undefined, EXPLICITLY_TYPED extends boolean | undefined = undefined>(modelName: string, inputSchemaDefinition: DEFINITION, inputOptions?: ConfigurationSchemaOptions<BASE_SCHEMA, EXPLICIT_IDENTIFIER, EXPLICITLY_TYPED, RequirementOf<NoInfer<DEFINITION>, NoInfer<BASE_SCHEMA>>, ConfigNodeProps<MergeConfigDef<NoInfer<DEFINITION>, NoInfer<BASE_SCHEMA>>> & ConfigNodeActions>): ConfigurationSchemaType<MergeConfigDef<DEFINITION & Record<EXPLICIT_IDENTIFIER & string, IdentifierSlotDef> & (EXPLICITLY_TYPED extends true ? {
+    type: TypeSlotDef;
+} : unknown), BASE_SCHEMA>, ConfigurationSchemaOptions<BASE_SCHEMA, EXPLICIT_IDENTIFIER, EXPLICITLY_TYPED>>;
+/**
+ * #api core/configuration
+ * Hydrate a plain track config into a live config node, dispatching on its
+ * `type` to find the schema. `session.tracks` holds `types.frozen` plain
+ * objects until something references a track (ADR-031). One of those holds only
+ * what was literally authored: a slot at its schema default is absent,
+ * `preProcessSnapshot` has not run, and nothing that walks a live node applies
+ * to it.
+ *
+ * Use it where a caller needs the resolved config and may be handed either
+ * form. The About dialog's "Copy config" is reached from two menus, and one of
+ * them passes a `session.tracks` entry.
+ *
+ * Returns **undefined** when the config names a track type no plugin
+ * registered, or when `create` rejects it as invalid. An un-hydrated config has
+ * never been validated, so the dialog opening over it should not throw. Callers
+ * fall back to using the plain object.
+ *
+ * Shares `TrackConfigurationReference`'s per-PluginManager cache, so hydrating
+ * the same entry twice returns the same node, and in an admin session a track
+ * opened later resolves to that same node. A non-admin's open track
+ * resolves to the session's private working copy (ADR-032), and this function
+ * returns the pristine mirror beside it. The two have the same content;
+ * `CopyConfigEntryPoints.test.ts` tests both cases.
+ */
+export declare function hydrateTrackConfig(pluginManager: PluginManager, config: Record<string, unknown>): AnyConfigurationModel | undefined;
+type ConfigReferenceInstance<SCHEMA extends AnyConfigurationSchemaType> = SCHEMA extends ConfigurationSchemaType<infer D, any> ? IsAny<D> extends true ? any : SCHEMA['Type'] : SCHEMA['Type'];
+/**
+ * Static type of the value `ConfigurationReference` produces, and therefore of a
+ * track/display state model's `configuration` prop. Its **instance** type is a
+ * clean, single-branded schema instance (see `ConfigReferenceInstance`), so
+ * `ConfigurationSchemaForModel` — and thus `getConf(self, slot)` /
+ * `readConfObject(self.configuration, slot)` — recovers the concrete schema and
+ * its precise slot value types instead of `any`. The snapshot types stay
+ * `id-string | schema-snapshot`, matching the runtime union (`idOrSnapshotUnion`):
+ * a saved config serializes to its id string, and both an id string and a full
+ * inline snapshot are accepted as input — so views that push string ids or
+ * synthesized configs (`CircularView`, `SvInspectorView`) keep type-checking.
+ *
+ * Built by `Omit`-ing `Type` off `IType` and re-adding it, rather than reusing
+ * the runtime `ITypeUnion`: `IType`'s own `Type` is `STNValue<T, this>`, which
+ * re-brands `T` with `IStateTreeNode<this>`. Layering that over an already-branded
+ * `SCHEMA['Type']` (which carries `IStateTreeNode<SCHEMA>`) double-brands the
+ * node, and the two competing `IStateTreeNode<…>` brands defeat the single
+ * `infer SCHEMA` in `ConfigurationSchemaForModel` (leaving it `any`). Re-adding a
+ * plain `Type` keeps the single brand. See the "Config read type narrowing"
+ * section of `packages/core/src/configuration/CLAUDE.md`.
+ */
+export type IConfigurationReference<SCHEMA extends AnyConfigurationSchemaType> = Omit<IType<ReferenceIdentifier | SnapshotIn<SCHEMA>, ReferenceIdentifier | SnapshotOut<SCHEMA>, ConfigReferenceInstance<SCHEMA>>, 'Type'> & {
+    readonly Type: ConfigReferenceInstance<SCHEMA>;
+};
+/**
+ * Dispatch by the schema's identifier: `trackId` → track-ref (resolves through
+ * `session.getTrackById`), `displayId` → display-ref (resolves through the
+ * parent track's displays array), anything else → plain reference.
+ *
+ * Display schemas must declare `explicitIdentifier: 'displayId'` (directly or
+ * via `baseConfiguration: baseLinearDisplayConfigSchema`, which merges its
+ * options through `preprocessConfigurationSchemaArguments`).
+ *
+ * The return is annotated `IConfigurationReference<SCHEMATYPE>` (see its doc)
+ * so `self.configuration` carries the concrete schema. The three runtime
+ * branches produce MST reference/union types over `schemaType` that are
+ * assignable to that annotation, so `return ref` needs no cast — and must not
+ * get one: a prior `as SCHEMATYPE` was dropped because it narrowed `SnapshotIn`
+ * to just the object branch and forced callers pushing string ids to
+ * `@ts-expect-error` (see `TrackConfigurationReference`'s note).
+ */
+export declare function ConfigurationReference<SCHEMATYPE extends AnyConfigurationSchemaType>(schemaType: SCHEMATYPE): IConfigurationReference<SCHEMATYPE>;