mobx-keystone 1.22.0 → 1.24.0

package/src/types/TypeChecker.ts

@@ -6,6 +6,195 @@ import type { TypeCheckError } from "./TypeCheckError"
 
 type CheckFunction = (value: any, path: Path, typeCheckedValue: any) => TypeCheckError | null
 
+/** @internal */
+export type SnapshotProcessor = (snapshot: any) => unknown
+
+/**
+ * A lazily discovered snapshot-processor node. Dependencies are deliberately
+ * TypeCheckers rather than processors so recursive graphs can be discovered
+ * before any processor body is compiled.
+ *
+ * @internal
+ */
+export interface SnapshotProcessorPlan {
+  readonly intrinsic?: boolean
+  readonly getDependencies: () => ReadonlyArray<TypeChecker>
+  readonly compile: (
+    dependencyProcessors: ReadonlyArray<SnapshotProcessor | undefined>
+  ) => SnapshotProcessor | undefined
+}
+
+/** @internal */
+export function snapshotProcessorPlan(
+  getDependencies: () => ReadonlyArray<TypeChecker>,
+  compile: SnapshotProcessorPlan["compile"],
+  intrinsic = false
+): SnapshotProcessorPlan {
+  return { intrinsic, getDependencies, compile }
+}
+
+type SnapshotProcessorSource = SnapshotProcessor | SnapshotProcessorPlan | undefined
+type SnapshotProcessorDirection = "from" | "to"
+
+/** @internal */
+export class SnapshotProcessorPlanNode {
+  private readonly owner: TypeChecker | undefined
+  private readonly direction: SnapshotProcessorDirection
+  private readonly source: SnapshotProcessorSource
+  private presence: boolean | undefined
+  private dependencies: SnapshotProcessorPlanNode[] | undefined
+  private discovering = false
+  private compiling = false
+  private compiled = false
+  private compiledProcessor: SnapshotProcessor | undefined
+  private forwardingProcessor: SnapshotProcessor | undefined
+
+  constructor(
+    owner: TypeChecker | undefined,
+    direction: SnapshotProcessorDirection,
+    source: SnapshotProcessorSource
+  ) {
+    this.owner = owner
+    this.direction = direction
+    this.source = source
+    if (typeof source === "function" || source === undefined) {
+      this.presence = !!source
+      this.compiled = true
+      this.compiledProcessor = source
+    }
+  }
+
+  resolve(): SnapshotProcessor | undefined {
+    if (this.compiled) {
+      return this.compiledProcessor
+    }
+
+    const discoveredNodes: SnapshotProcessorPlanNode[] = []
+    const dependents = new Map<SnapshotProcessorPlanNode, SnapshotProcessorPlanNode[]>()
+    this.discover(discoveredNodes, dependents, new Set())
+
+    // Presence is the least fixed point of
+    //   intrinsic || any(dependency is present)
+    // over the newly discovered graph. An identity-only recursive component
+    // therefore remains absent, while an intrinsic processor propagates
+    // through every parent that contains it.
+    const presentQueue: SnapshotProcessorPlanNode[] = []
+    for (let i = 0; i < discoveredNodes.length; i++) {
+      const node = discoveredNodes[i]
+      const plan = node.source as SnapshotProcessorPlan
+      if (plan.intrinsic || node.dependencies!.some((dependency) => dependency.presence === true)) {
+        node.presence = true
+        presentQueue.push(node)
+      }
+    }
+
+    for (let queueIndex = 0; queueIndex < presentQueue.length; queueIndex++) {
+      const nodeDependents = dependents.get(presentQueue[queueIndex])
+      if (!nodeDependents) {
+        continue
+      }
+      for (let i = 0; i < nodeDependents.length; i++) {
+        const dependent = nodeDependents[i]
+        if (dependent.presence === undefined) {
+          dependent.presence = true
+          presentQueue.push(dependent)
+        }
+      }
+    }
+
+    for (let i = 0; i < discoveredNodes.length; i++) {
+      const node = discoveredNodes[i]
+      if (node.presence === undefined) {
+        node.presence = false
+        node.compiled = true
+        node.compiledProcessor = undefined
+        node.dependencies = undefined
+      }
+    }
+
+    return this.compile()
+  }
+
+  private discover(
+    discoveredNodes: SnapshotProcessorPlanNode[],
+    dependents: Map<SnapshotProcessorPlanNode, SnapshotProcessorPlanNode[]>,
+    visited: Set<SnapshotProcessorPlanNode>
+  ): void {
+    if (this.presence !== undefined || this.discovering || visited.has(this)) {
+      return
+    }
+
+    visited.add(this)
+    this.discovering = true
+    discoveredNodes.push(this)
+    try {
+      const plan = this.source as SnapshotProcessorPlan
+      const dependencyCheckers = plan.getDependencies()
+      this.dependencies = new Array(dependencyCheckers.length)
+      for (let i = 0; i < dependencyCheckers.length; i++) {
+        const dependency = dependencyCheckers[i].getSnapshotProcessorPlanNode(this.direction)
+        this.dependencies[i] = dependency
+        if (dependency.presence === undefined) {
+          let dependencyDependents = dependents.get(dependency)
+          if (!dependencyDependents) {
+            dependencyDependents = []
+            dependents.set(dependency, dependencyDependents)
+          }
+          dependencyDependents.push(this)
+        }
+        dependency.discover(discoveredNodes, dependents, visited)
+      }
+    } catch (error) {
+      // A lazy schema may temporarily fail while a recursive declaration is
+      // still initializing. Leave this node discoverable for a later retry.
+      this.dependencies = undefined
+      throw error
+    } finally {
+      this.discovering = false
+    }
+  }
+
+  private compile(): SnapshotProcessor | undefined {
+    if (this.compiled) {
+      return this.compiledProcessor
+    }
+    if (!this.presence) {
+      this.compiled = true
+      return undefined
+    }
+    if (this.compiling) {
+      if (!this.forwardingProcessor) {
+        this.forwardingProcessor = (snapshot) => this.compiledProcessor!(snapshot)
+      }
+      return this.forwardingProcessor
+    }
+
+    this.compiling = true
+    try {
+      const dependencies = this.dependencies!
+      const dependencyProcessors = new Array<SnapshotProcessor | undefined>(dependencies.length)
+      for (let i = 0; i < dependencies.length; i++) {
+        dependencyProcessors[i] = dependencies[i].compileForDependency()
+      }
+
+      const processor = (this.source as SnapshotProcessorPlan).compile(dependencyProcessors)
+      this.compiledProcessor = processor
+      this.compiled = true
+      this.dependencies = undefined
+      return processor
+    } finally {
+      this.compiling = false
+    }
+  }
+
+  private compileForDependency(): SnapshotProcessor | undefined {
+    const processor = this.compile()
+    return processor && this.direction === "to" ? this.owner!.toSnapshotProcessor : processor
+  }
+}
+
+const absentSnapshotProcessorPlanNode = new SnapshotProcessorPlanNode(undefined, "from", undefined)
+
 /**
  * @internal
  */
@@ -37,6 +226,7 @@ const typeCheckersWithCachedSnapshotProcessorResultsOfObject = new WeakMap<
   object,
   Set<TypeChecker>
 >()
+const cachedUndefinedSnapshotProcessorResult = Symbol("cachedUndefinedSnapshotProcessorResult")
 
 /**
  * @internal
@@ -63,8 +253,10 @@ export class TypeChecker {
   readonly getTypeName: (...recursiveTypeCheckers: TypeChecker[]) => string
   readonly typeInfoGen: TypeInfoGen
   readonly snapshotType: (sn: unknown) => TypeChecker | null
-  private readonly _fromSnapshotProcessor: (sn: any) => unknown
-  private readonly _toSnapshotProcessor: (sn: any) => unknown
+  private readonly fromSnapshotProcessorSource: SnapshotProcessorSource
+  private readonly toSnapshotProcessorSource: SnapshotProcessorSource
+  private fromSnapshotProcessorPlanNode: SnapshotProcessorPlanNode | undefined
+  private toSnapshotProcessorPlanNode: SnapshotProcessorPlanNode | undefined
 
   check(value: any, path: Path, typeCheckedValue: any): TypeCheckError | null {
     if (this.unchecked || this.skipCheck) {
@@ -86,24 +278,63 @@ export class TypeChecker {
     getTypeName: (...recursiveTypeCheckers: TypeChecker[]) => string,
     typeInfoGen: TypeInfoGen,
     snapshotType: (sn: unknown) => TypeChecker | null,
-    _fromSnapshotProcessor: (sn: any) => unknown,
-    _toSnapshotProcessor: (sn: any) => unknown
+    fromSnapshotProcessor: SnapshotProcessorSource,
+    toSnapshotProcessor: SnapshotProcessorSource
   ) {
     this.baseType = baseType
     this._check = _check
     this.getTypeName = getTypeName
     this.typeInfoGen = typeInfoGen
     this.snapshotType = snapshotType
-    this._fromSnapshotProcessor = _fromSnapshotProcessor
-    this._toSnapshotProcessor = _toSnapshotProcessor
+    this.fromSnapshotProcessorSource = fromSnapshotProcessor
+    this.toSnapshotProcessorSource = toSnapshotProcessor
     this.unchecked = !_check
     this._cachedTypeInfoGen = lazy(typeInfoGen)
   }
 
+  getSnapshotProcessorPlanNode(direction: SnapshotProcessorDirection): SnapshotProcessorPlanNode {
+    const source =
+      direction === "from" ? this.fromSnapshotProcessorSource : this.toSnapshotProcessorSource
+    if (source === undefined) {
+      return absentSnapshotProcessorPlanNode
+    }
+
+    let node =
+      direction === "from" ? this.fromSnapshotProcessorPlanNode : this.toSnapshotProcessorPlanNode
+    if (!node) {
+      node = new SnapshotProcessorPlanNode(this, direction, source)
+      if (direction === "from") {
+        this.fromSnapshotProcessorPlanNode = node
+      } else {
+        this.toSnapshotProcessorPlanNode = node
+      }
+    }
+    return node
+  }
+
+  private resolveSnapshotProcessor(
+    direction: SnapshotProcessorDirection
+  ): SnapshotProcessor | undefined {
+    const source =
+      direction === "from" ? this.fromSnapshotProcessorSource : this.toSnapshotProcessorSource
+    return typeof source === "function"
+      ? source
+      : source === undefined
+        ? undefined
+        : this.getSnapshotProcessorPlanNode(direction).resolve()
+  }
+
+  getFromSnapshotProcessor(): SnapshotProcessor | undefined {
+    return this.resolveSnapshotProcessor("from")
+  }
+
+  getToSnapshotProcessor(): SnapshotProcessor | undefined {
+    return this.resolveSnapshotProcessor("to") ? this.toSnapshotProcessor : undefined
+  }
+
   fromSnapshotProcessor = (sn: any): unknown => {
-    // we cannot cache fromSnapshotProcessor since nobody ensures us
-    // the original snapshot won't be tweaked after use
-    return this._fromSnapshotProcessor(sn)
+    const processor = this.getFromSnapshotProcessor()
+    return processor ? processor(sn) : sn
   }
 
   private readonly _toSnapshotProcessorCache = new WeakMap<object, unknown>()
@@ -113,17 +344,26 @@ export class TypeChecker {
   }
 
   toSnapshotProcessor = (sn: any): unknown => {
+    const processor = this.resolveSnapshotProcessor("to")
+    if (!processor) {
+      return sn
+    }
+
     if (typeof sn !== "object" || sn === null) {
       // not cacheable
-      return this._toSnapshotProcessor(sn)
+      return processor(sn)
     }
 
-    if (this._toSnapshotProcessorCache.has(sn)) {
-      return this._toSnapshotProcessorCache.get(sn)
+    const cachedResult = this._toSnapshotProcessorCache.get(sn)
+    if (cachedResult !== undefined) {
+      return cachedResult === cachedUndefinedSnapshotProcessorResult ? undefined : cachedResult
     }
 
-    const val = this._toSnapshotProcessor(sn)
-    this._toSnapshotProcessorCache.set(sn, val)
+    const val = processor(sn)
+    this._toSnapshotProcessorCache.set(
+      sn,
+      val === undefined ? cachedUndefinedSnapshotProcessorResult : val
+    )
 
     // register this type checker as listener of that sn changes
     const typeCheckerSet = getOrCreate(
@@ -146,6 +386,8 @@ const lateTypeCheckerSymbol = Symbol("lateTypeCheker")
 export interface LateTypeChecker {
   [lateTypeCheckerSymbol]: true
   (): TypeChecker
+  getFromSnapshotProcessor(): SnapshotProcessor | undefined
+  getToSnapshotProcessor(): SnapshotProcessor | undefined
   typeInfo: TypeInfo
 }
 
@@ -162,7 +404,11 @@ export function lateTypeChecker(fn: () => TypeChecker, typeInfoGen: TypeInfoGen)
     cached = fn()
     return cached
   }
-  ;(ltc as LateTypeChecker)[lateTypeCheckerSymbol] = true
+  Object.assign(ltc, {
+    [lateTypeCheckerSymbol]: true as const,
+    getFromSnapshotProcessor: () => ltc().getFromSnapshotProcessor(),
+    getToSnapshotProcessor: () => ltc().getToSnapshotProcessor(),
+  })
 
   const cachedTypeInfoGen = lazy(typeInfoGen)
 

package/src/types/arrayBased/typesArray.ts

@@ -1,13 +1,14 @@
 import type { Path } from "../../parent/pathTypes"
 import { isArray } from "../../utils"
 import { withErrorPathSegment } from "../../utils/errorDiagnostics"
-import { arrayCachePruning, createPerEntryCachedCheck } from "../createPerEntryCachedCheck"
+import { createWholeContainerCachedCheck } from "../createCachedTypeCheck"
 import { getTypeInfo } from "../getTypeInfo"
 import { resolveStandardType, resolveTypeChecker } from "../resolveTypeChecker"
 import type { AnyStandardType, AnyType, ArrayType } from "../schemas"
 import { TypeCheckError } from "../TypeCheckError"
 import {
   lateTypeChecker,
+  snapshotProcessorPlan,
   TypeChecker,
   TypeCheckerBaseType,
   TypeInfo,
@@ -28,31 +29,27 @@ import { prependPathElementToTypeCheckError } from "../typeCheckErrorUtils"
  * @returns
  */
 export function typesArray<T extends AnyType>(itemType: T): ArrayType<T[]> {
-  const typeInfoGen: TypeInfoGen = (t) => new ArrayTypeInfo(t, resolveStandardType(itemType))
-
-  return lateTypeChecker(() => {
-    const itemChecker = resolveTypeChecker(itemType)
+  const resolvedItemType = resolveStandardType(itemType)
+  const typeInfoGen: TypeInfoGen = (t) => new ArrayTypeInfo(t, resolvedItemType)
+  const typeChecker = lateTypeChecker(() => {
+    const itemChecker = resolveTypeChecker(resolvedItemType)
     const emptyChildPath: Path = []
 
     const getTypeName = (...recursiveTypeCheckers: TypeChecker[]) =>
       `Array<${itemChecker.getTypeName(...recursiveTypeCheckers, itemChecker)}>`
 
-    const checkArrayItems = createPerEntryCachedCheck<number>(
-      (array, checkEntry) => {
-        for (let i = 0; i < array.length; i++) {
-          const error = checkEntry(i)
-          if (error) return error
-        }
-        return null
-      },
-      (array, index, path, typeCheckedValue) => {
+    // MobX observable arrays invalidate reads at collection granularity. Per-index
+    // computeds would therefore all be invalidated by the same mutation while adding
+    // a computed and cache entry per item.
+    const checkArrayItems = createWholeContainerCachedCheck((array, path, typeCheckedValue) => {
+      for (let index = 0; index < array.length; index++) {
         const error = itemChecker.check(array[index], emptyChildPath, typeCheckedValue)
-        return error
-          ? prependPathElementToTypeCheckError(error, path, index, typeCheckedValue)
-          : null
-      },
-      arrayCachePruning
-    )
+        if (error) {
+          return prependPathElementToTypeCheckError(error, path, index, typeCheckedValue)
+        }
+      }
+      return null
+    })
 
     const thisTc: TypeChecker = new TypeChecker(
       TypeCheckerBaseType.Array,
@@ -93,29 +90,30 @@ export function typesArray<T extends AnyType>(itemType: T): ArrayType<T[]> {
         return thisTc
       },
 
-      (sn: unknown[]) => {
-        if (itemChecker.unchecked) {
-          return sn
-        }
-
-        return sn.map((item, i) =>
-          withErrorPathSegment(i, () => itemChecker.fromSnapshotProcessor(item))
-        )
-      },
-
-      (sn: unknown[]) => {
-        if (itemChecker.unchecked) {
-          return sn
-        }
-
-        return sn.map((item, i) =>
-          withErrorPathSegment(i, () => itemChecker.toSnapshotProcessor(item))
-        )
-      }
+      snapshotProcessorPlan(
+        () => [itemChecker],
+        ([itemProcessor]) =>
+          itemProcessor
+            ? (sn: unknown[]) => {
+                return sn.map((item, i) => withErrorPathSegment(i, () => itemProcessor(item)))
+              }
+            : undefined
+      ),
+
+      snapshotProcessorPlan(
+        () => [itemChecker],
+        ([itemProcessor]) =>
+          itemProcessor
+            ? (sn: unknown[]) => {
+                return sn.map((item, i) => withErrorPathSegment(i, () => itemProcessor(item)))
+              }
+            : undefined
+      )
     )
 
     return thisTc
-  }, typeInfoGen) as any
+  }, typeInfoGen)
+  return typeChecker as any
 }
 
 /**

package/src/types/arrayBased/typesTuple.ts

@@ -1,13 +1,14 @@
 import type { Path } from "../../parent/pathTypes"
 import { isArray, lazy } from "../../utils"
 import { withErrorPathSegment } from "../../utils/errorDiagnostics"
-import { createPerEntryCachedCheck } from "../createPerEntryCachedCheck"
+import { createWholeContainerCachedCheck } from "../createCachedTypeCheck"
 import { getTypeInfo } from "../getTypeInfo"
 import { resolveStandardType, resolveTypeChecker } from "../resolveTypeChecker"
 import type { AnyStandardType, AnyType, ArrayType } from "../schemas"
 import { TypeCheckError } from "../TypeCheckError"
 import {
   lateTypeChecker,
+  snapshotProcessorPlan,
   TypeChecker,
   TypeCheckerBaseType,
   TypeInfo,
@@ -28,10 +29,10 @@ import { prependPathElementToTypeCheckError } from "../typeCheckErrorUtils"
  * @returns
  */
 export function typesTuple<T extends AnyType[]>(...itemTypes: T): ArrayType<T> {
-  const typeInfoGen: TypeInfoGen = (t) => new TupleTypeInfo(t, itemTypes.map(resolveStandardType))
-
-  return lateTypeChecker(() => {
-    const checkers = itemTypes.map(resolveTypeChecker)
+  const resolvedItemTypes = itemTypes.map(resolveStandardType)
+  const typeInfoGen: TypeInfoGen = (t) => new TupleTypeInfo(t, resolvedItemTypes)
+  const typeChecker = lateTypeChecker(() => {
+    const checkers = resolvedItemTypes.map(resolveTypeChecker)
     const emptyChildPath: Path = []
 
     const getTypeName = (...recursiveTypeCheckers: TypeChecker[]) => {
@@ -45,26 +46,27 @@ export function typesTuple<T extends AnyType[]>(...itemTypes: T): ArrayType<T> {
       return "[" + typeNames.join(", ") + "]"
     }
 
-    // No setupCachePruning needed: tuple length is fixed, so entries never become stale.
-    const checkTupleItems = createPerEntryCachedCheck<number>(
-      (_array, checkEntry) => {
-        for (let i = 0; i < checkers.length; i++) {
-          const error = checkEntry(i)
-          if (error) return error
-        }
-        return null
-      },
-      (array, index, path, typeCheckedValue) => {
-        const checker = checkers[index]
+    const checkTupleItemsImperatively = (
+      array: unknown[],
+      path: Path,
+      typeCheckedValue: any
+    ): TypeCheckError | null => {
+      for (let i = 0; i < checkers.length; i++) {
+        const checker = checkers[i]
         if (checker.unchecked || checker.skipCheck) {
-          return null
+          continue
+        }
+        const error = checker.check(array[i], emptyChildPath, typeCheckedValue)
+        if (error) {
+          return prependPathElementToTypeCheckError(error, path, i, typeCheckedValue)
         }
-        const error = checker.check(array[index], emptyChildPath, typeCheckedValue)
-        return error
-          ? prependPathElementToTypeCheckError(error, path, index, typeCheckedValue)
-          : null
       }
-    )
+      return null
+    }
+
+    // MobX observable arrays invalidate reads at collection granularity, so indexed
+    // computeds cannot isolate tuple-item changes and only add allocation overhead.
+    const checkTupleItems = createWholeContainerCachedCheck(checkTupleItemsImperatively)
 
     const thisTc: TypeChecker = new TypeChecker(
       TypeCheckerBaseType.Array,
@@ -100,21 +102,36 @@ export function typesTuple<T extends AnyType[]>(...itemTypes: T): ArrayType<T> {
         return thisTc
       },
 
-      (array: unknown[]) => {
-        return array.map((item, i) => {
-          return withErrorPathSegment(i, () => checkers[i].fromSnapshotProcessor(item))
-        })
-      },
-
-      (array: unknown[]) => {
-        return array.map((item, i) => {
-          return withErrorPathSegment(i, () => checkers[i].toSnapshotProcessor(item))
-        })
-      }
+      snapshotProcessorPlan(
+        () => checkers,
+        (processors) =>
+          processors.some(Boolean)
+            ? (array: unknown[]) => {
+                return array.map((item, i) => {
+                  const processor = processors[i]
+                  return processor ? withErrorPathSegment(i, () => processor(item)) : item
+                })
+              }
+            : undefined
+      ),
+
+      snapshotProcessorPlan(
+        () => checkers,
+        (processors) =>
+          processors.some(Boolean)
+            ? (array: unknown[]) => {
+                return array.map((item, i) => {
+                  const processor = processors[i]
+                  return processor ? withErrorPathSegment(i, () => processor(item)) : item
+                })
+              }
+            : undefined
+      )
     )
 
     return thisTc
-  }, typeInfoGen) as any
+  }, typeInfoGen)
+  return typeChecker as any
 }
 
 /**