mobx-keystone 2.3.1 → 2.4.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Change Log
 
+## 2.4.1
+
+- `Serializer.decodeCall` and `Serializer.decodeValue` take a `{ generateNewIds }` option (`DecodeOptions`) that gives new model ids to the models decoded from snapshots, nested ones included, e.g. for a server that accepts snapshots from clients, where duplicate ids would break `applyPatches` and `applySnapshot` on replicas. References are unaffected and ids are still kept by default. Value serializers see it as `DecodeContext.generateNewIds`.
+- A custom value serializer with the tag of a built-in now replaces that built-in in `createSerializer` (it used to throw because of the duplicate tag), so a built-in can be swapped without `builtins: false`.
+- A custom value serializer tagged `snapshot` now works like the built-in snapshot serializer it replaces: its encoded value is written unmarked and it decodes every `$modelType` / `$frozen` value. It used to be bypassed silently for those values unless it was a copy of the built-in. Its encoded value must be a snapshot, or encoding fails with `CannotEncode`.
+
+## 2.4.0
+
+- New serialization API for sending values and calls as JSON (see the new "Serialization" docs page):
+  - `createSerializer({ serializers, builtins })` composes `ValueSerializer`s into a `Serializer` with `encodeValue` / `decodeValue` / `encodeCall` / `decodeCall`, all taking the tree root first. The format marks special values as `{ "$mobxKeystone": tag, "v": payload }`; dates, maps, sets, non-finite numbers, bigints, `undefined`, data model instances and models outside the tree (as snapshots) are handled by built-in serializers (the `builtinSerializers` record), and anything else that isn't JSON fails instead of being dropped.
+  - `pathRefs()` and `idRefs()` reference nodes of the tree by path (checking ids) or by model type and id, with a `when` option to choose which nodes become references (value-type models go as snapshots by default). `defaultSerializer` uses `pathRefs()`. Custom reference serializers can reference call targets too through `ValueSerializer.claimsTarget`.
+  - `applyCall` / `applyCallAsync` run a decoded call (or a `Call` built in process). The call's name is resolved on its target into a `CallKind` (model action, standalone action, standard action, built-in action or view), and a `canCall` option decides what may run: by default only model actions (`allowModelActions`; `allowAnyCall` allows everything). `applyCall` is synchronous and refuses flows; `applyCallAsync` runs everything and returns a promise.
+  - Views: calls can also read getters and call methods of a model's (or data model's) own classes, running in one MobX batch, once `canCall` allows `CallKind.View`.
+  - Errors about a call are `CallError`s (a `MobxKeystoneError`) with a `code` (`CallErrorCode`), a `path` and a `toJSON()` that is safe to send back; errors thrown by the action or view itself pass through unchanged.
+  - New types: `Call`, `EncodedCall`, `ResolvedCall`, `ApplyCallOptions`, `CallErrorData`, `CallErrorJson`, `JsonValue`, `PathRefJson`, `IdRefJson`, `ReferenceNodeInfo`, `ReferenceSerializerOptions`, `EncodeContext`, `DecodeContext`, `SerializerOptions`, and the `serializationMarkerKey` constant.
+- Deprecated the action serialization API in favor of the above (`serializeActionCall`, `deserializeActionCall`, `serializeActionCallArgument`, `deserializeActionCallArgument`, `applySerializedActionAndTrackNewModelIds`, `applySerializedActionAndSyncNewModelIds`, `registerActionCallArgumentSerializer`, `ActionCallArgumentSerializer`, `cannotSerialize`, `SerializedActionCall`, `SerializedActionCallWithModelIdOverrides`, `SerializedActionCallArgument` and `ActionCall.serialized`). It keeps working unchanged until the next major version; the "Action Serialization (deprecated)" docs page lists the replacement of each and how to move over, including keeping replicas in sync by broadcasting the server's patches instead of replaying calls.
+- `applyAction` now resolves action names the same way `applyCall` does. A model prop, getter or other method that isn't an action now fails with "action '…' is not a model action" (it used to say it "could not be resolved to a function" for props and getters), and an inherited method such as `toString`, `constructor` or a lifecycle method such as `onInit` with "could not be resolved to a function" (it used to say it "is not a model action"). Both still throw the same error class.
+- Documented that `getCurrentActionContext()` inside `onPatches` / `onGlobalPatches` listeners returns the context of the action that made the change, whose `rootContext` is the top-level action (for a flow step, the flow).
+- Fixed serialized action calls resolving an object path that goes through an array's `length` (e.g. `["items", "length"]`) to a number: `deserializeActionCallArgument`, `deserializeActionCall` and the `applySerializedAction…` functions now throw a "could not be resolved" error for it, as for any path that doesn't lead to a tree node.
+- Fixed `applySet` (and so a serialized `$$applySet` action call) replacing a model's prototype when the field name is `__proto__`, or shadowing an inherited method of a model (e.g. one of its actions, or `constructor`) with an own field. It now throws for those on models; props, own fields and new fields can still be set, and plain objects keep `__proto__` as a data key, as before.
+- `resolvePath` no longer resolves inherited members: array steps must be indexes (so `length` doesn't resolve), plain object steps must be own keys (so `constructor`, `__proto__` or `toString` don't resolve), and model steps resolve the model's data, its own fields and the getters its classes define (e.g. computed trees), but not its methods. Paths reach `resolvePath` from remote updates in the Yjs and Loro bindings, among others.
+
 ## 2.3.1
 
 - Fixed dev mode (and so `ModelAutoTypeCheckingMode.DevModeOnly` type checking, `FrozenCheckMode.DevModeOnly` checks and other dev-only assertions) never turning on in browser development bundles (webpack 5, Vite, esbuild) since 2.0.0 (#593). `process.env.NODE_ENV` is now read in a form bundlers replace, while the library still loads where there is no global `process`.