mobx-keystone 2.3.0 → 2.4.0

package/src/serialization/Call.ts

@@ -0,0 +1,58 @@
+import type { CallKind } from "../action/CallKind"
+import type { JsonValue } from "./JsonValue"
+
+/**
+ * A call as JSON, as `Serializer.encodeCall` returns it and `Serializer.decodeCall` takes it.
+ */
+export interface EncodedCall {
+  /**
+   * A reference to the node the call runs on; for a standalone action, its first argument.
+   */
+  target: JsonValue
+  /**
+   * Name of the action or view.
+   */
+  name: string
+  /**
+   * Encoded arguments; left out to read a getter.
+   */
+  args?: JsonValue[]
+}
+
+/**
+ * A call to an action or a view of a node.
+ */
+export interface Call {
+  /**
+   * The node the call runs on; for a standalone action, its first argument.
+   */
+  target: object
+  /**
+   * Name of the action or view.
+   */
+  name: string
+  /**
+   * Arguments (for a standalone action, without the target); left out to read a getter.
+   */
+  args?: unknown[]
+}
+
+/**
+ * A call whose target and name are resolved, as `Serializer.decodeCall` returns it and `canCall`
+ * gets it.
+ */
+export interface ResolvedCall extends Readonly<Call> {
+  /**
+   * What `name` resolved to on the target.
+   */
+  readonly kind: CallKind
+  /**
+   * Whether it is a `@modelFlow` or a `standaloneFlow`, which needs `applyCallAsync`.
+   */
+  readonly isFlow: boolean
+  /**
+   * The arguments as JSON, only on a call returned by `decodeCall`. Reading `args` decodes them
+   * (once).
+   */
+  readonly rawArgs?: JsonValue[]
+}

package/src/serialization/CallError.ts

@@ -0,0 +1,153 @@
+import type { Path } from "../parent/pathTypes"
+import { MobxKeystoneError } from "../utils"
+import {
+  buildErrorMessageWithDiagnostics,
+  getErrorPathSnapshot,
+  noErrorValuePreview,
+} from "../utils/errorDiagnostics"
+
+/**
+ * The reason a call failed.
+ */
+export enum CallErrorCode {
+  /**
+   * The target, or a reference in the arguments, doesn't resolve.
+   */
+  NotFound = "notFound",
+  /**
+   * Nothing by that name can be called on the target.
+   */
+  UnknownName = "unknownName",
+  /**
+   * The name exists, but can't be used as asked (e.g. a method read without `args`).
+   */
+  WrongKind = "wrongKind",
+  /**
+   * Refused by `canCall`.
+   */
+  Forbidden = "forbidden",
+  /**
+   * An argument (or any other value being decoded) failed to decode.
+   */
+  BadArgument = "badArgument",
+  /**
+   * A value (usually the result) can't be encoded.
+   */
+  CannotEncode = "cannotEncode",
+}
+
+/**
+ * What a `CallError` is built from, e.g. by a custom `ValueSerializer` that wants to choose the
+ * code (a `CallError` it throws passes through as it is; any other error is wrapped).
+ */
+export interface CallErrorData {
+  /**
+   * The reason.
+   */
+  code: CallErrorCode
+  /**
+   * The message, without the path and value preview the error adds to it.
+   */
+  message: string
+  /**
+   * Path relative to the call or value, e.g. `["args", 1, "items", 3]`.
+   * Defaults to where the value being encoded or decoded is.
+   */
+  path?: Path
+  /**
+   * The value the error is about, shown in the message.
+   */
+  previewValue?: unknown
+  /**
+   * The error that caused it, if any. Its message is added to `message`, but left out of
+   * `toJSON()`, since it may hold the server's data.
+   */
+  cause?: unknown
+}
+
+/**
+ * The JSON form of a `CallError`, safe to send back to the caller.
+ */
+export interface CallErrorJson {
+  code: CallErrorCode
+  message: string
+  path: Path
+}
+
+/**
+ * Thrown when a call or a value can't be decoded, resolved, allowed, run or encoded
+ * (extends `MobxKeystoneError`). Errors thrown by the action or view being called are not
+ * `CallError`s: they are rethrown as they are.
+ *
+ * Use `instanceof CallError` to distinguish call errors from other
+ * `MobxKeystoneError` instances.
+ */
+export class CallError extends MobxKeystoneError {
+  /**
+   * The reason.
+   */
+  readonly code: CallErrorCode
+  /**
+   * Where in the call or value the error is, e.g. `["args", 1]`.
+   */
+  readonly path: Path
+  /**
+   * The error that caused it, if any.
+   */
+  readonly cause?: unknown
+
+  private readonly jsonMessage: string
+
+  constructor(data: CallErrorData) {
+    const path = data.path ?? getErrorPathSnapshot() ?? []
+    const previewValue = "previewValue" in data ? data.previewValue : noErrorValuePreview
+    const causeMessage =
+      data.cause === undefined
+        ? undefined
+        : data.cause instanceof Error
+          ? data.cause.message
+          : String(data.cause)
+
+    super(
+      buildErrorMessageWithDiagnostics({
+        message: causeMessage === undefined ? data.message : `${data.message}: ${causeMessage}`,
+        path,
+        previewValue,
+      })
+    )
+
+    this.code = data.code
+    this.path = path
+    this.cause = data.cause
+    // a CannotEncode value is the server's, and so may be a cause's message
+    this.jsonMessage =
+      data.code === CallErrorCode.CannotEncode
+        ? data.message
+        : causeMessage === undefined
+          ? this.message
+          : buildErrorMessageWithDiagnostics({ message: data.message, path, previewValue })
+  }
+
+  /**
+   * The error as JSON, for RPC and tool layers. It leaves out the cause's message, and the value
+   * preview of a `CannotEncode` error, since they may hold the server's data.
+   */
+  toJSON(): CallErrorJson {
+    return {
+      code: this.code,
+      message: this.jsonMessage,
+      path: this.path,
+    }
+  }
+}
+
+/**
+ * @internal
+ */
+export function badPayloadError(tag: string, json: unknown): CallError {
+  return new CallError({
+    code: CallErrorCode.BadArgument,
+    message: `invalid '${tag}' value`,
+    previewValue: json,
+  })
+}

package/src/serialization/JsonValue.ts

@@ -0,0 +1,12 @@
+/**
+ * A JSON value: what `JSON.parse` can return.
+ */
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | {
+      [key: string]: JsonValue
+    }

package/src/serialization/Serializer.ts

@@ -0,0 +1,321 @@
+import type { ActionCall } from "../action/applyAction"
+import { resolvePathCheckingIds } from "../parent/path"
+import { getStandaloneAction } from "../standardActions/actions"
+import { failure, hasOwnProp, isArray, isObject, isPlainObject } from "../utils"
+import { runWithNewErrorDiagnosticsContext, withErrorPathSegment } from "../utils/errorDiagnostics"
+import { builtinSerializers } from "./builtinSerializers"
+import type { Call, EncodedCall, ResolvedCall } from "./Call"
+import { CallError, CallErrorCode } from "./CallError"
+import {
+  createDecodeContext,
+  createEncodeContext,
+  escapedObjectTag,
+  groupSerializersByTypeof,
+  isUnmarkedSerializer,
+  markValue,
+  type SerializerConfig,
+  wrapSerializerError,
+} from "./codec"
+import type { JsonValue } from "./JsonValue"
+import { decodePathRef, encodePathRef, pathRefs, pathRefTag } from "./references"
+import {
+  assertIsCallShape,
+  assertIsTargetInTree,
+  assertIsTreeRoot,
+  createResolvedCall,
+  resolveCallNameOrThrow,
+} from "./resolvedCall"
+import type { DecodeContext, EncodeContext, ValueSerializer } from "./ValueSerializer"
+import { serializationMarkerKey } from "./ValueSerializer"
+
+/**
+ * Encodes and decodes values and calls against a tree, with a list of value serializers.
+ * Created with `createSerializer`.
+ *
+ * Every operation takes the root of the tree as its first argument; it must be a tree root.
+ */
+export interface Serializer {
+  /**
+   * The list of value serializers it was created with, without the built-ins.
+   */
+  readonly serializers: readonly ValueSerializer[]
+
+  /**
+   * Encodes a value as JSON. Nodes of the tree go as references when a reference serializer in
+   * the list claims them.
+   *
+   * @param root Root of the tree.
+   * @param value Value to encode.
+   * @returns The encoded value.
+   */
+  encodeValue(root: object, value: unknown): JsonValue
+
+  /**
+   * Decodes a value encoded with `encodeValue`. References are resolved against the tree;
+   * snapshots become new instances.
+   *
+   * @param root Root of the tree.
+   * @param json Value to decode.
+   * @returns The decoded value.
+   */
+  decodeValue(root: object, json: JsonValue): unknown
+
+  /**
+   * Encodes a call (an `ActionCall`, e.g. from `onActionMiddleware`'s `onStart`, or a `Call`)
+   * as JSON. The target always goes as a reference; for a standalone action, it isn't repeated
+   * in the arguments.
+   *
+   * Encode an `ActionCall` before the action runs (e.g. in `onStart`), so its arguments are
+   * encoded against the tree the receiver has.
+   *
+   * @param root Root of the tree.
+   * @param call The call.
+   * @returns The encoded call.
+   */
+  encodeCall(root: object, call: ActionCall | Call): EncodedCall
+
+  /**
+   * Decodes a call encoded with `encodeCall`: the target is resolved and the name resolved on
+   * it, nothing is run. The arguments are decoded when `args` is first read.
+   *
+   * @param root Root of the tree.
+   * @param json The encoded call.
+   * @returns The resolved call, to pass to `applyCall` or `applyCallAsync`.
+   */
+  decodeCall(root: object, json: EncodedCall | JsonValue): ResolvedCall
+}
+
+/**
+ * Options of `createSerializer`.
+ */
+export interface SerializerOptions {
+  /**
+   * Value serializers, tried in order before the built-ins when encoding.
+   */
+  serializers?: readonly ValueSerializer[]
+  /**
+   * Whether to append the built-in serializers (`builtinSerializers`) to the list.
+   * Defaults to `true`.
+   */
+  builtins?: boolean
+}
+
+function assertIsValueSerializer(serializer: unknown, index: number): void {
+  if (isObject(serializer) && typeof serializer.encodeValue === "function") {
+    throw failure(
+      `serializers[${index}] is a serializer; to extend one, spread its '.serializers' into the list`
+    )
+  }
+  if (
+    !isObject(serializer) ||
+    typeof serializer.tag !== "string" ||
+    serializer.tag === "" ||
+    typeof serializer.is !== "function" ||
+    typeof serializer.encode !== "function" ||
+    typeof serializer.decode !== "function" ||
+    (serializer.claimsTarget !== undefined && typeof serializer.claimsTarget !== "function")
+  ) {
+    throw failure(
+      `serializers[${index}] must be a value serializer ({ tag, is, encode, decode, claimsTarget? }) with a non-empty tag`
+    )
+  }
+}
+
+function isActionCall(call: ActionCall | Call): call is ActionCall {
+  return hasOwnProp(call, "actionName")
+}
+
+/**
+ * Creates a serializer from a list of value serializers. When encoding, a value goes through the
+ * first serializer whose `is` accepts it, then the built-ins (unless `builtins` is `false`),
+ * then as plain JSON; decoding picks the serializer by tag.
+ *
+ * @param options Options.
+ * @returns The serializer.
+ */
+export function createSerializer(options: SerializerOptions = {}): Serializer {
+  const custom = options.serializers ? [...options.serializers] : []
+  custom.forEach(assertIsValueSerializer)
+
+  const serializers: readonly ValueSerializer[] =
+    options.builtins === false
+      ? custom
+      : [
+          ...custom,
+          ...Object.values<ValueSerializer>(builtinSerializers).filter((s) => !custom.includes(s)),
+        ]
+
+  const byTag = new Map<string, ValueSerializer>()
+  for (const serializer of serializers) {
+    if (serializer.tag === escapedObjectTag) {
+      throw failure(`the tag '${escapedObjectTag}' is reserved`)
+    }
+    if (byTag.has(serializer.tag)) {
+      throw failure(`there is more than one serializer with tag '${serializer.tag}'`)
+    }
+    byTag.set(serializer.tag, serializer)
+  }
+
+  const config: SerializerConfig = {
+    serializers,
+    byTypeof: groupSerializersByTypeof(serializers),
+    byTag,
+    unmarked: serializers.find(isUnmarkedSerializer),
+  }
+
+  const encodeTarget = (target: unknown, ctx: EncodeContext): JsonValue => {
+    assertIsTargetInTree(target, ctx.root)
+    // only reference serializers are asked, through `claimsTarget`, which ignores `when` since
+    // the call must run on the node itself
+    for (const serializer of serializers) {
+      let payload: JsonValue | undefined
+      try {
+        if (!serializer.claimsTarget?.(target, ctx)) {
+          continue
+        }
+        payload = serializer.encode(target, ctx)
+      } catch (e) {
+        throw wrapSerializerError(e, CallErrorCode.CannotEncode, serializer.tag, target)
+      }
+      return markValue(serializer.tag, payload)
+    }
+    return markValue(pathRefTag, encodePathRef(target))
+  }
+
+  const decodeTarget = (json: unknown, ctx: DecodeContext): object => {
+    const tag = isPlainObject(json) ? json[serializationMarkerKey] : undefined
+    const serializer = typeof tag === "string" ? byTag.get(tag) : undefined
+
+    let target: unknown
+    if (tag === pathRefTag && !serializer) {
+      // the fallback every serializer decodes in a target position
+      target = decodePathRef((json as Record<string, unknown>).v, ctx.root)
+    } else if (serializer?.claimsTarget) {
+      target = ctx.decode(json as JsonValue)
+    } else {
+      throw new CallError({
+        code: CallErrorCode.BadArgument,
+        message: "the call target must be a reference",
+        previewValue: json,
+      })
+    }
+
+    assertIsTargetInTree(target, ctx.root)
+    return target
+  }
+
+  return {
+    serializers: Object.freeze(custom),
+
+    encodeValue(root, value) {
+      assertIsTreeRoot(root)
+      return runWithNewErrorDiagnosticsContext(() =>
+        createEncodeContext(config, root).encode(value)
+      )
+    },
+
+    decodeValue(root, json) {
+      assertIsTreeRoot(root)
+      return runWithNewErrorDiagnosticsContext(() => createDecodeContext(config, root).decode(json))
+    },
+
+    encodeCall(root, call) {
+      assertIsTreeRoot(root)
+      if (!isObject(call)) {
+        throw failure("call must be an object")
+      }
+
+      return runWithNewErrorDiagnosticsContext(() => {
+        let target: unknown
+        let name: string
+        let args: readonly unknown[] | undefined
+
+        if (isActionCall(call)) {
+          if (call.serialized) {
+            throw failure("cannot encode a serialized action call; deserialize it first")
+          }
+          const { value, resolved } = resolvePathCheckingIds(
+            root,
+            call.targetPath,
+            call.targetPathIds
+          )
+          if (!resolved) {
+            throw new CallError({
+              code: CallErrorCode.NotFound,
+              message: `object at path ${JSON.stringify(call.targetPath)} with ids ${JSON.stringify(
+                call.targetPathIds
+              )} could not be resolved`,
+              path: ["target"],
+            })
+          }
+          target = value
+          name = call.actionName
+          // the target of a standalone action is its first argument, sent once as the target
+          args = getStandaloneAction(name) ? call.args.slice(1) : call.args
+        } else {
+          assertIsCallShape(call)
+          target = call.target
+          name = call.name
+          args = call.args
+        }
+
+        const ctx = createEncodeContext(config, root)
+        const encoded: EncodedCall = {
+          target: withErrorPathSegment("target", () => encodeTarget(target, ctx)),
+          name,
+        }
+        if (args !== undefined) {
+          encoded.args = withErrorPathSegment("args", () =>
+            Array.from(args, (arg, i) => ctx.encode(arg, i))
+          )
+        }
+        return encoded
+      })
+    },
+
+    decodeCall(root, json) {
+      assertIsTreeRoot(root)
+
+      return runWithNewErrorDiagnosticsContext(() => {
+        if (
+          !isPlainObject(json) ||
+          !hasOwnProp(json, "target") ||
+          typeof json.name !== "string" ||
+          (json.args !== undefined && !isArray(json.args))
+        ) {
+          throw new CallError({
+            code: CallErrorCode.BadArgument,
+            message: "invalid call: expected { target, name, args? }",
+            previewValue: json,
+          })
+        }
+
+        const name = json.name
+        const rawArgs = json.args as JsonValue[] | undefined
+        const ctx = createDecodeContext(config, root)
+
+        const target = withErrorPathSegment("target", () => decodeTarget(json.target, ctx))
+        const resolution = resolveCallNameOrThrow(target, name)
+
+        return createResolvedCall(
+          target,
+          name,
+          resolution,
+          rawArgs && {
+            rawArgs,
+            decode: () =>
+              runWithNewErrorDiagnosticsContext(() =>
+                withErrorPathSegment("args", () => rawArgs.map((arg, i) => ctx.decode(arg, i)))
+              ),
+          }
+        )
+      })
+    },
+  }
+}
+
+/**
+ * The default serializer: nodes of the tree as path references (`pathRefs()`, value-type models
+ * excepted), plus the built-ins.
+ */
+export const defaultSerializer: Serializer = createSerializer({ serializers: [pathRefs()] })

package/src/serialization/ValueSerializer.ts

@@ -0,0 +1,98 @@
+import type { PathElement } from "../parent/pathTypes"
+import type { JsonValue } from "./JsonValue"
+
+/**
+ * The key that marks a special value in the encoded JSON:
+ * `{ "$mobxKeystone": <tag>, "v": <payload> }`.
+ */
+export const serializationMarkerKey = "$mobxKeystone"
+
+/**
+ * Context passed to `ValueSerializer.is` and `ValueSerializer.encode`.
+ */
+export interface EncodeContext {
+  /**
+   * Root of the tree the value is encoded against.
+   */
+  readonly root: object
+
+  /**
+   * Encodes a nested value with the same serializer.
+   *
+   * @param value Value to encode.
+   * @param key Where the value is inside its parent, for error paths.
+   * @returns The encoded value.
+   */
+  encode(value: unknown, key?: PathElement): JsonValue
+}
+
+/**
+ * Context passed to `ValueSerializer.decode`.
+ */
+export interface DecodeContext {
+  /**
+   * Root of the tree the value is decoded against.
+   */
+  readonly root: object
+
+  /**
+   * Decodes a nested value with the same serializer.
+   *
+   * @param json Value to decode.
+   * @param key Where the value is inside its parent, for error paths.
+   * @returns The decoded value.
+   */
+  decode(json: JsonValue, key?: PathElement): unknown
+}
+
+/**
+ * Handles one kind of value: encodes it as `{ "$mobxKeystone": tag, "v": payload }` and decodes
+ * it back. `createSerializer` composes a list of them into a `Serializer`.
+ *
+ * @template T Type of the values it handles.
+ * @template J Type of the encoded payload (`undefined` to carry none).
+ */
+export interface ValueSerializer<T = any, J extends JsonValue | undefined = any> {
+  /**
+   * Unique, e.g. `"geom/Polygon"`; the `$mobxKeystone` of the encoded value.
+   */
+  readonly tag: string
+
+  /**
+   * Whether this serializer encodes `value`.
+   *
+   * @param value Value to check.
+   * @param ctx Encoding context; `ctx.root` is the tree the value is encoded against.
+   */
+  is(value: unknown, ctx: EncodeContext): value is T
+
+  /**
+   * Encodes a value `is` accepted. Use `ctx.encode(child)` for nested values.
+   *
+   * @param value Value to encode.
+   * @param ctx Encoding context.
+   * @returns The payload (`v`), or `undefined` to carry none.
+   */
+  encode(value: T, ctx: EncodeContext): J
+
+  /**
+   * Decodes a payload back into a value. Use `ctx.decode(child)` for nested values.
+   *
+   * @param json The payload (`v`).
+   * @param ctx Decoding context.
+   * @returns The decoded value.
+   */
+  decode(json: J, ctx: DecodeContext): T
+
+  /**
+   * Only for reference serializers: whether this serializer references `value`, a node of the
+   * tree, when it is a call's target. Unlike `is`, it ignores options such as `when`, since the
+   * call must run on the node itself. A call's target goes through the first serializer whose
+   * `claimsTarget` accepts it (else as a `pathRef`), and only serializers with `claimsTarget`
+   * decode it.
+   *
+   * @param value The call's target.
+   * @param ctx Encoding context.
+   */
+  claimsTarget?(value: object, ctx: EncodeContext): boolean
+}