mobx-keystone 2.3.1 → 2.4.0

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

@@ -0,0 +1,74 @@
+import type { AnyModel } from "../model/BaseModel";
+import type { PathElement } from "../parent/pathTypes";
+import type { ValueSerializer } from "./ValueSerializer";
+/**
+ * What a reference serializer's `when` option is told about a node.
+ */
+export interface ReferenceNodeInfo {
+    /**
+     * Whether the node is a model.
+     */
+    readonly isModel: boolean;
+    /**
+     * Whether the node is a value-type model (`Model({...}, { valueType: true })`).
+     */
+    readonly isValueType: boolean;
+}
+/**
+ * Options of the built-in reference serializers.
+ */
+export interface ReferenceSerializerOptions {
+    /**
+     * Decides, for every node the serializer could reference, whether it does. A node it declines
+     * falls through the list like any other value: a model ends up as its snapshot, a tree array
+     * or plain object is walked. The call's target ignores it: it is always a reference.
+     *
+     * Defaults to declining value-type models: `(node, { isValueType }) => !isValueType`.
+     */
+    when?(node: object, info: ReferenceNodeInfo): boolean;
+}
+/**
+ * A path reference, the payload of `{ "$mobxKeystone": "pathRef", "v": ... }`.
+ */
+export type PathRefJson = {
+    /**
+     * Path from the root to the node, through data nodes (as in patches).
+     */
+    path: PathElement[];
+    /**
+     * Id of the model reached by each step of the path (`null` for non-models).
+     * Optional when decoding: without it, ids aren't checked.
+     */
+    ids?: (string | null)[];
+};
+/**
+ * An id reference, the payload of `{ "$mobxKeystone": "idRef", "v": ... }`.
+ */
+export type IdRefJson = {
+    /**
+     * The model type (`$modelType`).
+     */
+    type: string;
+    /**
+     * The model id.
+     */
+    id: string;
+};
+/**
+ * References nodes of the tree by their path from the root, checking the ids of the models along
+ * it: `{ "$mobxKeystone": "pathRef", "v": { "path": ["cards", 2], "ids": [null, "c1"] } }`.
+ * It reaches any node, including tree arrays and plain objects.
+ *
+ * @param options Options.
+ * @returns The reference serializer.
+ */
+export declare function pathRefs(options?: ReferenceSerializerOptions): ValueSerializer<object, PathRefJson>;
+/**
+ * References models of the tree that have an id by their type and id:
+ * `{ "$mobxKeystone": "idRef", "v": { "type": "app/Card", "id": "c1" } }`. Ids are read and
+ * resolved as `getModelRefId` and `resolveId` do, and the type must match.
+ *
+ * @param options Options.
+ * @returns The reference serializer.
+ */
+export declare function idRefs(options?: ReferenceSerializerOptions): ValueSerializer<AnyModel, IdRefJson>;

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

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobx-keystone",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "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/action/CallKind.ts

@@ -0,0 +1,29 @@
+/**
+ * What a call's name resolved to on its target.
+ */
+export enum CallKind {
+  /**
+   * An action declared on a class: a model's `@modelAction` / `@modelFlow` (including
+   * `withSetter()` setters), or a data model's action.
+   */
+  ModelAction = "modelAction",
+  /**
+   * An action the app defines with `standaloneAction` / `standaloneFlow`, under a global name.
+   */
+  StandaloneAction = "standaloneAction",
+  /**
+   * A standalone action the library ships for editing any array or plain object
+   * (`arrayActions`, `objectActions`).
+   */
+  StandardAction = "standardAction",
+  /**
+   * A built-in action, as library functions record when they change a node: `$$applySnapshot`,
+   * `$$applyPatches`, `$$detach`, `$$applySet`, `$$applyDelete`, `$$applyMethodCall` (see
+   * `BuiltInAction`).
+   */
+  BuiltInAction = "builtInAction",
+  /**
+   * Not an action: a method, getter or function field of a model's or data model's own classes.
+   */
+  View = "view",
+}

package/src/action/applyAction.ts

@@ -1,20 +1,10 @@
-import { getDataModelAction } from "../dataModel/actions"
-import { detach } from "../parent/detach"
 import { resolvePathCheckingIds } from "../parent/path"
 import type { Path } from "../parent/pathTypes"
-import { applyPatches } from "../patch/applyPatches"
-import { applySnapshot } from "../snapshot/applySnapshot"
 import { getStandaloneAction } from "../standardActions/actions"
 import { assertTweakedObject } from "../tweaker/core"
 import { failure } from "../utils"
-import type { AnyFunction } from "../utils/AnyFunction"
-import { applyDelete } from "./applyDelete"
-import { applyMethodCall } from "./applyMethodCall"
-import { applySet } from "./applySet"
-import { BuiltInAction, isBuiltInAction } from "./builtInActions"
-import { isHookAction } from "./hookActions"
-import { isModelAction } from "./isModelAction"
-import { isModelFlow } from "./modelFlow"
+import { CallKind } from "./CallKind"
+import { resolveCallName } from "./resolveCallName"
 
 /**
  * An action call.
@@ -42,23 +32,20 @@ export interface ActionCall {
 
   /**
    * Marks this action call as non-serialized.
+   *
+   * @deprecated Not needed with `createSerializer`: a `Call` is never serialized, an
+   * `EncodedCall` always is.
    */
   readonly serialized?: boolean
 }
 
-const builtInActionToFunction = {
-  [BuiltInAction.ApplySnapshot]: applySnapshot,
-  [BuiltInAction.ApplyPatches]: applyPatches,
-  [BuiltInAction.Detach]: detach,
-  [BuiltInAction.ApplySet]: applySet,
-  [BuiltInAction.ApplyDelete]: applyDelete,
-  [BuiltInAction.ApplyMethodCall]: applyMethodCall,
-}
-
 /**
  * Applies (runs) an action over a target object.
  *
- * If you intend to apply serialized actions check one of the `applySerializedAction` methods instead.
+ * It runs any kind of action (built-in, standalone, model actions and flows), but not views.
+ * To apply calls that come from outside (e.g. as JSON), decode them with a serializer
+ * (`defaultSerializer.decodeCall`) and use `applyCall` / `applyCallAsync` instead, which check
+ * what may be called.
  *
  * @param subtreeRoot Subtree root target object to run the action over.
  * @param call The action, usually as coming from `onActionMiddleware`.
@@ -88,38 +75,24 @@ export function applyAction<TRet = any>(subtreeRoot: object, call: ActionCall):
   }
   assertTweakedObject(current, "resolved target", true)
 
-  if (isBuiltInAction(call.actionName)) {
-    const fnToCall = builtInActionToFunction[call.actionName] as AnyFunction | undefined
-    if (!fnToCall) {
-      throw failure(`assertion failed: unknown built-in action - ${call.actionName}`)
-    }
-
-    return fnToCall.apply(current, [current, ...call.args])
-  }
-
-  if (isHookAction(call.actionName)) {
+  const resolution = resolveCallName(current, call.actionName)
+  if (resolution === "hook") {
     throw failure(`calls to hooks (${call.actionName}) cannot be applied`)
   }
-
-  const dataModelAction = getDataModelAction(call.actionName)
-  if (dataModelAction) {
-    const instance: any = new dataModelAction.modelClass(current)
-    return instance[dataModelAction.fnName](...call.args)
+  if (resolution === "unknown") {
+    throw failure(`action '${call.actionName}' could not be resolved to a function`)
   }
 
-  const standaloneAction = getStandaloneAction(call.actionName)
-  if (standaloneAction) {
-    return standaloneAction.apply(current, call.args as any)
-  }
+  switch (resolution.kind) {
+    case CallKind.View:
+      throw failure(`action '${call.actionName}' is not a model action`)
 
-  const actionFn = (current as any)[call.actionName]
-  if (typeof actionFn !== "function") {
-    throw failure(`action '${call.actionName}' could not be resolved to a function`)
-  }
+    case CallKind.StandaloneAction:
+    case CallKind.StandardAction:
+      // the target is already the first argument
+      return getStandaloneAction(call.actionName)!.fn(...call.args)
 
-  if (!isModelAction(actionFn) && !isModelFlow(actionFn)) {
-    throw failure(`action '${call.actionName}' is not a model action`)
+    default:
+      return resolution.run(call.args) as TRet
   }
-
-  return actionFn.apply(current, call.args)
 }

package/src/action/applySet.ts

@@ -1,7 +1,7 @@
 import { isObservable } from "mobx"
 import { isModel } from "../model/utils"
 import { assertTweakedObject } from "../tweaker/core"
-import { lazy } from "../utils"
+import { failure, hasOwnProp, lazy } from "../utils"
 import { setIfDifferent } from "../utils/setIfDifferent"
 import { BuiltInAction } from "./builtInActions"
 import { ActionContextActionType } from "./context"
@@ -30,10 +30,30 @@ function internalApplySet<O extends object>(this: O, fieldName: string | number,
   if (!isModel(this) && isObservable(this)) {
     setIfDifferent(this, fieldName, value)
   } else {
+    // assigning '__proto__' would replace the prototype of the model instead of setting a field,
+    // and assigning an inherited method (e.g. an action) would shadow it on this instance
+    if (fieldName === "__proto__" || isInheritedDataProp(this, fieldName)) {
+      throw failure(`applySet cannot set '${String(fieldName)}' on a model`)
+    }
     ;(this as any)[fieldName] = value
   }
 }
 
+function isInheritedDataProp(obj: object, fieldName: string | number): boolean {
+  if (hasOwnProp(obj, fieldName)) {
+    return false
+  }
+  let proto = Object.getPrototypeOf(obj)
+  while (proto) {
+    const descriptor = Object.getOwnPropertyDescriptor(proto, fieldName)
+    if (descriptor) {
+      return !descriptor.get && !descriptor.set
+    }
+    proto = Object.getPrototypeOf(proto)
+  }
+  return false
+}
+
 const wrappedInternalApplySet = lazy(() =>
   wrapInAction({
     nameOrNameFn: BuiltInAction.ApplySet,

package/src/action/index.ts

@@ -3,6 +3,7 @@ export * from "./applyDelete"
 export * from "./applyMethodCall"
 export * from "./applySet"
 export * from "./builtInActions"
+export * from "./CallKind"
 export * from "./context"
 export * from "./hookActions"
 export * from "./isModelAction"

package/src/action/resolveCallName.ts

@@ -0,0 +1,207 @@
+import { getDataModelAction } from "../dataModel/actions"
+import { BaseDataModel } from "../dataModel/BaseDataModel"
+import { isDataModelClass } from "../dataModel/utils"
+import { BaseModel } from "../model/BaseModel"
+import { isModel } from "../model/utils"
+import type { ModelClass } from "../modelShared/BaseModelShared"
+import { getModelInfoForName } from "../modelShared/modelInfo"
+import { detach } from "../parent/detach"
+import { applyPatches } from "../patch/applyPatches"
+import { applySnapshot } from "../snapshot/applySnapshot"
+import { getStandaloneAction } from "../standardActions/actions"
+import { failure, namespace } from "../utils"
+import type { AnyFunction } from "../utils/AnyFunction"
+import { applyDelete } from "./applyDelete"
+import { applyMethodCall } from "./applyMethodCall"
+import { applySet } from "./applySet"
+import { BuiltInAction, isBuiltInAction } from "./builtInActions"
+import { CallKind } from "./CallKind"
+import { isHookAction } from "./hookActions"
+import { isModelAction } from "./isModelAction"
+import { isModelFlow } from "./modelFlow"
+
+const builtInActionToFunction = {
+  [BuiltInAction.ApplySnapshot]: applySnapshot,
+  [BuiltInAction.ApplyPatches]: applyPatches,
+  [BuiltInAction.Detach]: detach,
+  [BuiltInAction.ApplySet]: applySet,
+  [BuiltInAction.ApplyDelete]: applyDelete,
+  [BuiltInAction.ApplyMethodCall]: applyMethodCall,
+}
+
+const standardActionPrefixes = [`${namespace}/arrayActions::`, `${namespace}/objectActions::`]
+
+const dataModelMemberPrefix = "fn::"
+
+// members that are never callable, even when defined below the base classes
+const nonCallableMemberNames: ReadonlySet<string> = new Set([
+  "constructor",
+  "onInit",
+  "onLazyInit",
+  "onAttachedToRootStore",
+  "onLazyAttachedToRootStore",
+])
+
+/**
+ * @internal
+ *
+ * How a view is used: a getter is read (no `args`), a method is called (with `args`).
+ */
+export type ViewForm = "getter" | "method"
+
+/**
+ * @internal
+ *
+ * What a call's name resolved to on its target.
+ */
+export interface CallResolution {
+  readonly kind: CallKind
+  readonly isFlow: boolean
+  /**
+   * Only for views.
+   */
+  readonly viewForm: ViewForm | undefined
+  /**
+   * Runs the call on the target it was resolved for (args are ignored when reading a getter).
+   */
+  run(args: readonly unknown[]): unknown
+}
+
+/**
+ * @internal
+ *
+ * Why a name couldn't be resolved: a hook (never callable) or nothing callable by that name.
+ */
+export type CallResolutionFailure = "hook" | "unknown"
+
+type FoundMember = { readonly get: AnyFunction } | { readonly fn: AnyFunction }
+
+/**
+ * Finds a callable member without running any getter: a method, getter or function field of the
+ * object or of its prototype chain below `stopProto`.
+ */
+function findMember(obj: object, name: string, stopProto: object): FoundMember | undefined {
+  if (nonCallableMemberNames.has(name)) {
+    return undefined
+  }
+
+  // own accessors too, e.g. computeds MobX defines on the instance with legacy decorators
+  for (
+    let current: object | null = obj;
+    current && current !== stopProto;
+    current = Object.getPrototypeOf(current)
+  ) {
+    const desc = Object.getOwnPropertyDescriptor(current, name)
+    if (desc) {
+      if (desc.get) {
+        return { get: desc.get }
+      }
+      return typeof desc.value === "function" ? { fn: desc.value } : undefined
+    }
+  }
+  return undefined
+}
+
+function resolveMember(member: FoundMember, self: object): CallResolution {
+  if ("get" in member) {
+    const get = member.get
+    return {
+      kind: CallKind.View,
+      isFlow: false,
+      viewForm: "getter",
+      run: () => get.call(self),
+    }
+  }
+
+  const fn = member.fn
+  const run = (args: readonly unknown[]) => fn.apply(self, args as unknown[])
+  if (isModelAction(fn) || isModelFlow(fn)) {
+    return { kind: CallKind.ModelAction, isFlow: isModelFlow(fn), viewForm: undefined, run }
+  }
+  return { kind: CallKind.View, isFlow: false, viewForm: "method", run }
+}
+
+function getDataModelClassAndMember(
+  name: string
+): { modelClass: ModelClass<any>; memberName: string } | undefined {
+  // data model actions are registered under their name
+  const registered = getDataModelAction(name)
+  if (registered) {
+    return { modelClass: registered.modelClass, memberName: registered.fnName }
+  }
+
+  // other members are named the same way: fn::<data model name>::<member>
+  if (!name.startsWith(dataModelMemberPrefix)) {
+    return undefined
+  }
+  const separatorIndex = name.lastIndexOf("::")
+  if (separatorIndex < dataModelMemberPrefix.length) {
+    return undefined
+  }
+  const modelInfo = getModelInfoForName(name.slice(dataModelMemberPrefix.length, separatorIndex))
+  if (!modelInfo || !isDataModelClass(modelInfo.class)) {
+    return undefined
+  }
+  return { modelClass: modelInfo.class, memberName: name.slice(separatorIndex + 2) }
+}
+
+/**
+ * @internal
+ *
+ * Resolves what a call's name refers to on its target, in this order: built-in actions, hooks
+ * (refused), data model members, standalone actions, the target's own model actions and flows,
+ * and finally the target's own methods, getters and function fields (views).
+ *
+ * Getters are never run while resolving.
+ */
+export function resolveCallName(
+  target: object,
+  name: string
+): CallResolution | CallResolutionFailure {
+  if (isBuiltInAction(name)) {
+    const fn = builtInActionToFunction[name] as AnyFunction | undefined
+    if (!fn) {
+      throw failure(`assertion failed: unknown built-in action - ${name}`)
+    }
+    return {
+      kind: CallKind.BuiltInAction,
+      isFlow: false,
+      viewForm: undefined,
+      run: (args) => fn.apply(target, [target, ...args]),
+    }
+  }
+
+  if (isHookAction(name)) {
+    return "hook"
+  }
+
+  const dataModelMember = getDataModelClassAndMember(name)
+  if (dataModelMember) {
+    // the instance is created (or reused, since they are cached) first, so decorators that
+    // initialize on first use have run; it throws when the target isn't valid data for the class
+    const instance: object = new dataModelMember.modelClass(target)
+    const member = findMember(instance, dataModelMember.memberName, BaseDataModel.prototype)
+    return member ? resolveMember(member, instance) : "unknown"
+  }
+
+  const standaloneAction = getStandaloneAction(name)
+  if (standaloneAction) {
+    return {
+      kind: standardActionPrefixes.some((prefix) => name.startsWith(prefix))
+        ? CallKind.StandardAction
+        : CallKind.StandaloneAction,
+      isFlow: standaloneAction.isFlow,
+      viewForm: undefined,
+      run: (args) => standaloneAction.fn(target, ...args),
+    }
+  }
+
+  if (isModel(target)) {
+    const member = findMember(target, name, BaseModel.prototype)
+    if (member) {
+      return resolveMember(member, target)
+    }
+  }
+
+  return "unknown"
+}

package/src/actionMiddlewares/actionSerialization/actionSerialization.ts

@@ -24,6 +24,8 @@ const serializersMap = new Map<string, ActionCallArgumentSerializer<any, any>>()
  *
  * @param serializer Serializer to register.
  * @returns A disposer to unregister the serializer.
+ *
+ * @deprecated Use a `ValueSerializer` in the list passed to `createSerializer` instead.
  */
 export function registerActionCallArgumentSerializer(
   serializer: ActionCallArgumentSerializer<any, any>
@@ -54,6 +56,8 @@ export function registerActionCallArgumentSerializer(
 
 /**
  * Serialized action call argument.
+ *
+ * @deprecated Replaced by the marked value `{ "$mobxKeystone": tag, "v": payload }` of `createSerializer`.
  */
 export interface SerializedActionCallArgument {
   /**
@@ -68,6 +72,8 @@ export interface SerializedActionCallArgument {
 
 /**
  * A serialized action call.
+ *
+ * @deprecated Use `EncodedCall` instead.
  */
 export interface SerializedActionCall extends Omit<ActionCall, "serialized"> {
   /**
@@ -99,6 +105,8 @@ export interface SerializedActionCall extends Omit<ActionCall, "serialized"> {
  * @param argValue Argument value to be transformed into its serializable form.
  * @param [targetRoot] Target root node of the model where this action is being performed.
  * @returns The serializable form of the passed value.
+ *
+ * @deprecated Use `serializer.encodeValue(root, value)` instead (e.g. with `defaultSerializer`).
  */
 export function serializeActionCallArgument(
   argValue: any,
@@ -137,6 +145,8 @@ export function serializeActionCallArgument(
  * @param actionCall Action call to convert.
  * @param [targetRoot] Target root node of the model where this action is being performed.
  * @returns The serializable action call.
+ *
+ * @deprecated Use `serializer.encodeCall(root, call)` instead (e.g. with `defaultSerializer`).
  */
 export function serializeActionCall(
   actionCall: ActionCall,
@@ -165,6 +175,8 @@ export function serializeActionCall(
  * @param argValue Argument value to be transformed into its deserialized form.
  * @param [targetRoot] Target root node of the model where this action is being performed.
  * @returns The deserialized form of the passed value.
+ *
+ * @deprecated Use `serializer.decodeValue(root, json)` instead (e.g. with `defaultSerializer`).
  */
 export function deserializeActionCallArgument(
   argValue: SerializedActionCallArgument | JSONPrimitiveValue,
@@ -200,6 +212,8 @@ export function deserializeActionCallArgument(
  * @param actionCall Action call to convert.
  * @param [targetRoot] Target root node of the model where this action is being performed.
  * @returns The deserialized action call.
+ *
+ * @deprecated Use `serializer.decodeCall(root, json)` instead (e.g. with `defaultSerializer`), then `applyCall`.
  */
 export function deserializeActionCall(
   actionCall: SerializedActionCall,

package/src/actionMiddlewares/actionSerialization/applySerializedAction.ts

@@ -17,6 +17,8 @@ import { deserializeActionCall, type SerializedActionCall } from "./actionSerial
  * Serialized action call with model ID overrides.
  * Can be generated with `applySerializedActionAndTrackNewModelIds`.
  * To be applied with `applySerializedActionAndSyncNewModelIds`.
+ *
+ * @deprecated Use `EncodedCall` instead; model id overrides aren't needed when replicas apply the patches the server broadcasts.
  */
 export interface SerializedActionCallWithModelIdOverrides extends SerializedActionCall {
   /**
@@ -38,6 +40,8 @@ export interface SerializedActionCallWithModelIdOverrides extends SerializedActi
  * @param call The serialized action, usually as coming from the server/client.
  * @returns The return value of the action, if any, plus a new serialized action
  * with model overrides.
+ *
+ * @deprecated Use `applyCall` / `applyCallAsync` on the server instead, broadcasting the patches the call produces.
  */
 export function applySerializedActionAndTrackNewModelIds<TRet = any>(
   subtreeRoot: object,
@@ -156,6 +160,8 @@ function deepScanValueForModelIdChanges(
  * @param subtreeRoot Subtree root target object to run the action over.
  * @param call The serialized action, usually as coming from the server/client.
  * @returns The return value of the action, if any.
+ *
+ * @deprecated Use `applyPatches` on the patches the server broadcasts instead.
  */
 export function applySerializedActionAndSyncNewModelIds<TRet = any>(
   subtreeRoot: object,

package/src/actionMiddlewares/actionSerialization/core.ts

@@ -1,7 +1,14 @@
+/**
+ * Returned by an `ActionCallArgumentSerializer` that can't serialize a value.
+ *
+ * @deprecated Use `ValueSerializer.is` returning false instead.
+ */
 export const cannotSerialize = Symbol("cannotSerialize")
 
 /**
  * Serializer of action call arguments.
+ *
+ * @deprecated Use `ValueSerializer` instead.
  */
 export interface ActionCallArgumentSerializer<TOriginal, TSerialized> {
   /**

package/src/actionMiddlewares/actionSerialization/index.ts

@@ -1,3 +1,5 @@
+// Deprecated: replaced by `src/serialization`; kept unchanged until the next major.
+
 export * from "./actionSerialization"
 export * from "./applySerializedAction"
 export * from "./core"

package/src/actionMiddlewares/actionSerialization/objectPathSerializer.ts

@@ -1,6 +1,6 @@
 import { fastGetRootPath, resolvePathCheckingIds } from "../../parent/path"
 import type { Path } from "../../parent/pathTypes"
-import { isTweakedObject } from "../../tweaker/core"
+import { isTreeNode, isTweakedObject } from "../../tweaker/core"
 import { failure, namespace } from "../../utils"
 import { rootPathToTargetPathIds } from "../utils"
 import { type ActionCallArgumentSerializer, cannotSerialize } from "./core"
@@ -36,7 +36,8 @@ export const objectPathSerializer: ActionCallArgumentSerializer<object, ObjectPa
     // try to resolve the node back
     if (targetRoot) {
       const result = resolvePathCheckingIds(targetRoot, ref.targetPath, ref.targetPathIds)
-      if (result.resolved) {
+      // only tree nodes can be serialized as paths, so anything else is not a valid target
+      if (result.resolved && isTreeNode(result.value)) {
         return result.value
       }
     }

package/src/index.ts

@@ -13,6 +13,7 @@ export * from "./patch"
 export * from "./redux"
 export * from "./ref"
 export * from "./rootStore"
+export * from "./serialization"
 export * from "./snapshot"
 export * from "./standardActions"
 export * from "./transforms"