@jbrowse/mobx-state-tree 5.6.10 → 5.7.1

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

@@ -0,0 +1,58 @@
+import { SimpleType } from "../../core/type/type.js";
+import { TypeFlags, createScalarNode, isPrimitive, isType, typeCheckFailure, typeCheckSuccess } from "../../internal.js";
+import { assertArg } from "../../utils.js";
+/**
+ * @internal
+ * @hidden
+ */
+export class Literal extends SimpleType {
+    value;
+    flags = TypeFlags.Literal;
+    constructor(value) {
+        super(JSON.stringify(value));
+        this.value = value;
+    }
+    instantiate(parent, subpath, environment, initialValue) {
+        return createScalarNode(this, parent, subpath, environment, initialValue);
+    }
+    describe() {
+        return JSON.stringify(this.value);
+    }
+    isValidSnapshot(value, context) {
+        if (isPrimitive(value) && value === this.value) {
+            return typeCheckSuccess();
+        }
+        return typeCheckFailure(context, value, `Value is not a literal ${JSON.stringify(this.value)}`);
+    }
+}
+/**
+ * `types.literal` - The literal type will return a type that will match only the exact given type.
+ * The given value must be a primitive, in order to be serialized to a snapshot correctly.
+ * You can use literal to match exact strings for example the exact male or female string.
+ *
+ * Example:
+ * ```ts
+ * const Person = types.model({
+ *     name: types.string,
+ *     gender: types.union(types.literal('male'), types.literal('female'))
+ * })
+ * ```
+ *
+ * @param value The value to use in the strict equal check
+ * @returns
+ */
+export function literal(value) {
+    // check that the given value is a primitive
+    assertArg(value, isPrimitive, "primitive", 1);
+    return new Literal(value);
+}
+/**
+ * Returns if a given value represents a literal type.
+ *
+ * @param type
+ * @returns
+ */
+export function isLiteralType(type) {
+    return isType(type) && (type.flags & TypeFlags.Literal) > 0;
+}
+//# sourceMappingURL=literal.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"literal.js","sourceRoot":"","sources":["../../../src/types/utility-types/literal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACpD,OAAO,EAML,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,MAAM,EACN,gBAAgB,EAChB,gBAAgB,EACjB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C;;;GAGG;AACH,MAAM,OAAO,OAAW,SAAQ,UAAmB;IACxC,KAAK,CAAG;IACR,KAAK,GAAG,SAAS,CAAC,OAAO,CAAA;IAElC,YAAY,KAAQ;QAClB,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAA;QAC5B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;IAED,WAAW,CACT,MAA4B,EAC5B,OAAe,EACf,WAAgB,EAChB,YAAuB;QAEvB,OAAO,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,CAAC,CAAA;IAC3E,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACnC,CAAC;IAED,eAAe,CACb,KAAgB,EAChB,OAA2B;QAE3B,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YAC/C,OAAO,gBAAgB,EAAE,CAAA;QAC3B,CAAC;QACD,OAAO,gBAAgB,CACrB,OAAO,EACP,KAAK,EACL,0BAA0B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CACvD,CAAA;IACH,CAAC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,OAAO,CAAuB,KAAQ;IACpD,4CAA4C;IAC5C,SAAS,CAAC,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,CAAC,CAAA;IAE7C,OAAO,IAAI,OAAO,CAAI,KAAK,CAAC,CAAA;AAC9B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAQ;IAER,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;AAC7D,CAAC","sourcesContent":["import { SimpleType } from \"../../core/type/type.ts\"\nimport {\n  type AnyObjectNode,\n  type ISimpleType,\n  type IValidationContext,\n  type IValidationResult,\n  type Primitives,\n  TypeFlags,\n  createScalarNode,\n  isPrimitive,\n  isType,\n  typeCheckFailure,\n  typeCheckSuccess\n} from \"../../internal.ts\"\nimport { assertArg } from \"../../utils.ts\"\n\n/**\n * @internal\n * @hidden\n */\nexport class Literal<T> extends SimpleType<T, T, T> {\n  readonly value: T\n  readonly flags = TypeFlags.Literal\n\n  constructor(value: T) {\n    super(JSON.stringify(value))\n    this.value = value\n  }\n\n  instantiate(\n    parent: AnyObjectNode | null,\n    subpath: string,\n    environment: any,\n    initialValue: this[\"C\"]\n  ): this[\"N\"] {\n    return createScalarNode(this, parent, subpath, environment, initialValue)\n  }\n\n  describe() {\n    return JSON.stringify(this.value)\n  }\n\n  isValidSnapshot(\n    value: this[\"C\"],\n    context: IValidationContext\n  ): IValidationResult {\n    if (isPrimitive(value) && value === this.value) {\n      return typeCheckSuccess()\n    }\n    return typeCheckFailure(\n      context,\n      value,\n      `Value is not a literal ${JSON.stringify(this.value)}`\n    )\n  }\n}\n\n/**\n * `types.literal` - The literal type will return a type that will match only the exact given type.\n * The given value must be a primitive, in order to be serialized to a snapshot correctly.\n * You can use literal to match exact strings for example the exact male or female string.\n *\n * Example:\n * ```ts\n * const Person = types.model({\n *     name: types.string,\n *     gender: types.union(types.literal('male'), types.literal('female'))\n * })\n * ```\n *\n * @param value The value to use in the strict equal check\n * @returns\n */\nexport function literal<S extends Primitives>(value: S): ISimpleType<S> {\n  // check that the given value is a primitive\n  assertArg(value, isPrimitive, \"primitive\", 1)\n\n  return new Literal<S>(value)\n}\n\n/**\n * Returns if a given value represents a literal type.\n *\n * @param type\n * @returns\n */\nexport function isLiteralType<IT extends ISimpleType<any>>(\n  type: IT\n): type is IT {\n  return isType(type) && (type.flags & TypeFlags.Literal) > 0\n}\n"]}

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

@@ -0,0 +1,26 @@
+import { type IAnyType, type IType } from "../../internal.ts";
+/** @hidden */
+export interface IMaybeIType<IT extends IAnyType, C, O> extends IType<IT["CreationType"] | C, IT["SnapshotType"] | O, IT["TypeWithoutSTN"] | O> {
+}
+/** @hidden */
+export interface IMaybe<IT extends IAnyType> extends IMaybeIType<IT, undefined, undefined> {
+}
+/** @hidden */
+export interface IMaybeNull<IT extends IAnyType> extends IMaybeIType<IT, null | undefined, null> {
+}
+/**
+ * `types.maybe` - Maybe will make a type nullable, and also optional.
+ * The value `undefined` will be used to represent nullability.
+ *
+ * @param type
+ * @returns
+ */
+export declare function maybe<IT extends IAnyType>(type: IT): IMaybe<IT>;
+/**
+ * `types.maybeNull` - Maybe will make a type nullable, and also optional.
+ * The value `null` will be used to represent no value.
+ *
+ * @param type
+ * @returns
+ */
+export declare function maybeNull<IT extends IAnyType>(type: IT): IMaybeNull<IT>;

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

@@ -0,0 +1,26 @@
+import { assertIsType, nullType, optional, undefinedType, union } from "../../internal.js";
+const optionalUndefinedType = optional(undefinedType, undefined);
+const optionalNullType = optional(nullType, null);
+/**
+ * `types.maybe` - Maybe will make a type nullable, and also optional.
+ * The value `undefined` will be used to represent nullability.
+ *
+ * @param type
+ * @returns
+ */
+export function maybe(type) {
+    assertIsType(type, 1);
+    return union(type, optionalUndefinedType);
+}
+/**
+ * `types.maybeNull` - Maybe will make a type nullable, and also optional.
+ * The value `null` will be used to represent no value.
+ *
+ * @param type
+ * @returns
+ */
+export function maybeNull(type) {
+    assertIsType(type, 1);
+    return union(type, optionalNullType);
+}
+//# sourceMappingURL=maybe.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"maybe.js","sourceRoot":"","sources":["../../../src/types/utility-types/maybe.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,YAAY,EACZ,QAAQ,EACR,QAAQ,EACR,aAAa,EACb,KAAK,EACN,MAAM,mBAAmB,CAAA;AAE1B,MAAM,qBAAqB,GAAG,QAAQ,CAAC,aAAa,EAAE,SAAS,CAAC,CAAA;AAChE,MAAM,gBAAgB,GAAG,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;AAuBjD;;;;;;GAMG;AACH,MAAM,UAAU,KAAK,CAAsB,IAAQ;IACjD,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,CAAA;IAErB,OAAO,KAAK,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAA;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAsB,IAAQ;IACrD,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,CAAA;IAErB,OAAO,KAAK,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAA;AACtC,CAAC","sourcesContent":["import {\n  type IAnyType,\n  type IType,\n  assertIsType,\n  nullType,\n  optional,\n  undefinedType,\n  union\n} from \"../../internal.ts\"\n\nconst optionalUndefinedType = optional(undefinedType, undefined)\nconst optionalNullType = optional(nullType, null)\n\n/** @hidden */\nexport interface IMaybeIType<IT extends IAnyType, C, O> extends IType<\n  IT[\"CreationType\"] | C,\n  IT[\"SnapshotType\"] | O,\n  IT[\"TypeWithoutSTN\"] | O\n> {}\n\n/** @hidden */\nexport interface IMaybe<IT extends IAnyType> extends IMaybeIType<\n  IT,\n  undefined,\n  undefined\n> {}\n\n/** @hidden */\nexport interface IMaybeNull<IT extends IAnyType> extends IMaybeIType<\n  IT,\n  null | undefined,\n  null\n> {}\n\n/**\n * `types.maybe` - Maybe will make a type nullable, and also optional.\n * The value `undefined` will be used to represent nullability.\n *\n * @param type\n * @returns\n */\nexport function maybe<IT extends IAnyType>(type: IT): IMaybe<IT> {\n  assertIsType(type, 1)\n\n  return union(type, optionalUndefinedType)\n}\n\n/**\n * `types.maybeNull` - Maybe will make a type nullable, and also optional.\n * The value `null` will be used to represent no value.\n *\n * @param type\n * @returns\n */\nexport function maybeNull<IT extends IAnyType>(type: IT): IMaybeNull<IT> {\n  assertIsType(type, 1)\n\n  return union(type, optionalNullType)\n}\n"]}

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

@@ -0,0 +1,42 @@
+import { BaseType } from "../../core/type/type.ts";
+import { type AnyObjectNode, type ExtractCSTWithSTN, type IAnyType, type IType, type IValidationContext, type IValidationResult } from "../../internal.ts";
+type IFunctionReturn<T> = () => T;
+type IOptionalValue<C, T> = C | IFunctionReturn<C | T>;
+/** @hidden */
+export type ValidOptionalValue = string | boolean | number | null | undefined;
+/** @hidden */
+export type ValidOptionalValues = [ValidOptionalValue, ...ValidOptionalValue[]];
+/**
+ * @hidden
+ * @internal
+ */
+export declare class OptionalValue<IT extends IAnyType, OptionalVals extends ValidOptionalValues> extends BaseType<IT["CreationType"] | OptionalVals[number], IT["SnapshotType"], IT["TypeWithoutSTN"]> {
+    private readonly _subtype;
+    private readonly _defaultValue;
+    readonly optionalValues: OptionalVals;
+    get flags(): number;
+    constructor(_subtype: IT, _defaultValue: IOptionalValue<IT["CreationType"], IT["Type"]>, optionalValues: OptionalVals);
+    describe(): string;
+    instantiate(parent: AnyObjectNode | null, subpath: string, environment: any, initialValue: this["C"] | this["T"]): this["N"];
+    reconcile(current: this["N"], newValue: this["C"] | this["T"], parent: AnyObjectNode, subpath: string): this["N"];
+    getDefaultInstanceOrSnapshot(): this["C"] | this["T"];
+    isValidSnapshot(value: this["C"], context: IValidationContext): IValidationResult;
+    isAssignableFrom(type: IAnyType): boolean;
+    getSubTypes(): IT;
+}
+/** @hidden */
+export type OptionalDefaultValueOrFunction<IT extends IAnyType> = IT["CreationType"] | IT["SnapshotType"] | (() => ExtractCSTWithSTN<IT>);
+/** @hidden */
+export interface IOptionalIType<IT extends IAnyType, OptionalVals extends ValidOptionalValues> extends IType<IT["CreationType"] | OptionalVals[number], IT["SnapshotType"], IT["TypeWithoutSTN"]> {
+}
+export declare function optional<IT extends IAnyType>(type: IT, defaultValueOrFunction: OptionalDefaultValueOrFunction<IT>): IOptionalIType<IT, [undefined]>;
+export declare function optional<IT extends IAnyType, OptionalVals extends ValidOptionalValues>(type: IT, defaultValueOrFunction: OptionalDefaultValueOrFunction<IT>, optionalValues: OptionalVals): IOptionalIType<IT, OptionalVals>;
+/**
+ * Returns if a value represents an optional type.
+ *
+ * @template IT
+ * @param type
+ * @returns
+ */
+export declare function isOptionalType<IT extends IAnyType>(type: IT): type is IT;
+export {};

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

@@ -0,0 +1,135 @@
+import { BaseType } from "../../core/type/type.js";
+import { TypeFlags, assertIsType, devMode, fail, isStateTreeNode, isType, typeCheckSuccess, typecheckInternal } from "../../internal.js";
+/**
+ * @hidden
+ * @internal
+ */
+export class OptionalValue extends BaseType {
+    _subtype;
+    _defaultValue;
+    optionalValues;
+    get flags() {
+        return this._subtype.flags | TypeFlags.Optional;
+    }
+    constructor(_subtype, _defaultValue, optionalValues) {
+        super(_subtype.name);
+        this._subtype = _subtype;
+        this._defaultValue = _defaultValue;
+        this.optionalValues = optionalValues;
+    }
+    describe() {
+        return this._subtype.describe() + "?";
+    }
+    instantiate(parent, subpath, environment, initialValue) {
+        if (this.optionalValues.indexOf(initialValue) >= 0) {
+            const defaultInstanceOrSnapshot = this.getDefaultInstanceOrSnapshot();
+            return this._subtype.instantiate(parent, subpath, environment, defaultInstanceOrSnapshot);
+        }
+        return this._subtype.instantiate(parent, subpath, environment, initialValue);
+    }
+    reconcile(current, newValue, parent, subpath) {
+        return this._subtype.reconcile(current, this.optionalValues.indexOf(newValue) < 0 && this._subtype.is(newValue)
+            ? newValue
+            : this.getDefaultInstanceOrSnapshot(), parent, subpath);
+    }
+    getDefaultInstanceOrSnapshot() {
+        const defaultInstanceOrSnapshot = typeof this._defaultValue === "function"
+            ? this._defaultValue()
+            : this._defaultValue;
+        // while static values are already snapshots and checked on types.optional
+        // generator functions must always be rechecked just in case
+        if (typeof this._defaultValue === "function") {
+            typecheckInternal(this, defaultInstanceOrSnapshot);
+        }
+        return defaultInstanceOrSnapshot;
+    }
+    isValidSnapshot(value, context) {
+        // defaulted values can be skipped
+        if (this.optionalValues.indexOf(value) >= 0) {
+            return typeCheckSuccess();
+        }
+        // bounce validation to the sub-type
+        return this._subtype.validate(value, context);
+    }
+    isAssignableFrom(type) {
+        return this._subtype.isAssignableFrom(type);
+    }
+    getSubTypes() {
+        return this._subtype;
+    }
+}
+function checkOptionalPreconditions(type, defaultValueOrFunction) {
+    // make sure we never pass direct instances
+    if (typeof defaultValueOrFunction !== "function" &&
+        isStateTreeNode(defaultValueOrFunction)) {
+        throw fail("default value cannot be an instance, pass a snapshot or a function that creates an instance/snapshot instead");
+    }
+    assertIsType(type, 1);
+    if (devMode()) {
+        // we only check default values if they are passed directly
+        // if they are generator functions they will be checked once they are generated
+        // we don't check generator function results here to avoid generating a node just for type-checking purposes
+        // which might generate side-effects
+        if (typeof defaultValueOrFunction !== "function") {
+            typecheckInternal(type, defaultValueOrFunction);
+        }
+    }
+}
+/**
+ * `types.optional` - Can be used to create a property with a default value.
+ *
+ * Depending on the third argument (`optionalValues`) there are two ways of operation:
+ * - If the argument is not provided, then if a value is not provided in the snapshot (`undefined` or missing),
+ *   it will default to the provided `defaultValue`
+ * - If the argument is provided, then if the value in the snapshot matches one of the optional values inside the array then it will
+ *   default to the provided `defaultValue`. Additionally, if one of the optional values inside the array is `undefined` then a missing
+ *   property is also valid.
+ *
+ *   Note that it is also possible to include values of the same type as the intended subtype as optional values,
+ *   in this case the optional value will be transformed into the `defaultValue` (e.g. `types.optional(types.string, "unnamed", [undefined, ""])`
+ *   will transform the snapshot values `undefined` (and therefore missing) and empty strings into the string `"unnamed"` when it gets
+ *   instantiated).
+ *
+ * If `defaultValue` is a function, the function will be invoked for every new instance.
+ * Applying a snapshot in which the optional value is one of the optional values (or `undefined`/_not_ present if none are provided) causes the
+ * value to be reset.
+ *
+ * Example:
+ * ```ts
+ * const Todo = types.model({
+ *   title: types.string,
+ *   subtitle1: types.optional(types.string, "", [null]),
+ *   subtitle2: types.optional(types.string, "", [null, undefined]),
+ *   done: types.optional(types.boolean, false),
+ *   created: types.optional(types.Date, () => new Date()),
+ * })
+ *
+ * // if done is missing / undefined it will become false
+ * // if created is missing / undefined it will get a freshly generated timestamp
+ * // if subtitle1 is null it will default to "", but it cannot be missing or undefined
+ * // if subtitle2 is null or undefined it will default to ""; since it can be undefined it can also be missing
+ * const todo = Todo.create({ title: "Get coffee", subtitle1: null })
+ * ```
+ *
+ * @param type
+ * @param defaultValueOrFunction
+ * @param optionalValues an optional array with zero or more primitive values (string, number, boolean, null or undefined)
+ *                       that will be converted into the default. `[ undefined ]` is assumed when none is provided
+ * @returns
+ */
+export function optional(type, defaultValueOrFunction, optionalValues) {
+    checkOptionalPreconditions(type, defaultValueOrFunction);
+    return new OptionalValue(type, defaultValueOrFunction, optionalValues ? optionalValues : undefinedAsOptionalValues);
+}
+const undefinedAsOptionalValues = [undefined];
+/**
+ * Returns if a value represents an optional type.
+ *
+ * @template IT
+ * @param type
+ * @returns
+ */
+export function isOptionalType(type) {
+    return isType(type) && (type.flags & TypeFlags.Optional) > 0;
+}
+//# sourceMappingURL=optional.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"optional.js","sourceRoot":"","sources":["../../../src/types/utility-types/optional.ts"],"names":[],"mappings":"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","sourcesContent":["import { BaseType } from \"../../core/type/type.ts\"\nimport {\n  type AnyObjectNode,\n  type ExtractCSTWithSTN,\n  type IAnyType,\n  type IType,\n  type IValidationContext,\n  type IValidationResult,\n  TypeFlags,\n  assertIsType,\n  devMode,\n  fail,\n  isStateTreeNode,\n  isType,\n  typeCheckSuccess,\n  typecheckInternal\n} from \"../../internal.ts\"\n\ntype IFunctionReturn<T> = () => T\n\ntype IOptionalValue<C, T> = C | IFunctionReturn<C | T>\n\n/** @hidden */\nexport type ValidOptionalValue = string | boolean | number | null | undefined\n\n/** @hidden */\nexport type ValidOptionalValues = [ValidOptionalValue, ...ValidOptionalValue[]]\n\n/**\n * @hidden\n * @internal\n */\nexport class OptionalValue<\n  IT extends IAnyType,\n  OptionalVals extends ValidOptionalValues\n> extends BaseType<\n  IT[\"CreationType\"] | OptionalVals[number],\n  IT[\"SnapshotType\"],\n  IT[\"TypeWithoutSTN\"]\n> {\n  get flags() {\n    return this._subtype.flags | TypeFlags.Optional\n  }\n\n  constructor(\n    private readonly _subtype: IT,\n    private readonly _defaultValue: IOptionalValue<\n      IT[\"CreationType\"],\n      IT[\"Type\"]\n    >,\n    readonly optionalValues: OptionalVals\n  ) {\n    super(_subtype.name)\n  }\n\n  describe() {\n    return this._subtype.describe() + \"?\"\n  }\n\n  instantiate(\n    parent: AnyObjectNode | null,\n    subpath: string,\n    environment: any,\n    initialValue: this[\"C\"] | this[\"T\"]\n  ): this[\"N\"] {\n    if (this.optionalValues.indexOf(initialValue) >= 0) {\n      const defaultInstanceOrSnapshot = this.getDefaultInstanceOrSnapshot()\n      return this._subtype.instantiate(\n        parent,\n        subpath,\n        environment,\n        defaultInstanceOrSnapshot\n      )\n    }\n    return this._subtype.instantiate(parent, subpath, environment, initialValue)\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(\n      current,\n      this.optionalValues.indexOf(newValue) < 0 && this._subtype.is(newValue)\n        ? newValue\n        : this.getDefaultInstanceOrSnapshot(),\n      parent,\n      subpath\n    )\n  }\n\n  getDefaultInstanceOrSnapshot(): this[\"C\"] | this[\"T\"] {\n    const defaultInstanceOrSnapshot =\n      typeof this._defaultValue === \"function\"\n        ? (this._defaultValue as IFunctionReturn<this[\"C\"] | this[\"T\"]>)()\n        : this._defaultValue\n\n    // while static values are already snapshots and checked on types.optional\n    // generator functions must always be rechecked just in case\n    if (typeof this._defaultValue === \"function\") {\n      typecheckInternal(this, defaultInstanceOrSnapshot)\n    }\n\n    return defaultInstanceOrSnapshot\n  }\n\n  isValidSnapshot(\n    value: this[\"C\"],\n    context: IValidationContext\n  ): IValidationResult {\n    // defaulted values can be skipped\n    if (this.optionalValues.indexOf(value) >= 0) {\n      return typeCheckSuccess()\n    }\n    // bounce validation to the sub-type\n    return this._subtype.validate(value, context)\n  }\n\n  isAssignableFrom(type: IAnyType) {\n    return this._subtype.isAssignableFrom(type)\n  }\n\n  getSubTypes() {\n    return this._subtype\n  }\n}\n\n/** @hidden */\nexport type OptionalDefaultValueOrFunction<IT extends IAnyType> =\n  | IT[\"CreationType\"]\n  | IT[\"SnapshotType\"]\n  | (() => ExtractCSTWithSTN<IT>)\n\n/** @hidden */\nexport interface IOptionalIType<\n  IT extends IAnyType,\n  OptionalVals extends ValidOptionalValues\n> extends IType<\n  IT[\"CreationType\"] | OptionalVals[number],\n  IT[\"SnapshotType\"],\n  IT[\"TypeWithoutSTN\"]\n> {}\n\nfunction checkOptionalPreconditions<IT extends IAnyType>(\n  type: IAnyType,\n  defaultValueOrFunction: OptionalDefaultValueOrFunction<IT>\n) {\n  // make sure we never pass direct instances\n  if (\n    typeof defaultValueOrFunction !== \"function\" &&\n    isStateTreeNode(defaultValueOrFunction)\n  ) {\n    throw fail(\n      \"default value cannot be an instance, pass a snapshot or a function that creates an instance/snapshot instead\"\n    )\n  }\n  assertIsType(type, 1)\n  if (devMode()) {\n    // we only check default values if they are passed directly\n    // if they are generator functions they will be checked once they are generated\n    // we don't check generator function results here to avoid generating a node just for type-checking purposes\n    // which might generate side-effects\n    if (typeof defaultValueOrFunction !== \"function\") {\n      typecheckInternal(type, defaultValueOrFunction)\n    }\n  }\n}\n\nexport function optional<IT extends IAnyType>(\n  type: IT,\n  defaultValueOrFunction: OptionalDefaultValueOrFunction<IT>\n): IOptionalIType<IT, [undefined]>\nexport function optional<\n  IT extends IAnyType,\n  OptionalVals extends ValidOptionalValues\n>(\n  type: IT,\n  defaultValueOrFunction: OptionalDefaultValueOrFunction<IT>,\n  optionalValues: OptionalVals\n): IOptionalIType<IT, OptionalVals>\n/**\n * `types.optional` - Can be used to create a property with a default value.\n *\n * Depending on the third argument (`optionalValues`) there are two ways of operation:\n * - If the argument is not provided, then if a value is not provided in the snapshot (`undefined` or missing),\n *   it will default to the provided `defaultValue`\n * - If the argument is provided, then if the value in the snapshot matches one of the optional values inside the array then it will\n *   default to the provided `defaultValue`. Additionally, if one of the optional values inside the array is `undefined` then a missing\n *   property is also valid.\n *\n *   Note that it is also possible to include values of the same type as the intended subtype as optional values,\n *   in this case the optional value will be transformed into the `defaultValue` (e.g. `types.optional(types.string, \"unnamed\", [undefined, \"\"])`\n *   will transform the snapshot values `undefined` (and therefore missing) and empty strings into the string `\"unnamed\"` when it gets\n *   instantiated).\n *\n * If `defaultValue` is a function, the function will be invoked for every new instance.\n * Applying a snapshot in which the optional value is one of the optional values (or `undefined`/_not_ present if none are provided) causes the\n * value to be reset.\n *\n * Example:\n * ```ts\n * const Todo = types.model({\n *   title: types.string,\n *   subtitle1: types.optional(types.string, \"\", [null]),\n *   subtitle2: types.optional(types.string, \"\", [null, undefined]),\n *   done: types.optional(types.boolean, false),\n *   created: types.optional(types.Date, () => new Date()),\n * })\n *\n * // if done is missing / undefined it will become false\n * // if created is missing / undefined it will get a freshly generated timestamp\n * // if subtitle1 is null it will default to \"\", but it cannot be missing or undefined\n * // if subtitle2 is null or undefined it will default to \"\"; since it can be undefined it can also be missing\n * const todo = Todo.create({ title: \"Get coffee\", subtitle1: null })\n * ```\n *\n * @param type\n * @param defaultValueOrFunction\n * @param optionalValues an optional array with zero or more primitive values (string, number, boolean, null or undefined)\n *                       that will be converted into the default. `[ undefined ]` is assumed when none is provided\n * @returns\n */\nexport function optional<\n  IT extends IAnyType,\n  OptionalVals extends ValidOptionalValues\n>(\n  type: IT,\n  defaultValueOrFunction: OptionalDefaultValueOrFunction<IT>,\n  optionalValues?: OptionalVals\n): IOptionalIType<IT, OptionalVals> {\n  checkOptionalPreconditions(type, defaultValueOrFunction)\n\n  return new OptionalValue(\n    type,\n    defaultValueOrFunction,\n    optionalValues ? optionalValues : undefinedAsOptionalValues\n  )\n}\n\nconst undefinedAsOptionalValues: [undefined] = [undefined]\n\n/**\n * Returns if a value represents an optional type.\n *\n * @template IT\n * @param type\n * @returns\n */\nexport function isOptionalType<IT extends IAnyType>(type: IT): type is IT {\n  return isType(type) && (type.flags & TypeFlags.Optional) > 0\n}\n"]}

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

@@ -0,0 +1,90 @@
+import { SimpleType } from "../../core/type/type.ts";
+import { type AnyObjectNode, type IAnyComplexType, type IAnyStateTreeNode, type IAnyType, type IMaybe, type IStateTreeNode, type IType, type IValidationContext, type IValidationResult, type ReferenceIdentifier, TypeFlags } from "../../internal.ts";
+export type OnReferenceInvalidatedEvent<STN extends IAnyStateTreeNode> = {
+    parent: IAnyStateTreeNode;
+    invalidTarget: STN | undefined;
+    invalidId: ReferenceIdentifier;
+    replaceRef: (newRef: STN | null | undefined) => void;
+    removeRef: () => void;
+    cause: "detach" | "destroy" | "invalidSnapshotReference";
+};
+export type OnReferenceInvalidated<STN extends IAnyStateTreeNode> = (event: OnReferenceInvalidatedEvent<STN>) => void;
+/** @hidden */
+export type ReferenceT<IT extends IAnyType> = IT["TypeWithoutSTN"] & IStateTreeNode<IReferenceType<IT>>;
+/**
+ * @internal
+ * @hidden
+ */
+export declare class InvalidReferenceError extends Error {
+    constructor(m: string);
+}
+/**
+ * @internal
+ * @hidden
+ */
+export declare abstract class BaseReferenceType<IT extends IAnyComplexType> extends SimpleType<ReferenceIdentifier, ReferenceIdentifier, IT["TypeWithoutSTN"]> {
+    protected readonly targetType: IT;
+    private readonly onInvalidated?;
+    readonly flags = TypeFlags.Reference;
+    constructor(targetType: IT, onInvalidated?: OnReferenceInvalidated<ReferenceT<IT>> | undefined);
+    describe(): string;
+    isAssignableFrom(type: IAnyType): boolean;
+    isValidSnapshot(value: this["C"], context: IValidationContext): IValidationResult;
+    private fireInvalidated;
+    private addTargetNodeWatcher;
+    protected watchTargetNodeForInvalidations(storedRefNode: this["N"], identifier: ReferenceIdentifier, customGetSet: ReferenceOptionsGetSet<IT> | undefined): void;
+}
+/**
+ * @internal
+ * @hidden
+ */
+export declare class IdentifierReferenceType<IT extends IAnyComplexType> extends BaseReferenceType<IT> {
+    constructor(targetType: IT, onInvalidated?: OnReferenceInvalidated<ReferenceT<IT>>);
+    getValue(storedRefNode: this["N"]): any;
+    getSnapshot(storedRefNode: this["N"]): ReferenceIdentifier;
+    instantiate(parent: AnyObjectNode | null, subpath: string, environment: any, initialValue: this["C"] | this["T"]): this["N"];
+    reconcile(current: this["N"], newValue: this["C"] | this["T"], parent: AnyObjectNode, subpath: string): this["N"];
+}
+/**
+ * @internal
+ * @hidden
+ */
+export declare class CustomReferenceType<IT extends IAnyComplexType> extends BaseReferenceType<IT> {
+    private readonly options;
+    constructor(targetType: IT, options: ReferenceOptionsGetSet<IT>, onInvalidated?: OnReferenceInvalidated<ReferenceT<IT>>);
+    getValue(storedRefNode: this["N"]): any;
+    getSnapshot(storedRefNode: this["N"]): any;
+    instantiate(parent: AnyObjectNode | null, subpath: string, environment: any, newValue: this["C"] | this["T"]): this["N"];
+    reconcile(current: this["N"], newValue: this["C"] | this["T"], parent: AnyObjectNode, subpath: string): this["N"];
+}
+export interface ReferenceOptionsGetSet<IT extends IAnyComplexType> {
+    get(identifier: ReferenceIdentifier, parent: IAnyStateTreeNode | null): ReferenceT<IT>;
+    set(value: ReferenceT<IT>, parent: IAnyStateTreeNode | null): ReferenceIdentifier;
+}
+export interface ReferenceOptionsOnInvalidated<IT extends IAnyComplexType> {
+    onInvalidated: OnReferenceInvalidated<ReferenceT<IT>>;
+}
+export type ReferenceOptions<IT extends IAnyComplexType> = ReferenceOptionsGetSet<IT> | ReferenceOptionsOnInvalidated<IT> | (ReferenceOptionsGetSet<IT> & ReferenceOptionsOnInvalidated<IT>);
+/** @hidden */
+export interface IReferenceType<IT extends IAnyComplexType> extends IType<ReferenceIdentifier, ReferenceIdentifier, IT["TypeWithoutSTN"]> {
+}
+/**
+ * `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 declare function reference<IT extends IAnyComplexType>(subType: IT, options?: ReferenceOptions<IT>): IReferenceType<IT>;
+/**
+ * Returns if a given value represents a reference type.
+ *
+ * @param type
+ * @returns
+ */
+export declare function isReferenceType<IT extends IReferenceType<any>>(type: IT): type is IT;
+export declare function safeReference<IT extends IAnyComplexType>(subType: IT, options: (ReferenceOptionsGetSet<IT> | object) & {
+    acceptsUndefined: false;
+    onInvalidated?: OnReferenceInvalidated<ReferenceT<IT>>;
+}): IReferenceType<IT>;
+export declare function safeReference<IT extends IAnyComplexType>(subType: IT, options?: (ReferenceOptionsGetSet<IT> | object) & {
+    acceptsUndefined?: boolean;
+    onInvalidated?: OnReferenceInvalidated<ReferenceT<IT>>;
+}): IMaybe<IReferenceType<IT>>;