@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/configuration/slotValueUtils.d.ts

@@ -0,0 +1,17 @@
+import type { JexlInstance } from '../util/jexlStrings.ts';
+/**
+ * The shared, MST-free jexl primitives for config values, with no knowledge of
+ * slot type names. Both the MST read path (`readConfObject`) and the
+ * plain-object/worker read path (`readConfigValue`) route through here.
+ *
+ * The value<->callback *conversions* (`toFixedValue`/`toCallbackValue`), which
+ * depend on the slot-type registry, live in `configurationSlot.ts`.
+ */
+export declare function isCallbackValue(value: unknown): value is string;
+/**
+ * The single jexl-evaluation boundary for config values.
+ *
+ * An empty body (`'jexl:'`, e.g. mid-typing in the editor) has no compilable
+ * code — return it literally instead of throwing (#4181).
+ */
+export declare function evaluateJexl(value: string, args: Record<string, unknown>, jexl: JexlInstance): unknown;

package/esm/configuration/slotValueUtils.js

@@ -0,0 +1,25 @@
+import { isJexl, stringToJexlExpression } from '../util/jexlStrings.js';
+import { buildJexlContext } from '../util/simpleFeature.js';
+/**
+ * The shared, MST-free jexl primitives for config values, with no knowledge of
+ * slot type names. Both the MST read path (`readConfObject`) and the
+ * plain-object/worker read path (`readConfigValue`) route through here.
+ *
+ * The value<->callback *conversions* (`toFixedValue`/`toCallbackValue`), which
+ * depend on the slot-type registry, live in `configurationSlot.ts`.
+ */
+export function isCallbackValue(value) {
+    return isJexl(value);
+}
+/**
+ * The single jexl-evaluation boundary for config values.
+ *
+ * An empty body (`'jexl:'`, e.g. mid-typing in the editor) has no compilable
+ * code — return it literally instead of throwing (#4181).
+ */
+export function evaluateJexl(value, args, jexl) {
+    if (value.length <= 'jexl:'.length) {
+        return value;
+    }
+    return stringToJexlExpression(value, jexl).eval(buildJexlContext(args));
+}

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

@@ -0,0 +1,70 @@
+/**
+ * The `index` sub-schema every tabix-indexed adapter declares: which index kind,
+ * and where it is.
+ *
+ * The **snapshot** half of this was extracted first (`tabixIndexSnapshot`, whose
+ * header explains why eight adapters writing out `CSI`/`TBI` and `.csi`/`.tbi`
+ * separately is a crossed pair waiting to happen). This is the schema half of
+ * the same job, and it was still nine hand-written copies under eight different
+ * type names — `TabixIndex`, `Index`, `VcfIndex`, `Gff3TabixIndex`,
+ * `GtfTabixIndex`, `BedGraphTabixIndex`, `PlinkLDTabixIndex` — for one concept,
+ * which is what let four of them drift:
+ *
+ * - `MafTabixAdapter` omitted `locationType` from its default and declared its
+ *   two slots in the opposite order
+ * - `PairwiseIndexedPAFAdapter`'s prose said `<file>.pif.gz.tbi` while its
+ *   default said `my.paf.gz.tbi`
+ * - `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
+ * file type, since none of them is more canonical than the others and the
+ * placeholder is not a value anyone copies — the `uri` shorthand derives the
+ * real one.
+ *
+ * **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. `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. 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.gz.tbi';
+            readonly locationType: 'UriLocation';
+        };
+        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

@@ -0,0 +1,62 @@
+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.
+ *
+ * The **snapshot** half of this was extracted first (`tabixIndexSnapshot`, whose
+ * header explains why eight adapters writing out `CSI`/`TBI` and `.csi`/`.tbi`
+ * separately is a crossed pair waiting to happen). This is the schema half of
+ * the same job, and it was still nine hand-written copies under eight different
+ * type names — `TabixIndex`, `Index`, `VcfIndex`, `Gff3TabixIndex`,
+ * `GtfTabixIndex`, `BedGraphTabixIndex`, `PlinkLDTabixIndex` — for one concept,
+ * which is what let four of them drift:
+ *
+ * - `MafTabixAdapter` omitted `locationType` from its default and declared its
+ *   two slots in the opposite order
+ * - `PairwiseIndexedPAFAdapter`'s prose said `<file>.pif.gz.tbi` while its
+ *   default said `my.paf.gz.tbi`
+ * - `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
+ * file type, since none of them is more canonical than the others and the
+ * placeholder is not a value anyone copies — the `uri` shorthand derives the
+ * real one.
+ *
+ * **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. `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. Derived from the index file name where the config names a `.csi` and leaves this unset.',
+    },
+    location: {
+        type: 'fileLocation',
+        defaultValue: {
+            uri: '/path/to/my.gz.tbi',
+            locationType: 'UriLocation',
+        },
+        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

@@ -0,0 +1,51 @@
+import type { IndexType, SiblingIndexType } from './indexType.ts';
+/**
+ * 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.
+ *
+ * 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: IndexType;
+    location: {
+        uri: string;
+        baseUri: 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 already in full form through untouched.
+ *
+ * `locationKey` is the only thing that differs between adapters
+ * (`gffGzLocation`, `vcfGzLocation`, `bedGzLocation`, `pifGzLocation`, …). An
+ * adapter whose shorthand carries more (maf's `nhUri`) composes
+ * `tabixIndexSnapshot` directly.
+ *
+ * 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

@@ -0,0 +1,72 @@
+import { isPlainObject } from '../util/objectUtils.js';
+import { fillLocations } from './fillLocations.js';
+import { indexSuffix, isCsiLocation } from './indexType.js';
+/**
+ * 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.
+ *
+ * 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 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,
+        location: {
+            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 already in full form through untouched.
+ *
+ * `locationKey` is the only thing that differs between adapters
+ * (`gffGzLocation`, `vcfGzLocation`, `bedGzLocation`, `pifGzLocation`, …). An
+ * adapter whose shorthand carries more (maf's `nhUri`) composes
+ * `tabixIndexSnapshot` directly.
+ *
+ * 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
+        ? {
+            ...fillLocations(snap, {
+                [locationKey]: { uri: snap.uri, baseUri: snap.baseUri },
+            }),
+            index: tabixIndexSnapshot(snap),
+        }
+        : snap;
+}