mobx-keystone 2.1.0 → 2.3.0

package/src/types/modelTypeMatching.ts

@@ -0,0 +1,276 @@
+import { modelTypeKey } from "../model/metadata"
+import {
+  findModelInfoForPrototype,
+  getModelSubclassDistance,
+  getModelSubclassDistanceForName,
+} from "../modelShared/modelInfo"
+import { isObject } from "../utils"
+
+/**
+ * Model type matching pass used while unions match a value against their branches, so they can
+ * prefer the branches whose models are the closest to the ones named by the snapshot
+ * (`$modelType`):
+ * - `none`: not matching union branches; model types match snapshots of their own model and of
+ *   its subclasses.
+ * - `exact`: model types only match snapshots of their own model.
+ * - `closest`: model types also match snapshots of subclasses, adding how far the subclass is
+ *   from the model to `subclassDistance`, so unions can pick the branch with the lowest total.
+ *
+ * @internal
+ */
+export type ModelTypeMatchingPass = "none" | "exact" | "closest"
+
+let currentPass: ModelTypeMatchingPass = "none"
+let subclassDistance = 0
+let rejectedModelSnapshot = false
+
+/**
+ * @internal
+ */
+export function getModelTypeMatchingPass(): ModelTypeMatchingPass {
+  return currentPass
+}
+
+/**
+ * Records that a model type matched a snapshot of a subclass `distance` levels below it.
+ *
+ * @internal
+ */
+export function addModelSubclassDistance(distance: number): void {
+  if (currentPass === "closest") {
+    subclassDistance += distance
+  }
+}
+
+/**
+ * Records, while unions match their branches, that a model type (or ref) rejected a model
+ * snapshot that some other branch could accept: one of a subclass in the exact pass (it would
+ * match it in the closest pass), or one of another registered model.
+ *
+ * @internal
+ */
+export function rejectModelSnapshot(): void {
+  if (currentPass !== "none") {
+    rejectedModelSnapshot = true
+  }
+}
+
+/**
+ * Runs a value match, returning whether it matched, or `undefined` if it did not because a model
+ * type (or ref) rejected a model snapshot (see `rejectModelSnapshot`).
+ *
+ * @internal
+ */
+export function matchUnlessModelSnapshotRejected<A, B>(
+  fn: (a: A, b: B) => unknown,
+  a: A,
+  b: B
+): boolean | undefined {
+  const prevRejectedModelSnapshot = rejectedModelSnapshot
+  rejectedModelSnapshot = false
+  try {
+    const matched = !!fn(a, b)
+    return matched || !rejectedModelSnapshot ? matched : undefined
+  } finally {
+    // let outer matches know too
+    rejectedModelSnapshot ||= prevRejectedModelSnapshot
+  }
+}
+
+/**
+ * Whether a snapshot `$modelType` matches a model (`modelName`): its own model or, outside the
+ * exact pass, a subclass of it. Registered names are compared rather than classes, since with
+ * hot reloading a subclass might still extend a previous registration of the model.
+ *
+ * @internal
+ */
+export function snapshotModelTypeMatches(snModelType: unknown, modelName: string): boolean {
+  if (typeof snModelType !== "string") {
+    return false
+  }
+  if (snModelType === modelName) {
+    return true
+  }
+  const distance = getModelSubclassDistanceForName(snModelType, modelName)
+  if (distance === undefined) {
+    return false
+  }
+  if (distance < 0 || currentPass === "exact") {
+    rejectModelSnapshot()
+    return false
+  }
+  addModelSubclassDistance(distance)
+  return true
+}
+
+/**
+ * Whether a snapshot `$modelType` names a registered model that is neither a model
+ * (`modelName`) nor a subclass of it, so processing the snapshot as that model would silently
+ * create an unrelated model (unregistered names are reported later by the model snapshotter).
+ *
+ * @internal
+ */
+export function isUnrelatedSnapshotModelType(snModelType: unknown, modelName: string): boolean {
+  return (
+    typeof snModelType === "string" &&
+    snModelType !== modelName &&
+    (getModelSubclassDistanceForName(snModelType, modelName) ?? 0) < 0
+  )
+}
+
+/**
+ * Whether a model instance is of a model (`modelName`) or of a subclass of it, comparing
+ * registered names, since with hot reloading the instance model might still extend a previous
+ * registration of the model.
+ *
+ * @internal
+ */
+export function isModelInstanceOfModelName(value: object, modelName: string): boolean {
+  const valueModelInfo = findModelInfoForPrototype(Object.getPrototypeOf(value))
+  return !!valueModelInfo && getModelSubclassDistance(valueModelInfo, modelName) >= 0
+}
+
+/**
+ * Whether a value is a snapshot that names its model (`$modelType`).
+ *
+ * @internal
+ */
+export function hasSnapshotModelType(value: unknown): boolean {
+  return isObject(value) && typeof value[modelTypeKey] === "string"
+}
+
+/**
+ * Runs a function in the given model type matching pass, restoring the current one afterwards.
+ *
+ * @internal
+ */
+export function runInModelTypeMatchingPass<A, B, R>(
+  pass: ModelTypeMatchingPass,
+  fn: (a: A, b: B) => R,
+  a: A,
+  b: B
+): R {
+  if (pass === "none" && currentPass === "none") {
+    return fn(a, b)
+  }
+
+  const prevPass = currentPass
+  const prevDistance = subclassDistance
+  const prevRejectedModelSnapshot = rejectedModelSnapshot
+  currentPass = pass
+  subclassDistance = 0
+  rejectedModelSnapshot = false
+  try {
+    return fn(a, b)
+  } finally {
+    currentPass = prevPass
+    subclassDistance = prevDistance
+    rejectedModelSnapshot = prevRejectedModelSnapshot
+  }
+}
+
+/**
+ * Finds the union branch (candidate) that matches a value, preferring branches that match the
+ * exact models named by the snapshot (branches without models count as exact matches), then
+ * the branches whose models are the closest base models of the snapshot ones (the fewest
+ * subclass levels away in total), and the first one on ties.
+ *
+ * @internal
+ */
+export function findClosestModelTypeMatch<T, R>(
+  candidates: ReadonlyArray<T>,
+  match: (candidate: T, value: unknown) => R | null | undefined,
+  value: unknown
+): R | undefined {
+  switch (currentPass) {
+    case "exact":
+      // nested inside an exact pass
+      return findNestedMatch(findFirstMatch, candidates, match, value, 0)
+    case "closest":
+      // nested inside a closest pass
+      return findNestedMatch(findClosestMatch, candidates, match, value, 0)
+    default:
+      try {
+        currentPass = "exact"
+        const exactMatch = findFirstMatch(candidates, match, value)
+        if (exactMatch != null) {
+          return exactMatch
+        }
+
+        currentPass = "closest"
+        subclassDistance = 0
+        // no branch matched exactly, so none can be less than one subclass level away
+        return findClosestMatch(candidates, match, value, 1)
+      } finally {
+        currentPass = "none"
+        subclassDistance = 0
+        rejectedModelSnapshot = false
+      }
+  }
+}
+
+function findNestedMatch<T, R>(
+  find: (
+    candidates: ReadonlyArray<T>,
+    match: (candidate: T, value: unknown) => R | null | undefined,
+    value: unknown,
+    minPossibleDistance: number
+  ) => R | undefined,
+  candidates: ReadonlyArray<T>,
+  match: (candidate: T, value: unknown) => R | null | undefined,
+  value: unknown,
+  minPossibleDistance: number
+): R | undefined {
+  const prevRejectedModelSnapshot = rejectedModelSnapshot
+  const result = find(candidates, match, value, minPossibleDistance)
+  if (result != null) {
+    // model snapshots rejected by other branches do not matter then
+    rejectedModelSnapshot = prevRejectedModelSnapshot
+  }
+  return result
+}
+
+/**
+ * Finds the first candidate that matches a value.
+ *
+ * @internal
+ */
+export function findFirstMatch<T, R>(
+  candidates: ReadonlyArray<T>,
+  match: (candidate: T, value: unknown) => R | null | undefined,
+  value: unknown
+): R | undefined {
+  for (let i = 0; i < candidates.length; i++) {
+    const result = match(candidates[i], value)
+    if (result != null) {
+      return result
+    }
+  }
+  return undefined
+}
+
+function findClosestMatch<T, R>(
+  candidates: ReadonlyArray<T>,
+  match: (candidate: T, value: unknown) => R | null | undefined,
+  value: unknown,
+  minPossibleDistance: number
+): R | undefined {
+  const prevDistance = subclassDistance
+  let best: R | undefined
+  let bestDistance = Number.POSITIVE_INFINITY
+
+  for (let i = 0; i < candidates.length; i++) {
+    subclassDistance = 0
+    const result = match(candidates[i], value)
+    if (result != null && subclassDistance < bestDistance) {
+      best = result
+      bestDistance = subclassDistance
+      if (bestDistance <= minPossibleDistance) {
+        break
+      }
+    }
+  }
+
+  subclassDistance = prevDistance + (best != null ? bestDistance : 0)
+  return best
+}

package/src/types/objectBased/typesDataModelData.ts

@@ -90,6 +90,11 @@ export function typesDataModelData<M = never, K = M>(
 
       const resolvedDataTypeChecker = resolveTypeChecker(standardDataType)
 
+      const processorPlan = snapshotProcessorPlan(
+        () => [resolvedDataTypeChecker],
+        ([processor]) => processor
+      )
+
       const thisTc: TypeChecker = new TypeChecker(
         TypeCheckerBaseType.Object,
 
@@ -104,15 +109,9 @@ export function typesDataModelData<M = never, K = M>(
           return resolvedDataTypeChecker.snapshotType(value) ? thisTc : null
         },
 
-        snapshotProcessorPlan(
-          () => [resolvedDataTypeChecker],
-          ([processor]) => processor
-        ),
+        processorPlan,
 
-        snapshotProcessorPlan(
-          () => [resolvedDataTypeChecker],
-          ([processor]) => processor
-        )
+        processorPlan
       )
 
       return thisTc

package/src/types/objectBased/typesModel.ts

@@ -2,14 +2,20 @@ import type { O } from "ts-toolbelt"
 import type { AnyModel } from "../../model/BaseModel"
 import { getModelMetadata } from "../../model/getModelMetadata"
 import { modelTypeKey } from "../../model/metadata"
-import { isModelClass } from "../../model/utils"
+import { isModel, isModelClass } from "../../model/utils"
 import type { ModelClass } from "../../modelShared/BaseModelShared"
 import { modelInfoByClass } from "../../modelShared/modelInfo"
 import { getInternalModelClassPropsInfo } from "../../modelShared/modelPropsInfo"
 import { noDefaultValue } from "../../modelShared/prop"
 import { isObject, lazy, setProtoProp } from "../../utils"
 import { getTypeInfo } from "../getTypeInfo"
+import {
+  isModelInstanceOfModelName,
+  isUnrelatedSnapshotModelType,
+  snapshotModelTypeMatches,
+} from "../modelTypeMatching"
 import { registerStandardTypeResolver, resolveTypeChecker } from "../resolveTypeChecker"
+import { SnapshotTypeMismatchError } from "../SnapshotTypeMismatchError"
 import type { AnyStandardType, ModelType } from "../schemas"
 import { TypeCheckError } from "../TypeCheckError"
 import {
@@ -73,7 +79,10 @@ export function typesModel<M = never, K = M>(modelClass: _ClassOrObject<M, K>):
         TypeCheckerBaseType.Object,
 
         (value, path, typeCheckedValue) => {
-          if (!(value instanceof modelClazz)) {
+          if (
+            !(value instanceof modelClazz) &&
+            !(isModel(value) && isModelInstanceOfModelName(value, modelInfo.name))
+          ) {
             return new TypeCheckError({
               path,
               expectedTypeName: typeName,
@@ -96,9 +105,9 @@ export function typesModel<M = never, K = M>(modelClass: _ClassOrObject<M, K>):
             return null
           }
 
-          if (value[modelTypeKey] !== undefined) {
-            // fast check
-            return value[modelTypeKey] === modelInfo.name ? thisTc : null
+          const snModelType = value[modelTypeKey]
+          if (snModelType !== undefined) {
+            return snapshotModelTypeMatches(snModelType, modelInfo.name) ? thisTc : null
           }
 
           if (resolvedDataTypeChecker) {
@@ -112,7 +121,15 @@ export function typesModel<M = never, K = M>(modelClass: _ClassOrObject<M, K>):
         // No withErrorPathSegment wrapping needed here — model snapshot processors
         // delegate to the data type checker, which handles path segments at the property level.
         (sn) => {
-          if (sn[modelTypeKey]) {
+          const snModelType = sn[modelTypeKey]
+          if (typeof snModelType === "string") {
+            // the snapshot names its own model; make sure it is this model or a subclass of it
+            if (isUnrelatedSnapshotModelType(snModelType, modelInfo.name)) {
+              throw new SnapshotTypeMismatchError({
+                expectedTypeName: typeName,
+                actualValue: sn,
+              })
+            }
             return sn
           } else {
             return {

package/src/types/objectBased/typesObject.ts

@@ -173,6 +173,14 @@ function typesObjectHelper<S>(objFn: S, frozen: boolean, typeInfoGen: TypeInfoGe
       }
     )
 
+    const processorPlan = snapshotProcessorPlan(
+      () => schemaEntries.map((entry) => entry.getResolvedChecker()),
+      (processors) =>
+        processors.some(Boolean)
+          ? (obj: Record<string, unknown>) => applySnapshotProcessor(obj, processors)
+          : undefined
+    )
+
     const thisTc: TypeChecker = new TypeChecker(
       TypeCheckerBaseType.Object,
 
@@ -208,21 +216,9 @@ function typesObjectHelper<S>(objFn: S, frozen: boolean, typeInfoGen: TypeInfoGe
         return thisTc
       },
 
-      snapshotProcessorPlan(
-        () => schemaEntries.map((entry) => entry.getResolvedChecker()),
-        (processors) =>
-          processors.some(Boolean)
-            ? (obj: Record<string, unknown>) => applySnapshotProcessor(obj, processors)
-            : undefined
-      ),
-
-      snapshotProcessorPlan(
-        () => schemaEntries.map((entry) => entry.getResolvedChecker()),
-        (processors) =>
-          processors.some(Boolean)
-            ? (obj: Record<string, unknown>) => applySnapshotProcessor(obj, processors)
-            : undefined
-      )
+      processorPlan,
+
+      processorPlan
     )
 
     return thisTc

package/src/types/objectBased/typesRecord.ts

@@ -83,6 +83,14 @@ export function typesRecord<T extends AnyType>(valueType: T): RecordType<T> {
 
     const checkRecordValues = createChunkedRecordCachedCheck(iterateRecordEntries, checkRecordEntry)
 
+    const processorPlan = snapshotProcessorPlan(
+      () => [valueChecker],
+      ([processor]) =>
+        processor
+          ? (obj: Record<string, unknown>) => applySnapshotProcessor(obj, processor)
+          : undefined
+    )
+
     const thisTc: TypeChecker = new TypeChecker(
       TypeCheckerBaseType.Object,
 
@@ -126,21 +134,9 @@ export function typesRecord<T extends AnyType>(valueType: T): RecordType<T> {
         return thisTc
       },
 
-      snapshotProcessorPlan(
-        () => [valueChecker],
-        ([processor]) =>
-          processor
-            ? (obj: Record<string, unknown>) => applySnapshotProcessor(obj, processor)
-            : undefined
-      ),
-
-      snapshotProcessorPlan(
-        () => [valueChecker],
-        ([processor]) =>
-          processor
-            ? (obj: Record<string, unknown>) => applySnapshotProcessor(obj, processor)
-            : undefined
-      )
+      processorPlan,
+
+      processorPlan
     )
 
     return thisTc

package/src/types/objectBased/typesRef.ts

@@ -1,9 +1,16 @@
 import { modelTypeKey } from "../../model/metadata"
+import { isModel } from "../../model/utils"
 import { modelInfoByClass } from "../../modelShared/modelInfo"
 import type { Ref, RefConstructor } from "../../ref/Ref"
 import { isObject } from "../../utils"
+import {
+  isModelInstanceOfModelName,
+  isUnrelatedSnapshotModelType,
+  snapshotModelTypeMatches,
+} from "../modelTypeMatching"
 import { typesString } from "../primitiveBased/typesPrimitive"
 import { resolveTypeChecker } from "../resolveTypeChecker"
+import { SnapshotTypeMismatchError } from "../SnapshotTypeMismatchError"
 import type { ModelType } from "../schemas"
 import { TypeCheckError } from "../TypeCheckError"
 import { TypeChecker, TypeCheckerBaseType, TypeInfo } from "../TypeChecker"
@@ -36,7 +43,10 @@ export function typesRef<O extends object>(refConstructor: RefConstructor<O>): M
     TypeCheckerBaseType.Object,
 
     (value, path, typeCheckedValue) => {
-      if (!(value instanceof refConstructor.refClass)) {
+      if (
+        !(value instanceof refConstructor.refClass) &&
+        !(isModel(value) && isModelInstanceOfModelName(value, modelInfo.name))
+      ) {
         return new TypeCheckError({
           path,
           expectedTypeName: typeName,
@@ -56,16 +66,25 @@ export function typesRef<O extends object>(refConstructor: RefConstructor<O>): M
         return null
       }
 
-      if (obj[modelTypeKey] !== undefined) {
+      const snModelType = obj[modelTypeKey]
+      if (snModelType !== undefined) {
         // fast check
-        return obj[modelTypeKey] === modelInfo.name ? thisTc : null
+        return snapshotModelTypeMatches(snModelType, modelInfo.name) ? thisTc : null
       }
 
       return refDataTypeChecker.snapshotType(obj) ? thisTc : null
     },
 
     (sn: Record<string, unknown>) => {
-      if (sn[modelTypeKey]) {
+      const snModelType = sn[modelTypeKey]
+      if (typeof snModelType === "string") {
+        // the snapshot names its own model; make sure it is this ref or a subclass of it
+        if (isUnrelatedSnapshotModelType(snModelType, modelInfo.name)) {
+          throw new SnapshotTypeMismatchError({
+            expectedTypeName: typeName,
+            actualValue: sn,
+          })
+        }
         return sn
       } else {
         return {