mobx-keystone 1.22.0 → 1.23.0

package/dist/types/action/runUnprotected.d.ts

@@ -1,6 +1,8 @@
 /**
- * Runs a block in unprocted mode, as if it were run inside a model action.
- * Consider using a proper model action instead since these kind of actions are not recorded.
+ * Runs a block in unprotected mode, as if it were run inside a model action.
+ * Structural mutations share one synchronous mutation batch, but the block is
+ * not recorded as an action. Consider using a proper model action when action
+ * recording is needed.
  *
  * @template T Return type.
  * @param name Mobx action name.
@@ -9,8 +11,10 @@
  */
 export declare function runUnprotected<T>(name: string, fn: () => T): T;
 /**
- * Runs a block in unprocted mode, as if it were run inside a model action.
- * Consider using a proper model action instead since these kind of actions are not recorded.
+ * Runs a block in unprotected mode, as if it were run inside a model action.
+ * Structural mutations share one synchronous mutation batch, but the block is
+ * not recorded as an action. Consider using a proper model action when action
+ * recording is needed.
  *
  * @template T Return type.
  * @param fn Action block.

package/dist/types/model/Model.d.ts

@@ -76,6 +76,9 @@ export interface ModelOptions<TProps extends ModelProps, FS, TS> {
     /**
      * Optional transformation that will be run when converting from a snapshot to the data part of the model.
      * Useful for example to do versioning and keep the data part up to date with the latest version of the model.
+     * Snapshot processors must be pure and deterministic. The model's canonical output snapshot must round-trip
+     * through this processor to the same model data. Reconciliation may skip invoking it when the input already
+     * equals the model's current canonical output snapshot.
      *
      * @param sn The custom input snapshot.
      * @returns An input snapshot that must match the expected model input snapshot.
@@ -83,6 +86,8 @@ export interface ModelOptions<TProps extends ModelProps, FS, TS> {
     fromSnapshotProcessor?: (sn: FS) => FromSnapshotDefaultType<TProps>;
     /**
      * Optional transformation that will be run when converting the data part of the model into a snapshot.
+     * Snapshot processors must be pure and deterministic, and their canonical output must round-trip through the
+     * corresponding input processor to the same model data. Snapshot generation may cache processor results.
      *
      * @param sn The output snapshot.
      * @param modelInstance The model instance.

package/dist/types/modelShared/prop.d.ts

@@ -23,17 +23,18 @@ export interface ModelProp<TPropValue, TPropCreationValue, TTransformedValue, TT
     _defaultFn: (() => TPropValue) | typeof noDefaultValue;
     _defaultValue: TPropValue | typeof noDefaultValue;
     _defaultValueIsTransformed: boolean;
+    _getDefaultValueIsTransformed?: () => boolean;
     _typeChecker: AnyStandardType | undefined;
     _setter: SetterMode;
     _setterValueTransform: ((value: unknown) => unknown) | undefined;
     _isId: boolean;
     _idGenerator?: (() => string) | undefined;
-    _transform: {
-        transform: (original: unknown, model: object, propName: PropertyKey, setOriginalValue: (newOriginalValue: unknown) => void) => unknown;
-        untransform: (transformed: unknown, model: object, propName: PropertyKey) => unknown;
-    } | undefined;
+    _transform: FullModelPropTransform | undefined;
+    _getTransform?: () => FullModelPropTransform | undefined;
     _fromSnapshotProcessor?: (sn: unknown) => unknown;
     _toSnapshotProcessor?: (sn: unknown) => unknown;
+    _getFromSnapshotProcessor?: () => ((sn: unknown) => unknown) | undefined;
+    _getToSnapshotProcessor?: () => ((sn: unknown) => unknown) | undefined;
     /**
      * Adds a setter to the property. The setter will be named `set${CapitalizedPropName}`
      * and will be available in the model instance.
@@ -66,6 +67,9 @@ export interface ModelProp<TPropValue, TPropCreationValue, TTransformedValue, TT
      *
      * `fromSnapshot` runs before assigning snapshot data into the model prop.
      * `toSnapshot` runs when exporting model data back to snapshot form.
+     * Both processors must be pure and deterministic, and their canonical output
+     * must round-trip to the same stored value. Reconciliation and snapshot
+     * generation may skip calls when that canonical snapshot is already current.
      */
     withSnapshotProcessor<FS = TFromSnapshotOverride, TS = TToSnapshotOverride, This extends AnyModelProp = this>(processor: {
         fromSnapshot?: (sn: FS) => ModelPropFromSnapshot<This>;

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

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

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

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

package/dist/types/types/createCachedTypeCheck.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobx-keystone",
-  "version": "1.22.0",
+  "version": "1.23.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",
@@ -58,9 +58,9 @@
     "test": "vitest run",
     "test:ci": "vitest run --coverage",
     "test:perf": "pnpm run build && pnpm run test:perf:run",
-    "test:perf:run": "cd perf_bench && NODE_ENV=production /usr/bin/time node --expose-gc --require ts-node/register ./report.ts",
-    "memtest": "cd perf_bench && NODE_ENV=production node --expose-gc --require ts-node/register ./memtest.ts",
-    "build-docs": "shx rm -rf api-docs && typedoc --options ./typedocconfig.js src/index.ts && shx rm -rf ../../apps/site/generated-static/api && shx mkdir -p ../../apps/site/generated-static/api && shx cp -R ./api-docs/* ../../apps/site/generated-static/api"
+    "test:perf:run": "cd perf_bench && NODE_ENV=production TS_NODE_COMPILER=@typescript/typescript6 /usr/bin/time node --expose-gc --require ts-node/register ./report.ts",
+    "memtest": "cd perf_bench && NODE_ENV=production TS_NODE_COMPILER=@typescript/typescript6 node --expose-gc --require ts-node/register ./memtest.ts",
+    "build-docs": "shx rm -rf api-docs && node --import ./scripts/typedoc-typescript6-register.mjs ./node_modules/typedoc/dist/cli.js --options ./typedocconfig.js src/index.ts && shx rm -rf ../../apps/site/generated-static/api && shx mkdir -p ../../apps/site/generated-static/api && shx cp -R ./api-docs/* ../../apps/site/generated-static/api"
   },
   "peerDependencies": {
     "mobx": "^6.0.0 || ^5.0.0 || ^4.0.0"
@@ -73,18 +73,19 @@
     "@babel/preset-env": "^8.0.2",
     "@swc/core": "^1.15.43",
     "@types/babel__core": "^7.20.5",
-    "@types/node": "^26.0.1",
-    "@vitest/coverage-v8": "^4.1.9",
+    "@types/node": "^26.1.1",
+    "@typescript/typescript6": "^6.0.2",
+    "@vitest/coverage-v8": "^4.1.10",
     "mobx-v4": "npm:mobx@^4.15.7",
     "mobx-v5": "npm:mobx@^5.15.7",
     "shx": "^0.4.0",
     "spec.ts": "^1.1.3",
     "ts-node": "^10.9.2",
-    "typedoc": "^0.28.19",
-    "typescript": "^6.0.3",
-    "vite": "^8.1.0",
+    "typedoc": "^0.28.20",
+    "typescript": "^7.0.2",
+    "vite": "^8.1.4",
     "vite-plugin-dts": "^5.0.3",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.10"
   },
   "dependencies": {
     "fast-deep-equal": "^3.1.3",

package/src/action/middleware.ts

@@ -1,5 +1,4 @@
 import { fastGetParent } from "../parent/path"
-import { isChildOfParent } from "../parent/path2"
 import { assertTweakedObject } from "../tweaker/core"
 import { assertIsFunction, assertIsObject, deleteFromArray, failure } from "../utils"
 import type { ActionContext } from "./context"
@@ -31,7 +30,7 @@ export interface ActionMiddleware {
  */
 export type ActionMiddlewareDisposer = () => void
 
-type PartialActionMiddleware = Pick<ActionMiddleware, "filter" | "middleware">
+type PartialActionMiddleware = Pick<ActionMiddleware, "subtreeRoot" | "filter" | "middleware">
 
 const perObjectActionMiddlewares = new WeakMap<object, PartialActionMiddleware[]>()
 
@@ -96,7 +95,7 @@ export function addActionMiddleware(mware: ActionMiddleware): ActionMiddlewareDi
   assertIsObject(mware, "middleware")
 
   const { middleware, subtreeRoot } = mware
-  let { filter } = mware
+  const { filter } = mware
 
   assertTweakedObject(subtreeRoot, "middleware.subtreeRoot")
   assertIsFunction(middleware, "middleware.middleware")
@@ -107,21 +106,10 @@ export function addActionMiddleware(mware: ActionMiddleware): ActionMiddlewareDi
   // reminder: never turn middlewares into actions or else
   // reactions will not be picked up by the undo manager
 
-  if (subtreeRoot) {
-    const targetFilter = (ctx: ActionContext) =>
-      ctx.target === subtreeRoot || isChildOfParent(ctx.target, subtreeRoot)
-
-    if (filter) {
-      const customFilter = filter
-      filter = (ctx) => {
-        return targetFilter(ctx) && customFilter(ctx)
-      }
-    } else {
-      filter = targetFilter
-    }
-  }
+  // Middleware collection establishes the initial subtree match. The runner
+  // revalidates it after user middleware or filter code may have changed parentage.
 
-  const actualMware = { middleware, filter }
+  const actualMware = { middleware, subtreeRoot, filter }
 
   let objMwares = perObjectActionMiddlewares.get(subtreeRoot)
   if (objMwares) {
@@ -130,7 +118,6 @@ export function addActionMiddleware(mware: ActionMiddleware): ActionMiddlewareDi
     objMwares = [actualMware]
     perObjectActionMiddlewares.set(subtreeRoot, objMwares)
   }
-
   return () => {
     deleteFromArray(objMwares, actualMware)
   }

package/src/action/mutationBatch.ts

@@ -0,0 +1,72 @@
+let mutationBatchActive = false
+let mutationBatchFinishers: (() => void) | (() => void)[] | undefined
+
+/**
+ * Starts a synchronous mutation batch if one is not already active.
+ *
+ * @returns `true` if this call owns the batch and must finish it.
+ * @internal
+ */
+export function startMutationBatch(): boolean {
+  if (mutationBatchActive) {
+    return false
+  }
+
+  mutationBatchActive = true
+  return true
+}
+
+/**
+ * @internal
+ */
+export function isMutationBatchActive(): boolean {
+  return mutationBatchActive
+}
+
+/**
+ * Registers a callback to run when the outermost synchronous mutation batch
+ * ends. The first callback is stored directly so the common single-finisher
+ * case does not allocate an array.
+ *
+ * @internal
+ */
+export function addMutationBatchFinisher(finisher: () => void): void {
+  const currentFinishers = mutationBatchFinishers
+  if (!currentFinishers) {
+    mutationBatchFinishers = finisher
+  } else if (typeof currentFinishers === "function") {
+    mutationBatchFinishers = [currentFinishers, finisher]
+  } else {
+    currentFinishers.push(finisher)
+  }
+}
+
+/**
+ * Finishes a batch started by `startMutationBatch`. Every finisher runs even
+ * if an earlier one throws, so a finisher's cleanup of its own module state
+ * cannot be skipped by another consumer's exception.
+ *
+ * @internal
+ */
+export function finishMutationBatch(): void {
+  mutationBatchActive = false
+
+  const finishers = mutationBatchFinishers
+  mutationBatchFinishers = undefined
+
+  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)
+    }
+  }
+}

package/src/action/runUnprotected.ts

@@ -1,10 +1,13 @@
 import { action } from "mobx"
+import { finishMutationBatch, startMutationBatch } from "./mutationBatch"
 import { tryRunPendingActions } from "./pendingActions"
 import { getActionProtection, setActionProtection } from "./protection"
 
 /**
- * Runs a block in unprocted mode, as if it were run inside a model action.
- * Consider using a proper model action instead since these kind of actions are not recorded.
+ * Runs a block in unprotected mode, as if it were run inside a model action.
+ * Structural mutations share one synchronous mutation batch, but the block is
+ * not recorded as an action. Consider using a proper model action when action
+ * recording is needed.
  *
  * @template T Return type.
  * @param name Mobx action name.
@@ -14,8 +17,10 @@ import { getActionProtection, setActionProtection } from "./protection"
 export function runUnprotected<T>(name: string, fn: () => T): T
 
 /**
- * Runs a block in unprocted mode, as if it were run inside a model action.
- * Consider using a proper model action instead since these kind of actions are not recorded.
+ * Runs a block in unprotected mode, as if it were run inside a model action.
+ * Structural mutations share one synchronous mutation batch, but the block is
+ * not recorded as an action. Consider using a proper model action when action
+ * recording is needed.
  *
  * @template T Return type.
  * @param fn Action block.
@@ -28,7 +33,9 @@ export function runUnprotected<T>(arg1: any, arg2?: any): T {
   const name = typeof arg1 === "string" ? arg1 : undefined
   const fn: () => T = typeof arg1 === "string" ? arg2 : arg1
 
+  let mutationBatchOwner = false
   const innerAction = () => {
+    mutationBatchOwner = startMutationBatch()
     const oldActionProtection = getActionProtection()
     setActionProtection(false)
 
@@ -41,9 +48,15 @@ export function runUnprotected<T>(arg1: any, arg2?: any): T {
     }
   }
 
-  if (name) {
-    return action(name, innerAction)()
-  } else {
-    return action(innerAction)()
+  try {
+    if (name) {
+      return action(name, innerAction)()
+    } else {
+      return action(innerAction)()
+    }
+  } finally {
+    if (mutationBatchOwner) {
+      finishMutationBatch()
+    }
   }
 }

package/src/action/wrapInAction.ts

@@ -2,6 +2,7 @@ import { action } from "mobx"
 import type { O } from "ts-toolbelt"
 import type { AnyDataModel } from "../dataModel/BaseDataModel"
 import type { AnyModel } from "../model/BaseModel"
+import { fastGetParent } from "../parent/path"
 import type { AnyFunction } from "../utils/AnyFunction"
 import { copyFunctionMetadata } from "../utils/decorators"
 import {
@@ -13,8 +14,20 @@ import {
 import { isModelAction, modelActionSymbol } from "./isModelAction"
 import { getPerObjectActionMiddlewares } from "./middleware"
 import type { FlowFinisher } from "./modelFlow"
+import { finishMutationBatch, startMutationBatch } from "./mutationBatch"
 import { tryRunPendingActions } from "./pendingActions"
 
+function isActionTargetInSubtree(target: object, subtreeRoot: object): boolean {
+  let current: object | undefined = target
+  while (current) {
+    if (current === subtreeRoot) {
+      return true
+    }
+    current = fastGetParent(current, false)
+  }
+  return false
+}
+
 /**
  * @internal
  */
@@ -77,29 +90,44 @@ export function wrapInAction<T extends Function>({
     setCurrentActionContext(context)
 
     const perObjectMiddlewares = getPerObjectActionMiddlewares(context.target)
-
     let objectIndex = perObjectMiddlewares.length - 1 // from topmost parent to the object itself
     let objectMwareIndex = 0
+    let scopeMayHaveChanged = false
 
     const runNextMiddleware = (): unknown => {
-      const objectMwares = perObjectMiddlewares[objectIndex]
-      if (!objectMwares) {
-        // no more middlewares, run base action
-        return fn.apply(this, args)
-      }
-      const mwareData = objectMwares[objectMwareIndex]
+      while (objectIndex >= 0) {
+        const objectMwares = perObjectMiddlewares[objectIndex]
+        const mwareData = objectMwares[objectMwareIndex]
+
+        // Advance before calling user code so next() continues with the following middleware.
+        objectMwareIndex++
+        if (objectMwareIndex >= objectMwares.length) {
+          objectMwareIndex = 0
+          objectIndex--
+        }
 
-      // advance to the next middleware
-      objectMwareIndex++
-      if (objectMwareIndex >= objectMwares.length) {
-        objectMwareIndex = 0
-        objectIndex--
+        if (
+          scopeMayHaveChanged &&
+          !isActionTargetInSubtree(context.target, mwareData.subtreeRoot)
+        ) {
+          continue
+        }
+
+        if (mwareData.filter) {
+          scopeMayHaveChanged = true
+          if (!mwareData.filter(context)) {
+            continue
+          }
+        }
+
+        scopeMayHaveChanged = true
+        return mwareData.middleware(context, runNextMiddleware)
       }
 
-      const filterPassed = mwareData.filter ? mwareData.filter(context) : true
-      return filterPassed ? mwareData.middleware(context, runNextMiddleware) : runNextMiddleware()
+      return fn.apply(this, args)
     }
 
+    const mutationBatchOwner = startMutationBatch()
     try {
       const ret = runNextMiddleware()
 
@@ -117,7 +145,9 @@ export function wrapInAction<T extends Function>({
       }
     } finally {
       setCurrentActionContext(context.parentContext)
-
+      if (mutationBatchOwner) {
+        finishMutationBatch()
+      }
       tryRunPendingActions()
     }
   }

package/src/dataModel/BaseDataModel.ts

@@ -32,7 +32,7 @@ const dataModelInstanceCache = new WeakMap<ModelClass<AnyDataModel>, WeakMap<any
  */
 export abstract class BaseDataModel<TProps extends ModelProps> {
   // just to make typing work properly
-  [propsTypeSymbol]!: TProps
+  declare [propsTypeSymbol]: TProps
 
   /**
    * Called after the instance is created when there's the first call to `fn(M, data)`.
@@ -105,9 +105,10 @@ export abstract class BaseDataModel<TProps extends ModelProps> {
         let changed = false
 
         // apply untransform (if any)
-        if (propData._transform) {
+        const transform = propData._getTransform ? propData._getTransform() : propData._transform
+        if (transform) {
           changed = true
-          newValue = propData._transform.untransform(newValue, this, k)
+          newValue = transform.untransform(newValue, this, k)
         }
 
         // apply default value (if needed)
@@ -143,11 +144,6 @@ export abstract class BaseDataModel<TProps extends ModelProps> {
 
     Object.setPrototypeOf(this, modelClass.prototype)
 
-    const self = this as any
-
-    // delete unnecessary props
-    delete self[propsTypeSymbol]
-
     internalNewDataModel(this, tweakedData as any, {
       modelClass,
     })