mobx-keystone 2.3.1 → 2.4.1

package/src/parent/path.ts

@@ -256,19 +256,20 @@ export function resolvePath<T = any>(
 
     const p = path[i]
 
-    // check just to avoid mobx warnings about trying to access out of bounds index
-    if (isArray(current) && +p >= current.length) {
-      return unresolved
-    }
-
-    if (isModel(current)) {
+    if (isArray(current)) {
+      if (!isArrayIndexOf(current, p)) {
+        return unresolved
+      }
+    } else if (isModel(current)) {
       const dataNode = modelToDataNode(current)
-      if (p in dataNode) {
+      if (hasOwnProp(dataNode, p)) {
         current = dataNode
+      } else if (!hasOwnProp(current, p) && !isInheritedGetter(current, p)) {
+        // the model's own fields and getters (e.g. computed trees) resolve,
+        // but not its methods or anything inherited from Object.prototype
+        return unresolved
       }
-    }
-
-    if (!(p in current)) {
+    } else if (!hasOwnProp(current, p)) {
       return unresolved
     }
 
@@ -278,6 +279,39 @@ export function resolvePath<T = any>(
   return { resolved: true, value: current }
 }
 
+/**
+ * @internal
+ *
+ * Whether a value can be a path element (a property name or an array index).
+ */
+export function isPathElement(value: unknown): value is PathElement {
+  return typeof value === "string" || typeof value === "number"
+}
+
+/**
+ * Whether a path element is an index of the array, so non-index props such as 'length' never
+ * resolve. It also avoids mobx warnings about trying to access out of bounds indexes.
+ */
+function isArrayIndexOf(array: readonly unknown[], p: PathElement): boolean {
+  const index = +p
+  return Number.isInteger(index) && index >= 0 && index < array.length && p in array
+}
+
+/**
+ * Whether a getter is defined for a prop by the prototype chain of an object, below `Object.prototype`.
+ */
+function isInheritedGetter(obj: object, p: PathElement): boolean {
+  let proto = Object.getPrototypeOf(obj)
+  while (proto && proto !== Object.prototype) {
+    const descriptor = Object.getOwnPropertyDescriptor(proto, p)
+    if (descriptor) {
+      return descriptor.get !== undefined
+    }
+    proto = Object.getPrototypeOf(proto)
+  }
+  return false
+}
+
 /**
  * @internal
  */
@@ -321,9 +355,8 @@ export function resolvePathCheckingIds<T = any>(
 
     const p = path[i]
 
-    // check just to avoid mobx warnings about trying to access out of bounds index
     if (isArray(current)) {
-      if (+p >= current.length || !(p in current)) {
+      if (!isArrayIndexOf(current, p)) {
         return { resolved: false }
       }
     } else if (!hasOwnProp(current, p)) {

package/src/patch/emitPatch.ts

@@ -148,6 +148,9 @@ export function hasPatchListenersFor(target: object): boolean {
 /**
  * Adds a listener that will be called every time a patch is generated for the tree of the given target object.
  *
+ * The listener runs inside the action that made the change, so `getCurrentActionContext()` returns
+ * that action's context: its `rootContext` is the top-level action (for a flow step, the flow).
+ *
  * @param subtreeRoot Subtree root object of the patch listener.
  * @param listener The listener function that will be called everytime a patch is generated for the object or its children.
  * @returns A disposer to stop listening to patches.
@@ -190,6 +193,9 @@ export function internalOnPatches(
  * Adds a listener that will be called every time a patch is generated anywhere.
  * Usually prefer using `onPatches`.
  *
+ * The listener runs inside the action that made the change, so `getCurrentActionContext()` returns
+ * that action's context: its `rootContext` is the top-level action (for a flow step, the flow).
+ *
  * @param listener The listener function that will be called everytime a patch is generated anywhere.
  * @returns A disposer to stop listening to patches.
  */

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,342 @@
+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.
+   * @param options Options.
+   * @returns The decoded value.
+   */
+  decodeValue(root: object, json: JsonValue, options?: DecodeOptions): 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.
+   * @param options Options, applied when the arguments are decoded.
+   * @returns The resolved call, to pass to `applyCall` or `applyCallAsync`.
+   */
+  decodeCall(root: object, json: EncodedCall | JsonValue, options?: DecodeOptions): ResolvedCall
+}
+
+/**
+ * Options of `Serializer.decodeValue` and `Serializer.decodeCall`.
+ */
+export interface DecodeOptions {
+  /**
+   * Pass `true` to give new model ids to the models decoded from snapshots (nested ones
+   * included), as `fromSnapshot(snapshot, { generateNewIds: true })` does, e.g. on a server that
+   * accepts snapshots from clients. References still resolve to the nodes they point to.
+   * Defaults to `false` (the ids in the snapshots are kept).
+   */
+  generateNewIds?: boolean
+}
+
+/**
+ * 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, except those
+   * whose tag a serializer in `serializers` takes, which it replaces. 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 customTags = new Set(custom.map((s) => s.tag))
+  const serializers: readonly ValueSerializer[] =
+    options.builtins === false
+      ? custom
+      : [
+          ...custom,
+          // a custom serializer replaces the built-in with its tag
+          ...Object.values<ValueSerializer>(builtinSerializers).filter(
+            (s) => !customTags.has(s.tag)
+          ),
+        ]
+
+  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, options) {
+      assertIsTreeRoot(root)
+      return runWithNewErrorDiagnosticsContext(() =>
+        createDecodeContext(config, root, !!options?.generateNewIds).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, options) {
+      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, !!options?.generateNewIds)
+
+        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()] })