mobx-keystone 2.0.0 → 2.1.0

package/src/snapshot/internal.ts

@@ -19,6 +19,10 @@ export interface SnapshotData {
   atom: IAtom | undefined
   // Source of truth for copy-on-write of this snapshot's untransformed data.
   untransformedFrozen: boolean
+  // When defined while `untransformed` is not frozen, every value in it except
+  // (possibly) these is already frozen, so freezing it only needs to visit them.
+  // Values listed here may no longer be in `untransformed`.
+  unfrozenValues: object[] | undefined
   dirtyChild: object | undefined
   dirtyChildSnapshot: SnapshotData | undefined
   dirtyChildPath: PathElement | undefined
@@ -94,6 +98,7 @@ export const setNewInternalSnapshot = action(
       transformed,
       atom: undefined, // will be created when first observed
       untransformedFrozen: markAsFrozen,
+      unfrozenValues: undefined,
       dirtyChild: undefined,
       dirtyChildSnapshot: undefined,
       dirtyChildPath: undefined,
@@ -113,7 +118,10 @@ export const setNewInternalSnapshot = action(
   }
 )
 
-type MutateInternalSnapshotFn<T> = (prevSn: T) => void
+/**
+ * Mutates a snapshot container in place and returns the values it wrote.
+ */
+type MutateInternalSnapshotFn<T> = (prevSn: T) => readonly unknown[]
 
 function makeSnapshotMutable(sn: SnapshotData): any {
   let untransformed = sn.untransformed
@@ -127,7 +135,39 @@ function makeSnapshotMutable(sn: SnapshotData): any {
   return untransformed
 }
 
-function setSnapshotData(sn: SnapshotData, untransformed: any, freezeIfCloned = false): void {
+function trackUnfrozenValues(
+  sn: SnapshotData,
+  untransformed: any,
+  wasFrozen: boolean,
+  writtenValues: readonly unknown[]
+): void {
+  // a cloned frozen container starts with only frozen values
+  let unfrozenValues = wasFrozen ? [] : sn.unfrozenValues
+  if (unfrozenValues === undefined) {
+    return
+  }
+  for (let i = 0; i < writtenValues.length; i++) {
+    const value = writtenValues[i]
+    if (!isPrimitive(value)) {
+      unfrozenValues.push(value)
+    }
+  }
+  const size = Array.isArray(untransformed)
+    ? untransformed.length
+    : Object.keys(untransformed).length
+  if (unfrozenValues.length > size) {
+    // cheaper to visit the whole container again
+    unfrozenValues = undefined
+  }
+  sn.unfrozenValues = unfrozenValues
+}
+
+function setSnapshotData(
+  sn: SnapshotData,
+  untransformed: any,
+  writtenValues: readonly unknown[],
+  freezeIfCloned = false
+): void {
   // `makeSnapshotMutable` returns a new container exactly when this snapshot
   // was frozen. All callers obtain `untransformed` through that helper.
   const wasFrozen = untransformed !== sn.untransformed
@@ -138,6 +178,11 @@ function setSnapshotData(sn: SnapshotData, untransformed: any, freezeIfCloned =
 
   const keepFrozen = freezeIfCloned && wasFrozen && !sn.transformFn
   sn.untransformedFrozen = keepFrozen
+  if (keepFrozen) {
+    sn.unfrozenValues = undefined
+  } else {
+    trackUnfrozenValues(sn, untransformed, wasFrozen, writtenValues)
+  }
   if (wasFrozen && !keepFrozen) {
     snapshotStates.set(untransformed, sn)
   }
@@ -152,8 +197,8 @@ function setSnapshotData(sn: SnapshotData, untransformed: any, freezeIfCloned =
 
 function updateOwnSnapshot<T>(sn: SnapshotData, mutate: MutateInternalSnapshotFn<T>): void {
   const untransformed = makeSnapshotMutable(sn)
-  mutate(untransformed)
-  setSnapshotData(sn, untransformed)
+  const writtenValues = mutate(untransformed)
+  setSnapshotData(sn, untransformed, writtenValues)
   sn.atom?.reportChanged()
 }
 
@@ -164,7 +209,7 @@ function updateParentSlot(parentSn: SnapshotData, path: PathElement, value: any)
   } else {
     untransformed[path] = value
   }
-  setSnapshotData(parentSn, untransformed)
+  setSnapshotData(parentSn, untransformed, [value])
   parentSn.atom?.reportChanged()
 }
 
@@ -175,7 +220,8 @@ function flushDirtyChild(
   childSn: SnapshotData,
   childPath: PathElement,
   freezeAfterFlush: boolean,
-  freezeClonedContainer: boolean
+  freezeClonedContainer: boolean,
+  writtenValues: unknown[]
 ): void {
   if (childSn.isUnset) {
     return
@@ -200,6 +246,7 @@ function flushDirtyChild(
   } else {
     untransformed[childPath] = childSn.transformed
   }
+  writtenValues.push(childSn.transformed)
 }
 
 function flushDirtyChildren(node: object, sn: SnapshotData, freezeAfterFlush: boolean): boolean {
@@ -218,6 +265,7 @@ function flushDirtyChildren(node: object, sn: SnapshotData, freezeAfterFlush: bo
   const untransformed = makeSnapshotMutable(sn)
   const freezeClonedContainer =
     freezeAfterFlush && untransformed !== sn.untransformed && !sn.transformFn
+  const writtenValues: unknown[] = []
 
   flushDirtyChild(
     node,
@@ -226,7 +274,8 @@ function flushDirtyChildren(node: object, sn: SnapshotData, freezeAfterFlush: bo
     dirtyChildSnapshot,
     dirtyChildPath,
     freezeAfterFlush,
-    freezeClonedContainer
+    freezeClonedContainer,
+    writtenValues
   )
   additionalDirtyChildren?.forEach((dirtyChild, child) => {
     flushDirtyChild(
@@ -236,11 +285,12 @@ function flushDirtyChildren(node: object, sn: SnapshotData, freezeAfterFlush: bo
       dirtyChild.snapshot,
       dirtyChild.path,
       freezeAfterFlush,
-      freezeClonedContainer
+      freezeClonedContainer,
+      writtenValues
     )
   })
 
-  setSnapshotData(sn, untransformed, freezeClonedContainer)
+  setSnapshotData(sn, untransformed, writtenValues, freezeClonedContainer)
   return freezeClonedContainer
 }
 
@@ -383,7 +433,13 @@ export function freezeInternalSnapshot<T extends PrimitiveValue | object>(data:
     freezeInternalSnapshot(owner.untransformed)
   }
 
-  if (Array.isArray(data)) {
+  const unfrozenValues =
+    owner !== undefined && owner.untransformed === data ? owner.unfrozenValues : undefined
+  if (unfrozenValues !== undefined) {
+    for (let i = 0; i < unfrozenValues.length; i++) {
+      freezeInternalSnapshot(unfrozenValues[i])
+    }
+  } else if (Array.isArray(data)) {
     for (let i = 0; i < data.length; i++) {
       freezeInternalSnapshot(data[i])
     }
@@ -398,6 +454,7 @@ export function freezeInternalSnapshot<T extends PrimitiveValue | object>(data:
 
   if (owner !== undefined && owner.untransformed === data) {
     owner.untransformedFrozen = true
+    owner.unfrozenValues = undefined
   }
 
   return data

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,43 +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 {
-  const metadata = treeNodeMetadata.get(value as object)
-  return metadata?.tweaked === true && (canBeDataObject || metadata.dataObjectParent === undefined)
+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)
   }