@jbrowse/mobx-state-tree 5.12.0 → 5.13.0

package/dist/index.d.ts

@@ -611,6 +611,7 @@ declare class ObjectNode<C, S, T> extends BaseNode<C, S, T> {
     private _cachedInitialSnapshot?;
     private _cachedInitialSnapshotCreated;
     private _snapshotComputed;
+    private _snapshotComputedEvaluated;
     constructor(complexType: ComplexType<C, S, T>, parent: AnyObjectNode | null, subpath: string, environment: any, initialValue: C);
     createObservableInstanceIfNeeded(fireHooks?: boolean): void;
     createObservableInstance(fireHooks?: boolean): void;
@@ -620,6 +621,17 @@ declare class ObjectNode<C, S, T> extends BaseNode<C, S, T> {
     protected fireHook(name: Hook): void;
     private _snapshotUponDeath?;
     get snapshot(): S;
+    /**
+     * @internal
+     * @hidden
+     * Recompute+retrack the keepAlive snapshot computed if it has already run.
+     * Needed whenever something changes what the snapshot would produce without
+     * an observable mobx would track: flipping the (non-observable) observable-
+     * instance state, or SnapshotProcessor rewriting getSnapshot after
+     * construction (see snapshotProcessor._fixNode). If it never ran, there is
+     * nothing cached to go stale, so this is a no-op.
+     */
+    refreshMemoizedSnapshot(): void;
     getSnapshot(): S;
     private _getActualSnapshot;
     private _getCachedInitialSnapshot;
@@ -1725,6 +1737,31 @@ declare function compose<PA extends ModelProperties, OA, FCA, FSA, PB extends Mo
  * @returns
  */
 declare function isModelType<IT extends IAnyModelType = IAnyModelType>(type: IAnyType): type is IT;
+/**
+ * `extendInstance` - attaches additional actions, views and volatile state to an
+ * already-created model instance, using the same instantiation machinery as
+ * `.extend()`. This enables lazily loading a model's views/actions chain: create
+ * the model with only its base props (plus any critical-path members), then attach
+ * the rest at runtime — e.g. from a dynamically imported module — without rebuilding
+ * the type or re-hydrating the tree.
+ *
+ * The extension is applied inside an action context, so it works on protected trees.
+ * Attached views are computeds (reactive, memoized) and attached actions get a full
+ * MST action context, exactly like members declared in the original chain.
+ *
+ * Note: the attached members are NOT part of the instance's *static* type. If you
+ * need them typed, declare the augmented shape separately (an `import type` of the
+ * chain's return type is erased at build time, so it costs nothing in the bundle).
+ *
+ * @param instance a live model instance
+ * @param fn receives the instance and returns `{ actions?, views?, state? }`
+ * @returns the same instance
+ */
+declare function extendInstance<T extends IAnyStateTreeNode>(instance: T, fn: (self: T) => {
+    actions?: ModelActions;
+    views?: object;
+    state?: object;
+}): T;
 
 /**
  * `types.Date` - Creates a type that can only contain a javascript Date value.
@@ -2139,5 +2176,5 @@ declare const types: {
     resilient: typeof resilient;
 };
 
-export { addDisposer, addMiddleware, applyAction, applyPatch, applySnapshot, cast, castFlowReturn, castToReferenceSnapshot, castToSnapshot, clone, createActionTrackingMiddleware, createActionTrackingMiddleware2, decorate, destroy, detach, escapeJsonPath, flow, getChildType, getEnv, getIdentifier, getLivelinessChecking, getMembers, getNodeId, getParent, getParentOfType, getPath, getPathParts, getPropertyMembers, getRelativePath, getRoot, getRunningActionContext, getSnapshot, getType, getUnionSubtypes, hasParent, hasParentOfType, isActionContextChildOf, isActionContextThisOrChildOf, isAlive, isArrayType, isFrozenType, isIdentifierType, isLateType, isLiteralType, isMapType, isModelType, isOptionalType, isPrimitiveType, isProtected, isReferenceType, isRefinementType, isRoot, isStateTreeNode, isType, isUnionType, isValidReference, joinJsonPath, onAction, onPatch, onSnapshot, protect, recordActions, recordPatches, resolveIdentifier, resolvePath, setDevMode, setLivelinessChecking, setLivelynessChecking, setTypeChecking, splitJsonPath, types as t, toGenerator, toGeneratorFunction, tryReference, tryResolve, typecheck, types, unescapeJsonPath, unprotect, walk };
+export { addDisposer, addMiddleware, applyAction, applyPatch, applySnapshot, cast, castFlowReturn, castToReferenceSnapshot, castToSnapshot, clone, createActionTrackingMiddleware, createActionTrackingMiddleware2, decorate, destroy, detach, escapeJsonPath, extendInstance, flow, getChildType, getEnv, getIdentifier, getLivelinessChecking, getMembers, getNodeId, getParent, getParentOfType, getPath, getPathParts, getPropertyMembers, getRelativePath, getRoot, getRunningActionContext, getSnapshot, getType, getUnionSubtypes, hasParent, hasParentOfType, isActionContextChildOf, isActionContextThisOrChildOf, isAlive, isArrayType, isFrozenType, isIdentifierType, isLateType, isLiteralType, isMapType, isModelType, isOptionalType, isPrimitiveType, isProtected, isReferenceType, isRefinementType, isRoot, isStateTreeNode, isType, isUnionType, isValidReference, joinJsonPath, onAction, onPatch, onSnapshot, protect, recordActions, recordPatches, resolveIdentifier, resolvePath, setDevMode, setLivelinessChecking, setLivelynessChecking, setTypeChecking, splitJsonPath, types as t, toGenerator, toGeneratorFunction, tryReference, tryResolve, typecheck, types, unescapeJsonPath, unprotect, walk };
 export type { $EmptyObjectBrand, CustomTypeOptions, IActionContext, IActionRecorder, IActionTrackingMiddleware2Call, IActionTrackingMiddleware2Hooks, IActionTrackingMiddlewareHooks, IAnyComplexType, IAnyModelType, IAnyStateTreeNode, IAnyType, IArrayType, IComplexType, IDisposer, IJsonPatch, IMSTArray, IMSTMap, IMapType, IMaybe, IMaybeIType, IMaybeNull, IMiddlewareEvent, IMiddlewareEventType, IMiddlewareHandler, IModelReflectionData, IModelReflectionPropertiesData, IModelType, IOptionalIType, IPatchRecorder, IReferenceType, IReversibleJsonPatch, ISerializedActionCall, ISimpleType, ISnapshotProcessor, ISnapshotProcessors, IStateTreeNode, IType, ITypeUnion, Instance, LivelinessMode, LivelynessMode, ModelActions, ModelCreationType, ModelCreationType2, ModelInstanceType, ModelInstanceTypeProps, ModelPrimitive, ModelProperties, ModelPropertiesDeclaration, ModelPropertiesDeclarationToProperties, ModelSnapshotType, ModelSnapshotType2, OnReferenceInvalidated, OnReferenceInvalidatedEvent, OptionalDefaultValueOrFunction, ReferenceIdentifier, ReferenceOptions, ReferenceOptionsGetSet, ReferenceOptionsOnInvalidated, SnapshotIn, SnapshotOrInstance, SnapshotOut, TypeOfValue, TypeOrStateTreeNodeToStateTreeNode, UnionOptions, UnionStringArray, ValidOptionalValue, ValidOptionalValues, _CustomCSProcessor, _CustomJoin, _CustomOrOther, _NotCustomized };

package/dist/mobx-state-tree.cjs

@@ -1139,6 +1139,10 @@ const snapshotReactionOptions = {
         throw e;
     }
 };
+// keepAlive lets the snapshot computed memoize its value even with no observer,
+// so getSnapshot() stays referentially stable without an eager snapshot
+// reaction serializing the whole tree at create time. Shared: mobx only reads it.
+const snapshotComputedOptions = { keepAlive: true };
 /**
  * @internal
  * @hidden
@@ -1171,9 +1175,18 @@ class ObjectNode extends BaseNode {
     _cachedInitialSnapshot;
     _cachedInitialSnapshotCreated = false;
     _snapshotComputed;
+    // whether _snapshotComputed has ever run — see createObservableInstance
+    _snapshotComputedEvaluated = false;
     constructor(complexType, parent, subpath, environment, initialValue) {
         super(complexType, parent, subpath, environment);
-        this._snapshotComputed = mobx.computed(() => freeze(this.getSnapshot()));
+        // keepAlive: memoize the snapshot after the first read even with no
+        // observer, so getSnapshot() is referentially stable (and reconcile-by-
+        // snapshot works) without eagerly serializing the whole tree at create
+        // time — the previous cost, driven by the eager root reaction below.
+        this._snapshotComputed = mobx.computed(() => {
+            this._snapshotComputedEvaluated = true;
+            return freeze(this.getSnapshot());
+        }, snapshotComputedOptions);
         this.unbox = this.unbox.bind(this);
         this._initialSnapshot = freeze(initialValue);
         this.identifierAttribute = complexType.identifierAttribute;
@@ -1257,10 +1270,17 @@ class ObjectNode extends BaseNode {
             this._isRunningAction = false;
         }
         this._observableInstanceState = ObservableInstanceLifecycle.CREATED;
-        this._snapshotComputed.trackAndCompute();
-        if (this.isRoot) {
-            this._addSnapshotReaction();
-        }
+        // The snapshot computed branches on the non-observable
+        // "_observableInstanceState" flag we just flipped, so a value already
+        // memoized from the initial snapshot is now stale (mobx can't see the
+        // change) — refresh it. When it was never read there is nothing to refresh,
+        // and forcing it here would serialize the whole subtree (the dominant cost
+        // of creating a root) for a value nobody has asked for yet, so we skip it.
+        this.refreshMemoizedSnapshot();
+        // The root's snapshot reaction only drives onSnapshot; set it up lazily
+        // (onSnapshot already does) rather than eagerly here, so a root nobody
+        // subscribes to never pays for a full-tree snapshot at creation. keepAlive
+        // on _snapshotComputed preserves snapshot referential stability without it.
         this._childNodes = EMPTY_OBJECT;
         this.state = NodeLifeCycle.CREATED;
         if (fireHooks) {
@@ -1365,6 +1385,21 @@ class ObjectNode extends BaseNode {
         }
         return this._snapshotComputed.get();
     }
+    /**
+     * @internal
+     * @hidden
+     * Recompute+retrack the keepAlive snapshot computed if it has already run.
+     * Needed whenever something changes what the snapshot would produce without
+     * an observable mobx would track: flipping the (non-observable) observable-
+     * instance state, or SnapshotProcessor rewriting getSnapshot after
+     * construction (see snapshotProcessor._fixNode). If it never ran, there is
+     * nothing cached to go stale, so this is a no-op.
+     */
+    refreshMemoizedSnapshot() {
+        if (this._snapshotComputedEvaluated) {
+            this._snapshotComputed.trackAndCompute();
+        }
+    }
     // NOTE: we use this method to get snapshot without creating @computed overhead
     getSnapshot() {
         if (!this.isAlive) {
@@ -3312,6 +3347,11 @@ let _typeChecking;
 function setTypeChecking(enabled) {
     _typeChecking = enabled;
 }
+// the ENABLE_TYPE_CHECK env var is fixed at process start, so read it once:
+// process.env access is a comparatively expensive lookup and isTypeCheckingEnabled
+// runs on every create() / typed write. The setTypeChecking() override and
+// dev-mode default stay live below.
+const _envTypeCheck = typeof process !== "undefined" && process.env?.ENABLE_TYPE_CHECK === "true";
 /**
  * @internal
  * @hidden
@@ -3319,10 +3359,7 @@ function setTypeChecking(enabled) {
 function isTypeCheckingEnabled() {
     // an explicit setTypeChecking() override (incl. `false`) wins over the
     // dev-mode / env-var default, hence ?? rather than ||
-    return (_typeChecking ??
-        (devMode() ||
-            (typeof process !== "undefined" &&
-                process.env?.ENABLE_TYPE_CHECK === "true")));
+    return _typeChecking ?? (devMode() || _envTypeCheck);
 }
 let _devMode = process.env.NODE_ENV !== "production";
 /**
@@ -3725,6 +3762,11 @@ class SnapshotProcessor extends BaseType {
         }
         const oldGetSnapshot = node.getSnapshot;
         node.getSnapshot = () => this.postProcessSnapshot(oldGetSnapshot.call(node), node);
+        // getSnapshot was just rewritten; refresh any snapshot already memoized for
+        // this node (e.g. it was serialized before being moved under this processor)
+        if (node instanceof ObjectNode) {
+            node.refreshMemoizedSnapshot();
+        }
         if (!isUnionType(this._subtype)) {
             node.getReconciliationType = () => {
                 return this;
@@ -4647,11 +4689,27 @@ class ModelType extends ComplexType {
     constructor(opts) {
         super(opts.name || defaultObjectOptions.name);
         Object.assign(this, defaultObjectOptions, opts);
-        // ensures that any default value gets converted to its related type
-        this.properties = toPropertiesObject(this.properties);
-        freeze(this.properties); // make sure nobody messes with it
-        this.propertyNames = Object.keys(this.properties);
-        this.identifierAttribute = this._getIdentifierAttribute();
+        if (opts.propertiesArePreProcessed) {
+            // `properties` is a parent type's already-converted + frozen output
+            // (chain step with no new props), so its derived propertyNames and
+            // identifierAttribute are identical to the parent's — reuse them verbatim
+            // (cloneAndEnhance passed them in) instead of re-running Object.keys and
+            // the per-prop identifier scan, both O(props), on every step.
+            this.propertyNames = opts.propertyNames;
+            this.identifierAttribute = opts.identifierAttribute;
+        }
+        else {
+            // `propertiesAreConverted` (set by cloneAndEnhance when props are added)
+            // means every value is already a type — the parent's converted bag merged
+            // with a freshly converted delta — so skip re-converting. Only raw entry
+            // points (`model()`) still need the full toPropertiesObject pass.
+            if (!opts.propertiesAreConverted) {
+                this.properties = toPropertiesObject(this.properties);
+            }
+            freeze(this.properties); // make sure nobody messes with it
+            this.propertyNames = Object.keys(this.properties);
+            this.identifierAttribute = this._getIdentifierAttribute();
+        }
     }
     _getIdentifierAttribute() {
         let identifierAttribute = undefined;
@@ -4666,9 +4724,35 @@ class ModelType extends ComplexType {
         return identifierAttribute;
     }
     cloneAndEnhance(opts) {
+        // Fast path: a chain step that adds no new properties (.actions/.views/
+        // .volatile/.named/pre-postProcessor) reuses this type's already-converted +
+        // frozen properties (and their derived names/identifier) verbatim.
+        const hasNewProps = opts.properties !== undefined && Object.keys(opts.properties).length > 0;
+        if (!hasNewProps) {
+            return new ModelType({
+                name: opts.name || this.name,
+                properties: this.properties,
+                propertiesArePreProcessed: true,
+                // safe to share: propertyNames is never mutated after construction
+                propertyNames: this.propertyNames,
+                identifierAttribute: this.identifierAttribute,
+                initializers: this.initializers.concat(opts.initializers || []),
+                preProcessor: opts.preProcessor || this.preProcessor,
+                postProcessor: opts.postProcessor || this.postProcessor
+            });
+        }
+        // Adding props: this type's `properties` is already converted+frozen, so only
+        // the delta needs conversion. compose passes already-converted props
+        // (cur.properties) and flags them; `.props()` passes a raw declaration. Either
+        // way the merged bag is fully converted, so the constructor skips re-converting
+        // the (potentially large) inherited set — the previous hot spot in compose.
+        const convertedNewProps = opts.propertiesAreConverted
+            ? opts.properties
+            : toPropertiesObject(opts.properties);
         return new ModelType({
             name: opts.name || this.name,
-            properties: Object.assign({}, this.properties, opts.properties),
+            properties: Object.assign({}, this.properties, convertedNewProps),
+            propertiesAreConverted: true,
             initializers: this.initializers.concat(opts.initializers || []),
             preProcessor: opts.preProcessor || this.preProcessor,
             postProcessor: opts.postProcessor || this.postProcessor
@@ -4765,6 +4849,29 @@ class ModelType extends ComplexType {
         };
         return this.cloneAndEnhance({ initializers: [viewInitializer] });
     }
+    /**
+     * @internal
+     * @hidden
+     * Materializes an additional actions/views/state extension onto an
+     * already-created instance, using the same machinery as `.extend()` runs at
+     * creation time. Powers {@link extendInstance}; callers must ensure the writes
+     * are permitted (see extendInstance, which runs this in an action context).
+     */
+    applyExtensionToInstance(self, extension) {
+        const { actions, views, state, ...rest } = extension;
+        for (const key in rest) {
+            throw fail(`extendInstance should return an object with a subset of the fields 'actions', 'views' and 'state'. Found invalid key '${key}'`);
+        }
+        if (state) {
+            this.instantiateVolatileState(self, state);
+        }
+        if (views) {
+            this.instantiateViews(self, views);
+        }
+        if (actions) {
+            this.instantiateActions(self, actions);
+        }
+    }
     instantiateViews(self, views) {
         // check views return
         if (!isPlainObject(views)) {
@@ -5025,6 +5132,8 @@ function compose(...args) {
         .reduce((prev, cur) => prev.cloneAndEnhance({
         name: `${prev.name}_${cur.name}`,
         properties: cur.properties,
+        // cur.properties is another ModelType's already-converted+frozen bag
+        propertiesAreConverted: true,
         initializers: cur.initializers,
         preProcessor: (snapshot) => cur.applySnapshotPreProcessor(prev.applySnapshotPreProcessor(snapshot)),
         postProcessor: (snapshot) => cur.applySnapshotPostProcessor(prev.applySnapshotPostProcessor(snapshot))
@@ -5040,6 +5149,46 @@ function compose(...args) {
 function isModelType(type) {
     return isType(type) && (type.flags & TypeFlags.Object) > 0;
 }
+/**
+ * `extendInstance` - attaches additional actions, views and volatile state to an
+ * already-created model instance, using the same instantiation machinery as
+ * `.extend()`. This enables lazily loading a model's views/actions chain: create
+ * the model with only its base props (plus any critical-path members), then attach
+ * the rest at runtime — e.g. from a dynamically imported module — without rebuilding
+ * the type or re-hydrating the tree.
+ *
+ * The extension is applied inside an action context, so it works on protected trees.
+ * Attached views are computeds (reactive, memoized) and attached actions get a full
+ * MST action context, exactly like members declared in the original chain.
+ *
+ * Note: the attached members are NOT part of the instance's *static* type. If you
+ * need them typed, declare the augmented shape separately (an `import type` of the
+ * chain's return type is erased at build time, so it costs nothing in the bundle).
+ *
+ * @param instance a live model instance
+ * @param fn receives the instance and returns `{ actions?, views?, state? }`
+ * @returns the same instance
+ */
+function extendInstance(instance, fn) {
+    if (!isStateTreeNode(instance)) {
+        throw fail("extendInstance expects a mobx-state-tree node");
+    }
+    const type = getStateTreeNode(instance).type;
+    if (!isModelType(type)) {
+        throw fail("extendInstance can only be used on model instances");
+    }
+    // Views/actions/volatile are installed via defineProperty + makeObservable — the
+    // same "add" operations the initializers perform at creation, before the
+    // write-protection interceptor is attached (see finalizeNewInstance). On a live
+    // instance that interceptor is already active, so run the attach inside an action
+    // context: isRunningAction() then short-circuits assertWritable.
+    const modelType = type;
+    const attach = createActionInvoker(instance, "@@extendInstance", (() => {
+        modelType.applyExtensionToInstance(instance, fn(instance));
+    }));
+    attach();
+    return instance;
+}
 
 // TODO: implement CoreType using types.custom ?
 /**
@@ -5468,7 +5617,24 @@ class Union extends BaseType {
         }
         return `${baseWithDiscriminator}:\n    ${formatValidationErrorLines(errors).join("\n    ")}`;
     }
+    // Memoizes the discriminator -> member scan below. Union membership is fixed
+    // at construction, so the result for a given `type` string never changes.
+    // Without this, validating a config with many elements drawn from a wide
+    // pluggable union (e.g. jbrowse's 30+ track/adapter types) re-scans every
+    // member — and calls resolveModelType + literal.is() on each — once per
+    // element. With it, each distinct discriminator scans once; the rest are
+    // O(1) map hits. `undefined` (no match OR ambiguous) is cached too.
+    _discriminatorCache;
     _findCandidateByTypeDiscriminator(discriminator) {
+        const cache = (this._discriminatorCache ??= new Map());
+        if (cache.has(discriminator)) {
+            return cache.get(discriminator);
+        }
+        const found = this._scanForTypeDiscriminator(discriminator);
+        cache.set(discriminator, found);
+        return found;
+    }
+    _scanForTypeDiscriminator(discriminator) {
         let found;
         for (const t of this._types) {
             const model = resolveModelType(t);
@@ -7005,6 +7171,7 @@ exports.decorate = decorate;
 exports.destroy = destroy;
 exports.detach = detach;
 exports.escapeJsonPath = escapeJsonPath;
+exports.extendInstance = extendInstance;
 exports.flow = flow;
 exports.getChildType = getChildType;
 exports.getEnv = getEnv;