mobx-keystone 1.25.0 → 2.1.0

package/src/treeUtils/sandbox.ts

@@ -7,7 +7,6 @@ import { createContext } from "../context"
 import { getParentToChildPath, resolvePath } from "../parent/path"
 import { applyPatches } from "../patch/applyPatches"
 import { onPatches } from "../patch/emitPatch"
-import type { Patch } from "../patch/Patch"
 import { type PatchRecorder, patchRecorder } from "../patch/patchRecorder"
 import {
   fastIsRootStoreNoAtom,
@@ -78,11 +77,6 @@ export class SandboxManager {
    */
   private allowWrite: ReadonlyMiddlewareReturn["allowWrite"]
 
-  /**
-   * Whether changes made in the sandbox are currently being committed to the original subtree.
-   */
-  private isCommitting = false
-
   private readonly subtreeRoot: object
 
   /**
@@ -127,11 +121,9 @@ export class SandboxManager {
       if (this.withSandboxPatchRecorder) {
         throw failure("original subtree must not change while 'withSandbox' executes")
       }
-      if (!this.isCommitting) {
-        this.allowWrite(() => {
-          applyPatches(this.subtreeRootClone, patches)
-        })
-      }
+      this.allowWrite(() => {
+        applyPatches(this.subtreeRootClone, patches)
+      })
     })
 
     const { allowWrite, dispose: disposeReadonlyMW } = readonlyMiddleware(this.subtreeRootClone)
@@ -232,26 +224,38 @@ export class SandboxManager {
       }
       if (commit) {
         if (!isNestedWithSandboxCall) {
-          const patches: Patch[] = []
-          const len = recorder.events.length
-          for (let i = 0; i < len; i++) {
-            patches.push(...recorder.events[i].patches)
-          }
-
-          const isCommitting = this.isCommitting
-          this.isCommitting = true
-          try {
-            applyPatches(this.subtreeRoot, patches)
-          } finally {
-            this.isCommitting = isCommitting
-          }
+          const events = recorder.events
+          // The clone already holds these changes, so revert them and let the regular
+          // patch sync mirror the original's final state back in. That way anything a
+          // listener changes on the original during the commit reaches the clone too,
+          // at a cost proportional to the changes rather than to the tree size.
+          // Both halves run in a single action so that observers of the sandbox never
+          // see the reverted intermediate state.
+          runInAction(() => {
+            this.allowWrite(() => {
+              for (let i = events.length - 1; i >= 0; i--) {
+                applyPatches(this.subtreeRootClone, events[i].inversePatches, true)
+              }
+            })
+            applyPatches(
+              this.subtreeRoot,
+              events.map((event) => event.patches)
+            )
+          })
         }
       } else {
         this.allowWrite(() => {
           runInAction(() => {
-            let i = recorder.events.length
-            while (i-- > numRecorderEvents) {
-              applyPatches(this.subtreeRootClone, recorder.events[i].inversePatches, true)
+            const wasRecording = recorder.recording
+            recorder.recording = false
+            try {
+              let i = recorder.events.length
+              while (i-- > numRecorderEvents) {
+                applyPatches(this.subtreeRootClone, recorder.events[i].inversePatches, true)
+              }
+              recorder.events.splice(numRecorderEvents)
+            } finally {
+              recorder.recording = wasRecording
             }
           })
         })

package/src/tweaker/changeRollback.ts

@@ -0,0 +1,218 @@
+import { type IArrayDidChange, type IObjectDidChange, remove, set } from "mobx"
+import type { AnyModel } from "../model/BaseModel"
+import type { DelayedError } from "../utils/forEachWithDelayedThrow"
+import { forEachTypedModelAncestor, isTypeCheckingAfterChangeEnabled } from "./typeChecking"
+import { withoutTypeChecking } from "./withoutTypeChecking"
+
+// Rolling back tree changes that failed partway (not to be confused with the
+// undo manager, which records user-level history): a change batch makes
+// `applySnapshot` / `applyPatches` all or nothing, and rollback recorders make
+// transactions revertible. Both restore the live values each change replaced.
+
+interface ChangeBatch {
+  /** Whether the changed models are type checked when the batch completes. */
+  validate: boolean
+  models: Set<AnyModel>
+  /** How to revert each recorded change, oldest first. */
+  reverts: (() => void)[]
+  recording: boolean
+  /** Last recorded change target, so a run of changes to it walks ancestors once. */
+  previousTarget?: object
+}
+
+let changeBatch: ChangeBatch | undefined
+
+const noListenerError = Symbol("noListenerError")
+let lastListenerError: unknown = noListenerError
+
+/**
+ * @internal
+ * Rethrows the errors thrown by the listeners of an applied change. A change
+ * batch does not roll back for them: the change itself was valid.
+ */
+export function throwDelayedListenerError(delayedError: DelayedError): void {
+  if (delayedError) {
+    lastListenerError = delayedError.value
+    throw delayedError.value
+  }
+}
+
+/**
+ * @internal
+ * Leaves the type check of a new model to the validating change batch being
+ * recorded, if any. Returns whether it did.
+ */
+export function deferModelTypeCheckToBatch(model: AnyModel): boolean {
+  if (changeBatch?.recording && changeBatch.validate) {
+    changeBatch.models.add(model)
+    return true
+  }
+  return false
+}
+
+/**
+ * @internal
+ * Records how to revert every change made while `recording` is set, wherever
+ * it happens, until disposed. Used to roll back failed transactions.
+ */
+export class ChangeRollbackRecorder {
+  recording = false
+  readonly reverts: (() => void)[] = []
+
+  constructor() {
+    rollbackRecorders.add(this)
+  }
+
+  dispose(): void {
+    rollbackRecorders.delete(this)
+  }
+}
+
+const rollbackRecorders = new Set<ChangeRollbackRecorder>()
+
+// (a suspended transaction keeps its recorder without recording)
+function isAnyRollbackRecorderRecording(): boolean {
+  for (const recorder of rollbackRecorders) {
+    if (recorder.recording) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * @internal
+ * Records how to revert a change for the change batch and the rollback
+ * recorders. It captures stored values before any listener can mutate them again. Restoring
+ * live values preserves identity and literal data, without snapshot processors
+ * or model defaults changing the state being restored.
+ */
+export function recordChangeForRollback(change: IObjectDidChange | IArrayDidChange): void {
+  const batch = changeBatch?.recording ? changeBatch : undefined
+  if (!batch && !isAnyRollbackRecorderRecording()) return
+  if (
+    change.type === "splice" &&
+    change.addedCount === change.removedCount &&
+    change.added.every((value, index) => value === change.removed[index])
+  )
+    return
+
+  const target = change.object
+  if (batch?.validate && target !== batch.previousTarget) {
+    forEachTypedModelAncestor(target, (model) => batch.models.add(model))
+    batch.previousTarget = target
+  }
+
+  const revert = createRevert(change)
+  batch?.reverts.push(revert)
+  for (const recorder of rollbackRecorders) {
+    if (recorder.recording) {
+      recorder.reverts.push(revert)
+    }
+  }
+}
+
+function createRevert(change: IObjectDidChange | IArrayDidChange): () => void {
+  if (change.type === "splice") {
+    const { object, index, addedCount } = change
+    const removed = change.removed.slice()
+    return () => object.spliceWithArray(index, addedCount, removed)
+  }
+  if ("index" in change) {
+    const { object, index, oldValue } = change
+    return () => {
+      object[index] = oldValue
+    }
+  }
+  const { object } = change
+  const key = change.name as string
+  if (change.type === "add") {
+    return () => remove(object, key)
+  }
+  const { oldValue } = change
+  return () => set(object, key, oldValue)
+}
+
+/**
+ * Reverts the changes recorded since `start`, newest first. Rollback publishes
+ * compensating changes, just like snapshot reconciliation.
+ */
+function rollBackBatch(batch: ChangeBatch, start: number): void {
+  batch.recording = false
+  try {
+    withoutTypeChecking(() => {
+      for (let i = batch.reverts.length - 1; i >= start; i--) {
+        try {
+          batch.reverts[i]()
+        } catch {
+          // Keep restoring after a rollback listener throws. The original
+          // failure takes precedence over errors from compensating changes.
+        }
+      }
+    })
+  } finally {
+    batch.reverts.length = start
+    batch.recording = true
+  }
+}
+
+/**
+ * @internal
+ * Applies the changes made by `fn` as a whole: when it throws, or when the
+ * changed models fail automatic type checking afterwards, the changes are
+ * rolled back before the error is rethrown. Errors thrown by the listeners of
+ * a change do not roll back, since the change itself was valid.
+ * A nested call only rolls back its own changes, while validation runs once
+ * the outermost call completes. Synchronous listener edits join the batch.
+ */
+export function withChangeBatch(fn: () => void): void {
+  const outer = changeBatch
+  if (outer) {
+    if (!outer.recording) {
+      // (rolling back)
+      fn()
+      return
+    }
+    const start = outer.reverts.length
+    try {
+      fn()
+    } catch (error) {
+      if (error !== lastListenerError) {
+        rollBackBatch(outer, start)
+      }
+      throw error
+    }
+    return
+  }
+
+  const batch: ChangeBatch = {
+    validate: isTypeCheckingAfterChangeEnabled(),
+    models: new Set(),
+    reverts: [],
+    recording: true,
+  }
+  changeBatch = batch
+  lastListenerError = noListenerError
+  let validating = false
+  try {
+    if (batch.validate) {
+      withoutTypeChecking(fn)
+      // MobX has now invalidated dependencies, including added/removed keys.
+      validating = true
+      for (const model of batch.models) {
+        const error = model.typeCheck()
+        if (error) error.throw()
+      }
+    } else {
+      fn()
+    }
+  } catch (error) {
+    if (validating || error !== lastListenerError) {
+      rollBackBatch(batch, 0)
+    }
+    throw error
+  } finally {
+    changeBatch = undefined
+    lastListenerError = noListenerError
+  }
+}

package/src/tweaker/core.ts

@@ -1,45 +1,56 @@
 import { runInAction } from "mobx"
 import { hasDataObjectParent } from "../parent/core"
 import { failure, isPrimitive } from "../utils"
-import { treeNodeMetadata } from "./treeNodeMetadata"
+import { type TreeNodeMetadata, treeNodeMetadata } from "./treeNodeMetadata"
+import { resyncTweakedChangeListeners } from "./tweakedChangeListeners"
 
-type Untweaker = (() => void) & {
-  [secondaryUntweakerSymbol]?: () => void
-}
+// untweaked objects that keep the MobX handlers they got when tweaked, which
+// do nothing until they are tweaked again
+const objectsWithIdleHandlers = new WeakSet<object>()
 
-const secondaryUntweakerSymbol = Symbol("secondaryUntweaker")
+/**
+ * Activates the MobX handlers of a fully tweaked plain object or array, and
+ * returns whether they still have to be installed. Untweaking keeps them idle
+ * rather than disposing them, so no disposers are kept for every node. When
+ * idle handlers are reused, the tweaked change listeners are resynced, since
+ * they missed the changes made while the handlers were idle.
+ *
+ * @internal
+ */
+export function activateHandlers(value: object): boolean {
+  treeNodeMetadata.get(value)!.handlersActive = true
+  if (!objectsWithIdleHandlers.delete(value)) {
+    return true
+  }
+  resyncTweakedChangeListeners(value)
+  return false
+}
 
 /**
- * Stores two existing cleanup functions without allocating a third function to
- * close over them. The primary function is internal and never exposed.
+ * Makes the MobX handlers of an untweaked plain object or array idle.
  *
  * @internal
  */
-export function setTweakedObjectUntweakers(
-  value: object,
-  primaryUntweaker: Untweaker,
-  secondaryUntweaker: () => void
-): void {
-  primaryUntweaker[secondaryUntweakerSymbol] = secondaryUntweaker
-  treeNodeMetadata.get(value)!.untweaker = primaryUntweaker
+export function deactivateHandlers(value: object, metadata: TreeNodeMetadata): void {
+  metadata.handlersActive = false
+  objectsWithIdleHandlers.add(value)
 }
 
 /**
+ * Whether the MobX handlers of a plain object or array are active.
+ *
  * @internal
  */
-export function isTweakedObject(value: unknown, canBeDataObject: boolean): value is object {
-  if (!canBeDataObject && hasDataObjectParent(value as object)) {
-    return false
-  }
-  return treeNodeMetadata.get(value as object)?.tweaked === true
+export function areHandlersActive(value: object): boolean {
+  return treeNodeMetadata.get(value)?.handlersActive === true
 }
 
 /**
  * @internal
  */
-export function runTweakedObjectUntweakers(untweaker: Untweaker): void {
-  untweaker()
-  untweaker[secondaryUntweakerSymbol]?.()
+export function isTweakedObject(value: unknown, canBeDataObject: boolean): value is object {
+  const metadata = treeNodeMetadata.get(value as object)
+  return metadata?.tweaked === true && (canBeDataObject || metadata.dataObjectParent === undefined)
 }
 
 /**

package/src/tweaker/treeNodeMetadata.ts

@@ -5,11 +5,20 @@ import type { SnapshotData } from "../snapshot/internal"
 /** @internal */
 export interface TreeNodeMetadata {
   tweaked: boolean
-  untweaker: (() => void) | undefined
+  /**
+   * Set once a plain object or array is fully tweaked, and unset when it is
+   * untweaked. Its MobX handlers do nothing while unset.
+   */
+  handlersActive: boolean
   parentPath: ParentPath<object> | undefined
   dataObjectParent: object | undefined
   objectChildren: ObjectChildrenData | undefined
   snapshot: SnapshotData | undefined
+  /**
+   * Increases every time the node is added to a parent's children, so it
+   * orders siblings like the parent's children set does.
+   */
+  attachOrder: number
 }
 
 /** @internal */
@@ -21,11 +30,12 @@ export function getOrCreateTreeNodeMetadata(value: object): TreeNodeMetadata {
   if (!metadata) {
     metadata = {
       tweaked: false,
-      untweaker: undefined,
+      handlersActive: false,
       parentPath: undefined,
       dataObjectParent: undefined,
       objectChildren: undefined,
       snapshot: undefined,
+      attachOrder: 0,
     }
     treeNodeMetadata.set(value, metadata)
   }

package/src/tweaker/tweak.ts

@@ -1,14 +1,28 @@
-import { action } from "mobx"
+import { action, isObservableArray, isObservableObject } from "mobx"
 import { isDataModel } from "../dataModel/utils"
+import { Frozen } from "../frozen/Frozen"
 import { isModelAutoTypeCheckingEnabled } from "../globalConfig/globalConfig"
+import { getModelMetadata } from "../model/getModelMetadata"
+import { isModel } from "../model/utils"
 import { getObjectChildren } from "../parent/coreObjectChildren"
 import { fastGetParent, type ParentPath } from "../parent/path"
 import { setParent } from "../parent/setParent"
+import { fastIsRootStoreNoAtom } from "../rootStore/rootStore"
 import { unsetInternalSnapshot } from "../snapshot/internal"
 import type { AnyStandardType, TypeToData } from "../types/schemas"
 import { typeCheck } from "../types/typeCheck"
-import { failure, inDevMode, isMap, isObject, isPrimitive, isSet } from "../utils"
-import { isTweakedObject, runTweakedObjectUntweakers } from "./core"
+import {
+  failure,
+  inDevMode,
+  isArray,
+  isMap,
+  isObject,
+  isPlainObject,
+  isPrimitive,
+  isSet,
+} from "../utils"
+import { getSafeErrorValuePreview } from "../utils/errorDiagnostics"
+import { deactivateHandlers, isTweakedObject } from "./core"
 import { registerDefaultTweakers } from "./registerDefaultTweakers"
 import { treeNodeMetadata } from "./treeNodeMetadata"
 
@@ -99,9 +113,7 @@ function internalTweak<T>(value: T, parentPath: ParentPath<any> | undefined): T
 
   // unsupported (must go before plain object tweaker)
   if (isDataModel(value)) {
-    throw failure(
-      "data models are not directly supported. you may insert the data in the tree instead ('$' property)."
-    )
+    throw dataModelsNotSupportedError()
   }
 
   registerDefaultTweakers()
@@ -115,18 +127,24 @@ function internalTweak<T>(value: T, parentPath: ParentPath<any> | undefined): T
     }
   }
 
-  // unsupported
+  throw unsupportedValueError(value)
+}
+
+function dataModelsNotSupportedError() {
+  return failure(
+    "data models are not directly supported. you may insert the data in the tree instead ('$' property)."
+  )
+}
+
+function unsupportedValueError(value: unknown) {
   if (isMap(value)) {
-    throw failure("maps are not directly supported. consider using 'ObjectMap' / 'asMap' instead.")
+    return failure("maps are not directly supported. consider using 'ObjectMap' / 'asMap' instead.")
   }
-
-  // unsupported
   if (isSet(value)) {
-    throw failure("sets are not directly supported. consider using 'ArraySet' / 'asSet' instead.")
+    return failure("sets are not directly supported. consider using 'ArraySet' / 'asSet' instead.")
   }
-
-  throw failure(
-    `tweak can only work over models, observable objects/arrays, or primitives, but got ${value} instead`
+  return failure(
+    `tweak can only work over models, observable objects/arrays, or primitives, but got ${getSafeErrorValuePreview(value)} instead`
   )
 }
 
@@ -140,6 +158,154 @@ export function tweak<T>(value: T, parentPath: ParentPath<any> | undefined): T {
   return isPrimitive(value) ? value : tweakNonPrimitive(value, parentPath)
 }
 
+/**
+ * Tells whether a node that has a parent gets detached by the change being
+ * intercepted before the new values are attached.
+ * @internal
+ */
+export type IsDetachedByChange = (node: object, parentPath: ParentPath<any>) => boolean
+
+// nodes to be attached by the change being checked, since a node cannot be
+// attached twice
+const seenNodes = new Set<object>()
+
+/**
+ * Throws the error `tweak` or `setParent` would throw when attaching `values`
+ * (and whatever they contain) after the change being intercepted detaches its
+ * values, without changing anything. Interceptors call it before detaching, so
+ * a rejected change leaves the tree as it was.
+ * `prepareValue`, when given, replaces each value before it is checked.
+ * @internal
+ */
+export function assertCanAttach(
+  values: unknown[],
+  isDetachedByChange: IsDetachedByChange,
+  prepareValue?: (value: unknown) => unknown
+): void {
+  try {
+    for (let i = 0; i < values.length; i++) {
+      if (prepareValue) {
+        values[i] = prepareValue(values[i])
+      }
+      checkAttach(values[i], isDetachedByChange)
+    }
+  } finally {
+    seenNodes.clear()
+  }
+}
+
+/**
+ * `assertCanAttach` for a single value.
+ * @internal
+ */
+export function assertCanAttachValue(value: unknown, isDetachedByChange: IsDetachedByChange): void {
+  if (isPrimitive(value)) {
+    return
+  }
+  try {
+    checkAttach(value, isDetachedByChange)
+  } finally {
+    seenNodes.clear()
+  }
+}
+
+function checkAttach(value: unknown, isDetachedByChange: IsDetachedByChange): void {
+  if (isPrimitive(value)) {
+    return
+  }
+
+  // (one metadata lookup instead of one per helper)
+  const metadata = treeNodeMetadata.get(value)
+  if (metadata?.tweaked) {
+    if (metadata.dataObjectParent !== undefined) {
+      throw failure("value must be the model object instance instead of the '$' sub-object")
+    }
+    if (fastIsRootStoreNoAtom(value)) {
+      throw failure("root stores cannot be attached to any parents")
+    }
+    if (isModel(value) && getModelMetadata(value).valueType) {
+      // setParent clones it when it has a parent
+      return
+    }
+    const parentPath = metadata.parentPath
+    if (
+      parentPath &&
+      !isDetachedByChange(value, parentPath) &&
+      !isUntweakedByChange(parentPath.parent, isDetachedByChange)
+    ) {
+      throw failure("an object cannot be assigned a new parent when it already has one")
+    }
+    assertNotSeen(value)
+    return
+  }
+
+  // the values internalTweak accepts, most common first
+  if (isPlainObject(value)) {
+    if (isObservableObject(value)) {
+      // (it becomes the tree node itself)
+      assertNotSeen(value)
+    }
+    checkAttachProps(value, isDetachedByChange)
+    return
+  }
+  if (isArray(value)) {
+    if (isObservableArray(value)) {
+      assertNotSeen(value)
+    }
+    for (let i = 0; i < value.length; i++) {
+      checkAttach(value[i], isDetachedByChange)
+    }
+    return
+  }
+  // (data models, frozen values and models can be observable objects too)
+  if (isDataModel(value)) {
+    throw dataModelsNotSupportedError()
+  }
+  if (value instanceof Frozen || isModel(value)) {
+    return
+  }
+  if (isObservableObject(value)) {
+    assertNotSeen(value)
+    checkAttachProps(value as Record<string, unknown>, isDetachedByChange)
+    return
+  }
+  throw unsupportedValueError(value)
+}
+
+function checkAttachProps(obj: Record<string, unknown>, isDetachedByChange: IsDetachedByChange) {
+  const keys = Object.keys(obj)
+  for (let i = 0; i < keys.length; i++) {
+    checkAttach(obj[keys[i]], isDetachedByChange)
+  }
+}
+
+function assertNotSeen(value: object) {
+  if (seenNodes.has(value)) {
+    throw failure("an object cannot be assigned a new parent when it already has one")
+  }
+  seenNodes.add(value)
+}
+
+/**
+ * Detaching a plain object or array untweaks it, which detaches its children.
+ */
+function isUntweakedByChange(node: object, isDetachedByChange: IsDetachedByChange): boolean {
+  for (;;) {
+    const metadata = treeNodeMetadata.get(node)
+    if (!metadata?.handlersActive) {
+      return false
+    }
+    const parentPath = metadata.parentPath
+    if (!parentPath) {
+      return false
+    }
+    if (isDetachedByChange(node, parentPath)) {
+      return true
+    }
+    node = parentPath.parent
+  }
+}
+
 /**
  * @internal
  */
@@ -155,8 +321,7 @@ export function tryUntweak(value: any): (() => void) | undefined {
   }
 
   const metadata = treeNodeMetadata.get(value)
-  const untweaker = metadata?.untweaker
-  if (!untweaker) {
+  if (!metadata?.handlersActive) {
     return undefined
   }
 
@@ -176,14 +341,13 @@ export function tryUntweak(value: any): (() => void) | undefined {
   }
 
   return () => {
-    // post-untweaking, call the untweaker
-    runTweakedObjectUntweakers(untweaker)
+    // post-untweaking
+    deactivateHandlers(value, metadata)
 
     // Match the former independent-map ordering: the node stops being tweaked
     // before its snapshot is unset, but the shared record must stay alive until
     // snapshot cleanup has consumed it.
     metadata.tweaked = false
-    metadata.untweaker = undefined
     unsetInternalSnapshot(value)
     // These associations previously lived in independent WeakMaps and remain
     // valid across untweak/retweak, so keep their shared record when present.