mobx-keystone 2.0.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobx-keystone",
-  "version": "2.0.0",
+  "version": "2.2.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",
@@ -61,7 +61,7 @@
     "test:perf": "pnpm run build && pnpm run test:perf:run",
     "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"
+    "build-docs": "shx rm -rf ../../apps/site/generated-api && node --import ./scripts/typedoc-typescript6-register.mjs ./node_modules/typedoc/dist/cli.js --options ./typedocconfig.js src/index.ts"
   },
   "peerDependencies": {
     "mobx": "^7.0.0 || ^6.0.0 || ^5.0.0 || ^4.0.0"
@@ -78,14 +78,16 @@
     "@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",
+    "typedoc-docusaurus-theme": "^1.4.3",
+    "typedoc-plugin-markdown": "^4.13.1",
     "typescript": "^7.0.2",
     "vite": "^8.2.2",
     "vite-plugin-dts": "^5.1.0",

package/src/action/modelFlow.ts

@@ -65,68 +65,53 @@ export function flow<R, Args extends any[]>({
     const genThrow = gen.throw!.bind(gen)
 
     const promise = new Promise<R>((resolve, reject) => {
-      function onFulfilled(res: any): void {
+      function finish(
+        stepType: ActionContextAsyncStepType,
+        resolution: FlowFinisher["resolution"],
+        value: unknown
+      ): void {
+        wrapInAction({
+          nameOrNameFn: name,
+          // we use a flow finisher to allow middlewares to tweak the return value before resolution
+          fn: (val: any): FlowFinisher => ({
+            value: val,
+            resolution,
+            accepter: resolve,
+            rejecter: reject,
+          }),
+          actionType: ActionContextActionType.Async,
+          overrideContext: ctxOverride(stepType),
+          isFlowFinisher: true,
+        }).call(target, value)
+      }
+
+      function resume(
+        genFn: (value: any) => IteratorResult<any>,
+        stepType: ActionContextAsyncStepType,
+        value: unknown
+      ): void {
         let ret: unknown
         try {
           ret = wrapInAction({
             nameOrNameFn: name,
-            fn: genNext,
+            fn: genFn,
             actionType: ActionContextActionType.Async,
-            overrideContext: ctxOverride(ActionContextAsyncStepType.Resume),
-          }).call(target, res)
+            overrideContext: ctxOverride(stepType),
+          }).call(target, value)
         } catch (e) {
-          wrapInAction({
-            nameOrNameFn: name,
-            fn: (err: any) => {
-              // we use a flow finisher to allow middlewares to tweak the return value before resolution
-              return {
-                value: err,
-                resolution: "reject",
-
-                accepter: resolve,
-                rejecter: reject,
-              } as FlowFinisher
-            },
-            actionType: ActionContextActionType.Async,
-            overrideContext: ctxOverride(ActionContextAsyncStepType.Throw),
-            isFlowFinisher: true,
-          }).call(target, e)
+          finish(ActionContextAsyncStepType.Throw, "reject", e)
           return
         }
 
         next(ret)
       }
 
-      function onRejected(err: unknown): void {
-        let ret: unknown
-        try {
-          ret = wrapInAction({
-            nameOrNameFn: name,
-            fn: genThrow,
-            actionType: ActionContextActionType.Async,
-            overrideContext: ctxOverride(ActionContextAsyncStepType.ResumeError),
-          }).call(target, err)
-        } catch (e) {
-          wrapInAction({
-            nameOrNameFn: name,
-            fn: (err: any) => {
-              // we use a flow finisher to allow middlewares to tweak the return value before resolution
-              return {
-                value: err,
-                resolution: "reject",
-
-                accepter: resolve,
-                rejecter: reject,
-              } as FlowFinisher
-            },
-            actionType: ActionContextActionType.Async,
-            overrideContext: ctxOverride(ActionContextAsyncStepType.Throw),
-            isFlowFinisher: true,
-          }).call(target, e)
-          return
-        }
+      function onFulfilled(res: unknown): void {
+        resume(genNext, ActionContextAsyncStepType.Resume, res)
+      }
 
-        next(ret)
+      function onRejected(err: unknown): void {
+        resume(genThrow, ActionContextAsyncStepType.ResumeError, err)
       }
 
       function next(ret: any): void {
@@ -134,23 +119,7 @@ export function flow<R, Args extends any[]>({
           // an async iterator
           Promise.resolve(ret).then(next, reject).catch(reject)
         } else if (ret.done) {
-          // done
-          wrapInAction({
-            nameOrNameFn: name,
-            fn: (val: any) => {
-              // we use a flow finisher to allow middlewares to tweak the return value before resolution
-              return {
-                value: val,
-                resolution: "accept",
-
-                accepter: resolve,
-                rejecter: reject,
-              } as FlowFinisher
-            },
-            actionType: ActionContextActionType.Async,
-            overrideContext: ctxOverride(ActionContextAsyncStepType.Return),
-            isFlowFinisher: true,
-          }).call(target, ret.value)
+          finish(ActionContextAsyncStepType.Return, "accept", ret.value)
         } else {
           // continue
           Promise.resolve(ret.value).then(onFulfilled, onRejected).catch(reject)

package/src/actionMiddlewares/actionTrackingMiddleware.ts

@@ -178,8 +178,11 @@ export function actionTrackingMiddleware(
   const resumeSuspendSupport = !!hooks.onResume || !!hooks.onSuspend
 
   const filter: ActionMiddleware["filter"] = (ctx) => {
-    if (ctx.type === ActionContextActionType.Sync) {
-      // start and finish is on the same context
+    if (
+      ctx.type === ActionContextActionType.Sync ||
+      ctx.asyncStepType === ActionContextAsyncStepType.Spawn
+    ) {
+      // (for sync actions start and finish are on the same context)
       const accepted = userFilter(ctx)
       if (accepted) {
         setCtxData(ctx, {
@@ -188,39 +191,21 @@ export function actionTrackingMiddleware(
         })
       }
       return accepted
-    } else {
-      switch (ctx.asyncStepType) {
-        case ActionContextAsyncStepType.Spawn: {
-          const accepted = userFilter(ctx)
-          if (accepted) {
-            setCtxData(ctx, {
-              startAccepted: true,
-              state: State.Idle,
-            })
-          }
-          return accepted
-        }
+    }
 
-        case ActionContextAsyncStepType.Return:
-        case ActionContextAsyncStepType.Throw: {
-          // depends if the spawn one was accepted or not
-          const data = getCtxData(ctx.spawnAsyncStepContext!)
-          return data ? data.startAccepted : false
-        }
+    // the other steps depend on whether the spawn one was accepted or not
+    const spawnAccepted = () => !!getCtxData(ctx.spawnAsyncStepContext!)?.startAccepted
+    switch (ctx.asyncStepType) {
+      case ActionContextAsyncStepType.Return:
+      case ActionContextAsyncStepType.Throw:
+        return spawnAccepted()
 
-        case ActionContextAsyncStepType.Resume:
-        case ActionContextAsyncStepType.ResumeError:
-          if (resumeSuspendSupport) {
-            // depends if the spawn one was accepted or not
-            const data = getCtxData(ctx.spawnAsyncStepContext!)
-            return data ? data.startAccepted : false
-          } else {
-            return false
-          }
+      case ActionContextAsyncStepType.Resume:
+      case ActionContextAsyncStepType.ResumeError:
+        return resumeSuspendSupport && spawnAccepted()
 
-        default:
-          return false
-      }
+      default:
+        return false
     }
   }
 
@@ -311,57 +296,42 @@ export function actionTrackingMiddleware(
       }
     }
 
-    if (ctx.type === ActionContextActionType.Sync) {
-      let retObj = start(simpleCtx)
-
-      if (retObj) {
+    if (
+      ctx.type === ActionContextActionType.Sync ||
+      ctx.asyncStepType === ActionContextAsyncStepType.Spawn
+    ) {
+      const overriddenRetObj = start(simpleCtx)
+      if (overriddenRetObj) {
         // action canceled / overridden by onStart
         resume(simpleCtx, true)
         suspend(simpleCtx)
-        retObj = finish(simpleCtx, retObj)
-      } else {
-        try {
-          retObj = { result: ActionTrackingResult.Return, value: next() }
-        } catch (err) {
-          retObj = { result: ActionTrackingResult.Throw, value: err }
-        }
-        retObj = finish(simpleCtx, retObj)
+        return returnOrThrowActionTrackingReturn(finish(simpleCtx, overriddenRetObj))
+      }
+
+      if (ctx.type !== ActionContextActionType.Sync) {
+        // a flow finishes in its return / throw step
+        return next()
       }
 
-      return returnOrThrowActionTrackingReturn(retObj)
+      let retObj: ActionTrackingReturn
+      try {
+        retObj = { result: ActionTrackingResult.Return, value: next() }
+      } catch (err) {
+        retObj = { result: ActionTrackingResult.Throw, value: err }
+      }
+      return returnOrThrowActionTrackingReturn(finish(simpleCtx, retObj))
     } else {
       // async
 
       switch (ctx.asyncStepType) {
-        case ActionContextAsyncStepType.Spawn: {
-          let retObj = start(simpleCtx)
-          if (retObj) {
-            // action canceled / overridden by onStart
-            resume(simpleCtx, true)
-            suspend(simpleCtx)
-            retObj = finish(simpleCtx, retObj)
-            return returnOrThrowActionTrackingReturn(retObj)
-          } else {
-            return next()
-          }
-        }
-
-        case ActionContextAsyncStepType.Return: {
-          const flowFinisher: FlowFinisher = next()
-          const retObj = finish(simpleCtx, {
-            result: ActionTrackingResult.Return,
-            value: flowFinisher.value,
-          })
-          flowFinisher.resolution =
-            retObj.result === ActionTrackingResult.Return ? "accept" : "reject"
-          flowFinisher.value = retObj.value
-          return flowFinisher
-        }
-
+        case ActionContextAsyncStepType.Return:
         case ActionContextAsyncStepType.Throw: {
           const flowFinisher: FlowFinisher = next()
           const retObj = finish(simpleCtx, {
-            result: ActionTrackingResult.Throw,
+            result:
+              ctx.asyncStepType === ActionContextAsyncStepType.Return
+                ? ActionTrackingResult.Return
+                : ActionTrackingResult.Throw,
             value: flowFinisher.value,
           })
           flowFinisher.resolution =

package/src/actionMiddlewares/transactionMiddleware.ts

@@ -1,10 +1,10 @@
 import type { ActionMiddlewareDisposer } from "../action/middleware"
+import { runUnprotected } from "../action/runUnprotected"
 import type { AnyModel } from "../model/BaseModel"
 import { assertIsModel } from "../model/utils"
 import { addModelClassInitializer } from "../modelShared/modelClassInitializer"
-import { applyPatches } from "../patch"
-import { internalPatchRecorder, type PatchRecorder } from "../patch/patchRecorder"
-import { withTypeCheckingBatch } from "../tweaker/typeChecking"
+import { ChangeRollbackRecorder } from "../tweaker/changeRollback"
+import { withoutTypeChecking } from "../tweaker/withoutTypeChecking"
 import { assertIsObject, failure, MobxKeystoneAggregateError } from "../utils"
 import { checkDecoratorContext } from "../utils/decorators"
 import { pushDelayedError } from "../utils/forEachWithDelayedThrow"
@@ -16,7 +16,7 @@ import {
 
 /**
  * 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`).
@@ -36,18 +36,18 @@ export function transactionMiddleware<M extends AnyModel>(target: {
     throw failure("target.actionName must be a string")
   }
 
-  const patchRecorderSymbol = Symbol("patchRecorder")
-  function initPatchRecorder(ctx: SimpleActionContext) {
-    ctx.rootContext.data[patchRecorderSymbol] = {
-      recorder: internalPatchRecorder(undefined, { recording: false }),
+  const rollbackRecorderSymbol = Symbol("rollbackRecorder")
+  function initRollbackRecorder(ctx: SimpleActionContext) {
+    ctx.rootContext.data[rollbackRecorderSymbol] = {
+      recorder: new ChangeRollbackRecorder(),
       activeCount: 0,
     }
   }
-  function getPatchRecorderData(ctx: SimpleActionContext): {
-    recorder: PatchRecorder
+  function getRollbackRecorderData(ctx: SimpleActionContext): {
+    recorder: ChangeRollbackRecorder
     activeCount: number
   } {
-    return ctx.rootContext.data[patchRecorderSymbol]
+    return ctx.rootContext.data[rollbackRecorderSymbol]
   }
 
   return actionTrackingMiddleware(model, {
@@ -58,55 +58,54 @@ export function transactionMiddleware<M extends AnyModel>(target: {
     },
     onStart(ctx) {
       if (ctx === ctx.rootContext) {
-        initPatchRecorder(ctx)
+        initRollbackRecorder(ctx)
       }
     },
     // Actions nest, so recording must only stop once every action of the transaction
     // has been suspended, not as soon as the innermost one returns.
     onResume(ctx) {
-      const data = getPatchRecorderData(ctx)
+      const data = getRollbackRecorderData(ctx)
       data.activeCount++
       data.recorder.recording = true
     },
     onSuspend(ctx) {
-      const data = getPatchRecorderData(ctx)
+      const data = getRollbackRecorderData(ctx)
       data.activeCount--
       data.recorder.recording = data.activeCount > 0
     },
     onFinish(ctx, ret) {
       if (ctx === ctx.rootContext) {
-        const patchRecorder = getPatchRecorderData(ctx).recorder
+        const recorder = getRollbackRecorderData(ctx).recorder
+        // stop recording, so the rollback is not recorded as well
+        recorder.dispose()
 
-        try {
-          if (ret.result === ActionTrackingResult.Throw) {
-            // undo changes (backwards for inverse patches)
-            const { events } = patchRecorder
-            const rollbackErrors: unknown[] = []
-            withTypeCheckingBatch(() => {
-              for (let i = events.length - 1; i >= 0; i--) {
-                const event = events[i]
-                // A listener may throw after a patch has already been applied.
-                // Continue at patch granularity so one failure cannot skip the
-                // remaining restoration, including patches from the same edit.
-                for (let j = event.inversePatches.length - 1; j >= 0; j--) {
-                  try {
-                    applyPatches(event.target, [event.inversePatches[j]])
-                  } catch (error) {
-                    pushDelayedError(rollbackErrors, error)
-                  }
+        if (ret.result === ActionTrackingResult.Throw) {
+          // revert changes (backwards). Restoring the replaced values themselves
+          // (rather than applying inverse patches) keeps node identities, so
+          // nodes that were detached and then changed are restored too.
+          const { reverts } = recorder
+          const rollbackErrors: unknown[] = []
+          runUnprotected(() => {
+            // it restores the state before the action, which was already checked
+            withoutTypeChecking(() => {
+              for (let i = reverts.length - 1; i >= 0; i--) {
+                // A listener may throw after a change has already been reverted.
+                // Keep going so one failure cannot skip the remaining restoration.
+                try {
+                  reverts[i]()
+                } catch (error) {
+                  pushDelayedError(rollbackErrors, error)
                 }
               }
             })
-            if (rollbackErrors.length > 0) {
-              // Keep the action error first so the reason for the rollback is not lost.
-              throw new MobxKeystoneAggregateError(
-                [ret.value, ...rollbackErrors],
-                "transaction rollback callbacks failed"
-              )
-            }
+          })
+          if (rollbackErrors.length > 0) {
+            // Keep the action error first so the reason for the rollback is not lost.
+            throw new MobxKeystoneAggregateError(
+              [ret.value, ...rollbackErrors],
+              "transaction rollback callbacks failed"
+            )
           }
-        } finally {
-          patchRecorder.dispose()
         }
       }
     },
@@ -123,7 +122,7 @@ export function transaction(...args: any[]): void {
 
     checkDecoratorContext("transaction", ctx.name, ctx.static)
     if (ctx.kind !== "method" && ctx.kind !== "field") {
-      throw failure(`@transaction can only be used on fields or methods}`)
+      throw failure(`@transaction can only be used on fields or methods`)
     }
 
     ctx.addInitializer(function (this: any) {

package/src/actionMiddlewares/undoMiddleware.ts

@@ -1,12 +1,15 @@
 import type { ActionMiddlewareDisposer } from "../action/middleware"
 import { modelAction } from "../action/modelAction"
+import { type Frozen, FrozenCheckMode, frozen, isFrozenSnapshot, toFrozenSnapshot } from "../frozen"
 import { Model } from "../model/Model"
 import { model } from "../modelShared/modelDecorator"
 import { fastGetRootPath } from "../parent/path"
 import type { Path } from "../parent/pathTypes"
 import { applyPatches, type Patch, type PatchRecorder, patchRecorder } from "../patch"
+import type { FrozenData } from "../snapshot"
 import { assertTweakedObject } from "../tweaker/core"
 import { typesArray } from "../types/arrayBased/typesArray"
+import { typesFrozen } from "../types/objectBased/typesObject"
 import { tProp } from "../types/tProp"
 import { typesUnchecked } from "../types/utility/typesUnchecked"
 import {
@@ -121,16 +124,45 @@ function toSingleEvents(
   return array
 }
 
+// snapshots from before events were frozen have them as plain objects
+function toFrozenEventSnapshots(
+  events: ReadonlyArray<UndoEvent | FrozenData<UndoEvent>> | undefined
+): FrozenData<UndoEvent>[] | undefined {
+  return events?.map((e) => (isFrozenSnapshot<UndoEvent>(e) ? e : toFrozenSnapshot(e)))
+}
+
+function freezeEvent(event: UndoEvent): Frozen<UndoEvent> {
+  // events are only read once recorded, so they are not checked or deeply
+  // frozen (that would also freeze the attached states given by the user)
+  return frozen(event, FrozenCheckMode.Off)
+}
+
 /**
  * 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.
  */
 @model(`${namespace}/UndoStore`)
-export class UndoStore extends Model({
-  // TODO: add proper type checking to undo store
-  undoEvents: tProp(typesArray(typesUnchecked<UndoEvent>()), () => []),
-  redoEvents: tProp(typesArray(typesUnchecked<UndoEvent>()), () => []),
-}) {
+export class UndoStore extends Model(
+  {
+    // TODO: add proper type checking to undo store
+    undoEvents: tProp(typesArray(typesFrozen(typesUnchecked<UndoEvent>())), () => []),
+    redoEvents: tProp(typesArray(typesFrozen(typesUnchecked<UndoEvent>())), () => []),
+  },
+  {
+    fromSnapshotProcessor(sn: {
+      undoEvents?: ReadonlyArray<UndoEvent | FrozenData<UndoEvent>>
+      redoEvents?: ReadonlyArray<UndoEvent | FrozenData<UndoEvent>>
+    }) {
+      return {
+        ...sn,
+        undoEvents: toFrozenEventSnapshots(sn.undoEvents),
+        redoEvents: toFrozenEventSnapshots(sn.redoEvents),
+      }
+    },
+  }
+) {
   /**
    * @ignore
    */
@@ -201,7 +233,7 @@ export class UndoStore extends Model({
   @modelAction
   _addUndo({ event, maxUndoLevels }: { event: UndoEvent; maxUndoLevels: number | undefined }) {
     withoutUndo(() => {
-      this.undoEvents.push(event)
+      this.undoEvents.push(freezeEvent(event))
       // once an undo event is added redo queue is no longer valid
       this.redoEvents.length = 0
       this.enforceMaxLevels({ maxUndoLevels })
@@ -323,7 +355,7 @@ export class UndoManager {
    */
   @mobxComputed
   get undoQueue(): ReadonlyArray<UndoEvent> {
-    return this.store.undoEvents
+    return this.store.undoEvents.map((e) => e.data)
   }
 
   /**
@@ -332,7 +364,7 @@ export class UndoManager {
    */
   @mobxComputed
   get redoQueue(): ReadonlyArray<UndoEvent> {
-    return this.store.redoEvents
+    return this.store.redoEvents.map((e) => e.data)
   }
 
   /**
@@ -340,7 +372,7 @@ export class UndoManager {
    */
   @mobxComputed
   get undoLevels() {
-    return this.undoQueue.length
+    return this.store.undoEvents.length
   }
 
   /**
@@ -364,7 +396,7 @@ export class UndoManager {
    */
   @mobxComputed
   get redoLevels() {
-    return this.redoQueue.length
+    return this.store.redoEvents.length
   }
 
   /**
@@ -392,14 +424,15 @@ export class UndoManager {
     if (!this.canUndo) {
       throw failure("nothing to undo")
     }
-    const event = this.undoQueue[this.undoQueue.length - 1]
+    const events = this.store.undoEvents
+    const event = events[events.length - 1].data
 
     withoutUndo(() => {
-      toSingleEvents(event)
-        .reverse()
-        .forEach((e) => {
-          applyPatches(this.subtreeRoot, e.inversePatches, true)
-        })
+      applyPatches(
+        this.subtreeRoot,
+        toSingleEvents(event).map((e) => e.inversePatches),
+        true
+      )
 
       // restore the attached state before the operation was made
       if (event.attachedState) {
@@ -419,12 +452,14 @@ export class UndoManager {
     if (!this.canRedo) {
       throw failure("nothing to redo")
     }
-    const event = this.redoQueue[this.redoQueue.length - 1]
+    const events = this.store.redoEvents
+    const event = events[events.length - 1].data
 
     withoutUndo(() => {
-      toSingleEvents(event).forEach((e) => {
-        applyPatches(this.subtreeRoot, e.patches)
-      })
+      applyPatches(
+        this.subtreeRoot,
+        toSingleEvents(event).map((e) => e.patches)
+      )
 
       // restore the attached state after the operation was made
       if (event.attachedState) {
@@ -567,11 +602,11 @@ export class UndoManager {
     const genThrow = gen.throw.bind(gen)
 
     const promise = new Promise<R>((resolve, reject) => {
-      function onFulfilled(res: any): void {
+      function resume(genFn: (value: any) => IteratorResult<any>, value: unknown): void {
         group.resume()
         let ret: unknown
         try {
-          ret = genNext(res)
+          ret = genFn(value)
         } catch (e) {
           group.end()
           reject(e as Error)
@@ -582,19 +617,12 @@ export class UndoManager {
         next(ret)
       }
 
-      function onRejected(err: unknown): void {
-        group.resume()
-        let ret: unknown
-        try {
-          ret = genThrow(err)
-        } catch (e) {
-          group.end()
-          reject(e as Error)
-          return
-        }
+      function onFulfilled(res: unknown): void {
+        resume(genNext, res)
+      }
 
-        group.pause()
-        next(ret)
+      function onRejected(err: unknown): void {
+        resume(genThrow, err)
       }
 
       function next(ret: any): void {