mobx-keystone 2.4.0 → 2.4.1

package/dist/types/serialization/Serializer.d.ts

@@ -28,9 +28,10 @@ export interface Serializer {
      *
      * @param root Root of the tree.
      * @param json Value to decode.
+     * @param options Options.
      * @returns The decoded value.
      */
-    decodeValue(root: object, json: JsonValue): unknown;
+    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
@@ -50,9 +51,22 @@ export interface Serializer {
      *
      * @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): ResolvedCall;
+    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`.
@@ -63,8 +77,8 @@ export interface SerializerOptions {
      */
     serializers?: readonly ValueSerializer[];
     /**
-     * Whether to append the built-in serializers (`builtinSerializers`) to the list.
-     * Defaults to `true`.
+     * 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;
 }

package/dist/types/serialization/ValueSerializer.d.ts

@@ -30,6 +30,11 @@ 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.
      *

package/dist/types/serialization/builtinSerializers.d.ts

@@ -3,14 +3,18 @@ import type { JsonValue } from "./JsonValue";
 import type { ValueSerializer } from "./ValueSerializer";
 /**
  * The built-in value serializers, appended in this order to every serializer's list (unless it is
- * created with `builtins: false`). Pick some of them to build a list by hand, e.g.
+ * 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 declare const builtinSerializers: Readonly<{
     /**
      * 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. Tree arrays and plain objects that aren't references are walked like any other.
+     * 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: ValueSerializer<object, any>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobx-keystone",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "A MobX powered state management solution based on data trees with first class support for TypeScript, snapshots, patches and much more",
   "keywords": [
     "mobx",

package/src/serialization/Serializer.ts

@@ -56,9 +56,10 @@ export interface Serializer {
    *
    * @param root Root of the tree.
    * @param json Value to decode.
+   * @param options Options.
    * @returns The decoded value.
    */
-  decodeValue(root: object, json: JsonValue): unknown
+  decodeValue(root: object, json: JsonValue, options?: DecodeOptions): unknown
 
   /**
    * Encodes a call (an `ActionCall`, e.g. from `onActionMiddleware`'s `onStart`, or a `Call`)
@@ -80,9 +81,23 @@ export interface Serializer {
    *
    * @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): ResolvedCall
+  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
 }
 
 /**
@@ -94,8 +109,8 @@ export interface SerializerOptions {
    */
   serializers?: readonly ValueSerializer[]
   /**
-   * Whether to append the built-in serializers (`builtinSerializers`) to the list.
-   * Defaults to `true`.
+   * 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
 }
@@ -137,12 +152,16 @@ 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,
-          ...Object.values<ValueSerializer>(builtinSerializers).filter((s) => !custom.includes(s)),
+          // 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>()
@@ -214,9 +233,11 @@ export function createSerializer(options: SerializerOptions = {}): Serializer {
       )
     },
 
-    decodeValue(root, json) {
+    decodeValue(root, json, options) {
       assertIsTreeRoot(root)
-      return runWithNewErrorDiagnosticsContext(() => createDecodeContext(config, root).decode(json))
+      return runWithNewErrorDiagnosticsContext(() =>
+        createDecodeContext(config, root, !!options?.generateNewIds).decode(json)
+      )
     },
 
     encodeCall(root, call) {
@@ -273,7 +294,7 @@ export function createSerializer(options: SerializerOptions = {}): Serializer {
       })
     },
 
-    decodeCall(root, json) {
+    decodeCall(root, json, options) {
       assertIsTreeRoot(root)
 
       return runWithNewErrorDiagnosticsContext(() => {
@@ -292,7 +313,7 @@ export function createSerializer(options: SerializerOptions = {}): Serializer {
 
         const name = json.name
         const rawArgs = json.args as JsonValue[] | undefined
-        const ctx = createDecodeContext(config, root)
+        const ctx = createDecodeContext(config, root, !!options?.generateNewIds)
 
         const target = withErrorPathSegment("target", () => decodeTarget(json.target, ctx))
         const resolution = resolveCallNameOrThrow(target, name)

package/src/serialization/ValueSerializer.ts

@@ -35,6 +35,12 @@ export interface DecodeContext {
    */
   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.
    *

package/src/serialization/builtinSerializers.ts

@@ -14,13 +14,13 @@ import type { ValueSerializer } from "./ValueSerializer"
 /**
  * @internal
  *
- * Marks a serializer whose encoded value is written as it is, without the marker
- * (snapshots already mark themselves).
+ * 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 unmarkedEncodingSymbol = Symbol("unmarkedEncoding")
+export const snapshotTag = "snapshot"
 
 const snapshotSerializer: ValueSerializer<object, any> = {
-  tag: "snapshot",
+  tag: snapshotTag,
 
   is(value): value is object {
     return isModel(value) || value instanceof Frozen
@@ -30,11 +30,10 @@ const snapshotSerializer: ValueSerializer<object, any> = {
     return getSnapshot(value)
   },
 
-  decode(json) {
-    return fromSnapshot(json)
+  decode(json, ctx) {
+    return fromSnapshot<object>(json, { generateNewIds: ctx.generateNewIds })
   },
 }
-;(snapshotSerializer as unknown as Record<symbol, boolean>)[unmarkedEncodingSymbol] = true
 
 const dataModelSerializer: ValueSerializer<AnyDataModel, { type: string; data: JsonValue }> = {
   tag: "dataModel",
@@ -198,14 +197,18 @@ const undefinedSerializer: ValueSerializer<undefined, undefined> = {
 
 /**
  * The built-in value serializers, appended in this order to every serializer's list (unless it is
- * created with `builtins: false`). Pick some of them to build a list by hand, e.g.
+ * 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. Tree arrays and plain objects that aren't references are walked like any other.
+   * 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,
   /**

package/src/serialization/codec.ts

@@ -3,7 +3,7 @@ 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 { builtinEncodedTypeof, snapshotTag } from "./builtinSerializers"
 import { badPayloadError, CallError, CallErrorCode } from "./CallError"
 import type { JsonValue } from "./JsonValue"
 import type { DecodeContext, EncodeContext, ValueSerializer } from "./ValueSerializer"
@@ -33,8 +33,8 @@ export interface SerializerConfig {
   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.
+   * The serializer that decodes values with `$modelType` / `$frozen` (the one tagged
+   * `snapshot`), if in the list.
    */
   readonly unmarked: ValueSerializer | undefined
 }
@@ -114,7 +114,13 @@ function withPathSegment<A, R>(key: PathElement, fn: (arg: A) => R, arg: A): R {
  * @internal
  */
 export function isUnmarkedSerializer(serializer: ValueSerializer): boolean {
-  return unmarkedEncodingSymbol in serializer
+  return serializer.tag === snapshotTag
+}
+
+function isSnapshotJson(payload: unknown): boolean {
+  return (
+    isPlainObject(payload) && (hasOwnProp(payload, modelTypeKey) || hasOwnProp(payload, frozenKey))
+  )
 }
 
 /**
@@ -180,7 +186,18 @@ export function createEncodeContext(config: SerializerConfig, root: object): Enc
     } catch (e) {
       throw wrapSerializerError(e, CallErrorCode.CannotEncode, serializer.tag, value)
     }
-    return isUnmarkedSerializer(serializer) ? payload! : markValue(serializer.tag, payload)
+    if (!isUnmarkedSerializer(serializer)) {
+      return markValue(serializer.tag, payload)
+    }
+    // written unmarked, so it must mark itself to be decoded by the same serializer
+    if (!isSnapshotJson(payload)) {
+      throw new CallError({
+        code: CallErrorCode.CannotEncode,
+        message: `the '${snapshotTag}' serializer must encode a snapshot (with $modelType or $frozen)`,
+        previewValue: value,
+      })
+    }
+    return payload!
   }
 
   const encodePlain = (value: unknown, plainKind: PlainKind): JsonValue => {
@@ -266,7 +283,11 @@ export function createEncodeContext(config: SerializerConfig, root: object): Enc
  * 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 {
+export function createDecodeContext(
+  config: SerializerConfig,
+  root: object,
+  generateNewIds: boolean
+): DecodeContext {
   const decodeWithSerializer = (serializer: ValueSerializer, json: unknown): unknown => {
     try {
       return serializer.decode(json, ctx)
@@ -330,6 +351,7 @@ export function createDecodeContext(config: SerializerConfig, root: object): Dec
 
   const ctx: DecodeContext = {
     root,
+    generateNewIds,
     decode: (json: JsonValue, key?: PathElement): unknown =>
       key === undefined ? decodeAny(json) : withPathSegment(key, decodeAny, json),
   }