mobx-keystone 1.25.0 → 2.1.0

package/dist/types/actionMiddlewares/actionSerialization/dateSerializer.d.ts

@@ -1,2 +1,2 @@
 import { ActionCallArgumentSerializer } from './core';
-export declare const dateSerializer: ActionCallArgumentSerializer<Date, number>;
+export declare const dateSerializer: ActionCallArgumentSerializer<Date, number | null>;

package/dist/types/actionMiddlewares/transactionMiddleware.d.ts

@@ -2,7 +2,7 @@ import { ActionMiddlewareDisposer } from '../action/middleware';
 import { AnyModel } from '../model/BaseModel';
 /**
  * Creates a transaction middleware, which reverts changes made by an action / child
- * actions when the root action throws an exception by applying inverse patches.
+ * actions when the root action throws an exception, restoring the values those changes replaced.
  *
  * @template M Model
  * @param target Object with the root target model object (`model`) and root action name (`actionName`).

package/dist/types/actionMiddlewares/undoMiddleware.d.ts

@@ -1,6 +1,8 @@
 import { ActionMiddlewareDisposer } from '../action/middleware';
+import { Frozen } from '../frozen';
 import { Path } from '../parent/pathTypes';
 import { Patch } from '../patch';
+import { FrozenData } from '../snapshot';
 /**
  * An undo/redo event without attached state.
  */
@@ -75,20 +77,25 @@ export interface UndoEventGroup {
     readonly events: ReadonlyArray<UndoEventWithoutAttachedState>;
 }
 declare const UndoStore_base: import('..')._Model<unknown, {
-    undoEvents: import('..').OptionalModelProp<UndoEvent[]> & {
-        $storedValueType: UndoEvent[];
-        $storedCreationValueType: UndoEvent[] | null | undefined;
-        $typedFromSnapshotOverride: UndoEvent[] | null | undefined;
+    undoEvents: import('..').OptionalModelProp<Frozen<UndoEvent>[]> & {
+        $storedValueType: Frozen<UndoEvent>[];
+        $storedCreationValueType: Frozen<UndoEvent>[] | null | undefined;
+        $typedFromSnapshotOverride: import('..').SnapshotInOfFrozen<Frozen<UndoEvent>>[] | null | undefined;
     };
-    redoEvents: import('..').OptionalModelProp<UndoEvent[]> & {
-        $storedValueType: UndoEvent[];
-        $storedCreationValueType: UndoEvent[] | null | undefined;
-        $typedFromSnapshotOverride: UndoEvent[] | null | undefined;
+    redoEvents: import('..').OptionalModelProp<Frozen<UndoEvent>[]> & {
+        $storedValueType: Frozen<UndoEvent>[];
+        $storedCreationValueType: Frozen<UndoEvent>[] | null | undefined;
+        $typedFromSnapshotOverride: import('..').SnapshotInOfFrozen<Frozen<UndoEvent>>[] | null | undefined;
     };
-}, never, never>;
+}, {
+    undoEvents?: ReadonlyArray<UndoEvent | FrozenData<UndoEvent>>;
+    redoEvents?: ReadonlyArray<UndoEvent | FrozenData<UndoEvent>>;
+}, never>;
 /**
  * Store model instance for undo/redo actions.
- * Do not manipulate directly, other that creating it.
+ * Do not manipulate directly, other than creating it.
+ *
+ * Events are stored as frozen data, since they never change once recorded.
  */
 export declare class UndoStore extends UndoStore_base {
     /**

package/dist/types/dataModel/dataModelInstanceCache.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/deepChange/onDeepChange.d.ts

@@ -11,6 +11,8 @@ export declare enum DeepChangeType {
     ObjectRemove = "objectRemove"
 }
 export interface DeepChangeBase {
+    /** Whether this notification overlaps a mutation made by a change listener. */
+    readonly isReentrant?: boolean;
     readonly type: DeepChangeType;
     readonly path: Path;
     /**
@@ -78,6 +80,13 @@ export type OnDeepChangeListener = (change: DeepChange) => void;
 /**
  * Adds a listener that will be called every time a deep change is generated for the tree of the given target object.
  * Unlike `onPatches`, this provides raw MobX change information including proper splice detection for arrays.
+ * Individual mutations notify listeners after automatic type checking succeeds and snapshots update;
+ * rejected mutations and their quiet rollbacks do not notify listeners.
+ * Listener errors do not stop delivery to other listeners. After delivery completes,
+ * a single error is rethrown unchanged and multiple errors are grouped in a MobxKeystoneAggregateError.
+ * Listeners added while callbacks for the same target are running start with the next
+ * change delivered to that target. Listeners disposed during delivery do not receive
+ * the current change if their callback has not run yet.
  *
  * @param subtreeRoot Subtree root object of the deep change listener.
  * @param listener The listener function that will be called every time a change is generated for the object or its children.

package/dist/types/parent/arrayPaths.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/parent/detach.d.ts

@@ -2,7 +2,7 @@
  * Detaches a given object from a tree.
  * If the parent is an object / model, detaching will delete the property.
  * If the parent is an array detaching will remove the node by splicing it.
- * If there's no parent it will throw.
+ * If there's no parent it does nothing.
  *
  * @param node Object to be detached.
  */

package/dist/types/parent/findChildren.d.ts

@@ -6,7 +6,7 @@
  * @param predicate Function that will be run for every child of the root object.
  * @param [options] An optional object with the `deep` option (defaults to `false`) set to `true` to
  * get the children deeply or `false` to get them shallowly.
- * @returns A readonly observable set with the matching children.
+ * @returns A readonly set with the matching children.
  */
 export declare function findChildren<T extends object = any>(root: object, predicate: (node: object) => boolean, options?: {
     deep?: boolean;

package/dist/types/parent/treeOrder.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/patch/applyPatches.d.ts

@@ -1,6 +1,9 @@
 import { Patch } from '../patch/Patch';
 /**
  * Applies the given patches to the given target object.
+ * Automatic type checking validates the completed batch, including nested lists.
+ * A batch that throws or is rejected is rolled back with compensating patches.
+ * Errors thrown by listeners do not roll it back.
  *
  * @param node Target object.
  * @param patches List of patches to apply.

package/dist/types/redux/connectReduxDevTools.d.ts

@@ -20,5 +20,6 @@ export interface ConnectReduxDevToolsOptions {
  * @param remotedevConnection The result of a connect method from the remotedev package (usually the result of `remoteDev.connectViaExtension(...)`).
  * @param target Object to use as root.
  * @param [options] Optional options object.
+ * @returns An idempotent disposer that stops logging and unsubscribes from monitor messages.
  */
-export declare function connectReduxDevTools(remotedevPackage: any, remotedevConnection: any, target: object, options?: ConnectReduxDevToolsOptions): void;
+export declare function connectReduxDevTools(remotedevPackage: any, remotedevConnection: any, target: object, options?: ConnectReduxDevToolsOptions): () => void;

package/dist/types/ref/modelRefIdIndex.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/ref/nodesById.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/ref/refIdIndex.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/snapshot/SnapshotOf.d.ts

@@ -34,13 +34,13 @@ export interface SnapshotInOfFrozen<F extends Frozen<any>> extends FrozenData<F[
 }
 export interface SnapshotInOfObjectMap<V> {
     items?: {
-        [k: string]: SnapshotOutOf<V>;
+        [k: string]: SnapshotInOf<V>;
     };
     [modelTypeKey]?: string;
     [modelIdKey]: string;
 }
 export interface SnapshotInOfArraySet<V> {
-    items?: SnapshotOutOf<V>[];
+    items?: SnapshotInOf<V>[];
     [modelTypeKey]?: string;
     [modelIdKey]: string;
 }

package/dist/types/snapshot/applySnapshot.d.ts

@@ -1,6 +1,7 @@
 import { SnapshotInOf, SnapshotOutOf } from './SnapshotOf';
 /**
  * Applies a full snapshot over an object, reconciling it with the current contents of the object.
+ * If it throws, the changes it made are rolled back (errors thrown by listeners do not roll them back).
  *
  * @template T Object type.
  * @param node Target object (model object, object or array).

package/dist/types/snapshot/fromSnapshot.d.ts

@@ -28,6 +28,3 @@ export declare function fromSnapshot<TType extends AnyType>(type: TType, snapsho
  * @returns The deserialized object.
  */
 export declare function fromSnapshot<T>(snapshot: SnapshotInOf<T> | SnapshotOutOf<T>, options?: Partial<FromSnapshotOptions>): T;
-export declare const observableOptions: {
-    deep: boolean;
-};

package/dist/types/standardActions/arrayActions.d.ts

@@ -2,7 +2,7 @@ export declare const arrayActions: {
     set: <T>(array: T[], index: number, value: any) => void;
     delete: <T>(array: T[], index: number) => boolean;
     setLength: <T>(array: T[], length: number) => void;
-    concat: <T>(array: T[], ...items: ConcatArray<T>[]) => T[];
+    concat: <T>(array: T[], ...items: (T | ConcatArray<T>)[]) => T[];
     copyWithin: <T>(array: T[], target: number, start: number, end?: number) => T[];
     fill: <T>(array: T[], value: T, start?: number, end?: number) => T[];
     pop: <T>(array: T[]) => T | undefined;

package/dist/types/treeUtils/sandbox.d.ts

@@ -42,10 +42,6 @@ export declare class SandboxManager {
      * code block on a readonly node.
      */
     private allowWrite;
-    /**
-     * Whether changes made in the sandbox are currently being committed to the original subtree.
-     */
-    private isCommitting;
     private readonly subtreeRoot;
     /**
      * Creates an instance of `SandboxManager`.

package/dist/types/tweaker/changeRollback.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/tweaker/tweakedChangeListeners.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/types/TypeCheckError.d.ts

@@ -1,6 +1,7 @@
 import { Path } from '../parent/pathTypes';
 import { MobxKeystoneError } from '../utils';
 export interface TypeCheckErrorData {
+    /** Path relative to the value being type checked. */
     path: Path;
     expectedTypeName: string;
     actualValue: any;

package/dist/types/types/utility/typesRefinement.d.ts

@@ -32,8 +32,8 @@ import { TypeInfo } from '../TypeChecker';
  * @template T Base type.
  * @param baseType Base type.
  * @param checkFn Function that will receive the data (if it passes the base type
- * check) and return null or false if there were no errors or either a TypeCheckError instance or
- * true if there were.
+ * check) and return null or true if there were no errors or either a TypeCheckError instance or
+ * false if there were.
  * @returns
  */
 export declare function typesRefinement<T extends AnyType>(baseType: T, checkFn: (data: TypeToData<T>) => TypeCheckError | null | boolean, typeName?: string): T;

package/dist/types/utils/ModelPool.d.ts

@@ -1,7 +1,13 @@
 import { AnyModel } from '../model/BaseModel';
+/**
+ * A view of the models under a node, as they were when the pool was created.
+ * Must be released once no longer used.
+ */
 export declare class ModelPool {
-    private pool;
+    private readonly pool;
+    private readonly pinned;
     constructor(root: object);
+    release(): void;
     findModelByTypeAndId(modelType: string, modelId: string | undefined): AnyModel | undefined;
     findModelForSnapshot(sn: any): AnyModel | undefined;
 }

package/dist/types/utils/chunks.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/utils/forEachWithDelayedThrow.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/utils/index.d.ts

@@ -4,6 +4,19 @@
 export declare class MobxKeystoneError extends Error {
     constructor(msg: string);
 }
+/**
+ * A mobx-keystone error that groups several failures that happened while delivering
+ * a single notification, such as multiple patch listeners or root store hooks throwing.
+ *
+ * It is only used when more than one callback failed; a lone failure is rethrown as is.
+ */
+export declare class MobxKeystoneAggregateError extends MobxKeystoneError {
+    /**
+     * The values thrown by the failing callbacks, in the order they were thrown.
+     */
+    readonly errors: readonly unknown[];
+    constructor(errors: readonly unknown[], msg: string);
+}
 /**
  * MobX method action decorator compatible with both legacy decorators and
  * MobX 7's standard decorator API.

package/dist/types/utils/mapUtils.d.ts

@@ -1,2 +1,2 @@
-export declare function getOrCreate<K, V, C = V>(map: Map<K, V>, key: K, create: () => C): V;
-export declare function getOrCreate<K extends object, V, C = V>(map: WeakMap<K, V>, key: K, create: () => C): V;
+export declare function getOrCreate<K, V>(map: Map<K, V>, key: K, create: () => V): V;
+export declare function getOrCreate<K extends object, V>(map: WeakMap<K, V>, key: K, create: () => V): V;

package/dist/types/utils/setLike.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobx-keystone",
-  "version": "1.25.0",
+  "version": "2.1.0",
   "description": "A MobX powered state management solution based on data trees with first class support for TypeScript, snapshots, patches and much more",
   "keywords": [
     "mobx",
@@ -78,12 +78,12 @@
     "@types/node": "^26.4.1",
     "@typescript/typescript6": "^6.0.2",
     "@vitest/coverage-v8": "^5.0.0",
+    "expect-type": "^1.4.0",
     "mobx-v4": "npm:mobx@^4.15.7",
     "mobx-v5": "npm:mobx@^5.15.7",
     "mobx-v6": "npm:mobx@^6.0.0",
     "mobx-v7": "npm:mobx@^7.0.0",
     "shx": "^0.4.0",
-    "spec.ts": "^1.1.3",
     "ts-node": "^10.9.2",
     "typedoc": "^0.28.20",
     "typescript": "^7.0.2",

package/src/action/applyAction.ts

@@ -86,7 +86,7 @@ export function applyAction<TRet = any>(subtreeRoot: object, call: ActionCall):
       )} could not be resolved`
     )
   }
-  assertTweakedObject(current, `resolved ${current}`, true)
+  assertTweakedObject(current, "resolved target", true)
 
   if (isBuiltInAction(call.actionName)) {
     const fnToCall = builtInActionToFunction[call.actionName] as AnyFunction | undefined

package/src/action/middleware.ts

@@ -1,6 +1,6 @@
 import { fastGetParent } from "../parent/path"
 import { assertTweakedObject } from "../tweaker/core"
-import { assertIsFunction, assertIsObject, deleteFromArray, failure } from "../utils"
+import { assertIsFunction, assertIsObject, failure } from "../utils"
 import type { ActionContext } from "./context"
 
 /**
@@ -37,33 +37,9 @@ const perObjectActionMiddlewares = new WeakMap<object, PartialActionMiddleware[]
 /**
  * @internal
  *
- * Runs a callback for each action middlewares to be run over a given object.
- *
- * @returns
- */
-export function forEachActionMiddleware(
-  obj: object,
-  callback: (middleware: PartialActionMiddleware) => void
-): void {
-  // when we call a middleware we will call the middlewares of that object plus all parent objects
-  // the parent object middlewares are run last
-
-  // since an array like [a, b, c] will be called like c(b(a())) this means that we need to call
-  // the parent object ones at the end of the array
-
-  let current: unknown = obj
-  while (current) {
-    const objMwares = perObjectActionMiddlewares.get(current)
-    if (objMwares && objMwares.length > 0) {
-      objMwares.forEach(callback)
-    }
-    current = fastGetParent(current, false)
-  }
-}
-/**
- * @internal
- *
- * Returns the action middlewares to be run over a given object.
+ * Returns the action middlewares to be run over a given object, from the object itself to the
+ * topmost parent. Since an array like [a, b, c] will be called like c(b(a())) the caller runs
+ * them in reverse, so the parent object ones run last.
  *
  * @returns
  */
@@ -111,14 +87,19 @@ export function addActionMiddleware(mware: ActionMiddleware): ActionMiddlewareDi
 
   const actualMware = { middleware, subtreeRoot, filter }
 
-  let objMwares = perObjectActionMiddlewares.get(subtreeRoot)
-  if (objMwares) {
-    objMwares.push(actualMware)
-  } else {
-    objMwares = [actualMware]
-    perObjectActionMiddlewares.set(subtreeRoot, objMwares)
-  }
+  // Each action keeps the middleware arrays it collected. Update registrations by
+  // replacement so user code cannot shift or extend an in-progress chain.
+  const objMwares = perObjectActionMiddlewares.get(subtreeRoot) ?? []
+  perObjectActionMiddlewares.set(subtreeRoot, [...objMwares, actualMware])
+
+  let disposed = false
   return () => {
-    deleteFromArray(objMwares, actualMware)
+    if (disposed) return
+    disposed = true
+    const current = perObjectActionMiddlewares.get(subtreeRoot)!
+    perObjectActionMiddlewares.set(
+      subtreeRoot,
+      current.filter((entry) => entry !== actualMware)
+    )
   }
 }

package/src/action/modelFlow.ts

@@ -2,7 +2,6 @@ import type { O } from "ts-toolbelt"
 import { failure } from "../utils"
 import { copyFunctionMetadata, decorateWrapMethodOrField } from "../utils/decorators"
 import { type ActionContext, ActionContextActionType, ActionContextAsyncStepType } from "./context"
-import { promiseGenerator } from "./modelFlowPromiseGenerator"
 import { type WrapInActionOverrideContextFn, wrapInAction } from "./wrapInAction"
 
 const modelFlowSymbol = Symbol("modelFlow")
@@ -133,7 +132,7 @@ export function flow<R, Args extends any[]>({
       function next(ret: any): void {
         if (ret && typeof ret.then === "function") {
           // an async iterator
-          ret.then(next, reject)
+          Promise.resolve(ret).then(next, reject).catch(reject)
         } else if (ret.done) {
           // done
           wrapInAction({
@@ -154,7 +153,7 @@ export function flow<R, Args extends any[]>({
           }).call(target, ret.value)
         } else {
           // continue
-          Promise.resolve(ret.value).then(onFulfilled, onRejected)
+          Promise.resolve(ret.value).then(onFulfilled, onRejected).catch(reject)
         }
       }
 
@@ -235,6 +234,6 @@ export function _async<A extends any[], R>(
  * @param promise Promise.
  * @returns
  */
-export function _await<T>(promise: Promise<T>): Generator<Promise<T>, T, unknown> {
-  return promiseGenerator.call(promise)
+export function* _await<T>(promise: Promise<T>): Generator<Promise<T>, T, unknown> {
+  return (yield promise) as T
 }

package/src/action/mutationBatch.ts

@@ -57,16 +57,16 @@ export function finishMutationBatch(): void {
   if (typeof finishers === "function") {
     finishers()
   } else if (finishers) {
-    runFinishers(finishers, finishers.length - 1)
-  }
-}
-
-function runFinishers(finishers: (() => void)[], index: number): void {
-  try {
-    finishers[index]()
-  } finally {
-    if (index > 0) {
-      runFinishers(finishers, index - 1)
+    let lastError: { value: unknown } | undefined
+    for (let i = finishers.length - 1; i >= 0; i--) {
+      try {
+        finishers[i]()
+      } catch (value) {
+        lastError = { value }
+      }
+    }
+    if (lastError) {
+      throw lastError.value
     }
   }
 }

package/src/action/pendingActions.ts

@@ -1,3 +1,4 @@
+import { forEachWithDelayedThrow } from "../utils/forEachWithDelayedThrow"
 import { getCurrentActionContext } from "./context"
 import { getActionProtection } from "./protection"
 
@@ -32,11 +33,9 @@ export function tryRunPendingActions(): void {
   pendingActionsRunning = true
 
   try {
-    while (pendingActions.length > 0) {
-      const nextAction = pendingActions.shift()!
-      nextAction()
-    }
+    forEachWithDelayedThrow(pendingActions, (nextAction) => nextAction())
   } finally {
+    pendingActions.length = 0
     pendingActionsRunning = false
   }
 }

package/src/actionMiddlewares/actionSerialization/actionSerialization.ts

@@ -2,6 +2,7 @@ import type { O } from "ts-toolbelt"
 import type { ActionCall } from "../../action/applyAction"
 import { assertTweakedObject } from "../../tweaker/core"
 import { failure, isJSONPrimitive, isPlainObject } from "../../utils"
+import { getSafeErrorValuePreview } from "../../utils/errorDiagnostics"
 import type { JSONPrimitiveValue } from "../../utils/types"
 import { arraySerializer } from "./arraySerializer"
 import { type ActionCallArgumentSerializer, cannotSerialize } from "./core"
@@ -13,7 +14,7 @@ import { plainObjectSerializer } from "./plainObjectSerializer"
 import { primitiveSerializer } from "./primitiveSerializer"
 import { setSerializer } from "./setSerializer"
 
-const serializersArray: ActionCallArgumentSerializer<any, any>[] = []
+let serializersArray: ActionCallArgumentSerializer<any, any>[] = []
 const serializersMap = new Map<string, ActionCallArgumentSerializer<any, any>>()
 
 /**
@@ -32,19 +33,22 @@ export function registerActionCallArgumentSerializer(
   if (serializersArray.includes(serializer)) {
     throw failure("action call argument serializer already registered")
   }
-  if (serializersMap.has(serializer.id)) {
+  const id = serializer.id
+  if (serializersMap.has(id)) {
     throw failure(`action call argument serializer with id '${serializer.id}' already registered`)
   }
 
-  serializersArray.unshift(serializer)
-  serializersMap.set(serializer.id, serializer)
+  serializersArray = [serializer, ...serializersArray]
+  serializersMap.set(id, serializer)
 
+  let disposed = false
   return () => {
-    const index = serializersArray.indexOf(serializer)
-    if (index >= 0) {
-      serializersArray.splice(index, 1)
+    if (disposed) {
+      return
     }
-    serializersMap.delete(serializer.id)
+    disposed = true
+    serializersArray = serializersArray.filter((entry) => entry !== serializer)
+    serializersMap.delete(id)
   }
 }
 
@@ -106,13 +110,12 @@ export function serializeActionCallArgument(
     return argValue
   }
 
-  const origValue = argValue
-
   const serialize = (v: any) => serializeActionCallArgument(v, targetRoot)
 
   // try serializers
-  for (let i = 0; i < serializersArray.length; i++) {
-    const serializer = serializersArray[i]
+  const serializers = serializersArray
+  for (let i = 0; i < serializers.length; i++) {
+    const serializer = serializers[i]
     const serializedValue = serializer.serialize(argValue, serialize, targetRoot)
     if (serializedValue !== cannotSerialize) {
       return {
@@ -122,7 +125,9 @@ export function serializeActionCallArgument(
     }
   }
 
-  throw failure(`serializeActionCallArgument could not serialize the given value: ${origValue}`)
+  throw failure(
+    `serializeActionCallArgument could not serialize the given value: ${getSafeErrorValuePreview(argValue)}`
+  )
 }
 
 /**
@@ -150,7 +155,7 @@ export function serializeActionCall(
   return {
     ...actionCall,
     serialized: true,
-    args: actionCall.args.map(serialize),
+    args: Array.from(actionCall.args, serialize),
   }
 }