mobx-keystone 1.22.0 → 1.24.0

package/src/deepChange/onDeepChange.ts

@@ -1,8 +1,8 @@
 import { action, isAction } from "mobx"
-import { fastGetParentPath } from "../parent/path"
-import type { Path, WritablePath } from "../parent/pathTypes"
+import { fastGetParentPath, type ParentPath } from "../parent/path"
+import type { Path, PathElement, WritablePath } from "../parent/pathTypes"
 import { assertTweakedObject } from "../tweaker/core"
-import { assertIsFunction, deleteFromArray } from "../utils"
+import { assertIsFunction, deleteFromArray, failure } from "../utils"
 
 /**
  * Disposer function to stop listening to deep changes.
@@ -99,11 +99,26 @@ export type OnDeepChangeListener = (change: DeepChange) => void
 
 const deepChangeListeners = new WeakMap<object, OnDeepChangeListener[]>()
 const globalDeepChangeListeners: ((target: object, change: DeepChange) => void)[] = []
+const emptyPath: Path = Object.freeze([])
 
 let deepChangeListenerCount = 0
 
 let initPhaseDepth = 0
 
+/**
+ * @internal
+ */
+export function hasAnyDeepChangeListeners(): boolean {
+  return deepChangeListenerCount > 0 || hasGlobalDeepChangeListeners()
+}
+
+/**
+ * @internal
+ */
+export function hasGlobalDeepChangeListeners(): boolean {
+  return globalDeepChangeListeners.length > 0
+}
+
 /**
  * @internal
  * Returns whether we're currently in an initialization phase.
@@ -132,9 +147,7 @@ export function exitInitPhase(): void {
  * @internal
  */
 export function emitDeepChange(obj: object, change: DeepChange): void {
-  const hasAnyListeners = deepChangeListenerCount > 0 || globalDeepChangeListeners.length > 0
-
-  if (!hasAnyListeners) {
+  if (!hasAnyDeepChangeListeners()) {
     return
   }
 
@@ -144,6 +157,200 @@ export function emitDeepChange(obj: object, change: DeepChange): void {
   }
 }
 
+/**
+ * @internal
+ */
+export function emitObjectAddDeepChange(
+  node: object,
+  target: object,
+  key: string,
+  newValue: unknown
+): void {
+  emitDeepChangeFromValues(node, DeepChangeType.ObjectAdd, target, key, newValue, undefined)
+}
+
+/**
+ * @internal
+ */
+export function emitObjectUpdateDeepChange(
+  node: object,
+  target: object,
+  key: string,
+  newValue: unknown,
+  oldValue: unknown
+): void {
+  emitDeepChangeFromValues(node, DeepChangeType.ObjectUpdate, target, key, newValue, oldValue)
+}
+
+/**
+ * @internal
+ */
+export function emitObjectRemoveDeepChange(
+  node: object,
+  target: object,
+  key: string,
+  oldValue: unknown
+): void {
+  emitDeepChangeFromValues(node, DeepChangeType.ObjectRemove, target, key, undefined, oldValue)
+}
+
+/**
+ * @internal
+ */
+export function emitArraySpliceDeepChange(
+  node: object,
+  target: unknown[],
+  index: number,
+  addedValues: unknown[],
+  removedValues: unknown[]
+): void {
+  emitDeepChangeFromValues(
+    node,
+    DeepChangeType.ArraySplice,
+    target,
+    index,
+    undefined,
+    undefined,
+    addedValues,
+    removedValues
+  )
+}
+
+/**
+ * @internal
+ */
+export function emitArrayUpdateDeepChange(
+  node: object,
+  target: unknown[],
+  index: number,
+  newValue: unknown,
+  oldValue: unknown
+): void {
+  emitDeepChangeFromValues(node, DeepChangeType.ArrayUpdate, target, index, newValue, oldValue)
+}
+
+function emitDeepChangeFromValues(
+  node: object,
+  type: DeepChangeType,
+  target: object | unknown[],
+  keyOrIndex: string | number,
+  newValue: unknown,
+  oldValue: unknown,
+  addedValues?: unknown[],
+  removedValues?: unknown[]
+): void {
+  let change: DeepChange | undefined
+
+  if (globalDeepChangeListeners.length > 0) {
+    change = createDeepChange(
+      type,
+      target,
+      keyOrIndex,
+      newValue,
+      oldValue,
+      addedValues,
+      removedValues
+    )
+    emitGlobalDeepChange(node, change)
+  }
+
+  if (deepChangeListenerCount === 0) {
+    return
+  }
+
+  // Segments are pushed in child-to-root order (O(1) each) rather than unshifted
+  // at the front (O(depth) each), keeping the whole walk O(depth) instead of
+  // O(depth^2) on deep trees.
+  const reversedPrefix: WritablePath = []
+  let current: object | undefined = node
+  while (current) {
+    const listenersForObject = deepChangeListeners.get(current)
+    if (listenersForObject && listenersForObject.length > 0) {
+      change ??= createDeepChange(
+        type,
+        target,
+        keyOrIndex,
+        newValue,
+        oldValue,
+        addedValues,
+        removedValues
+      )
+      emitDeepChangeForTarget(current, change, reversedPrefix, reversedPrefix.length)
+    }
+
+    const parentPath: ParentPath<object> | undefined = fastGetParentPath(current, false)
+    if (!parentPath) {
+      break
+    }
+    reversedPrefix.push(parentPath.path)
+    current = parentPath.parent
+  }
+}
+
+function createDeepChange(
+  type: DeepChangeType,
+  target: object | unknown[],
+  keyOrIndex: string | number,
+  newValue: unknown,
+  oldValue: unknown,
+  addedValues: unknown[] | undefined,
+  removedValues: unknown[] | undefined
+): DeepChange {
+  const isInit = getIsInInitPhase()
+  switch (type) {
+    case DeepChangeType.ObjectAdd:
+      return {
+        type,
+        target: target as object,
+        path: emptyPath,
+        key: keyOrIndex as string,
+        newValue,
+        isInit,
+      }
+    case DeepChangeType.ObjectUpdate:
+      return {
+        type,
+        target: target as object,
+        path: emptyPath,
+        key: keyOrIndex as string,
+        newValue,
+        oldValue,
+        isInit,
+      }
+    case DeepChangeType.ObjectRemove:
+      return {
+        type,
+        target: target as object,
+        path: emptyPath,
+        key: keyOrIndex as string,
+        oldValue,
+        isInit,
+      }
+    case DeepChangeType.ArraySplice:
+      return {
+        type,
+        target: target as unknown[],
+        path: emptyPath,
+        index: keyOrIndex as number,
+        addedValues: addedValues!,
+        removedValues: removedValues!,
+        isInit,
+      }
+    case DeepChangeType.ArrayUpdate:
+      return {
+        type,
+        target: target as unknown[],
+        path: emptyPath,
+        index: keyOrIndex as number,
+        newValue,
+        oldValue,
+        isInit,
+      }
+    default:
+      throw failure("unsupported deep change type")
+  }
+}
+
 function emitGlobalDeepChange(obj: object, change: DeepChange): void {
   for (let i = 0; i < globalDeepChangeListeners.length; i++) {
     const listener = globalDeepChangeListeners[i]
@@ -152,21 +359,32 @@ function emitGlobalDeepChange(obj: object, change: DeepChange): void {
 }
 
 function emitDeepChangeToListeners(obj: object, change: DeepChange): void {
-  const pathPrefix: WritablePath = []
+  // Segments are pushed in child-to-root order (O(1) each) rather than unshifted
+  // at the front (O(depth) each), keeping the whole walk O(depth) instead of
+  // O(depth^2) on deep trees.
+  const reversedPrefix: WritablePath = []
 
-  emitDeepChangeForTarget(obj, change, pathPrefix)
+  emitDeepChangeForTarget(obj, change, reversedPrefix, 0)
 
   // and also emit subtree listeners all the way to the root
   let parentPath = fastGetParentPath(obj, false)
   while (parentPath) {
-    pathPrefix.unshift(parentPath.path)
-    emitDeepChangeForTarget(parentPath.parent, change, pathPrefix)
+    reversedPrefix.push(parentPath.path)
+    emitDeepChangeForTarget(parentPath.parent, change, reversedPrefix, reversedPrefix.length)
 
     parentPath = fastGetParentPath(parentPath.parent, false)
   }
 }
 
-function emitDeepChangeForTarget(obj: object, change: DeepChange, pathPrefix: Path): void {
+// `reversedPrefix` holds the path segments from the changed node up to (but not
+// including) `obj`, in child-to-root order; the emitted path prepends that slice
+// reversed (root-to-child). `prefixCount` is how many leading entries apply.
+function emitDeepChangeForTarget(
+  obj: object,
+  change: DeepChange,
+  reversedPrefix: readonly PathElement[],
+  prefixCount: number
+): void {
   const listenersForObject = deepChangeListeners.get(obj)
 
   if (!listenersForObject || listenersForObject.length === 0) {
@@ -174,11 +392,8 @@ function emitDeepChangeForTarget(obj: object, change: DeepChange, pathPrefix: Pa
   }
 
   const changeWithPath =
-    pathPrefix.length > 0
-      ? {
-          ...change,
-          path: [...pathPrefix, ...change.path],
-        }
+    prefixCount > 0
+      ? { ...change, path: buildPrefixedPath(reversedPrefix, prefixCount, change.path) }
       : change
 
   for (let i = 0; i < listenersForObject.length; i++) {
@@ -187,6 +402,21 @@ function emitDeepChangeForTarget(obj: object, change: DeepChange, pathPrefix: Pa
   }
 }
 
+function buildPrefixedPath(
+  reversedPrefix: readonly PathElement[],
+  prefixCount: number,
+  suffix: Path
+): WritablePath {
+  const newPath: WritablePath = new Array(prefixCount + suffix.length)
+  for (let i = 0; i < prefixCount; i++) {
+    newPath[i] = reversedPrefix[prefixCount - 1 - i]
+  }
+  for (let j = 0; j < suffix.length; j++) {
+    newPath[prefixCount + j] = suffix[j]
+  }
+  return newPath
+}
+
 /**
  * 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.

package/src/model/BaseModel.ts

@@ -53,10 +53,10 @@ export abstract class BaseModel<
   ModelIdPropertyName extends string = never,
 > {
   // just to make typing work properly
-  [propsTypeSymbol]!: TProps;
-  [fromSnapshotOverrideTypeSymbol]!: FromSnapshotOverride;
-  [toSnapshotOverrideTypeSymbol]!: ToSnapshotOverride;
-  [modelIdPropertyNameSymbol]!: ModelIdPropertyName
+  declare [propsTypeSymbol]: TProps
+  declare [fromSnapshotOverrideTypeSymbol]: FromSnapshotOverride
+  declare [toSnapshotOverrideTypeSymbol]: ToSnapshotOverride
+  declare [modelIdPropertyNameSymbol]: ModelIdPropertyName
 
   /**
    * Model type name.
@@ -139,14 +139,6 @@ export abstract class BaseModel<
 
     Object.setPrototypeOf(this, modelClass!.prototype)
 
-    const self = this as any
-
-    // delete unnecessary props
-    delete self[propsTypeSymbol]
-    delete self[fromSnapshotOverrideTypeSymbol]
-    delete self[toSnapshotOverrideTypeSymbol]
-    delete self[modelIdPropertyNameSymbol]
-
     if (snapshotInitialData) {
       // from snapshot
       internalFromSnapshotModel(this, snapshotInitialData, modelClass!, !!generateNewIds)

package/src/model/Model.ts

@@ -217,6 +217,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.
@@ -225,6 +228,8 @@ export interface ModelOptions<TProps extends ModelProps, FS, TS> {
 
   /**
    * 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/src/model/newModel.ts

@@ -3,6 +3,7 @@ import type { O } from "ts-toolbelt"
 import {
   DeepChangeType,
   emitDeepChange,
+  hasGlobalDeepChangeListeners,
   type ObjectAddChange,
   type ObjectUpdateChange,
 } from "../deepChange/onDeepChange"
@@ -12,8 +13,13 @@ import { modelInfoByClass } from "../modelShared/modelInfo"
 import { getInternalModelClassPropsInfo } from "../modelShared/modelPropsInfo"
 import { applyModelInitializers } from "../modelShared/newModel"
 import { getModelPropStoredDefaultValue, noDefaultValue } from "../modelShared/prop"
-import { createPatchForObjectValueChange, emitPatches } from "../patch/emitPatch"
+import {
+  createPatchForObjectValueChange,
+  emitPatches,
+  hasGlobalPatchListeners,
+} from "../patch/emitPatch"
 import type { Patch } from "../patch/Patch"
+import { invalidateModelInitialDataSnapshot } from "../snapshot/modelInitialData"
 import { tweakModel } from "../tweaker/tweakModel"
 import { tweakPlainObject } from "../tweaker/tweakPlainObject"
 import { failure, inDevMode, makePropReadonly } from "../utils"
@@ -72,9 +78,10 @@ export const internalNewModel = action(
       let changed = false
 
       // apply untransform (if any) if not in snapshot mode
-      if (propData._transform) {
+      const transform = propData._getTransform ? propData._getTransform() : propData._transform
+      if (transform) {
         changed = true
-        newValue = propData._transform.untransform(newValue, modelObj, k)
+        newValue = transform.untransform(newValue, modelObj, k)
       }
 
       // apply default value (if needed)
@@ -145,17 +152,28 @@ export const internalFromSnapshotModel = action(
     const modelObj = origModelObj as O.Writable<M>
     modelObj[modelTypeKey] = modelInfo.name
 
-    const patches: Patch[] = []
-    const inversePatches: Patch[] = []
-    const defaultsApplied: { key: string; oldValue: unknown; newValue: unknown }[] = []
+    // At this point the model is not attached to a tree yet, so initialization
+    // corrections can only be observed by global listeners. Tree-local listeners
+    // will observe the eventual insertion of the fully initialized model instead.
+    const shouldEmitPatches = hasGlobalPatchListeners()
+    const shouldEmitDeepChanges = hasGlobalDeepChangeListeners()
+    let patches: Patch[] | undefined
+    let inversePatches: Patch[] | undefined
+    let defaultsApplied: { key: string; oldValue: unknown; newValue: unknown }[] | undefined
 
     if (modelIdPropertyName) {
       const initialValue = initialData[modelIdPropertyName]
       const valueChanged = setIfDifferentWithReturn(initialData, modelIdPropertyName, id)
 
       if (valueChanged) {
+        invalidateModelInitialDataSnapshot(initialData)
+      }
+
+      if (valueChanged && shouldEmitPatches) {
         const modelIdPath = [modelIdPropertyName]
 
+        patches ??= []
+        inversePatches ??= []
         patches.push(createPatchForObjectValueChange(modelIdPath, initialValue, id))
         inversePatches.push(createPatchForObjectValueChange(modelIdPath, id, initialValue))
       }
@@ -192,15 +210,23 @@ export const internalFromSnapshotModel = action(
       if (changed) {
         // setIfDifferent not required
         set(initialData, k, newValue)
+        invalidateModelInitialDataSnapshot(initialData)
 
         if (newValue !== initialValue) {
-          const propPath = [k]
+          if (shouldEmitPatches) {
+            const propPath = [k]
 
-          patches.push(createPatchForObjectValueChange(propPath, initialValue, newValue))
-          inversePatches.push(createPatchForObjectValueChange(propPath, newValue, initialValue))
+            patches ??= []
+            inversePatches ??= []
+            patches.push(createPatchForObjectValueChange(propPath, initialValue, newValue))
+            inversePatches.push(createPatchForObjectValueChange(propPath, newValue, initialValue))
+          }
 
           // Track defaults applied for deep change emission
-          defaultsApplied.push({ key: k, oldValue: initialValue, newValue })
+          if (shouldEmitDeepChanges) {
+            defaultsApplied ??= []
+            defaultsApplied.push({ key: k, oldValue: initialValue, newValue })
+          }
         }
       }
     }
@@ -208,9 +234,11 @@ export const internalFromSnapshotModel = action(
     // also emit a patch for modelType, since it will get included in the snapshot
     const initialModelType = snapshotInitialData?.unprocessedModelType
     const newModelType = modelInfo.name
-    if (initialModelType !== newModelType) {
+    if (initialModelType !== newModelType && shouldEmitPatches) {
       const modelTypePath = [modelTypeKey]
 
+      patches ??= []
+      inversePatches ??= []
       patches.push(createPatchForObjectValueChange(modelTypePath, initialModelType, newModelType))
       inversePatches.push(
         createPatchForObjectValueChange(modelTypePath, newModelType, initialModelType)
@@ -219,35 +247,39 @@ export const internalFromSnapshotModel = action(
 
     finalizeNewModel(modelObj, initialData, modelClass)
 
-    emitPatches(modelObj, patches, inversePatches)
+    if (patches && inversePatches) {
+      emitPatches(modelObj, patches, inversePatches)
+    }
 
     // Emit deep changes for defaults applied during fromSnapshot
     // These are emitted with isInit: true so bindings can sync them to CRDTs
-    for (const { key, oldValue } of defaultsApplied) {
-      const target = modelObj.$
-      if (oldValue === undefined) {
-        // Key was added (didn't exist in snapshot)
-        const change: ObjectAddChange = {
-          type: DeepChangeType.ObjectAdd,
-          path: [],
-          target,
-          key,
-          newValue: target[key], // Use the tweaked value from $
-          isInit: true,
-        }
-        emitDeepChange(modelObj, change)
-      } else {
-        // Key was updated (had a different value in snapshot, e.g., null -> default)
-        const change: ObjectUpdateChange = {
-          type: DeepChangeType.ObjectUpdate,
-          path: [],
-          target,
-          key,
-          newValue: target[key], // Use the tweaked value from $
-          oldValue,
-          isInit: true,
+    if (defaultsApplied) {
+      for (const { key, oldValue } of defaultsApplied) {
+        const target = modelObj.$
+        if (oldValue === undefined) {
+          // Key was added (didn't exist in snapshot)
+          const change: ObjectAddChange = {
+            type: DeepChangeType.ObjectAdd,
+            path: [],
+            target,
+            key,
+            newValue: target[key], // Use the tweaked value from $
+            isInit: true,
+          }
+          emitDeepChange(modelObj, change)
+        } else {
+          // Key was updated (had a different value in snapshot, e.g., null -> default)
+          const change: ObjectUpdateChange = {
+            type: DeepChangeType.ObjectUpdate,
+            path: [],
+            target,
+            key,
+            newValue: target[key], // Use the tweaked value from $
+            oldValue,
+            isInit: true,
+          }
+          emitDeepChange(modelObj, change)
         }
-        emitDeepChange(modelObj, change)
       }
     }