mobx-keystone 1.25.0 → 2.1.0

package/src/deepChange/onDeepChange.ts

@@ -2,7 +2,8 @@ import { action, isAction } from "mobx"
 import { fastGetParentPath, type ParentPath } from "../parent/path"
 import type { Path, PathElement, WritablePath } from "../parent/pathTypes"
 import { assertTweakedObject } from "../tweaker/core"
-import { assertIsFunction, deleteFromArray, failure } from "../utils"
+import { assertIsFunction, failure } from "../utils"
+import { addDelayedError, type DelayedError } from "../utils/forEachWithDelayedThrow"
 
 /**
  * Disposer function to stop listening to deep changes.
@@ -18,6 +19,8 @@ export enum DeepChangeType {
 }
 
 export interface DeepChangeBase {
+  /** Whether this notification overlaps a mutation made by a change listener. */
+  readonly isReentrant?: boolean
   readonly type: DeepChangeType
   readonly path: Path
   /**
@@ -97,8 +100,17 @@ export type DeepChange =
  */
 export type OnDeepChangeListener = (change: DeepChange) => void
 
-const deepChangeListeners = new WeakMap<object, OnDeepChangeListener[]>()
-const globalDeepChangeListeners: ((target: object, change: DeepChange) => void)[] = []
+interface ListenerSubscription<Listener> {
+  readonly listener: Listener
+  active: boolean
+}
+
+const deepChangeListeners = new WeakMap<object, ListenerSubscription<OnDeepChangeListener>[]>()
+
+let globalDeepChangeListeners: ListenerSubscription<
+  (target: object, change: DeepChange) => void
+>[] = []
+
 const emptyPath: Path = Object.freeze([])
 
 let deepChangeListenerCount = 0
@@ -143,6 +155,56 @@ export function exitInitPhase(): void {
   }
 }
 
+interface DeepChangeEmission {
+  reentrant: boolean
+  /** Failures thrown by the listeners of this emission, reported once it has been delivered. */
+  error: DelayedError
+  parent: DeepChangeEmission | undefined
+  /** Shared by every change of this emission, so they all observe `reentrant` live. */
+  isReentrantDescriptor: PropertyDescriptor | undefined
+}
+
+let currentEmission: DeepChangeEmission | undefined
+
+function rethrowDeepChangeListenerError(emission: DeepChangeEmission): void {
+  const error = emission.error
+  if (error) {
+    // Listeners may keep change objects around, and those keep this emission alive
+    // through their `isReentrant` getter, so don't retain the errors with it.
+    emission.error = undefined
+    throw error.value
+  }
+}
+
+function beginDeepChangeEmission(): DeepChangeEmission {
+  for (let parent = currentEmission; parent; parent = parent.parent) parent.reentrant = true
+  const emission: DeepChangeEmission = {
+    reentrant: currentEmission !== undefined,
+    error: undefined,
+    parent: currentEmission,
+    isReentrantDescriptor: undefined,
+  }
+  currentEmission = emission
+  return emission
+}
+
+// `isReentrant` is deliberately non-enumerable so that object spread and JSON
+// serialization of a change do not copy it.
+function attachEmission(change: DeepChange): DeepChange {
+  const emission = currentEmission!
+  emission.isReentrantDescriptor ??= {
+    get: () => emission.reentrant,
+    configurable: true,
+  }
+  Object.defineProperty(change, "isReentrant", emission.isReentrantDescriptor)
+  return change
+}
+
+function changeWithPath(change: DeepChange, path: Path): DeepChange {
+  // The copy belongs to the same (still current) emission as the original.
+  return attachEmission({ ...change, path })
+}
+
 /**
  * @internal
  */
@@ -151,10 +213,17 @@ export function emitDeepChange(obj: object, change: DeepChange): void {
     return
   }
 
-  emitGlobalDeepChange(obj, change)
-  if (deepChangeListenerCount > 0) {
-    emitDeepChangeToListeners(obj, change)
+  const emission = beginDeepChangeEmission()
+  try {
+    attachEmission(change)
+    emitGlobalDeepChange(obj, change)
+    if (deepChangeListenerCount > 0) {
+      emitDeepChangeToListeners(obj, change)
+    }
+  } finally {
+    currentEmission = emission.parent
   }
+  rethrowDeepChangeListenerError(emission)
 }
 
 /**
@@ -238,6 +307,38 @@ function emitDeepChangeFromValues(
   oldValue: unknown,
   addedValues?: unknown[],
   removedValues?: unknown[]
+): void {
+  if (!hasAnyDeepChangeListeners()) {
+    return
+  }
+
+  const emission = beginDeepChangeEmission()
+  try {
+    emitDeepChangeFromValuesInEmission(
+      node,
+      type,
+      target,
+      keyOrIndex,
+      newValue,
+      oldValue,
+      addedValues,
+      removedValues
+    )
+  } finally {
+    currentEmission = emission.parent
+  }
+  rethrowDeepChangeListenerError(emission)
+}
+
+function emitDeepChangeFromValuesInEmission(
+  node: object,
+  type: DeepChangeType,
+  target: object | unknown[],
+  keyOrIndex: string | number,
+  newValue: unknown,
+  oldValue: unknown,
+  addedValues?: unknown[],
+  removedValues?: unknown[]
 ): void {
   let change: DeepChange | undefined
 
@@ -295,6 +396,20 @@ function createDeepChange(
   oldValue: unknown,
   addedValues: unknown[] | undefined,
   removedValues: unknown[] | undefined
+): DeepChange {
+  return attachEmission(
+    buildDeepChange(type, target, keyOrIndex, newValue, oldValue, addedValues, removedValues)
+  )
+}
+
+function buildDeepChange(
+  type: DeepChangeType,
+  target: object | unknown[],
+  keyOrIndex: string | number,
+  newValue: unknown,
+  oldValue: unknown,
+  addedValues: unknown[] | undefined,
+  removedValues: unknown[] | undefined
 ): DeepChange {
   const isInit = getIsInInitPhase()
   switch (type) {
@@ -352,12 +467,28 @@ function createDeepChange(
 }
 
 function emitGlobalDeepChange(obj: object, change: DeepChange): void {
-  for (let i = 0; i < globalDeepChangeListeners.length; i++) {
-    const listener = globalDeepChangeListeners[i]
-    listener(obj, change)
+  const listeners = globalDeepChangeListeners
+  for (let i = 0; i < listeners.length; i++) {
+    const subscription = listeners[i]
+    if (subscription.active) {
+      try {
+        subscription.listener(obj, change)
+      } catch (error) {
+        rememberDeepChangeListenerError(error)
+      }
+    }
   }
 }
 
+// The mutation is already applied by the time listeners run, so a failing listener
+// must not keep it from reaching bindings and other observers. Once the whole emission
+// has been delivered a lone failure is rethrown as is, and several failures are grouped
+// in a MobxKeystoneAggregateError.
+function rememberDeepChangeListenerError(error: unknown): void {
+  const emission = currentEmission!
+  emission.error = addDelayedError(emission.error, error, "multiple deep change listeners failed")
+}
+
 function emitDeepChangeToListeners(obj: object, change: DeepChange): void {
   // 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
@@ -391,14 +522,20 @@ function emitDeepChangeForTarget(
     return
   }
 
-  const changeWithPath =
+  const prefixedChange =
     prefixCount > 0
-      ? { ...change, path: buildPrefixedPath(reversedPrefix, prefixCount, change.path) }
+      ? changeWithPath(change, buildPrefixedPath(reversedPrefix, prefixCount, change.path))
       : change
 
   for (let i = 0; i < listenersForObject.length; i++) {
-    const listener = listenersForObject[i]
-    listener(changeWithPath)
+    const subscription = listenersForObject[i]
+    if (subscription.active) {
+      try {
+        subscription.listener(prefixedChange)
+      } catch (error) {
+        rememberDeepChangeListenerError(error)
+      }
+    }
   }
 }
 
@@ -420,6 +557,13 @@ function buildPrefixedPath(
 /**
  * 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.
+ * Individual mutations notify listeners after automatic type checking succeeds and snapshots update;
+ * rejected mutations and their quiet rollbacks do not notify listeners.
+ * Listener errors do not stop delivery to other listeners. After delivery completes,
+ * a single error is rethrown unchanged and multiple errors are grouped in a MobxKeystoneAggregateError.
+ * Listeners added while callbacks for the same target are running start with the next
+ * change delivered to that target. Listeners disposed during delivery do not receive
+ * the current change if their callback has not run yet.
  *
  * @param subtreeRoot Subtree root object of the deep change listener.
  * @param listener The listener function that will be called every time a change is generated for the object or its children.
@@ -436,18 +580,23 @@ export function onDeepChange(
     listener = action(listener.name || "onDeepChangeListener", listener)
   }
 
-  let listenersForObject = deepChangeListeners.get(subtreeRoot)
-  if (!listenersForObject) {
-    listenersForObject = []
-    deepChangeListeners.set(subtreeRoot, listenersForObject)
-  }
-
-  listenersForObject.push(listener)
+  // Keep the array held by an ongoing delivery unchanged. Subscription changes
+  // are infrequent, so copy here rather than on every mutation notification.
+  const listeners = deepChangeListeners.get(subtreeRoot) ?? []
+  const subscription = { listener, active: true }
+  deepChangeListeners.set(subtreeRoot, [...listeners, subscription])
   deepChangeListenerCount++
+
   return () => {
-    if (deleteFromArray(listenersForObject, listener)) {
-      deepChangeListenerCount--
+    if (!subscription.active) {
+      return
     }
+    subscription.active = false
+    deepChangeListenerCount--
+    deepChangeListeners.set(
+      subtreeRoot,
+      deepChangeListeners.get(subtreeRoot)!.filter((s) => s !== subscription)
+    )
   }
 }
 
@@ -467,8 +616,14 @@ export function onGlobalDeepChange(
     listener = action(listener.name || "onGlobalDeepChangeListener", listener)
   }
 
-  globalDeepChangeListeners.push(listener)
+  const subscription = { listener, active: true }
+  globalDeepChangeListeners = [...globalDeepChangeListeners, subscription]
+
   return () => {
-    deleteFromArray(globalDeepChangeListeners, listener)
+    if (!subscription.active) {
+      return
+    }
+    subscription.active = false
+    globalDeepChangeListeners = globalDeepChangeListeners.filter((s) => s !== subscription)
   }
 }

package/src/frozen/Frozen.ts

@@ -3,6 +3,7 @@ import { getGlobalConfig } from "../globalConfig"
 import type { FrozenData } from "../snapshot"
 import { tweak } from "../tweaker/tweak"
 import { failure, inDevMode, isPlainObject, isPrimitive } from "../utils"
+import { getSafeErrorValuePreview } from "../utils/errorDiagnostics"
 
 /**
  * Should freeze and plain json checks be done when creating the frozen object?
@@ -54,7 +55,7 @@ export class Frozen<T> {
     this.data = dataToFreeze
 
     if (check) {
-      Object.freeze(this.data)
+      Object.defineProperty(this, "data", { writable: false, configurable: false })
     }
 
     tweak(this, undefined)
@@ -95,44 +96,60 @@ export function toFrozenSnapshot<T>(data: T): FrozenData<T> {
   }
 }
 
-function checkDataIsSerializableAndFreeze(data: any) {
-  // TODO: detect cycles and throw if present?
-
-  // primitives are ok
-  if (isPrimitive(data)) {
-    return
-  }
-
-  if (Array.isArray(data)) {
-    const arrLen = data.length
-    for (let i = 0; i < arrLen; i++) {
-      const v = data[i]
-      if (v === undefined && !getGlobalConfig().allowUndefinedArrayElements) {
-        throw failure(
-          "undefined is not supported inside arrays since it is not serializable in JSON, consider using null instead"
-        )
-      }
-      checkDataIsSerializableAndFreeze(v)
+function checkDataIsSerializableAndFreeze(data: unknown) {
+  // false means the object is still on the traversal stack; true means fully checked.
+  const checked = new Map<object, boolean>()
+  const stack: {
+    data: object
+    keys: string[] | undefined
+    length: number
+    nextIndex: number
+  }[] = []
+
+  const visit = (value: unknown) => {
+    if (isPrimitive(value)) return
+
+    if (!Array.isArray(value) && !isPlainObject(value)) {
+      throw failure(
+        `frozen data must be plainly serializable to JSON, but ${getSafeErrorValuePreview(value)} is not`
+      )
     }
-    Object.freeze(data)
-    return
+    const state = checked.get(value)
+    if (state === true) return
+    if (state === false) {
+      throw failure("frozen data must not contain cycles")
+    }
+    checked.set(value, false)
+    const keys = Array.isArray(value) ? undefined : Object.keys(value)
+    stack.push({
+      data: value,
+      keys,
+      length: keys ? keys.length : (value as unknown[]).length,
+      nextIndex: 0,
+    })
   }
 
-  if (isPlainObject(data)) {
-    const dataKeys = Object.keys(data)
-    const dataKeysLen = dataKeys.length
-    for (let i = 0; i < dataKeysLen; i++) {
-      const k = dataKeys[i]
-      const v = data[k]
+  visit(data)
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1]
+    if (frame.nextIndex === frame.length) {
+      Object.freeze(frame.data)
+      checked.set(frame.data, true)
+      stack.pop()
+      continue
+    }
 
-      checkDataIsSerializableAndFreeze(k)
-      checkDataIsSerializableAndFreeze(v)
+    const index = frame.nextIndex++
+    const value = frame.keys
+      ? (frame.data as Record<string, unknown>)[frame.keys[index]]
+      : (frame.data as unknown[])[index]
+    if (!frame.keys && value === undefined && !getGlobalConfig().allowUndefinedArrayElements) {
+      throw failure(
+        "undefined is not supported inside arrays since it is not serializable in JSON, consider using null instead"
+      )
     }
-    Object.freeze(data)
-    return
+    visit(value)
   }
-
-  throw failure(`frozen data must be plainly serializable to JSON, but ${data} is not`)
 }
 
 /**

package/src/model/BaseModel.ts

@@ -17,7 +17,7 @@ import type { SnapshotInOfModel, SnapshotOutOfModel } from "../snapshot/Snapshot
 import { typesModel } from "../types/objectBased/typesModel"
 import type { TypeCheckError } from "../types/TypeCheckError"
 import { typeCheck } from "../types/typeCheck"
-import { assertIsObject, failure } from "../utils"
+import { assertIsObject, failure, nodeObservableOptions } from "../utils"
 import { getModelIdPropertyName } from "./getModelMetadata"
 import type { ModelConstructorOptions } from "./ModelConstructorOptions"
 import { modelIdKey, modelTypeKey } from "./metadata"
@@ -70,7 +70,7 @@ export abstract class BaseModel<
    */
   get [modelIdKey](): ModelIdPropertyType<TProps, ModelIdPropertyName> {
     const idProp = getModelIdPropertyName(this.constructor as any)
-    return (idProp ? (this.$ as any)[idProp] : undefined) as ModelIdPropertyType<
+    return (idProp !== undefined ? (this.$ as any)[idProp] : undefined) as ModelIdPropertyType<
       TProps,
       ModelIdPropertyName
     >
@@ -78,7 +78,7 @@ export abstract class BaseModel<
 
   set [modelIdKey](newId: ModelIdPropertyType<TProps, ModelIdPropertyName>) {
     const idProp = getModelIdPropertyName(this.constructor as any)
-    if (!idProp) {
+    if (idProp === undefined) {
       throw failure("$modelId cannot be set when there is no idProp set in the model")
     }
     ;(this.$ as any)[idProp] = newId
@@ -150,9 +150,11 @@ export abstract class BaseModel<
       // Empty input is filled by the constructor below. Track its primitive
       // defaults directly instead of rereading observable fields for the snapshot.
       const useInitialDataSnapshot = Reflect.ownKeys(initialData).length === 0
-      const observableInitialData = observable.object(initialData as any, undefined, {
-        deep: false,
-      })
+      const observableInitialData = observable.object(
+        initialData as any,
+        undefined,
+        nodeObservableOptions
+      )
       if (useInitialDataSnapshot) {
         setModelInitialDataSnapshot(observableInitialData, {})
       }
@@ -161,16 +163,11 @@ export abstract class BaseModel<
   }
 
   toString(options?: { withData?: boolean }) {
-    const finalOptions = {
-      withData: true,
-      ...options,
-    }
+    const { withData = true } = options ?? {}
 
     const firstPart = `${this.constructor.name}#${this[modelTypeKey]}`
 
-    return finalOptions.withData
-      ? `[${firstPart} ${JSON.stringify(getSnapshot(this))}]`
-      : `[${firstPart}]`
+    return withData ? `[${firstPart} ${JSON.stringify(getSnapshot(this))}]` : `[${firstPart}]`
   }
 }
 

package/src/model/newModel.ts

@@ -22,7 +22,8 @@ import type { Patch } from "../patch/Patch"
 import { updateModelInitialDataSnapshot } from "../snapshot/modelInitialData"
 import { tweakModel } from "../tweaker/tweakModel"
 import { tweakPlainObject } from "../tweaker/tweakPlainObject"
-import { failure, inDevMode, makePropReadonly } from "../utils"
+import { typeCheckAfterCreation } from "../tweaker/typeChecking"
+import { failure, hasOwnProp, inDevMode, makePropReadonly } from "../utils"
 import { setIfDifferent, setIfDifferentWithReturn } from "../utils/setIfDifferent"
 import type { AnyModel } from "./BaseModel"
 import { getModelIdPropertyName } from "./getModelMetadata"
@@ -49,13 +50,12 @@ export const internalNewModel = action(
       getModelDetails(modelClass)
 
     // use symbol if provided
-    if (modelIdPropertyName && modelIdPropData) {
-      let id: string | undefined
-      if (initialData[modelIdPropertyName]) {
-        id = initialData[modelIdPropertyName]
-      } else {
-        id = (modelIdPropData._defaultFn as () => string)()
-      }
+    if (modelIdPropertyName !== undefined && modelIdPropData) {
+      const providedId = hasOwnProp(initialData, modelIdPropertyName)
+        ? initialData[modelIdPropertyName]
+        : undefined
+      const id: string =
+        providedId != null ? providedId : (modelIdPropData._defaultFn as () => string)()
       setIfDifferent(initialData, modelIdPropertyName, id)
       if (useInitialDataSnapshot) {
         updateModelInitialDataSnapshot(initialData, modelIdPropertyName, id)
@@ -77,7 +77,8 @@ export const internalNewModel = action(
 
       const propData = modelProps[k]
 
-      const initialValue = initialData[k]
+      const hasInitialValue = hasOwnProp(initialData, k)
+      const initialValue = hasInitialValue ? initialData[k] : undefined
       let newValue = initialValue
       let changed = false
 
@@ -94,7 +95,7 @@ export const internalNewModel = action(
         if (defaultValue !== noDefaultValue) {
           changed = true
           newValue = defaultValue
-        } else if (!(k in initialData)) {
+        } else if (!hasInitialValue) {
           // for mobx4, we need to set up properties even if they are undefined
           changed = true
         }
@@ -113,10 +114,7 @@ export const internalNewModel = action(
 
     // type check it if needed
     if (isModelAutoTypeCheckingEnabled()) {
-      const err = modelObj.typeCheck()
-      if (err) {
-        err.throw()
-      }
+      typeCheckAfterCreation(modelObj)
     }
   }
 )
@@ -142,10 +140,10 @@ export const internalFromSnapshotModel = action(
     let id: string | undefined
     let sn = snapshotInitialData.unprocessedSnapshot
 
-    if (modelIdPropData && modelIdPropertyName) {
+    if (modelIdPropData && modelIdPropertyName !== undefined) {
       if (generateNewIds) {
         id = (modelIdPropData._defaultFn as () => string)()
-      } else {
+      } else if (hasOwnProp(sn, modelIdPropertyName)) {
         id = sn[modelIdPropertyName]
       }
     }
@@ -168,7 +166,7 @@ export const internalFromSnapshotModel = action(
     let inversePatches: Patch[] | undefined
     let defaultsApplied: { key: string; oldValue: unknown; newValue: unknown }[] | undefined
 
-    if (modelIdPropertyName) {
+    if (modelIdPropertyName !== undefined) {
       const initialValue = initialData[modelIdPropertyName]
       const valueChanged = setIfDifferentWithReturn(initialData, modelIdPropertyName, id)
 
@@ -198,7 +196,8 @@ export const internalFromSnapshotModel = action(
 
       const propData = modelProps[k]
 
-      const initialValue = initialData[k]
+      const hasInitialValue = hasOwnProp(initialData, k)
+      const initialValue = hasInitialValue ? initialData[k] : undefined
       let newValue = initialValue
       let changed = false
 
@@ -208,7 +207,7 @@ export const internalFromSnapshotModel = action(
         if (defaultValue !== noDefaultValue) {
           changed = true
           newValue = defaultValue
-        } else if (!(k in initialData!)) {
+        } else if (!hasInitialValue) {
           // for mobx4, we need to set up properties even if they are undefined
           changed = true
         }
@@ -292,10 +291,7 @@ export const internalFromSnapshotModel = action(
 
     // type check it if needed
     if (isModelAutoTypeCheckingEnabled()) {
-      const err = modelObj.typeCheck()
-      if (err) {
-        err.throw()
-      }
+      typeCheckAfterCreation(modelObj)
     }
   }
 )
@@ -310,7 +306,8 @@ function getModelDetails(modelClass: ModelClass<AnyModel>) {
 
   const modelIdPropertyName = getModelIdPropertyName(modelClass)
   const modelProps = getInternalModelClassPropsInfo(modelClass)
-  const modelIdPropData = modelIdPropertyName ? modelProps[modelIdPropertyName] : undefined
+  const modelIdPropData =
+    modelIdPropertyName !== undefined ? modelProps[modelIdPropertyName] : undefined
 
   return { modelInfo, modelIdPropertyName, modelProps, modelIdPropData }
 }

package/src/model/utils.ts

@@ -175,7 +175,7 @@ export function getSnapshotModelTypeAndId(snapshot: unknown): ModelTypeAndId | u
   const modelIdPropertyName = getModelIdPropertyName(modelInfo.class as ModelClass<AnyModel>)
 
   let modelId: string | undefined
-  if (modelIdPropertyName) {
+  if (modelIdPropertyName !== undefined) {
     const id = (snapshot as Record<string, unknown>)[modelIdPropertyName]
     modelId = typeof id === "string" ? id : undefined
   }
@@ -214,7 +214,7 @@ export function getModelTypeAndId(model: AnyModel | AnyDataModel): ModelTypeAndI
   const modelIdPropertyName = getModelIdPropertyName(modelInfo.class as ModelClass<AnyModel>)
 
   let modelId: string | undefined
-  if (modelIdPropertyName) {
+  if (modelIdPropertyName !== undefined) {
     const id = (model as any)[modelIdKey] as string | undefined
     modelId = typeof id === "string" ? id : undefined
   }

package/src/modelShared/modelClassInitializer.ts

@@ -1,5 +1,6 @@
 import type { AnyDataModel } from "../dataModel/BaseDataModel"
 import type { AnyModel } from "../model/BaseModel"
+import { hasOwnProp } from "../utils"
 import type { ModelClass } from "./BaseModelShared"
 
 /**
@@ -20,8 +21,8 @@ export function addModelClassInitializer(
   init: ModelClassInitializer
 ) {
   let initializers: ModelClassInitializer[] = (modelClass as any)[modelInitializersSymbol]
-  if (!initializers) {
-    initializers = []
+  if (!hasOwnProp(modelClass, modelInitializersSymbol)) {
+    initializers = initializers ? initializers.slice() : []
     ;(modelClass as any)[modelInitializersSymbol] = initializers
   }
   initializers.push(init)