@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.11

package/esm/configuration/snapshotPreprocess.d.ts

@@ -0,0 +1,43 @@
+import type { RetiredSpelling } from './configurationSchema.ts';
+import type { ConfigurationSchemaMetadata } from './schemaRegistry.ts';
+import type { IAnyType } from '@jbrowse/mobx-state-tree';
+export declare function listed(keys: readonly string[]): string;
+/**
+ * The snapshot with each spelling `retired` names rewritten: a lift's members
+ * take the old key's place, and what the snapshot already spells wins, member
+ * by member inside an object, since writing the current name is the stronger
+ * statement — so a retired flag lifting into `scales.y` lands beside a
+ * `scales.y` the snapshot writes. The old key goes whether or not it carried a
+ * value, so a `closed` schema never meets it. Where two retired names lift
+ * onto one member — a slot the entry spelt directly and the same slot inside a
+ * retired `renderer` — the one declared first wins.
+ */
+export declare function liftRetiredSpellings(schema: ConfigurationSchemaMetadata, snapshot: Record<string, unknown>): Record<string, unknown>;
+/**
+ * `liftRetiredSpellings` over a map directly, for a schema whose own
+ * `preProcessSnapshot` uncovers a retired name the pass above could not see —
+ * one that arrives out of a legacy sub-config rather than off the entry.
+ * Applying the same map twice costs nothing, since a lift deletes the name it
+ * reads.
+ */
+export declare function applyRetiredSpellings(retired: Record<string, RetiredSpelling>, snapshot: Record<string, unknown>): Record<string, unknown>;
+/**
+ * What a schema does to every snapshot on its way in, whichever door it
+ * arrives by (`create`, `applySnapshot`, `setSubschema`, a settings bag): a
+ * bare string or number lifts into the `shorthand` slot taking its form, beside any
+ * `shorthandWith` slots, and `null` into the empty object that clears it; a
+ * `null` member reads as unset, except in a frozen-family slot, which stores
+ * it; a `retired` spelling becomes the members that replaced it; a `closed`
+ * schema refuses a key it does not declare, then the schema's
+ * own `preProcessSnapshot` runs, and a `jexl:` callback in a slot declaring no
+ * `contextVariable` is refused. A bare value the shorthand does not lift
+ * passes through for MST to refuse.
+ */
+export declare function preProcessSnapshotWith(schema: ConfigurationSchemaMetadata, snapshot: unknown): Record<string, unknown>;
+/**
+ * #api core/configuration
+ * A snapshot as `type` admits it: the same lift and checks `type.create`
+ * applies, so a dialog or a validator refuses exactly what a config file
+ * cannot hold. Throws what the schema's `preProcessSnapshot` throws.
+ */
+export declare function preProcessConfigSnapshot(type: IAnyType, snapshot: unknown): Record<string, unknown>;

package/esm/configuration/snapshotPreprocess.js

@@ -0,0 +1,161 @@
+import { isJexl } from '../util/jexlStrings.js';
+import { slotWriteRefusal } from './configurationSlot.js';
+import { getConfigurationSchemaMetadata } from './schemaRegistry.js';
+import { bareFormOf, isConstantEntry, shorthandTargets } from './schemaTypes.js';
+// the keys a config file may annotate any object with, as the JSON schema's
+// `patternProperties` admits them
+const COMMENT_KEY = /^_+comment/;
+export function listed(keys) {
+    return keys.length > 1
+        ? `${keys.slice(0, -1).join(', ')} and ${keys.at(-1)}`
+        : (keys[0] ?? 'nothing');
+}
+function refuseUndeclaredKeys({ name, definition, options }, snapshot) {
+    const id = options.explicitIdentifier;
+    const declared = [
+        ...Object.keys(definition).filter(key => !isConstantEntry(definition[key])),
+        ...(options.explicitlyTyped ? ['type'] : []),
+        ...(id ? [id] : []),
+    ];
+    const unknown = typeof snapshot === 'string'
+        ? [JSON.stringify(snapshot)]
+        : Object.keys(snapshot ?? {}).filter(key => !declared.includes(key) && !COMMENT_KEY.test(key));
+    if (unknown.length > 0) {
+        throw new Error(`${name} takes ${listed(declared)}, not ${unknown.join(', ')}`);
+    }
+}
+// Checked here as well as by each slot's MST type because this runs on every
+// create, where MST's own check is off in a build that has not enabled it
+function refuseCallbacks({ name, takesNoCallback }, snapshot) {
+    if (typeof snapshot === 'object' && snapshot !== null) {
+        for (const key in snapshot) {
+            const type = takesNoCallback.get(key);
+            const value = snapshot[key];
+            if (type !== undefined && isJexl(value)) {
+                throw new Error(slotWriteRefusal(`${name}.${key}`, type, value));
+            }
+        }
+    }
+}
+// ADR-146's reset, on the snapshot path: the member keeps its key, so a
+// settings bag still resets it, and `create` reads `undefined` as the default
+function nullMembersAsUnset(snapshot, storesNull) {
+    let out = snapshot;
+    for (const key in snapshot) {
+        if (snapshot[key] === null && !storesNull.has(key)) {
+            out = out === snapshot ? { ...snapshot } : out;
+            out[key] = undefined;
+        }
+    }
+    return out;
+}
+/**
+ * A schema reads its own entry alone. A `displays` union runs every member's
+ * preprocessor over every entry while it works out which display an entry is,
+ * so an entry naming another type is left as it was, and one naming no type is
+ * a bag headed here.
+ */
+function isOwnSnapshot({ name, options }, snapshot) {
+    return (!options.explicitlyTyped ||
+        snapshot.type === undefined ||
+        snapshot.type === name);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// `lifted` under `written`: what the snapshot spells wins, member by member
+// where both are objects.
+function underWritten(written, lifted) {
+    if (written === undefined) {
+        return lifted;
+    }
+    if (isPlainObject(written) && isPlainObject(lifted)) {
+        const out = { ...written };
+        for (const [key, value] of Object.entries(lifted)) {
+            out[key] = underWritten(written[key], value);
+        }
+        return out;
+    }
+    return written;
+}
+/**
+ * The snapshot with each spelling `retired` names rewritten: a lift's members
+ * take the old key's place, and what the snapshot already spells wins, member
+ * by member inside an object, since writing the current name is the stronger
+ * statement — so a retired flag lifting into `scales.y` lands beside a
+ * `scales.y` the snapshot writes. The old key goes whether or not it carried a
+ * value, so a `closed` schema never meets it. Where two retired names lift
+ * onto one member — a slot the entry spelt directly and the same slot inside a
+ * retired `renderer` — the one declared first wins.
+ */
+export function liftRetiredSpellings(schema, snapshot) {
+    const { retired } = schema.options;
+    return retired && isOwnSnapshot(schema, snapshot)
+        ? applyRetiredSpellings(retired, snapshot)
+        : snapshot;
+}
+/**
+ * `liftRetiredSpellings` over a map directly, for a schema whose own
+ * `preProcessSnapshot` uncovers a retired name the pass above could not see —
+ * one that arrives out of a legacy sub-config rather than off the entry.
+ * Applying the same map twice costs nothing, since a lift deletes the name it
+ * reads.
+ */
+export function applyRetiredSpellings(retired, snapshot) {
+    const present = Object.keys(retired).filter(key => key in snapshot);
+    if (present.length === 0) {
+        return snapshot;
+    }
+    const out = { ...snapshot };
+    for (const key of present) {
+        delete out[key];
+    }
+    for (const key of present.filter(key => snapshot[key] !== undefined)) {
+        const lifted = retired[key](snapshot[key]);
+        for (const [name, value] of Object.entries(lifted)) {
+            out[name] = underWritten(out[name], value);
+        }
+    }
+    return out;
+}
+/**
+ * What a schema does to every snapshot on its way in, whichever door it
+ * arrives by (`create`, `applySnapshot`, `setSubschema`, a settings bag): a
+ * bare string or number lifts into the `shorthand` slot taking its form, beside any
+ * `shorthandWith` slots, and `null` into the empty object that clears it; a
+ * `null` member reads as unset, except in a frozen-family slot, which stores
+ * it; a `retired` spelling becomes the members that replaced it; a `closed`
+ * schema refuses a key it does not declare, then the schema's
+ * own `preProcessSnapshot` runs, and a `jexl:` callback in a slot declaring no
+ * `contextVariable` is refused. A bare value the shorthand does not lift
+ * passes through for MST to refuse.
+ */
+export function preProcessSnapshotWith(schema, snapshot) {
+    const { shorthandWith, closed, preProcessSnapshot } = schema.options;
+    const form = bareFormOf(snapshot);
+    const target = form && shorthandTargets(schema)[form];
+    const lifted = snapshot === null
+        ? {}
+        : target !== undefined
+            ? { ...shorthandWith, [target]: snapshot }
+            : nullMembersAsUnset(snapshot, schema.storesNull);
+    const named = liftRetiredSpellings(schema, lifted);
+    if (closed) {
+        refuseUndeclaredKeys(schema, named);
+    }
+    const processed = preProcessSnapshot ? preProcessSnapshot(named) : named;
+    refuseCallbacks(schema, processed);
+    return processed;
+}
+/**
+ * #api core/configuration
+ * A snapshot as `type` admits it: the same lift and checks `type.create`
+ * applies, so a dialog or a validator refuses exactly what a config file
+ * cannot hold. Throws what the schema's `preProcessSnapshot` throws.
+ */
+export function preProcessConfigSnapshot(type, snapshot) {
+    const schema = getConfigurationSchemaMetadata(type);
+    return schema
+        ? preProcessSnapshotWith(schema, snapshot)
+        : snapshot;
+}

package/esm/configuration/tabixIndexFields.d.ts

@@ -14,7 +14,7 @@
  *   two slots in the opposite order
  * - `PairwiseIndexedPAFAdapter`'s prose said `<file>.pif.gz.tbi` while its
  *   default said `my.paf.gz.tbi`
- * - `PlinkLDTabixAdapter` dropped the `(or .csi)` clause
+ * - `PlinkLDTabixAdapter`'s description dropped a clause the other eight carried
  * - the placeholder extensions disagreed with each other for no reason
  *
  * The description is written for every tabix adapter rather than naming one
@@ -24,14 +24,15 @@
  *
  * **BAM is deliberately not here.** Its index is BAI/CSI rather than TBI/CSI, so
  * it is a different enumeration with a different default, and folding the two
- * would mean a slot whose vocabulary depends on its adapter.
+ * would mean a slot whose vocabulary depends on its adapter. `bamIndexFields`
+ * is the same pair over that enumeration, and the two share `fillIndexType`.
  */
 export declare const tabixIndexFields: {
     readonly indexType: {
         readonly model: import("@jbrowse/mobx-state-tree").ISimpleType<"CSI" | "TBI">;
         readonly type: 'stringEnum';
         readonly defaultValue: 'TBI';
-        readonly description: '`TBI` is the usual `tabix` output. `CSI` is required for a reference longer than 512 Mb, which TBI cannot address.';
+        readonly description: '`TBI` is the usual `tabix` output. `CSI` is required for a reference longer than 512 Mb, which TBI cannot address. Derived from the index file name where the config names a `.csi` and leaves this unset.';
     };
     readonly location: {
         readonly type: 'fileLocation';
@@ -39,6 +40,31 @@ export declare const tabixIndexFields: {
             readonly uri: '/path/to/my.gz.tbi';
             readonly locationType: 'UriLocation';
         };
-        readonly description: 'location of the tabix index. Only needed when it is not named `<file>.tbi` (or `.csi`), which is what the `uri` shorthand assumes.';
+        readonly description: 'location of the tabix index. Only needed when it is not named `<file>.tbi`, which is what the `uri` shorthand assumes — a `.csi` beside the file is reached with `csi: true` rather than by spelling this out.';
     };
 };
+/**
+ * #config TabixIndex
+ * #category adapter
+ * The `index` every tabix-indexed adapter hangs off itself: where the 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 data file; a `.csi` named there is read as a CSI
+ * without `indexType` as well.
+ */
+export declare function tabixIndexSchema(): import("./configurationSchema.ts").ConfigurationSchemaType<{
+    readonly indexType: {
+        type: "stringEnum";
+    } & {
+        model: import("@jbrowse/mobx-state-tree").ISimpleType<"CSI" | "TBI">;
+    } & {
+        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/tabixIndexFields.js

@@ -1,4 +1,6 @@
 import { types } from '@jbrowse/mobx-state-tree';
+import { ConfigurationSchema } from './configurationSchema.js';
+import { fillIndexType } from './indexType.js';
 /**
  * The `index` sub-schema every tabix-indexed adapter declares: which index kind,
  * and where it is.
@@ -15,7 +17,7 @@ import { types } from '@jbrowse/mobx-state-tree';
  *   two slots in the opposite order
  * - `PairwiseIndexedPAFAdapter`'s prose said `<file>.pif.gz.tbi` while its
  *   default said `my.paf.gz.tbi`
- * - `PlinkLDTabixAdapter` dropped the `(or .csi)` clause
+ * - `PlinkLDTabixAdapter`'s description dropped a clause the other eight carried
  * - the placeholder extensions disagreed with each other for no reason
  *
  * The description is written for every tabix adapter rather than naming one
@@ -25,14 +27,15 @@ import { types } from '@jbrowse/mobx-state-tree';
  *
  * **BAM is deliberately not here.** Its index is BAI/CSI rather than TBI/CSI, so
  * it is a different enumeration with a different default, and folding the two
- * would mean a slot whose vocabulary depends on its adapter.
+ * would mean a slot whose vocabulary depends on its adapter. `bamIndexFields`
+ * is the same pair over that enumeration, and the two share `fillIndexType`.
  */
 export const tabixIndexFields = {
     indexType: {
         model: types.enumeration('IndexType', ['TBI', 'CSI']),
         type: 'stringEnum',
         defaultValue: 'TBI',
-        description: '`TBI` is the usual `tabix` output. `CSI` is required for a reference longer than 512 Mb, which TBI cannot address.',
+        description: '`TBI` is the usual `tabix` output. `CSI` is required for a reference longer than 512 Mb, which TBI cannot address. Derived from the index file name where the config names a `.csi` and leaves this unset.',
     },
     location: {
         type: 'fileLocation',
@@ -40,6 +43,20 @@ export const tabixIndexFields = {
             uri: '/path/to/my.gz.tbi',
             locationType: 'UriLocation',
         },
-        description: 'location of the tabix index. Only needed when it is not named `<file>.tbi` (or `.csi`), which is what the `uri` shorthand assumes.',
+        description: 'location of the tabix index. Only needed when it is not named `<file>.tbi`, which is what the `uri` shorthand assumes — a `.csi` beside the file is reached with `csi: true` rather than by spelling this out.',
     },
 };
+/**
+ * #config TabixIndex
+ * #category adapter
+ * The `index` every tabix-indexed adapter hangs off itself: where the 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 data file; a `.csi` named there is read as a CSI
+ * without `indexType` as well.
+ */
+export function tabixIndexSchema() {
+    return ConfigurationSchema('TabixIndex', { ...tabixIndexFields }, { preProcessSnapshot: fillIndexType });
+}

package/esm/configuration/tabixShorthand.d.ts

@@ -1,15 +1,32 @@
+import type { IndexType, SiblingIndexType } from './indexType.ts';
 /**
- * The `index` half of a tabix-indexed adapter's shorthand snapshot: given
- * `{ uri, baseUri?, csi? }`, where the index file sits and what kind it is.
+ * The index type a config asks for, by whichever of its three spellings: the
+ * `csi` flag, `index.indexType`, or the extension on the index file it names.
+ * Explicit beats derived.
  *
- * Two spellings of the same flag have to agree — `CSI`/`TBI` names the type and
- * `.csi`/`.tbi` the file extension — and eight adapters were each writing both
- * out. Getting the pair crossed is an adapter that looks for the wrong index
- * file, or claims the wrong format for the right one, on a config the user
- * wrote correctly.
+ * One reader for all three, because they are one fact and disagreeing copies of
+ * it open the wrong parser — `openTabixIndexFilehandle` hands @gmod/tabix a
+ * `csiFilehandle` or a `tbiFilehandle` off `indexType` alone.
  */
+export declare function requestedIndexType(snap: Record<string, unknown>, fallback: SiblingIndexType): IndexType;
+/**
+ * The `index` half of an indexed adapter's shorthand snapshot. The filename
+ * follows from {@link requestedIndexType}, so the type and the extension cannot
+ * disagree, and whatever the config wrote under `index` then wins member by
+ * member: naming a location keeps the derived type, naming a type keeps the
+ * derived location, and an `indexType` the enumeration does not have reaches MST
+ * to be refused rather than being quietly read as the sibling format.
+ */
+export declare function indexSnapshot(snap: Record<string, unknown>, fallback: SiblingIndexType): {
+    indexType: IndexType;
+    location: {
+        uri: string;
+        baseUri: unknown;
+    };
+};
+/** {@link indexSnapshot} for the tabix family, whose sibling format is TBI. */
 export declare function tabixIndexSnapshot(snap: Record<string, unknown>): {
-    indexType: string;
+    indexType: IndexType;
     location: {
         uri: string;
         baseUri: unknown;
@@ -18,17 +35,17 @@ export declare function tabixIndexSnapshot(snap: Record<string, unknown>): {
 /**
  * Expand a tabix adapter's one-line shorthand — `{ uri: 'x.gff.gz' }`, plus
  * optional `csi` — into the full `{ <locationKey>, index }` snapshot, or pass a
- * snapshot that is already in full form through untouched.
+ * snapshot already in full form through untouched.
  *
  * `locationKey` is the only thing that differs between adapters
- * (`gffGzLocation`, `vcfGzLocation`, `bedGzLocation`, `pifGzLocation`, …), so
- * it is the only thing they now supply. An adapter whose shorthand carries more
- * than this (maf's `nhUri`) composes `tabixIndexSnapshot` directly instead.
+ * (`gffGzLocation`, `vcfGzLocation`, `bedGzLocation`, `pifGzLocation`, …). An
+ * adapter whose shorthand carries more (maf's `nhUri`) composes
+ * `tabixIndexSnapshot` directly.
  *
- * Kept a plain function on the adapter type rather than folded into
- * `ConfigurationSchema`: `scripts/generateConfigManifest.ts` derives each
- * adapter's `shorthandKeys` by EXECUTING `normalizeSnapshot` against probe
- * snapshots and diffing what it derived, so the manifest — and the config docs
- * built from it — follow this without knowing it exists.
+ * Kept a plain function rather than folded into `ConfigurationSchema`:
+ * `scripts/generateConfigManifest.ts` derives each adapter's `shorthandKeys` by
+ * EXECUTING `normalizeSnapshot` against probe snapshots, so the manifest and the
+ * config docs follow this without knowing it exists. It finds the candidate keys
+ * by reading them out of source, following what an adapter schema imports.
  */
 export declare function expandTabixShorthand(snap: Record<string, unknown>, locationKey: string): Record<string, unknown>;

package/esm/configuration/tabixShorthand.js

@@ -1,44 +1,71 @@
+import { isPlainObject } from '../util/objectUtils.js';
+import { fillLocations } from './fillLocations.js';
+import { indexSuffix, isCsiLocation } from './indexType.js';
 /**
- * The `index` half of a tabix-indexed adapter's shorthand snapshot: given
- * `{ uri, baseUri?, csi? }`, where the index file sits and what kind it is.
+ * The index type a config asks for, by whichever of its three spellings: the
+ * `csi` flag, `index.indexType`, or the extension on the index file it names.
+ * Explicit beats derived.
  *
- * Two spellings of the same flag have to agree — `CSI`/`TBI` names the type and
- * `.csi`/`.tbi` the file extension — and eight adapters were each writing both
- * out. Getting the pair crossed is an adapter that looks for the wrong index
- * file, or claims the wrong format for the right one, on a config the user
- * wrote correctly.
+ * One reader for all three, because they are one fact and disagreeing copies of
+ * it open the wrong parser — `openTabixIndexFilehandle` hands @gmod/tabix a
+ * `csiFilehandle` or a `tbiFilehandle` off `indexType` alone.
  */
-export function tabixIndexSnapshot(snap) {
-    const csi = Boolean(snap.csi);
+export function requestedIndexType(snap, fallback) {
+    const written = isPlainObject(snap.index) ? snap.index : undefined;
+    const declared = written?.indexType;
+    if (declared === 'CSI') {
+        return 'CSI';
+    }
+    if (declared === fallback) {
+        return fallback;
+    }
+    return snap.csi || isCsiLocation(written?.location) ? 'CSI' : fallback;
+}
+/**
+ * The `index` half of an indexed adapter's shorthand snapshot. The filename
+ * follows from {@link requestedIndexType}, so the type and the extension cannot
+ * disagree, and whatever the config wrote under `index` then wins member by
+ * member: naming a location keeps the derived type, naming a type keeps the
+ * derived location, and an `indexType` the enumeration does not have reaches MST
+ * to be refused rather than being quietly read as the sibling format.
+ */
+export function indexSnapshot(snap, fallback) {
+    const indexType = requestedIndexType(snap, fallback);
     return {
-        indexType: csi ? 'CSI' : 'TBI',
+        indexType,
         location: {
-            uri: `${snap.uri}.${csi ? 'csi' : 'tbi'}`,
+            uri: `${snap.uri}${indexSuffix(indexType)}`,
             baseUri: snap.baseUri,
         },
+        ...(isPlainObject(snap.index) ? snap.index : {}),
     };
 }
+/** {@link indexSnapshot} for the tabix family, whose sibling format is TBI. */
+export function tabixIndexSnapshot(snap) {
+    return indexSnapshot(snap, 'TBI');
+}
 /**
  * Expand a tabix adapter's one-line shorthand — `{ uri: 'x.gff.gz' }`, plus
  * optional `csi` — into the full `{ <locationKey>, index }` snapshot, or pass a
- * snapshot that is already in full form through untouched.
+ * snapshot already in full form through untouched.
  *
  * `locationKey` is the only thing that differs between adapters
- * (`gffGzLocation`, `vcfGzLocation`, `bedGzLocation`, `pifGzLocation`, …), so
- * it is the only thing they now supply. An adapter whose shorthand carries more
- * than this (maf's `nhUri`) composes `tabixIndexSnapshot` directly instead.
+ * (`gffGzLocation`, `vcfGzLocation`, `bedGzLocation`, `pifGzLocation`, …). An
+ * adapter whose shorthand carries more (maf's `nhUri`) composes
+ * `tabixIndexSnapshot` directly.
  *
- * Kept a plain function on the adapter type rather than folded into
- * `ConfigurationSchema`: `scripts/generateConfigManifest.ts` derives each
- * adapter's `shorthandKeys` by EXECUTING `normalizeSnapshot` against probe
- * snapshots and diffing what it derived, so the manifest — and the config docs
- * built from it — follow this without knowing it exists.
+ * Kept a plain function rather than folded into `ConfigurationSchema`:
+ * `scripts/generateConfigManifest.ts` derives each adapter's `shorthandKeys` by
+ * EXECUTING `normalizeSnapshot` against probe snapshots, so the manifest and the
+ * config docs follow this without knowing it exists. It finds the candidate keys
+ * by reading them out of source, following what an adapter schema imports.
  */
 export function expandTabixShorthand(snap, locationKey) {
     return snap.uri
         ? {
-            ...snap,
-            [locationKey]: { uri: snap.uri, baseUri: snap.baseUri },
+            ...fillLocations(snap, {
+                [locationKey]: { uri: snap.uri, baseUri: snap.baseUri },
+            }),
             index: tabixIndexSnapshot(snap),
         }
         : snap;