mobx-keystone 2.3.1 → 2.4.0

package/src/serialization/codec.ts

@@ -0,0 +1,338 @@
+import { frozenKey } from "../frozen/Frozen"
+import { modelTypeKey } from "../model/metadata"
+import type { PathElement } from "../parent/pathTypes"
+import { copyOwnEnumerableProps, hasOwnProp, isArray, isObject, isPlainObject } from "../utils"
+import { getCurrentErrorDiagnosticsContext } from "../utils/errorDiagnostics"
+import { builtinEncodedTypeof, unmarkedEncodingSymbol } from "./builtinSerializers"
+import { badPayloadError, CallError, CallErrorCode } from "./CallError"
+import type { JsonValue } from "./JsonValue"
+import type { DecodeContext, EncodeContext, ValueSerializer } from "./ValueSerializer"
+import { serializationMarkerKey } from "./ValueSerializer"
+
+/**
+ * @internal
+ *
+ * The tag of an escaped plain object: `{ "$mobxKeystone": "object", "v": { ...fields } }`.
+ */
+export const escapedObjectTag = "object"
+
+const reservedKeys: readonly string[] = [serializationMarkerKey, modelTypeKey, frozenKey]
+
+/**
+ * @internal
+ */
+export interface SerializerConfig {
+  /**
+   * Custom serializers followed by the built-ins (if any).
+   */
+  readonly serializers: readonly ValueSerializer[]
+  /**
+   * The serializers that could encode a value, by its `typeof`, or `"plain"` for plain arrays and
+   * objects, which no built-in encodes (custom ones are in every list).
+   */
+  readonly byTypeof: ReadonlyMap<SerializerGroup, readonly ValueSerializer[]>
+  readonly byTag: ReadonlyMap<string, ValueSerializer>
+  /**
+   * The serializer that decodes values with `$modelType` / `$frozen` (the snapshot serializer),
+   * if in the list.
+   */
+  readonly unmarked: ValueSerializer | undefined
+}
+
+const typeofResults = [
+  "string",
+  "number",
+  "bigint",
+  "boolean",
+  "symbol",
+  "undefined",
+  "object",
+  "function",
+] as const
+
+/**
+ * @internal
+ */
+export type TypeofResult = (typeof typeofResults)[number]
+
+type SerializerGroup = TypeofResult | "plain"
+
+/**
+ * @internal
+ *
+ * Groups serializers by the `typeof` of the values they could encode, plus `"plain"` for plain
+ * arrays and objects, keeping their order.
+ */
+export function groupSerializersByTypeof(
+  serializers: readonly ValueSerializer[]
+): ReadonlyMap<SerializerGroup, readonly ValueSerializer[]> {
+  const byTypeof = new Map<SerializerGroup, readonly ValueSerializer[]>(
+    typeofResults.map((t) => [
+      t,
+      serializers.filter((s) => {
+        const encodedTypeof = builtinEncodedTypeof.get(s)
+        return encodedTypeof === undefined || encodedTypeof === t
+      }),
+    ])
+  )
+  byTypeof.set(
+    "plain",
+    serializers.filter((s) => !builtinEncodedTypeof.has(s))
+  )
+  return byTypeof
+}
+
+type PlainKind = "array" | "object" | undefined
+
+function getPlainKind(value: unknown): PlainKind {
+  if (!isObject(value)) {
+    return undefined
+  }
+  if (isArray(value)) {
+    return "array"
+  }
+  return isPlainObject(value) ? "object" : undefined
+}
+
+/**
+ * Runs `fn` with `key` pushed to the error path (without allocating a closure per value).
+ */
+function withPathSegment<A, R>(key: PathElement, fn: (arg: A) => R, arg: A): R {
+  const diagnostics = getCurrentErrorDiagnosticsContext()
+  if (!diagnostics) {
+    return fn(arg)
+  }
+  diagnostics.pushPath(key)
+  try {
+    return fn(arg)
+  } finally {
+    diagnostics.popPath()
+  }
+}
+
+/**
+ * @internal
+ */
+export function isUnmarkedSerializer(serializer: ValueSerializer): boolean {
+  return unmarkedEncodingSymbol in serializer
+}
+
+/**
+ * @internal
+ */
+export function markValue(tag: string, payload: JsonValue | undefined): JsonValue {
+  return payload === undefined
+    ? { [serializationMarkerKey]: tag }
+    : { [serializationMarkerKey]: tag, v: payload }
+}
+
+/**
+ * @internal
+ */
+export function wrapSerializerError(
+  error: unknown,
+  code: CallErrorCode,
+  tag: string,
+  value: unknown
+): CallError {
+  if (error instanceof CallError) {
+    return error
+  }
+  const op = code === CallErrorCode.CannotEncode ? "encode" : "decode"
+  return new CallError({
+    code,
+    message: `the '${tag}' serializer failed to ${op} the value`,
+    previewValue: value,
+    cause: error,
+  })
+}
+
+function describeValue(value: unknown): string {
+  switch (typeof value) {
+    case "function":
+      return "a function"
+    case "symbol":
+      return "a symbol"
+    case "object": {
+      const proto = value === null ? null : Object.getPrototypeOf(value)
+      const name = proto?.constructor?.name
+      return name ? `an instance of ${name}` : "an object"
+    }
+    default:
+      return String(value)
+  }
+}
+
+/**
+ * @internal
+ *
+ * Creates the encoding context for one encoding: `ctx.encode` encodes any value, going through
+ * the list of serializers. It must run inside an error diagnostics context.
+ */
+export function createEncodeContext(config: SerializerConfig, root: object): EncodeContext {
+  // values being encoded, to detect cycles
+  const ancestors = new Set<unknown>()
+
+  const encodeWithSerializer = (serializer: ValueSerializer, value: unknown): JsonValue => {
+    let payload: JsonValue | undefined
+    try {
+      payload = serializer.encode(value, ctx)
+    } catch (e) {
+      throw wrapSerializerError(e, CallErrorCode.CannotEncode, serializer.tag, value)
+    }
+    return isUnmarkedSerializer(serializer) ? payload! : markValue(serializer.tag, payload)
+  }
+
+  const encodePlain = (value: unknown, plainKind: PlainKind): JsonValue => {
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
+      return value
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value
+    }
+    if (plainKind === "array") {
+      const array = value as readonly unknown[]
+      const len = array.length
+      const out: JsonValue[] = new Array(len)
+      for (let i = 0; i < len; i++) {
+        out[i] = ctx.encode(array[i], i)
+      }
+      return out
+    }
+    if (plainKind === "object") {
+      const object = value as Record<string, unknown>
+      const out = copyOwnEnumerableProps({} as Record<string, JsonValue>, object, ctx.encode)
+      return reservedKeys.some((k) => hasOwnProp(object, k))
+        ? markValue(escapedObjectTag, out)
+        : out
+    }
+    throw new CallError({
+      code: CallErrorCode.CannotEncode,
+      message: `cannot encode ${describeValue(value)}: no serializer handles it`,
+      previewValue: value,
+    })
+  }
+
+  const encodeAny = (value: unknown): JsonValue => {
+    const plainKind = getPlainKind(value)
+    const serializers = config.byTypeof.get(plainKind ? "plain" : typeof value)!
+    const len = serializers.length
+    for (let i = 0; i < len; i++) {
+      const serializer = serializers[i]
+      let claimed: boolean
+      try {
+        claimed = serializer.is(value, ctx)
+      } catch (e) {
+        throw wrapSerializerError(e, CallErrorCode.CannotEncode, serializer.tag, value)
+      }
+      if (claimed) {
+        return encodeWithSerializer(serializer, value)
+      }
+    }
+    return encodePlain(value, plainKind)
+  }
+
+  const encodeChecked = (value: unknown): JsonValue => {
+    if (!isObject(value) && typeof value !== "function") {
+      return encodeAny(value)
+    }
+    if (ancestors.has(value)) {
+      throw new CallError({
+        code: CallErrorCode.CannotEncode,
+        message: "cannot encode a value that contains itself",
+      })
+    }
+    ancestors.add(value)
+    try {
+      return encodeAny(value)
+    } finally {
+      ancestors.delete(value)
+    }
+  }
+
+  const ctx: EncodeContext = {
+    root,
+    encode(value: unknown, key?: PathElement): JsonValue {
+      return key === undefined ? encodeChecked(value) : withPathSegment(key, encodeChecked, value)
+    },
+  }
+
+  return ctx
+}
+
+/**
+ * @internal
+ *
+ * Creates the decoding context for one decoding: `ctx.decode` decodes any JSON value. It must run
+ * inside an error diagnostics context.
+ */
+export function createDecodeContext(config: SerializerConfig, root: object): DecodeContext {
+  const decodeWithSerializer = (serializer: ValueSerializer, json: unknown): unknown => {
+    try {
+      return serializer.decode(json, ctx)
+    } catch (e) {
+      throw wrapSerializerError(e, CallErrorCode.BadArgument, serializer.tag, json)
+    }
+  }
+
+  const decodeFields = (json: Record<string, unknown>): Record<string, unknown> =>
+    copyOwnEnumerableProps({} as Record<string, unknown>, json, (v, k) =>
+      ctx.decode(v as JsonValue, k)
+    )
+
+  const decodeMarked = (json: Record<string, unknown>): unknown => {
+    const tag = json[serializationMarkerKey]
+    if (tag === escapedObjectTag) {
+      if (!isPlainObject(json.v)) {
+        throw badPayloadError(escapedObjectTag, json)
+      }
+      return decodeFields(json.v)
+    }
+
+    const serializer = typeof tag === "string" ? config.byTag.get(tag) : undefined
+    if (!serializer) {
+      throw new CallError({
+        code: CallErrorCode.BadArgument,
+        message: `no serializer handles the tag ${JSON.stringify(tag)}`,
+        previewValue: json,
+      })
+    }
+    return decodeWithSerializer(serializer, json.v)
+  }
+
+  const decodeAny = (json: unknown): unknown => {
+    if (
+      json === null ||
+      typeof json === "string" ||
+      typeof json === "number" ||
+      typeof json === "boolean"
+    ) {
+      return json
+    }
+    if (isArray(json)) {
+      return json.map((v, i) => ctx.decode(v, i))
+    }
+    if (isPlainObject(json)) {
+      if (hasOwnProp(json, serializationMarkerKey)) {
+        return decodeMarked(json)
+      }
+      if (config.unmarked && (hasOwnProp(json, modelTypeKey) || hasOwnProp(json, frozenKey))) {
+        return decodeWithSerializer(config.unmarked, json)
+      }
+      return decodeFields(json)
+    }
+    throw new CallError({
+      code: CallErrorCode.BadArgument,
+      message: `cannot decode ${describeValue(json)}: it is not a JSON value`,
+      previewValue: json,
+    })
+  }
+
+  const ctx: DecodeContext = {
+    root,
+    decode: (json: JsonValue, key?: PathElement): unknown =>
+      key === undefined ? decodeAny(json) : withPathSegment(key, decodeAny, json),
+  }
+
+  return ctx
+}

package/src/serialization/index.ts

@@ -0,0 +1,15 @@
+export * from "./applyCall"
+export { builtinSerializers } from "./builtinSerializers"
+export * from "./Call"
+export { CallError, CallErrorCode, type CallErrorData, type CallErrorJson } from "./CallError"
+export * from "./JsonValue"
+export {
+  type IdRefJson,
+  idRefs,
+  type PathRefJson,
+  pathRefs,
+  type ReferenceNodeInfo,
+  type ReferenceSerializerOptions,
+} from "./references"
+export * from "./Serializer"
+export * from "./ValueSerializer"

package/src/serialization/references.ts

@@ -0,0 +1,225 @@
+import { rootPathToTargetPathIds } from "../actionMiddlewares/utils"
+import type { AnyModel } from "../model/BaseModel"
+import { getModelMetadata } from "../model/getModelMetadata"
+import { modelTypeKey } from "../model/metadata"
+import { isModel } from "../model/utils"
+import {
+  fastGetRoot,
+  fastGetRootPath,
+  isPathElement,
+  resolvePathCheckingIds,
+  skipIdChecking,
+} from "../parent/path"
+import type { Path, PathElement } from "../parent/pathTypes"
+import { getModelRefId, resolveId } from "../ref/core"
+import { isTreeNode } from "../tweaker/core"
+import { isArray, isPlainObject } from "../utils"
+import { badPayloadError, CallError, CallErrorCode } from "./CallError"
+import type { ValueSerializer } from "./ValueSerializer"
+
+/**
+ * What a reference serializer's `when` option is told about a node.
+ */
+export interface ReferenceNodeInfo {
+  /**
+   * Whether the node is a model.
+   */
+  readonly isModel: boolean
+  /**
+   * Whether the node is a value-type model (`Model({...}, { valueType: true })`).
+   */
+  readonly isValueType: boolean
+}
+
+/**
+ * Options of the built-in reference serializers.
+ */
+export interface ReferenceSerializerOptions {
+  /**
+   * Decides, for every node the serializer could reference, whether it does. A node it declines
+   * falls through the list like any other value: a model ends up as its snapshot, a tree array
+   * or plain object is walked. The call's target ignores it: it is always a reference.
+   *
+   * Defaults to declining value-type models: `(node, { isValueType }) => !isValueType`.
+   */
+  when?(node: object, info: ReferenceNodeInfo): boolean
+}
+
+/**
+ * A path reference, the payload of `{ "$mobxKeystone": "pathRef", "v": ... }`.
+ */
+export type PathRefJson = {
+  /**
+   * Path from the root to the node, through data nodes (as in patches).
+   */
+  path: PathElement[]
+  /**
+   * Id of the model reached by each step of the path (`null` for non-models).
+   * Optional when decoding: without it, ids aren't checked.
+   */
+  ids?: (string | null)[]
+}
+
+/**
+ * An id reference, the payload of `{ "$mobxKeystone": "idRef", "v": ... }`.
+ */
+export type IdRefJson = {
+  /**
+   * The model type (`$modelType`).
+   */
+  type: string
+  /**
+   * The model id.
+   */
+  id: string
+}
+
+const defaultWhen = (_node: object, info: ReferenceNodeInfo) => !info.isValueType
+
+function getNodeInfo(node: object): ReferenceNodeInfo {
+  const nodeIsModel = isModel(node)
+  return {
+    isModel: nodeIsModel,
+    isValueType: nodeIsModel && getModelMetadata(node).valueType,
+  }
+}
+
+/**
+ * @internal
+ */
+export function isNodeOfTree(value: unknown, root: object): value is object {
+  return isTreeNode(value) && fastGetRoot(value, false) === root
+}
+
+/**
+ * @internal
+ */
+export const pathRefTag = "pathRef"
+
+/**
+ * @internal
+ *
+ * Encodes a node of the tree as a full path reference.
+ */
+export function encodePathRef(node: object): PathRefJson {
+  const rootPath = fastGetRootPath(node, false)
+  return {
+    path: [...rootPath.path],
+    ids: rootPathToTargetPathIds(rootPath),
+  }
+}
+
+/**
+ * @internal
+ *
+ * Decodes a path reference against a tree.
+ */
+export function decodePathRef(json: unknown, root: object): object {
+  if (!isPlainObject(json) || !isArray(json.path) || !json.path.every(isPathElement)) {
+    throw badPayloadError(pathRefTag, json)
+  }
+  const path = json.path as Path
+  const ids = json.ids
+  if (
+    ids !== undefined &&
+    (!isArray(ids) ||
+      ids.length !== path.length ||
+      !ids.every((id) => id === null || typeof id === "string"))
+  ) {
+    throw badPayloadError(pathRefTag, json)
+  }
+
+  const result = resolvePathCheckingIds(
+    root,
+    path,
+    (ids as (string | null)[] | undefined) ?? path.map(() => skipIdChecking)
+  )
+  // only tree nodes can be referenced, so anything else is not a valid reference
+  if (!result.resolved || !isTreeNode(result.value)) {
+    throw new CallError({
+      code: CallErrorCode.NotFound,
+      message: `object at path ${JSON.stringify(path)}${
+        ids === undefined ? "" : ` with ids ${JSON.stringify(ids)}`
+      } could not be resolved`,
+    })
+  }
+  return result.value
+}
+
+/**
+ * References nodes of the tree by their path from the root, checking the ids of the models along
+ * it: `{ "$mobxKeystone": "pathRef", "v": { "path": ["cards", 2], "ids": [null, "c1"] } }`.
+ * It reaches any node, including tree arrays and plain objects.
+ *
+ * @param options Options.
+ * @returns The reference serializer.
+ */
+export function pathRefs(
+  options?: ReferenceSerializerOptions
+): ValueSerializer<object, PathRefJson> {
+  const when = options?.when ?? defaultWhen
+
+  return {
+    tag: pathRefTag,
+
+    is(value, ctx): value is object {
+      return isNodeOfTree(value, ctx.root) && when(value, getNodeInfo(value))
+    },
+
+    encode: encodePathRef,
+
+    decode(json, ctx) {
+      return decodePathRef(json, ctx.root)
+    },
+
+    claimsTarget(value, ctx) {
+      return isNodeOfTree(value, ctx.root)
+    },
+  }
+}
+
+function claimsById(value: unknown, root: object): value is AnyModel {
+  return isModel(value) && getModelRefId(value) !== undefined && isNodeOfTree(value, root)
+}
+
+/**
+ * References models of the tree that have an id by their type and id:
+ * `{ "$mobxKeystone": "idRef", "v": { "type": "app/Card", "id": "c1" } }`. Ids are read and
+ * resolved as `getModelRefId` and `resolveId` do, and the type must match.
+ *
+ * @param options Options.
+ * @returns The reference serializer.
+ */
+export function idRefs(options?: ReferenceSerializerOptions): ValueSerializer<AnyModel, IdRefJson> {
+  const when = options?.when ?? defaultWhen
+
+  return {
+    tag: "idRef",
+
+    is(value, ctx): value is AnyModel {
+      return claimsById(value, ctx.root) && when(value, getNodeInfo(value))
+    },
+
+    encode(value) {
+      return { type: value[modelTypeKey], id: getModelRefId(value)! }
+    },
+
+    decode(json, ctx) {
+      if (!isPlainObject(json) || typeof json.type !== "string" || typeof json.id !== "string") {
+        throw badPayloadError("idRef", json)
+      }
+      const found = resolveId(ctx.root, json.id)
+      if (!isModel(found) || found[modelTypeKey] !== json.type) {
+        throw new CallError({
+          code: CallErrorCode.NotFound,
+          message: `model of type '${json.type}' with id '${json.id}' could not be resolved`,
+        })
+      }
+      return found
+    },
+
+    claimsTarget(value, ctx) {
+      return claimsById(value, ctx.root)
+    },
+  }
+}