@jbrowse/mobx-state-tree 5.6.10 → 5.7.0

package/esm/types/utility-types/reference.js

@@ -0,0 +1,383 @@
+import { SimpleType } from "../../core/type/type.js";
+import { Hook, NodeLifeCycle, TypeFlags, applyPatch, assertIsType, createScalarNode, devMode, fail, getIdentifier, getStateTreeNode, isModelType, isStateTreeNode, isValidIdentifier, maybe, normalizeIdentifier, typeCheckFailure, typeCheckSuccess } from "../../internal.js";
+function getInvalidationCause(hook) {
+    switch (hook) {
+        case Hook.beforeDestroy:
+            return "destroy";
+        case Hook.beforeDetach:
+            return "detach";
+        default:
+            return undefined;
+    }
+}
+class StoredReference {
+    targetType;
+    identifier;
+    node;
+    resolvedReference;
+    constructor(value, targetType) {
+        this.targetType = targetType;
+        if (isValidIdentifier(value)) {
+            this.identifier = value;
+        }
+        else if (isStateTreeNode(value)) {
+            const targetNode = getStateTreeNode(value);
+            if (!targetNode.identifierAttribute) {
+                throw fail(`Can only store references with a defined identifier attribute.`);
+            }
+            const id = targetNode.unnormalizedIdentifier;
+            if (id === null || id === undefined) {
+                throw fail(`Can only store references to tree nodes with a defined identifier.`);
+            }
+            this.identifier = id;
+        }
+        else {
+            throw fail(`Can only store references to tree nodes or identifiers, got: '${value}'`);
+        }
+    }
+    updateResolvedReference(node) {
+        const normalizedId = normalizeIdentifier(this.identifier);
+        const root = node.root;
+        const lastCacheModification = root.identifierCache.getLastCacheModificationPerId(normalizedId);
+        if (!this.resolvedReference ||
+            this.resolvedReference.lastCacheModification !== lastCacheModification) {
+            const { targetType } = this;
+            // reference was initialized with the identifier of the target
+            const target = root.identifierCache.resolve(targetType, normalizedId);
+            if (!target) {
+                throw new InvalidReferenceError(`[mobx-state-tree] Failed to resolve reference '${this.identifier}' to type '${this.targetType.name}' (from node: ${node.path})`);
+            }
+            this.resolvedReference = {
+                node: target,
+                lastCacheModification: lastCacheModification
+            };
+        }
+    }
+    get resolvedValue() {
+        this.updateResolvedReference(this.node);
+        return this.resolvedReference.node.value;
+    }
+}
+/**
+ * @internal
+ * @hidden
+ */
+export class InvalidReferenceError extends Error {
+    constructor(m) {
+        super(m);
+        Object.setPrototypeOf(this, InvalidReferenceError.prototype);
+    }
+}
+/**
+ * @internal
+ * @hidden
+ */
+export class BaseReferenceType extends SimpleType {
+    targetType;
+    onInvalidated;
+    flags = TypeFlags.Reference;
+    constructor(targetType, onInvalidated) {
+        super(`reference(${targetType.name})`);
+        this.targetType = targetType;
+        this.onInvalidated = onInvalidated;
+    }
+    describe() {
+        return this.name;
+    }
+    isAssignableFrom(type) {
+        return this.targetType.isAssignableFrom(type);
+    }
+    isValidSnapshot(value, context) {
+        return isValidIdentifier(value)
+            ? typeCheckSuccess()
+            : typeCheckFailure(context, value, "Value is not a valid identifier, which is a string or a number");
+    }
+    fireInvalidated(cause, storedRefNode, referenceId, refTargetNode) {
+        // to actually invalidate a reference we need an alive parent,
+        // since it is a scalar value (immutable-ish) and we need to change it
+        // from the parent
+        const storedRefParentNode = storedRefNode.parent;
+        if (!storedRefParentNode || !storedRefParentNode.isAlive) {
+            return;
+        }
+        const storedRefParentValue = storedRefParentNode.storedValue;
+        if (!storedRefParentValue) {
+            return;
+        }
+        this.onInvalidated({
+            cause,
+            parent: storedRefParentValue,
+            invalidTarget: refTargetNode ? refTargetNode.storedValue : undefined,
+            invalidId: referenceId,
+            replaceRef(newRef) {
+                applyPatch(storedRefNode.root.storedValue, {
+                    op: "replace",
+                    value: newRef,
+                    path: storedRefNode.path
+                });
+            },
+            removeRef() {
+                if (isModelType(storedRefParentNode.type)) {
+                    this.replaceRef(undefined);
+                }
+                else {
+                    applyPatch(storedRefNode.root.storedValue, {
+                        op: "remove",
+                        path: storedRefNode.path
+                    });
+                }
+            }
+        });
+    }
+    addTargetNodeWatcher(storedRefNode, referenceId) {
+        // this will make sure the target node becomes created
+        const refTargetValue = this.getValue(storedRefNode);
+        if (!refTargetValue) {
+            return undefined;
+        }
+        const refTargetNode = getStateTreeNode(refTargetValue);
+        const hookHandler = (_, refTargetNodeHook) => {
+            const cause = getInvalidationCause(refTargetNodeHook);
+            if (!cause) {
+                return;
+            }
+            this.fireInvalidated(cause, storedRefNode, referenceId, refTargetNode);
+        };
+        const refTargetDetachHookDisposer = refTargetNode.registerHook(Hook.beforeDetach, hookHandler);
+        const refTargetDestroyHookDisposer = refTargetNode.registerHook(Hook.beforeDestroy, hookHandler);
+        return () => {
+            refTargetDetachHookDisposer();
+            refTargetDestroyHookDisposer();
+        };
+    }
+    watchTargetNodeForInvalidations(storedRefNode, identifier, customGetSet) {
+        if (!this.onInvalidated) {
+            return;
+        }
+        let onRefTargetDestroyedHookDisposer;
+        // get rid of the watcher hook when the stored ref node is destroyed
+        // detached is ignored since scalar nodes (where the reference resides) cannot be detached
+        storedRefNode.registerHook(Hook.beforeDestroy, () => {
+            if (onRefTargetDestroyedHookDisposer) {
+                onRefTargetDestroyedHookDisposer();
+            }
+        });
+        const startWatching = (sync) => {
+            // re-create hook in case the stored ref gets reattached
+            if (onRefTargetDestroyedHookDisposer) {
+                onRefTargetDestroyedHookDisposer();
+            }
+            // make sure the target node is actually there and initialized
+            const storedRefParentNode = storedRefNode.parent;
+            const storedRefParentValue = storedRefParentNode && storedRefParentNode.storedValue;
+            if (storedRefParentNode &&
+                storedRefParentNode.isAlive &&
+                storedRefParentValue) {
+                let refTargetNodeExists;
+                if (customGetSet) {
+                    refTargetNodeExists = !!customGetSet.get(identifier, storedRefParentValue);
+                }
+                else {
+                    refTargetNodeExists = storedRefNode.root.identifierCache.has(this.targetType, normalizeIdentifier(identifier));
+                }
+                if (!refTargetNodeExists) {
+                    // we cannot change the reference in sync mode
+                    // since we are in the middle of a reconciliation/instantiation and the change would be overwritten
+                    // for those cases just let the wrong reference be assigned and fail upon usage
+                    // (like current references do)
+                    // this means that effectively this code will only run when it is created from a snapshot
+                    if (!sync) {
+                        this.fireInvalidated("invalidSnapshotReference", storedRefNode, identifier, null);
+                    }
+                }
+                else {
+                    onRefTargetDestroyedHookDisposer = this.addTargetNodeWatcher(storedRefNode, identifier);
+                }
+            }
+        };
+        if (storedRefNode.state === NodeLifeCycle.FINALIZED) {
+            // already attached, so the whole tree is ready
+            startWatching(true);
+        }
+        else {
+            if (!storedRefNode.isRoot) {
+                // start watching once the whole tree is ready
+                storedRefNode.root.registerHook(Hook.afterCreationFinalization, () => {
+                    // make sure to attach it so it can start listening
+                    if (storedRefNode.parent) {
+                        storedRefNode.parent.createObservableInstanceIfNeeded();
+                    }
+                });
+            }
+            // start watching once the node is attached somewhere / parent changes
+            storedRefNode.registerHook(Hook.afterAttach, () => {
+                startWatching(false);
+            });
+        }
+    }
+}
+/**
+ * @internal
+ * @hidden
+ */
+export class IdentifierReferenceType extends BaseReferenceType {
+    constructor(targetType, onInvalidated) {
+        super(targetType, onInvalidated);
+    }
+    getValue(storedRefNode) {
+        if (!storedRefNode.isAlive) {
+            return undefined;
+        }
+        const storedRef = storedRefNode.storedValue;
+        return storedRef.resolvedValue;
+    }
+    getSnapshot(storedRefNode) {
+        const ref = storedRefNode.storedValue;
+        return ref.identifier;
+    }
+    instantiate(parent, subpath, environment, initialValue) {
+        const identifier = isStateTreeNode(initialValue)
+            ? getIdentifier(initialValue)
+            : initialValue;
+        const storedRef = new StoredReference(initialValue, this.targetType);
+        const storedRefNode = createScalarNode(this, parent, subpath, environment, storedRef);
+        storedRef.node = storedRefNode;
+        this.watchTargetNodeForInvalidations(storedRefNode, identifier, undefined);
+        return storedRefNode;
+    }
+    reconcile(current, newValue, parent, subpath) {
+        if (!current.isDetaching && current.type === this) {
+            const compareByValue = isStateTreeNode(newValue);
+            const ref = current.storedValue;
+            if ((!compareByValue && ref.identifier === newValue) ||
+                (compareByValue && ref.resolvedValue === newValue)) {
+                current.setParent(parent, subpath);
+                return current;
+            }
+        }
+        const newNode = this.instantiate(parent, subpath, undefined, newValue);
+        current.die(); // noop if detaching
+        return newNode;
+    }
+}
+/**
+ * @internal
+ * @hidden
+ */
+export class CustomReferenceType extends BaseReferenceType {
+    options;
+    constructor(targetType, options, onInvalidated) {
+        super(targetType, onInvalidated);
+        this.options = options;
+    }
+    getValue(storedRefNode) {
+        if (!storedRefNode.isAlive) {
+            return undefined;
+        }
+        const referencedNode = this.options.get(storedRefNode.storedValue, storedRefNode.parent ? storedRefNode.parent.storedValue : null);
+        return referencedNode;
+    }
+    getSnapshot(storedRefNode) {
+        return storedRefNode.storedValue;
+    }
+    instantiate(parent, subpath, environment, newValue) {
+        const identifier = isStateTreeNode(newValue)
+            ? this.options.set(newValue, parent ? parent.storedValue : null)
+            : newValue;
+        const storedRefNode = createScalarNode(this, parent, subpath, environment, identifier);
+        this.watchTargetNodeForInvalidations(storedRefNode, identifier, this.options);
+        return storedRefNode;
+    }
+    reconcile(current, newValue, parent, subpath) {
+        const newIdentifier = isStateTreeNode(newValue)
+            ? this.options.set(newValue, current ? current.storedValue : null)
+            : newValue;
+        if (!current.isDetaching &&
+            current.type === this &&
+            current.storedValue === newIdentifier) {
+            current.setParent(parent, subpath);
+            return current;
+        }
+        const newNode = this.instantiate(parent, subpath, undefined, newIdentifier);
+        current.die(); // noop if detaching
+        return newNode;
+    }
+}
+/**
+ * `types.reference` - Creates a reference to another type, which should have defined an identifier.
+ * See also the [reference and identifiers](https://github.com/mobxjs/mobx-state-tree#references-and-identifiers) section.
+ */
+export function reference(subType, options) {
+    assertIsType(subType, 1);
+    if (devMode()) {
+        if (options && typeof options === "string") {
+            // istanbul ignore next
+            throw fail("References with base path are no longer supported. Please remove the base path.");
+        }
+    }
+    const getSetOptions = options
+        ? options
+        : undefined;
+    const onInvalidated = options
+        ? options.onInvalidated
+        : undefined;
+    if (getSetOptions && (getSetOptions.get || getSetOptions.set)) {
+        if (devMode()) {
+            if (!getSetOptions.get || !getSetOptions.set) {
+                throw fail("reference options must either contain both a 'get' and a 'set' method or none of them");
+            }
+        }
+        return new CustomReferenceType(subType, {
+            get: getSetOptions.get,
+            set: getSetOptions.set
+        }, onInvalidated);
+    }
+    else {
+        return new IdentifierReferenceType(subType, onInvalidated);
+    }
+}
+/**
+ * Returns if a given value represents a reference type.
+ *
+ * @param type
+ * @returns
+ */
+export function isReferenceType(type) {
+    return (type.flags & TypeFlags.Reference) > 0;
+}
+/**
+ * `types.safeReference` - A safe reference is like a standard reference, except that it accepts the undefined value by default
+ * and automatically sets itself to undefined (when the parent is a model) / removes itself from arrays and maps
+ * when the reference it is pointing to gets detached/destroyed.
+ *
+ * The optional options parameter object accepts a parameter named `acceptsUndefined`, which is set to true by default, so it is suitable
+ * for model properties.
+ * When used inside collections (arrays/maps), it is recommended to set this option to false so it can't take undefined as value,
+ * which is usually the desired in those cases.
+ * Additionally, the optional options parameter object accepts a parameter named `onInvalidated`, which will be called when the reference target node that the reference is pointing to is about to be detached/destroyed
+ *
+ * Strictly speaking it is a `types.maybe(types.reference(X))` (when `acceptsUndefined` is set to true, the default) and
+ * `types.reference(X)` (when `acceptsUndefined` is set to false), both of them with a customized `onInvalidated` option.
+ *
+ * @param subType
+ * @param options
+ * @returns
+ */
+export function safeReference(subType, options) {
+    const refType = reference(subType, {
+        ...options,
+        onInvalidated(ev) {
+            if (options && options.onInvalidated) {
+                options.onInvalidated(ev);
+            }
+            ev.removeRef();
+        }
+    });
+    if (options && options.acceptsUndefined === false) {
+        return refType;
+    }
+    else {
+        return maybe(refType);
+    }
+}
+//# sourceMappingURL=reference.js.map

package/esm/types/utility-types/reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.js","sourceRoot":"","sources":["../../../src/types/utility-types/reference.ts"],"names":[],"mappings":"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","sourcesContent":["import { SimpleType } from \"../../core/type/type.ts\"\nimport {\n  type AnyNode,\n  type AnyObjectNode,\n  Hook,\n  type IAnyComplexType,\n  type IAnyStateTreeNode,\n  type IAnyType,\n  type IDisposer,\n  type IMaybe,\n  type IStateTreeNode,\n  type IType,\n  type IValidationContext,\n  type IValidationResult,\n  NodeLifeCycle,\n  type ReferenceIdentifier,\n  TypeFlags,\n  applyPatch,\n  assertIsType,\n  createScalarNode,\n  devMode,\n  fail,\n  getIdentifier,\n  getStateTreeNode,\n  isModelType,\n  isStateTreeNode,\n  isValidIdentifier,\n  maybe,\n  normalizeIdentifier,\n  typeCheckFailure,\n  typeCheckSuccess\n} from \"../../internal.ts\"\n\nexport type OnReferenceInvalidatedEvent<STN extends IAnyStateTreeNode> = {\n  parent: IAnyStateTreeNode\n  invalidTarget: STN | undefined\n  invalidId: ReferenceIdentifier\n  replaceRef: (newRef: STN | null | undefined) => void\n  removeRef: () => void\n  cause: \"detach\" | \"destroy\" | \"invalidSnapshotReference\"\n}\n\nexport type OnReferenceInvalidated<STN extends IAnyStateTreeNode> = (\n  event: OnReferenceInvalidatedEvent<STN>\n) => void\n\nfunction getInvalidationCause(hook: Hook): \"detach\" | \"destroy\" | undefined {\n  switch (hook) {\n    case Hook.beforeDestroy:\n      return \"destroy\"\n    case Hook.beforeDetach:\n      return \"detach\"\n    default:\n      return undefined\n  }\n}\n\n/** @hidden */\nexport type ReferenceT<IT extends IAnyType> = IT[\"TypeWithoutSTN\"] &\n  IStateTreeNode<IReferenceType<IT>>\n\nclass StoredReference<IT extends IAnyType> {\n  readonly identifier!: ReferenceIdentifier\n  node!: AnyNode\n\n  private resolvedReference?: {\n    node: AnyObjectNode\n    lastCacheModification: string\n  }\n\n  constructor(\n    value: ReferenceT<IT> | ReferenceIdentifier,\n    private readonly targetType: IT\n  ) {\n    if (isValidIdentifier(value)) {\n      this.identifier = value\n    } else if (isStateTreeNode(value)) {\n      const targetNode = getStateTreeNode(value)\n      if (!targetNode.identifierAttribute) {\n        throw fail(\n          `Can only store references with a defined identifier attribute.`\n        )\n      }\n      const id = targetNode.unnormalizedIdentifier\n      if (id === null || id === undefined) {\n        throw fail(\n          `Can only store references to tree nodes with a defined identifier.`\n        )\n      }\n      this.identifier = id\n    } else {\n      throw fail(\n        `Can only store references to tree nodes or identifiers, got: '${value}'`\n      )\n    }\n  }\n\n  private updateResolvedReference(node: AnyNode) {\n    const normalizedId = normalizeIdentifier(this.identifier)\n    const root = node.root\n    const lastCacheModification =\n      root.identifierCache!.getLastCacheModificationPerId(normalizedId)\n    if (\n      !this.resolvedReference ||\n      this.resolvedReference.lastCacheModification !== lastCacheModification\n    ) {\n      const { targetType } = this\n      // reference was initialized with the identifier of the target\n\n      const target = root.identifierCache!.resolve(targetType, normalizedId)\n\n      if (!target) {\n        throw new InvalidReferenceError(\n          `[mobx-state-tree] Failed to resolve reference '${this.identifier}' to type '${this.targetType.name}' (from node: ${node.path})`\n        )\n      }\n\n      this.resolvedReference = {\n        node: target!,\n        lastCacheModification: lastCacheModification\n      }\n    }\n  }\n\n  get resolvedValue(): ReferenceT<IT> {\n    this.updateResolvedReference(this.node)\n    return this.resolvedReference!.node.value\n  }\n}\n\n/**\n * @internal\n * @hidden\n */\nexport class InvalidReferenceError extends Error {\n  constructor(m: string) {\n    super(m)\n\n    Object.setPrototypeOf(this, InvalidReferenceError.prototype)\n  }\n}\n\n/**\n * @internal\n * @hidden\n */\nexport abstract class BaseReferenceType<\n  IT extends IAnyComplexType\n> extends SimpleType<\n  ReferenceIdentifier,\n  ReferenceIdentifier,\n  IT[\"TypeWithoutSTN\"]\n> {\n  readonly flags = TypeFlags.Reference\n\n  constructor(\n    protected readonly targetType: IT,\n    private readonly onInvalidated?: OnReferenceInvalidated<ReferenceT<IT>>\n  ) {\n    super(`reference(${targetType.name})`)\n  }\n\n  describe() {\n    return this.name\n  }\n\n  isAssignableFrom(type: IAnyType): boolean {\n    return this.targetType.isAssignableFrom(type)\n  }\n\n  isValidSnapshot(\n    value: this[\"C\"],\n    context: IValidationContext\n  ): IValidationResult {\n    return isValidIdentifier(value)\n      ? typeCheckSuccess()\n      : typeCheckFailure(\n          context,\n          value,\n          \"Value is not a valid identifier, which is a string or a number\"\n        )\n  }\n\n  private fireInvalidated(\n    cause: \"detach\" | \"destroy\" | \"invalidSnapshotReference\",\n    storedRefNode: this[\"N\"],\n    referenceId: ReferenceIdentifier,\n    refTargetNode: AnyObjectNode | null\n  ) {\n    // to actually invalidate a reference we need an alive parent,\n    // since it is a scalar value (immutable-ish) and we need to change it\n    // from the parent\n    const storedRefParentNode = storedRefNode.parent\n    if (!storedRefParentNode || !storedRefParentNode.isAlive) {\n      return\n    }\n    const storedRefParentValue = storedRefParentNode.storedValue\n    if (!storedRefParentValue) {\n      return\n    }\n    this.onInvalidated!({\n      cause,\n      parent: storedRefParentValue,\n      invalidTarget: refTargetNode ? refTargetNode.storedValue : undefined,\n      invalidId: referenceId,\n      replaceRef(newRef) {\n        applyPatch(storedRefNode.root.storedValue, {\n          op: \"replace\",\n          value: newRef,\n          path: storedRefNode.path\n        })\n      },\n      removeRef() {\n        if (isModelType(storedRefParentNode.type)) {\n          this.replaceRef(undefined as any)\n        } else {\n          applyPatch(storedRefNode.root.storedValue, {\n            op: \"remove\",\n            path: storedRefNode.path\n          })\n        }\n      }\n    })\n  }\n\n  private addTargetNodeWatcher(\n    storedRefNode: this[\"N\"],\n    referenceId: ReferenceIdentifier\n  ): IDisposer | undefined {\n    // this will make sure the target node becomes created\n    const refTargetValue = this.getValue(storedRefNode)\n    if (!refTargetValue) {\n      return undefined\n    }\n    const refTargetNode = getStateTreeNode(refTargetValue)\n\n    const hookHandler = (_: AnyNode, refTargetNodeHook: Hook) => {\n      const cause = getInvalidationCause(refTargetNodeHook)\n      if (!cause) {\n        return\n      }\n      this.fireInvalidated(cause, storedRefNode, referenceId, refTargetNode)\n    }\n\n    const refTargetDetachHookDisposer = refTargetNode.registerHook(\n      Hook.beforeDetach,\n      hookHandler\n    )\n    const refTargetDestroyHookDisposer = refTargetNode.registerHook(\n      Hook.beforeDestroy,\n      hookHandler\n    )\n\n    return () => {\n      refTargetDetachHookDisposer()\n      refTargetDestroyHookDisposer()\n    }\n  }\n\n  protected watchTargetNodeForInvalidations(\n    storedRefNode: this[\"N\"],\n    identifier: ReferenceIdentifier,\n    customGetSet: ReferenceOptionsGetSet<IT> | undefined\n  ) {\n    if (!this.onInvalidated) {\n      return\n    }\n\n    let onRefTargetDestroyedHookDisposer: IDisposer | undefined\n\n    // get rid of the watcher hook when the stored ref node is destroyed\n    // detached is ignored since scalar nodes (where the reference resides) cannot be detached\n    storedRefNode.registerHook(Hook.beforeDestroy, () => {\n      if (onRefTargetDestroyedHookDisposer) {\n        onRefTargetDestroyedHookDisposer()\n      }\n    })\n\n    const startWatching = (sync: boolean) => {\n      // re-create hook in case the stored ref gets reattached\n      if (onRefTargetDestroyedHookDisposer) {\n        onRefTargetDestroyedHookDisposer()\n      }\n\n      // make sure the target node is actually there and initialized\n      const storedRefParentNode = storedRefNode.parent\n      const storedRefParentValue =\n        storedRefParentNode && storedRefParentNode.storedValue\n      if (\n        storedRefParentNode &&\n        storedRefParentNode.isAlive &&\n        storedRefParentValue\n      ) {\n        let refTargetNodeExists: boolean\n        if (customGetSet) {\n          refTargetNodeExists = !!customGetSet.get(\n            identifier,\n            storedRefParentValue\n          )\n        } else {\n          refTargetNodeExists = storedRefNode.root.identifierCache!.has(\n            this.targetType,\n            normalizeIdentifier(identifier)\n          )\n        }\n\n        if (!refTargetNodeExists) {\n          // we cannot change the reference in sync mode\n          // since we are in the middle of a reconciliation/instantiation and the change would be overwritten\n          // for those cases just let the wrong reference be assigned and fail upon usage\n          // (like current references do)\n          // this means that effectively this code will only run when it is created from a snapshot\n          if (!sync) {\n            this.fireInvalidated(\n              \"invalidSnapshotReference\",\n              storedRefNode,\n              identifier,\n              null\n            )\n          }\n        } else {\n          onRefTargetDestroyedHookDisposer = this.addTargetNodeWatcher(\n            storedRefNode,\n            identifier\n          )\n        }\n      }\n    }\n\n    if (storedRefNode.state === NodeLifeCycle.FINALIZED) {\n      // already attached, so the whole tree is ready\n      startWatching(true)\n    } else {\n      if (!storedRefNode.isRoot) {\n        // start watching once the whole tree is ready\n        storedRefNode.root.registerHook(Hook.afterCreationFinalization, () => {\n          // make sure to attach it so it can start listening\n          if (storedRefNode.parent) {\n            storedRefNode.parent.createObservableInstanceIfNeeded()\n          }\n        })\n      }\n      // start watching once the node is attached somewhere / parent changes\n      storedRefNode.registerHook(Hook.afterAttach, () => {\n        startWatching(false)\n      })\n    }\n  }\n}\n\n/**\n * @internal\n * @hidden\n */\nexport class IdentifierReferenceType<\n  IT extends IAnyComplexType\n> extends BaseReferenceType<IT> {\n  constructor(\n    targetType: IT,\n    onInvalidated?: OnReferenceInvalidated<ReferenceT<IT>>\n  ) {\n    super(targetType, onInvalidated)\n  }\n\n  getValue(storedRefNode: this[\"N\"]) {\n    if (!storedRefNode.isAlive) {\n      return undefined\n    }\n    const storedRef: StoredReference<IT> = storedRefNode.storedValue\n    return storedRef.resolvedValue as any\n  }\n\n  getSnapshot(storedRefNode: this[\"N\"]) {\n    const ref: StoredReference<IT> = storedRefNode.storedValue\n    return ref.identifier\n  }\n\n  instantiate(\n    parent: AnyObjectNode | null,\n    subpath: string,\n    environment: any,\n    initialValue: this[\"C\"] | this[\"T\"]\n  ): this[\"N\"] {\n    const identifier = isStateTreeNode(initialValue)\n      ? getIdentifier(initialValue)!\n      : initialValue\n    const storedRef = new StoredReference(initialValue, this.targetType as any)\n    const storedRefNode: this[\"N\"] = createScalarNode(\n      this,\n      parent,\n      subpath,\n      environment,\n      storedRef as any\n    )\n    storedRef.node = storedRefNode\n    this.watchTargetNodeForInvalidations(\n      storedRefNode,\n      identifier as string,\n      undefined\n    )\n    return storedRefNode\n  }\n\n  reconcile(\n    current: this[\"N\"],\n    newValue: this[\"C\"] | this[\"T\"],\n    parent: AnyObjectNode,\n    subpath: string\n  ): this[\"N\"] {\n    if (!current.isDetaching && current.type === this) {\n      const compareByValue = isStateTreeNode(newValue)\n      const ref: StoredReference<IT> = current.storedValue\n      if (\n        (!compareByValue && ref.identifier === newValue) ||\n        (compareByValue && ref.resolvedValue === newValue)\n      ) {\n        current.setParent(parent, subpath)\n        return current\n      }\n    }\n    const newNode = this.instantiate(parent, subpath, undefined, newValue)\n    current.die() // noop if detaching\n    return newNode\n  }\n}\n\n/**\n * @internal\n * @hidden\n */\nexport class CustomReferenceType<\n  IT extends IAnyComplexType\n> extends BaseReferenceType<IT> {\n  constructor(\n    targetType: IT,\n    private readonly options: ReferenceOptionsGetSet<IT>,\n    onInvalidated?: OnReferenceInvalidated<ReferenceT<IT>>\n  ) {\n    super(targetType, onInvalidated)\n  }\n\n  getValue(storedRefNode: this[\"N\"]) {\n    if (!storedRefNode.isAlive) {\n      return undefined as any\n    }\n    const referencedNode = this.options.get(\n      storedRefNode.storedValue,\n      storedRefNode.parent ? storedRefNode.parent.storedValue : null\n    )\n    return referencedNode\n  }\n\n  getSnapshot(storedRefNode: this[\"N\"]) {\n    return storedRefNode.storedValue\n  }\n\n  instantiate(\n    parent: AnyObjectNode | null,\n    subpath: string,\n    environment: any,\n    newValue: this[\"C\"] | this[\"T\"]\n  ): this[\"N\"] {\n    const identifier = isStateTreeNode(newValue)\n      ? this.options.set(newValue as any, parent ? parent.storedValue : null)\n      : newValue\n    const storedRefNode: this[\"N\"] = createScalarNode(\n      this,\n      parent,\n      subpath,\n      environment,\n      identifier as any\n    )\n    this.watchTargetNodeForInvalidations(\n      storedRefNode,\n      identifier as string,\n      this.options\n    )\n    return storedRefNode\n  }\n\n  reconcile(\n    current: this[\"N\"],\n    newValue: this[\"C\"] | this[\"T\"],\n    parent: AnyObjectNode,\n    subpath: string\n  ): this[\"N\"] {\n    const newIdentifier = isStateTreeNode(newValue)\n      ? this.options.set(newValue as any, current ? current.storedValue : null)\n      : newValue\n    if (\n      !current.isDetaching &&\n      current.type === this &&\n      current.storedValue === newIdentifier\n    ) {\n      current.setParent(parent, subpath)\n      return current\n    }\n    const newNode = this.instantiate(parent, subpath, undefined, newIdentifier)\n    current.die() // noop if detaching\n    return newNode\n  }\n}\n\nexport interface ReferenceOptionsGetSet<IT extends IAnyComplexType> {\n  get(\n    identifier: ReferenceIdentifier,\n    parent: IAnyStateTreeNode | null\n  ): ReferenceT<IT>\n  set(\n    value: ReferenceT<IT>,\n    parent: IAnyStateTreeNode | null\n  ): ReferenceIdentifier\n}\n\nexport interface ReferenceOptionsOnInvalidated<IT extends IAnyComplexType> {\n  // called when the current reference is about to become invalid\n  onInvalidated: OnReferenceInvalidated<ReferenceT<IT>>\n}\n\nexport type ReferenceOptions<IT extends IAnyComplexType> =\n  | ReferenceOptionsGetSet<IT>\n  | ReferenceOptionsOnInvalidated<IT>\n  | (ReferenceOptionsGetSet<IT> & ReferenceOptionsOnInvalidated<IT>)\n\n/** @hidden */\nexport interface IReferenceType<IT extends IAnyComplexType> extends IType<\n  ReferenceIdentifier,\n  ReferenceIdentifier,\n  IT[\"TypeWithoutSTN\"]\n> {}\n\n/**\n * `types.reference` - Creates a reference to another type, which should have defined an identifier.\n * See also the [reference and identifiers](https://github.com/mobxjs/mobx-state-tree#references-and-identifiers) section.\n */\nexport function reference<IT extends IAnyComplexType>(\n  subType: IT,\n  options?: ReferenceOptions<IT>\n): IReferenceType<IT> {\n  assertIsType(subType, 1)\n  if (devMode()) {\n    if (options && typeof options === \"string\") {\n      // istanbul ignore next\n      throw fail(\n        \"References with base path are no longer supported. Please remove the base path.\"\n      )\n    }\n  }\n\n  const getSetOptions = options\n    ? (options as ReferenceOptionsGetSet<IT>)\n    : undefined\n  const onInvalidated = options\n    ? (options as ReferenceOptionsOnInvalidated<IT>).onInvalidated\n    : undefined\n\n  if (getSetOptions && (getSetOptions.get || getSetOptions.set)) {\n    if (devMode()) {\n      if (!getSetOptions.get || !getSetOptions.set) {\n        throw fail(\n          \"reference options must either contain both a 'get' and a 'set' method or none of them\"\n        )\n      }\n    }\n\n    return new CustomReferenceType(\n      subType,\n      {\n        get: getSetOptions.get,\n        set: getSetOptions.set\n      },\n      onInvalidated\n    )\n  } else {\n    return new IdentifierReferenceType(subType, onInvalidated)\n  }\n}\n\n/**\n * Returns if a given value represents a reference type.\n *\n * @param type\n * @returns\n */\nexport function isReferenceType<IT extends IReferenceType<any>>(\n  type: IT\n): type is IT {\n  return (type.flags & TypeFlags.Reference) > 0\n}\n\nexport function safeReference<IT extends IAnyComplexType>(\n  subType: IT,\n  options: (ReferenceOptionsGetSet<IT> | object) & {\n    acceptsUndefined: false\n    onInvalidated?: OnReferenceInvalidated<ReferenceT<IT>>\n  }\n): IReferenceType<IT>\nexport function safeReference<IT extends IAnyComplexType>(\n  subType: IT,\n  options?: (ReferenceOptionsGetSet<IT> | object) & {\n    acceptsUndefined?: boolean\n    onInvalidated?: OnReferenceInvalidated<ReferenceT<IT>>\n  }\n): IMaybe<IReferenceType<IT>>\n/**\n * `types.safeReference` - A safe reference is like a standard reference, except that it accepts the undefined value by default\n * and automatically sets itself to undefined (when the parent is a model) / removes itself from arrays and maps\n * when the reference it is pointing to gets detached/destroyed.\n *\n * The optional options parameter object accepts a parameter named `acceptsUndefined`, which is set to true by default, so it is suitable\n * for model properties.\n * When used inside collections (arrays/maps), it is recommended to set this option to false so it can't take undefined as value,\n * which is usually the desired in those cases.\n * Additionally, the optional options parameter object accepts a parameter named `onInvalidated`, which will be called when the reference target node that the reference is pointing to is about to be detached/destroyed\n *\n * Strictly speaking it is a `types.maybe(types.reference(X))` (when `acceptsUndefined` is set to true, the default) and\n * `types.reference(X)` (when `acceptsUndefined` is set to false), both of them with a customized `onInvalidated` option.\n *\n * @param subType\n * @param options\n * @returns\n */\nexport function safeReference<IT extends IAnyComplexType>(\n  subType: IT,\n  options?: (ReferenceOptionsGetSet<IT> | object) & {\n    acceptsUndefined?: boolean\n    onInvalidated?: OnReferenceInvalidated<ReferenceT<IT>>\n  }\n): IReferenceType<IT> | IMaybe<IReferenceType<IT>> {\n  const refType = reference(subType, {\n    ...options,\n    onInvalidated(ev) {\n      if (options && options.onInvalidated) {\n        options.onInvalidated(ev)\n      }\n      ev.removeRef()\n    }\n  })\n\n  if (options && options.acceptsUndefined === false) {\n    return refType\n  } else {\n    return maybe(refType)\n  }\n}\n"]}

package/esm/types/utility-types/refinement.d.ts

@@ -0,0 +1,10 @@
+import { type IAnyType } from "../../internal.ts";
+export declare function refinement<IT extends IAnyType>(name: string, type: IT, predicate: (snapshot: IT["CreationType"]) => boolean, message?: string | ((v: IT["CreationType"]) => string)): IT;
+export declare function refinement<IT extends IAnyType>(type: IT, predicate: (snapshot: IT["CreationType"]) => boolean, message?: string | ((v: IT["CreationType"]) => string)): IT;
+/**
+ * Returns if a given value is a refinement type.
+ *
+ * @param type
+ * @returns
+ */
+export declare function isRefinementType<IT extends IAnyType>(type: IT): type is IT;

package/esm/types/utility-types/refinement.js

@@ -0,0 +1,82 @@
+import { BaseType } from "../../core/type/type.js";
+import { TypeFlags, assertIsType, getStateTreeNode, isStateTreeNode, isType, typeCheckFailure, typeCheckSuccess } from "../../internal.js";
+import { assertIsFunction, assertIsString } from "../../utils.js";
+class Refinement extends BaseType {
+    _subtype;
+    _predicate;
+    _message;
+    get flags() {
+        return this._subtype.flags | TypeFlags.Refinement;
+    }
+    constructor(name, _subtype, _predicate, _message) {
+        super(name);
+        this._subtype = _subtype;
+        this._predicate = _predicate;
+        this._message = _message;
+    }
+    describe() {
+        return this.name;
+    }
+    instantiate(parent, subpath, environment, initialValue) {
+        // create the child type
+        return this._subtype.instantiate(parent, subpath, environment, initialValue);
+    }
+    isAssignableFrom(type) {
+        return this._subtype.isAssignableFrom(type);
+    }
+    isValidSnapshot(value, context) {
+        const subtypeErrors = this._subtype.validate(value, context);
+        if (subtypeErrors.length > 0) {
+            return subtypeErrors;
+        }
+        const snapshot = isStateTreeNode(value)
+            ? getStateTreeNode(value).snapshot
+            : value;
+        if (!this._predicate(snapshot)) {
+            return typeCheckFailure(context, value, this._message(value));
+        }
+        return typeCheckSuccess();
+    }
+    reconcile(current, newValue, parent, subpath) {
+        return this._subtype.reconcile(current, newValue, parent, subpath);
+    }
+    getSubTypes() {
+        return this._subtype;
+    }
+}
+/**
+ * `types.refinement` - Creates a type that is more specific than the base type, e.g. `types.refinement(types.string, value => value.length > 5)` to create a type of strings that can only be longer then 5.
+ *
+ * @param name
+ * @param type
+ * @param predicate
+ * @returns
+ */
+export function refinement(...args) {
+    const name = typeof args[0] === "string"
+        ? args.shift()
+        : isType(args[0])
+            ? args[0].name
+            : null;
+    const type = args[0];
+    const predicate = args[1];
+    const message = args[2]
+        ? args[2]
+        : (_v) => "Value does not respect the refinement predicate";
+    // ensures all parameters are correct
+    assertIsType(type, [1, 2]);
+    assertIsString(name, 1);
+    assertIsFunction(predicate, [2, 3]);
+    assertIsFunction(message, [3, 4]);
+    return new Refinement(name, type, predicate, message);
+}
+/**
+ * Returns if a given value is a refinement type.
+ *
+ * @param type
+ * @returns
+ */
+export function isRefinementType(type) {
+    return (type.flags & TypeFlags.Refinement) > 0;
+}
+//# sourceMappingURL=refinement.js.map

package/esm/types/utility-types/refinement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refinement.js","sourceRoot":"","sources":["../../../src/types/utility-types/refinement.ts"],"names":[],"mappings":"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","sourcesContent":["import { BaseType } from \"../../core/type/type.ts\"\nimport {\n  type AnyObjectNode,\n  type ExtractNodeType,\n  type IAnyType,\n  type IValidationContext,\n  type IValidationResult,\n  TypeFlags,\n  assertIsType,\n  getStateTreeNode,\n  isStateTreeNode,\n  isType,\n  typeCheckFailure,\n  typeCheckSuccess\n} from \"../../internal.ts\"\nimport { assertIsFunction, assertIsString } from \"../../utils.ts\"\n\nclass Refinement<IT extends IAnyType> extends BaseType<\n  IT[\"CreationType\"],\n  IT[\"SnapshotType\"],\n  IT[\"TypeWithoutSTN\"],\n  ExtractNodeType<IT>\n> {\n  get flags() {\n    return this._subtype.flags | TypeFlags.Refinement\n  }\n\n  constructor(\n    name: string,\n    private readonly _subtype: IT,\n    private readonly _predicate: (v: IT[\"CreationType\"]) => boolean,\n    private readonly _message: (v: IT[\"CreationType\"]) => string\n  ) {\n    super(name)\n  }\n\n  describe() {\n    return this.name\n  }\n\n  instantiate(\n    parent: AnyObjectNode | null,\n    subpath: string,\n    environment: any,\n    initialValue: this[\"C\"] | this[\"T\"]\n  ): this[\"N\"] {\n    // create the child type\n    return this._subtype.instantiate(\n      parent,\n      subpath,\n      environment,\n      initialValue\n    ) as any\n  }\n\n  isAssignableFrom(type: IAnyType) {\n    return this._subtype.isAssignableFrom(type)\n  }\n\n  isValidSnapshot(\n    value: this[\"C\"],\n    context: IValidationContext\n  ): IValidationResult {\n    const subtypeErrors = this._subtype.validate(value, context)\n    if (subtypeErrors.length > 0) {\n      return subtypeErrors\n    }\n\n    const snapshot = isStateTreeNode(value)\n      ? getStateTreeNode(value).snapshot\n      : value\n\n    if (!this._predicate(snapshot)) {\n      return typeCheckFailure(context, value, this._message(value))\n    }\n\n    return typeCheckSuccess()\n  }\n\n  reconcile(\n    current: this[\"N\"],\n    newValue: this[\"C\"] | this[\"T\"],\n    parent: AnyObjectNode,\n    subpath: string\n  ): this[\"N\"] {\n    return this._subtype.reconcile(current, newValue, parent, subpath) as any\n  }\n\n  getSubTypes() {\n    return this._subtype\n  }\n}\n\nexport function refinement<IT extends IAnyType>(\n  name: string,\n  type: IT,\n  predicate: (snapshot: IT[\"CreationType\"]) => boolean,\n  message?: string | ((v: IT[\"CreationType\"]) => string)\n): IT\nexport function refinement<IT extends IAnyType>(\n  type: IT,\n  predicate: (snapshot: IT[\"CreationType\"]) => boolean,\n  message?: string | ((v: IT[\"CreationType\"]) => string)\n): IT\n\n/**\n * `types.refinement` - Creates a type that is more specific than the base type, e.g. `types.refinement(types.string, value => value.length > 5)` to create a type of strings that can only be longer then 5.\n *\n * @param name\n * @param type\n * @param predicate\n * @returns\n */\nexport function refinement(...args: any[]): IAnyType {\n  const name =\n    typeof args[0] === \"string\"\n      ? args.shift()\n      : isType(args[0])\n        ? args[0].name\n        : null\n  const type = args[0]\n  const predicate = args[1]\n  const message = args[2]\n    ? args[2]\n    : (_v: any) => \"Value does not respect the refinement predicate\"\n  // ensures all parameters are correct\n  assertIsType(type, [1, 2])\n  assertIsString(name, 1)\n  assertIsFunction(predicate, [2, 3])\n  assertIsFunction(message, [3, 4])\n\n  return new Refinement(name, type, predicate, message)\n}\n\n/**\n * Returns if a given value is a refinement type.\n *\n * @param type\n * @returns\n */\nexport function isRefinementType<IT extends IAnyType>(type: IT): type is IT {\n  return (type.flags & TypeFlags.Refinement) > 0\n}\n"]}

package/esm/types/utility-types/resilient.d.ts

@@ -0,0 +1,18 @@
+import { type IAnyType, type IType } from "../../internal.ts";
+export interface IResilientType<IT extends IAnyType, FT extends IAnyType> extends IType<IT["CreationType"] | FT["CreationType"], IT["SnapshotType"] | FT["SnapshotType"], IT["TypeWithoutSTN"] | FT["TypeWithoutSTN"]> {
+}
+/**
+ * `types.resilient` - Wraps a type so that instantiation errors are caught
+ * and a fallback type is used instead. This is useful for loading data that
+ * may contain unknown or invalid subtrees (e.g., plugin types that are not
+ * installed) without crashing the entire state tree.
+ *
+ * The `createFallbackSnapshot` callback receives the caught error and the
+ * original snapshot, and must return a valid snapshot for the fallback type.
+ *
+ * @param type The type to wrap.
+ * @param fallbackType The fallback type to use when instantiation fails.
+ * @param createFallbackSnapshot Callback that produces a fallback snapshot from the error and original snapshot.
+ * @returns A resilient type.
+ */
+export declare function resilient<IT extends IAnyType, FT extends IAnyType>(type: IT, fallbackType: FT, createFallbackSnapshot: (error: unknown, snapshot: any) => FT["CreationType"]): IResilientType<IT, FT>;