mobx-keystone 2.3.1 → 2.4.1

package/src/serialization/ValueSerializer.ts

@@ -0,0 +1,104 @@
+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
+
+  /**
+   * Whether models decoded from snapshots must get new model ids (the `generateNewIds` option
+   * of the decoding). A serializer that creates models honors it; references ignore it.
+   */
+  readonly generateNewIds: boolean
+
+  /**
+   * 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
+}

package/src/serialization/applyCall.ts

@@ -0,0 +1,190 @@
+import { transaction } from "mobx"
+import { CallKind } from "../action/CallKind"
+import { isTreeNode } from "../tweaker/core"
+import { failure, hasOwnProp, isObject, isPlainObject } from "../utils"
+import type { Call, ResolvedCall } from "./Call"
+import { CallError, CallErrorCode } from "./CallError"
+import {
+  assertIsCallShape,
+  assertIsTargetInTree,
+  assertIsTreeRoot,
+  getResolvedCallData,
+  toResolvedCall,
+} from "./resolvedCall"
+import { serializationMarkerKey } from "./ValueSerializer"
+
+/**
+ * Options of `applyCall` and `applyCallAsync`.
+ */
+export interface ApplyCallOptions {
+  /**
+   * Decides whether a call may run, after its target and name are resolved and before anything
+   * runs. Returning false throws a `CallError` with code `Forbidden`; an error it throws passes
+   * through as it is. Reading `call.args` decodes the arguments (once).
+   *
+   * Defaults to `allowModelActions`.
+   */
+  canCall?(call: ResolvedCall): boolean
+}
+
+/**
+ * The default `canCall`: allows model actions (`CallKind.ModelAction`) only.
+ *
+ * @param call The call.
+ * @returns Whether it is a model action.
+ */
+export function allowModelActions(call: ResolvedCall): boolean {
+  return call.kind === CallKind.ModelAction
+}
+
+/**
+ * A `canCall` that allows every call, for calls from a source that is trusted.
+ *
+ * @param _call The call.
+ * @returns `true`.
+ */
+export function allowAnyCall(_call: ResolvedCall): boolean {
+  return true
+}
+
+const kindDescriptions: Record<CallKind, string> = {
+  [CallKind.ModelAction]: "a model action",
+  [CallKind.StandaloneAction]: "a standalone action",
+  [CallKind.StandardAction]: "a standard action",
+  [CallKind.BuiltInAction]: "a built-in action",
+  [CallKind.View]: "a view",
+}
+
+function looksLikeEncodedCall(call: Call): boolean {
+  const target: unknown = call.target
+  return isPlainObject(target) && hasOwnProp(target, serializationMarkerKey) && !isTreeNode(target)
+}
+
+function wrongKind(call: Call, message: string): CallError {
+  return new CallError({
+    code: CallErrorCode.WrongKind,
+    message: `'${call.name}' ${message}`,
+    path: ["name"],
+  })
+}
+
+function isPromiseLike(value: unknown): boolean {
+  return (
+    (isObject(value) || typeof value === "function") &&
+    typeof (value as { then?: unknown }).then === "function"
+  )
+}
+
+/**
+ * Resolves and checks a call, and returns the function that runs it.
+ */
+function prepareCall(
+  root: object,
+  call: Call | ResolvedCall,
+  options: ApplyCallOptions | undefined,
+  allowFlows: boolean
+): () => unknown {
+  assertIsTreeRoot(root)
+
+  if (!isObject(call)) {
+    throw failure("call must be an object")
+  }
+
+  const isResolved = getResolvedCallData(call) !== undefined
+  if (!isResolved) {
+    if (looksLikeEncodedCall(call)) {
+      throw failure("this looks like an EncodedCall; decode it first")
+    }
+    assertIsCallShape(call)
+  }
+
+  // also checked for decoded calls, since they could be applied to another tree
+  assertIsTargetInTree(call.target, root)
+
+  const resolvedCall = isResolved ? (call as ResolvedCall) : toResolvedCall(call)
+  const { resolution, hasArgs } = getResolvedCallData(resolvedCall)!
+
+  if (!allowFlows && resolution.isFlow) {
+    throw wrongKind(resolvedCall, "is a flow; use applyCallAsync")
+  }
+
+  if (resolution.kind !== CallKind.View) {
+    if (!hasArgs) {
+      throw wrongKind(resolvedCall, "is an action; pass args")
+    }
+  } else if (resolution.viewForm === "getter") {
+    if (hasArgs) {
+      throw wrongKind(resolvedCall, "is a getter; leave args out")
+    }
+  } else if (!hasArgs) {
+    throw wrongKind(resolvedCall, "is a method; pass args")
+  }
+
+  const canCall = options?.canCall ?? allowModelActions
+  if (!canCall(resolvedCall)) {
+    const kindDescription = kindDescriptions[resolution.kind]
+    throw new CallError({
+      code: CallErrorCode.Forbidden,
+      message: options?.canCall
+        ? `'${resolvedCall.name}' (${kindDescription}) was refused by canCall`
+        : `'${resolvedCall.name}' is ${kindDescription}, which the default canCall refuses; pass canCall to allow it`,
+      path: [],
+    })
+  }
+
+  return () => {
+    const args = resolvedCall.args ?? []
+
+    if (resolution.kind !== CallKind.View) {
+      return resolution.run(args)
+    }
+
+    // one batch, so computeds read by the view stay cached while it runs
+    const result = transaction(() => resolution.run(args))
+    if (isPromiseLike(result)) {
+      throw wrongKind(resolvedCall, "returned a promise; async reads belong in a flow")
+    }
+    return result
+  }
+}
+
+/**
+ * Runs a call (as returned by `Serializer.decodeCall`, or built in process) on a tree and returns
+ * its result as is. Flows are refused (`call.isFlow`); use `applyCallAsync` for them.
+ *
+ * The call's name is resolved on its target (see `CallKind`), then `canCall` decides whether it
+ * may run (by default only model actions may). Errors about the call are `CallError`s; errors
+ * thrown by the action or view are rethrown as they are.
+ *
+ * @template TRet Return type.
+ * @param root Root of the tree.
+ * @param call The call.
+ * @param options Options.
+ * @returns The result of the call.
+ */
+export function applyCall<TRet = unknown>(
+  root: object,
+  call: Call | ResolvedCall,
+  options?: ApplyCallOptions
+): TRet {
+  return prepareCall(root, call, options, false)() as TRet
+}
+
+/**
+ * Like `applyCall`, but accepts flows too and always returns a promise, which resolves to the
+ * result once the call (or the flow) ends. Every error is a rejection.
+ *
+ * @template TRet Return type.
+ * @param root Root of the tree.
+ * @param call The call.
+ * @param options Options.
+ * @returns A promise of the result of the call.
+ */
+export async function applyCallAsync<TRet = unknown>(
+  root: object,
+  call: Call | ResolvedCall,
+  options?: ApplyCallOptions
+): Promise<TRet> {
+  const run = prepareCall(root, call, options, true)
+  return (await run()) as TRet
+}

package/src/serialization/builtinSerializers.ts

@@ -0,0 +1,264 @@
+import type { AnyDataModel } from "../dataModel/BaseDataModel"
+import { isDataModel, isDataModelClass } from "../dataModel/utils"
+import { Frozen } from "../frozen/Frozen"
+import { isModel } from "../model/utils"
+import { findModelInfoForPrototype, getModelInfoForName } from "../modelShared/modelInfo"
+import { fromSnapshot } from "../snapshot/fromSnapshot"
+import { getSnapshot } from "../snapshot/getSnapshot"
+import { hasOwnProp, isArray, isMap, isPlainObject, isSet } from "../utils"
+import { badPayloadError, CallError, CallErrorCode } from "./CallError"
+import type { TypeofResult } from "./codec"
+import type { JsonValue } from "./JsonValue"
+import type { ValueSerializer } from "./ValueSerializer"
+
+/**
+ * @internal
+ *
+ * The tag of the serializer whose encoded value is written as it is, without the marker
+ * (snapshots already mark themselves), and that decodes every value with `$modelType` / `$frozen`.
+ */
+export const snapshotTag = "snapshot"
+
+const snapshotSerializer: ValueSerializer<object, any> = {
+  tag: snapshotTag,
+
+  is(value): value is object {
+    return isModel(value) || value instanceof Frozen
+  },
+
+  encode(value) {
+    return getSnapshot(value)
+  },
+
+  decode(json, ctx) {
+    return fromSnapshot<object>(json, { generateNewIds: ctx.generateNewIds })
+  },
+}
+
+const dataModelSerializer: ValueSerializer<AnyDataModel, { type: string; data: JsonValue }> = {
+  tag: "dataModel",
+
+  is(value): value is AnyDataModel {
+    return isDataModel(value)
+  },
+
+  encode(value, ctx) {
+    // data models can only be created from registered classes
+    const modelInfo = findModelInfoForPrototype(Object.getPrototypeOf(value))!
+    return { type: modelInfo.name, data: ctx.encode(value.$) }
+  },
+
+  decode(json, ctx) {
+    if (!isPlainObject(json) || typeof json.type !== "string" || !hasOwnProp(json, "data")) {
+      throw badPayloadError("dataModel", json)
+    }
+    const modelInfo = getModelInfoForName(json.type)
+    if (!modelInfo || !isDataModelClass(modelInfo.class)) {
+      throw new CallError({
+        code: CallErrorCode.BadArgument,
+        message: `no data model is registered as '${json.type}'`,
+        previewValue: json,
+      })
+    }
+    return new modelInfo.class(ctx.decode(json.data))
+  },
+}
+
+const dateSerializer: ValueSerializer<Date, string | number | null> = {
+  tag: "date",
+
+  is(value): value is Date {
+    return value instanceof Date
+  },
+
+  encode(value) {
+    return Number.isNaN(value.getTime()) ? null : value.toISOString()
+  },
+
+  decode(json) {
+    if (json === null) {
+      return new Date(Number.NaN)
+    }
+    const date = typeof json === "number" || typeof json === "string" ? new Date(json) : undefined
+    if (!date || Number.isNaN(date.getTime())) {
+      throw badPayloadError("date", json)
+    }
+    return date
+  },
+}
+
+const mapSerializer: ValueSerializer<Map<unknown, unknown>, [JsonValue, JsonValue][]> = {
+  tag: "map",
+
+  is(value): value is Map<unknown, unknown> {
+    return isMap(value)
+  },
+
+  encode(value, ctx) {
+    return Array.from(value.entries(), ([k, v], i): [JsonValue, JsonValue] => [
+      ctx.encode(k, i),
+      ctx.encode(v, i),
+    ])
+  },
+
+  decode(json, ctx) {
+    if (!isArray(json)) {
+      throw badPayloadError("map", json)
+    }
+    const map = new Map<unknown, unknown>()
+    json.forEach((entry, i) => {
+      if (!isArray(entry) || entry.length !== 2) {
+        throw badPayloadError("map", json)
+      }
+      map.set(ctx.decode(entry[0], i), ctx.decode(entry[1], i))
+    })
+    return map
+  },
+}
+
+const setSerializer: ValueSerializer<Set<unknown>, JsonValue[]> = {
+  tag: "set",
+
+  is(value): value is Set<unknown> {
+    return isSet(value)
+  },
+
+  encode(value, ctx) {
+    return Array.from(value.values(), (v, i) => ctx.encode(v, i))
+  },
+
+  decode(json, ctx) {
+    if (!isArray(json)) {
+      throw badPayloadError("set", json)
+    }
+    return new Set(json.map((v, i) => ctx.decode(v, i)))
+  },
+}
+
+const nonFiniteNumbers: Record<string, number> = {
+  NaN: Number.NaN,
+  Infinity: Number.POSITIVE_INFINITY,
+  "-Infinity": Number.NEGATIVE_INFINITY,
+}
+
+const numberSerializer: ValueSerializer<number, string> = {
+  tag: "number",
+
+  is(value): value is number {
+    return typeof value === "number" && !Number.isFinite(value)
+  },
+
+  encode(value) {
+    return String(value)
+  },
+
+  decode(json) {
+    if (typeof json !== "string" || !hasOwnProp(nonFiniteNumbers, json)) {
+      throw badPayloadError("number", json)
+    }
+    return nonFiniteNumbers[json]
+  },
+}
+
+const bigintSerializer: ValueSerializer<bigint, string> = {
+  tag: "bigint",
+
+  is(value): value is bigint {
+    return typeof value === "bigint"
+  },
+
+  encode(value) {
+    return value.toString()
+  },
+
+  decode(json) {
+    if (typeof json !== "string" || !/^-?\d+$/.test(json)) {
+      throw badPayloadError("bigint", json)
+    }
+    return BigInt(json)
+  },
+}
+
+const undefinedSerializer: ValueSerializer<undefined, undefined> = {
+  tag: "undefined",
+
+  is(value): value is undefined {
+    return value === undefined
+  },
+
+  encode() {
+    return undefined
+  },
+
+  decode() {
+    return undefined
+  },
+}
+
+/**
+ * The built-in value serializers, appended in this order to every serializer's list (unless it is
+ * created with `builtins: false`), except those whose tag a serializer of the list takes. Pick some of them to build a list by hand, e.g.
+ * `createSerializer({ serializers: [builtinSerializers.date], builtins: false })`.
+ */
+export const builtinSerializers = Object.freeze({
+  /**
+   * Models and frozen data that aren't references, as their snapshots (unmarked, since snapshots
+   * mark themselves with `$modelType` / `$frozen`), decoded with `fromSnapshot` into new
+   * instances (with new model ids when decoded with `generateNewIds`). Tree arrays and plain
+   * objects that aren't references are walked like any other.
+   *
+   * A custom serializer tagged `snapshot` replaces it: its encoded value must be a snapshot too,
+   * and it decodes every value with `$modelType` / `$frozen`.
+   */
+  snapshot: snapshotSerializer,
+  /**
+   * Data model instances, as their registered name and their data (encoded, so data of the tree
+   * goes as a reference), decoded as a new instance over the decoded data.
+   */
+  dataModel: dataModelSerializer,
+  /**
+   * Dates, as `toISOString()` (an invalid date as `null`); decodes an ISO string, a timestamp or
+   * `null`.
+   */
+  date: dateSerializer,
+  /**
+   * Maps (plain or observable), as an array of `[key, value]` entries; decoded as plain maps.
+   */
+  map: mapSerializer,
+  /**
+   * Sets (plain or observable), as an array of their values; decoded as plain sets.
+   */
+  set: setSerializer,
+  /**
+   * The numbers JSON can't hold: `"NaN"`, `"Infinity"`, `"-Infinity"`.
+   */
+  number: numberSerializer,
+  /**
+   * Bigints, as a decimal string, with no loss of precision.
+   */
+  bigint: bigintSerializer,
+  /**
+   * `undefined` (as an array item, an argument or an object property, which keeps its key).
+   */
+  undefined: undefinedSerializer,
+})
+
+/**
+ * @internal
+ *
+ * The only `typeof` of the values each built-in encodes, so encoding can skip the built-ins that
+ * can't apply to a value.
+ */
+export const builtinEncodedTypeof: ReadonlyMap<ValueSerializer, TypeofResult> = new Map<
+  ValueSerializer,
+  TypeofResult
+>([
+  [snapshotSerializer, "object"],
+  [dataModelSerializer, "object"],
+  [dateSerializer, "object"],
+  [mapSerializer, "object"],
+  [setSerializer, "object"],
+  [numberSerializer, "number"],
+  [bigintSerializer, "bigint"],
+  [undefinedSerializer, "undefined"],
+])