@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/withLaunchInput.js

@@ -0,0 +1,228 @@
+import { reportLegacyInit, reportMalformedRows, reportUnknownKeys, } from './unknownSnapshotKeys.js';
+// re-exported here because the surfaces that classify their own keys — a
+// session spec, which launches without ever building a snapshot — reach the
+// partition's vocabulary through this module
+export { legacyInitMessage, unknownKeysMessage } from './unknownSnapshotKeys.js';
+// What afterAttach reports rather than applies. They live in the blob so the
+// partition has one place to put everything, and `pendingLaunch` is what keeps
+// them from reading as work to do.
+const REPORTED = new Set(['unknown', 'malformed', 'legacyInit']);
+/**
+ * The blob when it still holds something to apply, else undefined. A view's
+ * gates ask this rather than the raw property: a snapshot whose only launch
+ * content was a typo has nothing to launch, and a view that thinks otherwise
+ * waits on an assembly nobody named and never leaves the spinner.
+ *
+ * Returns the blob itself, never a copy — the launch autorun clears by
+ * identity, and a fresh object per read strands the init it just applied.
+ */
+export function pendingLaunch(launch) {
+    return launch && Object.keys(launch).some(k => !REPORTED.has(k))
+        ? launch
+        : undefined;
+}
+/**
+ * Declare one view's launch keys. The argument is
+ * `Record<keyof Commands, LaunchKeySpec>`, so a command the view interprets and
+ * nobody registered is a compile error rather than a key that partitions as a
+ * typo and warns.
+ *
+ * `passThrough` names keys that are neither a launch key nor a declared
+ * property and still belong on the snapshot — a legacy spelling the view's own
+ * `preProcessSnapshot` converts.
+ */
+export function defineLaunchKeys() {
+    return (keys, { passThrough } = {}) => ({
+        keys,
+        passThrough: passThrough ?? [],
+    });
+}
+// `id` picks up MST's optional identifier and `type` picks the view, so neither
+// is ever a setting and neither can be lifted off the snapshot.
+const IDENTITY = new Set(['id', 'type']);
+const LAUNCH = 'launch';
+function isObject(value) {
+    return !!value && typeof value === 'object';
+}
+// Each per-entry kind says only which entries are an authored recipe. A recipe
+// goes to the blob for the launcher to resolve; everything else is a built
+// snapshot and stays on the property, so a mixed array splits rather than
+// picking one meaning for the whole thing.
+function isRecipeEntry(kind, entry) {
+    switch (kind) {
+        case 'trackEntries':
+            // a built track snapshot cannot carry `trackId` — BaseTrackModel does not
+            // declare it. `type` does not discriminate: a spec writes display types
+            // inline
+            return (typeof entry === 'string' || (isObject(entry) && 'trackId' in entry));
+        case 'highlightEntries':
+            // a string needs coerceHighlight and the assembly manager, neither of
+            // which a pure preprocessor can reach; an object is the persisted shape
+            return typeof entry === 'string';
+        case 'rows':
+            // a built row is a view snapshot, and every view's `type` is a required
+            // literal
+            return !(isObject(entry) && 'type' in entry);
+        default:
+            return true;
+    }
+}
+function splitEntries(kind, value) {
+    const entries = Array.isArray(value) ? value : [value];
+    const recipes = entries.filter(e => isRecipeEntry(kind, e));
+    const built = entries.filter(e => !isRecipeEntry(kind, e));
+    return {
+        launch: recipes.length
+            ? Array.isArray(value)
+                ? recipes
+                : value
+            : undefined,
+        state: built.length ? (Array.isArray(value) ? built : value) : undefined,
+    };
+}
+function classify(snap, { keys, passThrough }, known, out) {
+    for (const [key, value] of Object.entries(snap)) {
+        const spec = keys[key];
+        if (IDENTITY.has(key)) {
+            out.state[key] = value;
+        }
+        else if (spec?.kind === 'launch') {
+            out.launch[key] = value;
+        }
+        else if (spec?.kind === 'replay') {
+            out.state[key] = value;
+            out.launch[key] = value;
+        }
+        else if (spec) {
+            const { launch, state } = splitEntries(spec.kind, value);
+            if (spec.kind === 'rows' && launch !== undefined && state !== undefined) {
+                // A row list indexes against `levels` and `tracks[i]`, so lifting half
+                // of it renumbers the other half. Nothing here can throw — a pure
+                // preprocessor runs against snapshots the union is about to reject — so
+                // the whole list goes to the bucket afterAttach reports and the view
+                // comes up on its import form rather than on a silently misaligned
+                // stack.
+                out.malformed[key] = value;
+            }
+            else {
+                if (launch !== undefined) {
+                    out.launch[key] = launch;
+                }
+                if (state !== undefined) {
+                    out.state[key] = state;
+                }
+            }
+        }
+        else if (known.has(key) || passThrough.includes(key)) {
+            out.state[key] = value;
+        }
+        else {
+            out.unknown[key] = value;
+        }
+    }
+}
+// BreakpointSplitView's v4 `init` was a bare array of panels rather than an
+// object of settings. A positional list can only be the view's row list, and a
+// view declares at most one, so it is read as that key rather than classified
+// per index — which would name "0" and "1" as unknown keys.
+function legacyInitSnapshot(init, { keys }) {
+    const rows = Object.entries(keys).find(([, spec]) => spec.kind === 'rows')?.[0];
+    return Array.isArray(init) && rows ? { [rows]: init } : init;
+}
+/**
+ * Accept a view's settings written directly on the view object, and move the
+ * ones a launcher has to resolve into the internal `launch` property.
+ *
+ * The partition is a `preProcessSnapshot` and is PURE. A session's view type is
+ * a `types.union`, so MST runs every member's preprocessor against every
+ * candidate snapshot while deciding which one matches, and runs it about twice
+ * more per instantiation; a warning from in here fires against snapshots that
+ * are about to be rejected. `afterAttach` — reached only by a snapshot that won
+ * — reports what the partition captured.
+ *
+ * ORDER: MST runs preprocessors in the reverse of the order they were added, so
+ * this belongs on the chain BEFORE a view's own legacy-key preprocessor, where
+ * it partitions the snapshot MST finally consumes rather than a key that remap
+ * is about to convert.
+ *
+ * The widening cast is the LAST link that may change the creation type: it
+ * replaces `CustomC`, so a `.props()` added after it is invisible to
+ * `SnapshotIn`. Further `preProcessSnapshot`/`postProcessSnapshot` links are
+ * fine — both carry `CustomC` through.
+ *
+ * Not `types.snapshotProcessor`, which carries the same widened input and stops
+ * being a `ModelType`. `PluginManager.pluggableMstType` filters union members on
+ * `isModelType`, so a wrapped view is dropped from the session's view union
+ * without a word, and `ViewType.stateModel` and every `.properties`
+ * introspection site break with it.
+ */
+export function withLaunchInput(model, registration) {
+    const known = new Set(Object.keys(model.properties));
+    const partitioned = model
+        .preProcessSnapshot((snap) => {
+        if (!isObject(snap)) {
+            return snap;
+        }
+        const { init, ...rest } = snap;
+        const out = {
+            state: {},
+            launch: {},
+            unknown: {},
+            malformed: {},
+        };
+        if (isObject(init)) {
+            // v4's nesting, unwrapped rather than refused: a nested key sorts the
+            // same three ways a flat one does, so honoring it costs one more pass
+            // and a deprecation warning, where dropping it opens an admin's
+            // `defaultSession` on its defaults. First, so a snapshot spelling one
+            // key both ways resolves to the flat one the docs teach.
+            classify(legacyInitSnapshot(init, registration), registration, known, out);
+            out.launch.legacyInit = true;
+        }
+        classify(rest, registration, known, out);
+        if (Object.keys(out.unknown).length) {
+            out.launch.unknown = out.unknown;
+        }
+        if (Object.keys(out.malformed).length) {
+            out.launch.malformed = out.malformed;
+        }
+        const persisted = out.state[LAUNCH];
+        return Object.keys(out.launch).length
+            ? {
+                ...out.state,
+                [LAUNCH]: {
+                    ...(isObject(persisted) ? persisted : {}),
+                    ...out.launch,
+                },
+            }
+            : out.state;
+    })
+        .actions(self => ({
+        afterAttach() {
+            const { launch } = self;
+            if (launch?.legacyInit) {
+                reportLegacyInit(self);
+            }
+            reportUnknownKeys(self, Object.keys(launch?.unknown ?? {}));
+            reportMalformedRows(self, Object.keys(launch?.malformed ?? {}));
+        },
+    }))
+        // `legacyInit` names the SPELLING of the snapshot this view was opened from,
+        // and a saved one does not use it — so persisting the flag makes every later
+        // restore report nesting the snapshot it is reading does not contain,
+        // forever, since nothing clears it (`pendingLaunch` excludes the report
+        // keys, so the launch autorun never runs). `unknown` and `malformed` stay:
+        // those name content that was DISCARDED, which is still true of the saved
+        // snapshot, and the blob is the only record of it.
+        .postProcessSnapshot((snap) => {
+        const launch = snap[LAUNCH];
+        if (!isObject(launch) || !launch.legacyInit) {
+            return snap;
+        }
+        const { legacyInit, ...kept } = launch;
+        return Object.keys(kept).length
+            ? { ...snap, [LAUNCH]: kept }
+            : Object.fromEntries(Object.entries(snap).filter(([key]) => key !== LAUNCH));
+    });
+    return partitioned;
+}