mobx-keystone 0.67.4 → 0.68.1-alpha

package/src/dist/action/applyMethodCall.d.ts

@@ -0,0 +1,9 @@
+declare type AnyFunction = (...args: any[]) => any;
+/**
+ * Calls an object method wrapped in an action.
+ *
+ * @param node  Target object.
+ * @param methodName Method name.
+ */
+export declare function applyMethodCall<O extends object, K extends keyof O, FN extends O[K]>(node: O, methodName: K, ...args: FN extends AnyFunction ? Parameters<FN> : never): FN extends AnyFunction ? ReturnType<FN> : never;
+export {};

package/src/dist/action/applySet.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Sets an object field wrapped in an action.
+ *
+ * @param node  Target object.
+ * @param fieldName Field name.
+ * @param value Value to set.
+ */
+export declare function applySet<O extends object, K extends keyof O, V extends O[K]>(node: O, fieldName: K, value: V): void;

package/src/dist/action/builtInActions.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A built-in action.
+ */
+export declare enum BuiltInAction {
+    /**
+     * applyPatches
+     */
+    ApplyPatches = "$$applyPatches",
+    /**
+     * applySnapshot
+     */
+    ApplySnapshot = "$$applySnapshot",
+    /**
+     * detach
+     */
+    Detach = "$$detach",
+    /**
+     * applySet
+     */
+    ApplySet = "$$applySet",
+    /**
+     * applyDelete
+     */
+    ApplyDelete = "$$applyDelete",
+    /**
+     * applyMethodCall
+     */
+    ApplyMethodCall = "$$applyMethodCall"
+}
+/**
+ * Returns if a given action name is a built-in action, this is, one of:
+ * - applyPatches()
+ * - applySnapshot()
+ * - detach()
+ *
+ * @param actionName Action name to check.
+ * @returns true if it is a built-in action, false otherwise.
+ */
+export declare function isBuiltInAction(actionName: string): actionName is BuiltInAction;

package/src/dist/action/context.d.ts

@@ -0,0 +1,85 @@
+import type { AnyModel } from "../model/BaseModel";
+/**
+ * Low level action context.
+ */
+export interface ActionContext {
+    /**
+     * Action name
+     */
+    readonly actionName: string;
+    /**
+     * Action type, sync or async.
+     */
+    readonly type: ActionContextActionType;
+    /**
+     * Action target object.
+     */
+    readonly target: AnyModel;
+    /**
+     * Array of action arguments.
+     */
+    readonly args: ReadonlyArray<any>;
+    /**
+     * Parent action context, if any.
+     */
+    readonly parentContext?: ActionContext;
+    /**
+     * Root action context, or itself if the root.
+     */
+    readonly rootContext: ActionContext;
+    /**
+     * Previous async step context, undefined for sync actions or the first action of a flow.
+     */
+    readonly previousAsyncStepContext?: ActionContext;
+    /**
+     * Spawn async step context, undefined for sync actions.
+     */
+    readonly spawnAsyncStepContext?: ActionContext;
+    /**
+     * Async step type, or undefined for sync actions.
+     */
+    readonly asyncStepType?: ActionContextAsyncStepType;
+    /**
+     * Custom data for the action context to be set by middlewares, an object.
+     * Symbols must be used as keys to avoid name clashing between middlewares.
+     */
+    readonly data: Record<symbol, any>;
+}
+/**
+ * Action type, sync or async.
+ */
+export declare enum ActionContextActionType {
+    Sync = "sync",
+    Async = "async"
+}
+/**
+ * An async step type.
+ */
+export declare enum ActionContextAsyncStepType {
+    /**
+     * The flow is about to start.
+     */
+    Spawn = "spawn",
+    /**
+     * The flow is about to return (finish).
+     */
+    Return = "return",
+    /**
+     * The flow is about to continue.
+     */
+    Resume = "resume",
+    /**
+     * The flow yield just threw, which might be recovered (caught) or not.
+     */
+    ResumeError = "resumeError",
+    /**
+     * The flow is about to throw an error to the flow caller.
+     */
+    Throw = "throw"
+}
+/**
+ * Gets the currently running action context, or undefined if none.
+ *
+ * @returns
+ */
+export declare function getCurrentActionContext(): ActionContext | undefined;

package/src/dist/action/hookActions.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A hook action.
+ */
+export declare enum HookAction {
+    /**
+     * onInit hook
+     */
+    OnInit = "$$onInit",
+    /**
+     * onLazyInit hook
+     */
+    OnLazyInit = "$$onLazyInit",
+    /**
+     * onAttachedToRootStore hook
+     */
+    OnAttachedToRootStore = "$$onAttachedToRootStore",
+    /**
+     * disposer for onAttachedToRootStore hook
+     */
+    OnAttachedToRootStoreDisposer = "$$onAttachedToRootStoreDisposer"
+}
+/**
+ * Returns if a given action name corresponds to a hook, this is, one of:
+ * - onInit() hook
+ * - onLazyInit() hook
+ * - onAttachedToRootStore() hook
+ * - disposer returned by a onAttachedToRootStore() hook
+ *
+ * @param actionName Action name to check.
+ * @returns true if it is a hook, false otherwise.
+ */
+export declare function isHookAction(actionName: string): actionName is HookAction;

package/src/dist/action/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./applyAction";
+export * from "./applyDelete";
+export * from "./applyMethodCall";
+export * from "./applySet";
+export * from "./builtInActions";
+export * from "./context";
+export * from "./hookActions";
+export * from "./isModelAction";
+export * from "./middleware";
+export * from "./modelAction";
+export * from "./modelFlow";
+export * from "./runUnprotected";

package/src/dist/action/isModelAction.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns if the given function is a model action or not.
+ *
+ * @param fn Function to check.
+ * @returns
+ */
+export declare function isModelAction(fn: (...args: any[]) => any): boolean;

package/src/dist/action/middleware.d.ts

@@ -0,0 +1,34 @@
+import type { ActionContext } from "./context";
+/**
+ * An action middleware.
+ */
+export interface ActionMiddleware {
+    /**
+     * Subtree root object (object and child objects) this middleware will run for.
+     * This target "filter" will be run before the custom filter.
+     */
+    readonly subtreeRoot: object;
+    /**
+     * A filter function to decide if an action middleware function should be run or not.
+     */
+    filter?(ctx: ActionContext): boolean;
+    /**
+     * An action middleware function.
+     * Rember to `return next()` if you want to continue the action or throw if you want to cancel it.
+     */
+    middleware(ctx: ActionContext, next: () => any): any;
+}
+/**
+ * The disposer of an action middleware.
+ */
+export declare type ActionMiddlewareDisposer = () => void;
+/**
+ * Adds a global action middleware to be run when an action is performed.
+ * It is usually preferable to use `onActionMiddleware` instead to limit it to a given tree and only to topmost level actions
+ * or `actionTrackingMiddleware` for a simplified middleware.
+ *
+ * @param mware Action middleware to be run.
+ * @returns A disposer to cancel the middleware. Note that if you don't plan to do an early disposal of the middleware
+ * calling this function becomes optional.
+ */
+export declare function addActionMiddleware(mware: ActionMiddleware): ActionMiddlewareDisposer;

package/src/dist/action/modelAction.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Decorator that turns a function into a model action.
+ *
+ * @param target
+ * @param propertyKey
+ * @param [baseDescriptor]
+ * @returns
+ */
+export declare function modelAction(target: any, propertyKey: string, baseDescriptor?: PropertyDescriptor): void;

package/src/dist/action/modelFlow.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Returns if the given function is a model flow or not.
+ *
+ * @param fn Function to check.
+ * @returns
+ */
+export declare function isModelFlow(fn: unknown): boolean;
+/**
+ * Decorator that turns a function generator into a model flow.
+ *
+ * @param target
+ * @param propertyKey
+ * @param [baseDescriptor]
+ * @returns
+ */
+export declare function modelFlow(target: any, propertyKey: string, baseDescriptor?: PropertyDescriptor): void;
+/**
+ * Tricks the TS compiler into thinking that a model flow generator function can be awaited
+ * (is a promise).
+ *
+ * @typeparam A Function arguments.
+ * @typeparam R Return value.
+ * @param fn Flow function.
+ * @returns
+ */
+export declare function _async<A extends any[], R>(fn: (...args: A) => Generator<any, R, any>): (...args: A) => Promise<R>;
+/**
+ * Makes a promise a flow, so it can be awaited with yield*.
+ *
+ * @typeparam T Promise return type.
+ * @param promise Promise.
+ * @returns
+ */
+export declare function _await<T>(promise: Promise<T>): Generator<Promise<T>, T, unknown>;

package/src/dist/action/pendingActions.d.ts

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

package/src/dist/action/protection.d.ts

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

package/src/dist/action/runUnprotected.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Runs a block in unprocted mode, as if it were run inside a model action.
+ * Consider using a proper model action instead since these kind of actions are not recorded.
+ *
+ * @typeparam T Return type.
+ * @param name Mobx action name.
+ * @param fn Action block.
+ * @returns
+ */
+export declare function runUnprotected<T>(name: string, fn: () => T): T;
+/**
+ * Runs a block in unprocted mode, as if it were run inside a model action.
+ * Consider using a proper model action instead since these kind of actions are not recorded.
+ *
+ * @typeparam T Return type.
+ * @param fn Action block.
+ * @returns
+ */
+export declare function runUnprotected<T>(fn: () => T): T;

package/src/dist/action/wrapInAction.d.ts

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

package/src/dist/actionMiddlewares/actionSerialization/actionSerialization.d.ts

@@ -0,0 +1,84 @@
+import type { ActionCall } from "../../action/applyAction";
+import type { JSONPrimitiveValue } from "../../utils/types";
+import { ActionCallArgumentSerializer } from "./core";
+/**
+ * Registers a new action call argument serializers.
+ * Serializers are called in the inverse order they are registered, meaning the
+ * latest one registered will be called first.
+ *
+ * @param serializer Serializer to register.
+ * @returns A disposer to unregister the serializer.
+ */
+export declare function registerActionCallArgumentSerializer(serializer: ActionCallArgumentSerializer<any, any>): () => void;
+/**
+ * Serialized action call argument.
+ */
+export interface SerializedActionCallArgument {
+    /**
+     * Serializer id.
+     */
+    readonly $mobxKeystoneSerializer: string;
+    /**
+     * Serialized value.
+     */
+    readonly value: any;
+}
+/**
+ * A serialized action call.
+ */
+export interface SerializedActionCall extends Omit<ActionCall, "serialized"> {
+    /**
+     * Serialized action arguments.
+     */
+    readonly args: ReadonlyArray<SerializedActionCallArgument | JSONPrimitiveValue>;
+    /**
+     * Marks this action call as serialized.
+     */
+    serialized: true;
+}
+/**
+ * Transforms an action call argument by returning a `SerializedActionCallArgument`.
+ * The following are supported out of the box:
+ * - Primitives.
+ * - Nodes that are under the same root node as the target root (when provided) will be serialized
+ *   as a path.
+ * - Nodes that are not under the same root node as the target root will be serialized as their snapshot.
+ * - Arrays (observable or not).
+ * - Dates.
+ * - Maps (observable or not).
+ * - Sets (observable or not).
+ * - Plain objects (observable or not).
+ *
+ * If the value cannot be serialized it will throw an exception.
+ *
+ * @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.
+ */
+export declare function serializeActionCallArgument(argValue: any, targetRoot?: object): SerializedActionCallArgument | JSONPrimitiveValue;
+/**
+ * Ensures that an action call is serializable by mapping the action arguments into its
+ * serializable version by using `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.
+ */
+export declare function serializeActionCall(actionCall: ActionCall, targetRoot?: object): SerializedActionCall;
+/**
+ * Transforms an action call argument by returning its deserialized equivalent.
+ *
+ * @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.
+ */
+export declare function deserializeActionCallArgument(argValue: SerializedActionCallArgument | JSONPrimitiveValue, targetRoot?: object): any;
+/**
+ * Ensures that an action call is deserialized by mapping the action arguments into its
+ * deserialized version by using `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.
+ */
+export declare function deserializeActionCall(actionCall: SerializedActionCall, targetRoot?: object): ActionCall;

package/src/dist/actionMiddlewares/actionSerialization/applySerializedAction.d.ts

@@ -0,0 +1,45 @@
+import type { Patch } from "../../patch/Patch";
+import { SerializedActionCall } from "./actionSerialization";
+/**
+ * Serialized action call with model ID overrides.
+ * Can be generated with `applySerializedActionAndTrackNewModelIds`.
+ * To be applied with `applySerializedActionAndSyncNewModelIds`.
+ */
+export interface SerializedActionCallWithModelIdOverrides extends SerializedActionCall {
+    /**
+     * Model Id overrides to be applied at the end of applying the action.
+     */
+    readonly modelIdOverrides: ReadonlyArray<Patch>;
+}
+/**
+ * Applies (runs) a serialized action over a target object.
+ * In this mode newly generated / modified model IDs will be tracked
+ * so they can be later synchronized when applying it on another machine
+ * via `applySerializedActionAndSyncNewModelIds`.
+ * This means this method is usually used on the server side.
+ *
+ * If you intend to apply non-serialized actions check `applyAction` instead.
+ *
+ * @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, plus a new serialized action
+ * with model overrides.
+ */
+export declare function applySerializedActionAndTrackNewModelIds<TRet = any>(subtreeRoot: object, call: SerializedActionCall): {
+    returnValue: TRet;
+    serializedActionCall: SerializedActionCallWithModelIdOverrides;
+};
+/**
+ * Applies (runs) a serialized action over a target object.
+ * In this mode newly generated / modified model IDs previously tracked
+ * by `applySerializedActionAndTrackNewModelIds` will be synchronized after
+ * the action is applied.
+ * This means this method is usually used on the client side.
+ *
+ * If you intend to apply non-serialized actions check `applyAction` instead.
+ *
+ * @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.
+ */
+export declare function applySerializedActionAndSyncNewModelIds<TRet = any>(subtreeRoot: object, call: SerializedActionCallWithModelIdOverrides): TRet;

package/src/dist/actionMiddlewares/actionSerialization/arraySerializer.d.ts

@@ -0,0 +1,3 @@
+import type { IObservableArray } from "mobx";
+import { ActionCallArgumentSerializer } from "./core";
+export declare const arraySerializer: ActionCallArgumentSerializer<any[] | IObservableArray<any>, any[]>;

package/src/dist/actionMiddlewares/actionSerialization/core.d.ts

@@ -0,0 +1,28 @@
+export declare const cannotSerialize: unique symbol;
+/**
+ * Serializer of action call arguments.
+ */
+export interface ActionCallArgumentSerializer<TOriginal, TSerialized> {
+    /**
+     * Serializer ID, must be unique.
+     */
+    id: string;
+    /**
+     * Serializes an action call argument, returning `cannotSerialize` if not possible.
+     *
+     * @param value Value to serialize.
+     * @param targetRoot Target root, if provided.
+     * @param serializeChild Serialize a child.
+     * @returns
+     */
+    serialize(value: unknown, serializeChild: (v: unknown) => unknown, targetRoot: object | undefined): TSerialized | typeof cannotSerialize;
+    /**
+     * Deserializes an action call argument.
+     *
+     * @param value Value to deserialize.
+     * @param targetRoot Target root, if provided.
+     * @param deserializeChild Deserialize a child.
+     * @returns
+     */
+    deserialize(value: TSerialized, deserializeChild: (v: unknown) => unknown, targetRoot: object | undefined): TOriginal;
+}

package/src/dist/actionMiddlewares/actionSerialization/dateSerializer.d.ts

@@ -0,0 +1,2 @@
+import { ActionCallArgumentSerializer } from "./core";
+export declare const dateSerializer: ActionCallArgumentSerializer<Date, number>;

package/src/dist/actionMiddlewares/actionSerialization/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./actionSerialization";
+export * from "./applySerializedAction";
+export * from "./core";

package/src/dist/actionMiddlewares/actionSerialization/mapSerializer.d.ts

@@ -0,0 +1,6 @@
+import { ObservableMap } from "mobx";
+import { ActionCallArgumentSerializer } from "./core";
+export declare const mapSerializer: ActionCallArgumentSerializer<Map<any, any> | ObservableMap<any, any>, [
+    any,
+    any
+][]>;

package/src/dist/actionMiddlewares/actionSerialization/objectPathSerializer.d.ts

@@ -0,0 +1,8 @@
+import { Path } from "../../parent/pathTypes";
+import { ActionCallArgumentSerializer } from "./core";
+interface ObjectPath {
+    targetPath: Path;
+    targetPathIds: (string | null)[];
+}
+export declare const objectPathSerializer: ActionCallArgumentSerializer<object, ObjectPath>;
+export {};

package/src/dist/actionMiddlewares/actionSerialization/objectSnapshotSerializer.d.ts

@@ -0,0 +1,2 @@
+import { ActionCallArgumentSerializer } from "./core";
+export declare const objectSnapshotSerializer: ActionCallArgumentSerializer<object, object>;

package/src/dist/actionMiddlewares/actionSerialization/plainObjectSerializer.d.ts

@@ -0,0 +1,2 @@
+import { ActionCallArgumentSerializer } from "./core";
+export declare const plainObjectSerializer: ActionCallArgumentSerializer<object, object>;

package/src/dist/actionMiddlewares/actionSerialization/primitiveSerializer.d.ts

@@ -0,0 +1,2 @@
+import { ActionCallArgumentSerializer } from "./core";
+export declare const primitiveSerializer: ActionCallArgumentSerializer<number | bigint | undefined, string>;

package/src/dist/actionMiddlewares/actionSerialization/setSerializer.d.ts

@@ -0,0 +1,3 @@
+import type { ObservableSet } from "mobx";
+import { ActionCallArgumentSerializer } from "./core";
+export declare const setSerializer: ActionCallArgumentSerializer<Set<any> | ObservableSet<any>, any[]>;

package/src/dist/actionMiddlewares/actionTrackingMiddleware.d.ts

@@ -0,0 +1,122 @@
+import { ActionContext, ActionContextActionType } from "../action/context";
+import { ActionMiddlewareDisposer } from "../action/middleware";
+import type { AnyModel } from "../model/BaseModel";
+/**
+ * Simplified version of action context.
+ */
+export interface SimpleActionContext {
+    /**
+     * Action name
+     */
+    readonly actionName: string;
+    /**
+     * Action type, sync or async.
+     */
+    readonly type: ActionContextActionType;
+    /**
+     * Action target model instance.
+     */
+    readonly target: AnyModel;
+    /**
+     * Array of action arguments.
+     */
+    readonly args: ReadonlyArray<any>;
+    /**
+     * Parent action context, if any.
+     */
+    readonly parentContext?: SimpleActionContext;
+    /**
+     * Root action context, or itself if the root.
+     */
+    readonly rootContext: SimpleActionContext;
+    /**
+     * Custom data for the action context to be set by middlewares, an object.
+     * Symbols must be used as keys to avoid name clashing between middlewares.
+     */
+    readonly data: Record<symbol, any>;
+}
+/**
+ * Action tracking middleware finish result.
+ */
+export declare enum ActionTrackingResult {
+    /**
+     * The action returned normally (without throwing).
+     */
+    Return = "return",
+    /**
+     * The action threw an error.
+     */
+    Throw = "throw"
+}
+/**
+ * Action tracking middleware hooks.
+ */
+export interface ActionTrackingMiddleware {
+    /**
+     * Filter function called whenever each action starts, and only then.
+     *
+     * If the action is accepted then `onStart`, `onResume`, `onSuspend` and `onFinish`
+     * for that particular action will be called.
+     *
+     * All actions are accepted by default if no filter function is present.
+     *
+     * @param ctx Simplified action context.
+     * @returns true to accept the action, false to skip it.
+     */
+    filter?(ctx: SimpleActionContext): boolean;
+    /**
+     * Called when an action just started.
+     *
+     * @param ctx Simplified action context.
+     * @returns Can optionally return a result that will cancel the original action and finish it
+     * with the returned value / error to be thrown. In either case case resume / suspend / finish will
+     * still be called normally.
+     */
+    onStart?(ctx: SimpleActionContext): void | ActionTrackingReturn;
+    /**
+     * Called when an action just resumed a synchronous piece of code execution.
+     * Gets called once for sync actions and multiple times for flows.
+     *
+     * @param ctx Simplified action context.
+     */
+    onResume?(ctx: SimpleActionContext): void;
+    /**
+     * Called when an action just finished a synchronous pice of code execution.
+     * Note that this doesn't necessarily mean the action is finished.
+     * Gets called once for sync actions and multiple times for flows.
+     *
+     * @param ctx Simplified action context.
+     */
+    onSuspend?(ctx: SimpleActionContext): void;
+    /**
+     * Called when an action just finished, either by returning normally or by throwing an error.
+     *
+     * @param ctx Simplified action context.
+     * @param ret Action return result.
+     * @returns Can optionally return a new result that will override the original one.
+     */
+    onFinish?(ctx: SimpleActionContext, ret: ActionTrackingReturn): void | ActionTrackingReturn;
+}
+/**
+ * Return result of an action.
+ */
+export interface ActionTrackingReturn {
+    result: ActionTrackingResult;
+    value: any;
+}
+/**
+ * Creates an action tracking middleware, which is a simplified version
+ * of the standard action middleware.
+ *
+ * @param subtreeRoot Subtree root target object.
+ * @param hooks Middleware hooks.
+ * @returns The middleware disposer.
+ */
+export declare function actionTrackingMiddleware(subtreeRoot: object, hooks: ActionTrackingMiddleware): ActionMiddlewareDisposer;
+/**
+ * Simplifies an action context by converting an async call hierarchy into a simpler one.
+ *
+ * @param ctx Action context to convert.
+ * @returns Simplified action context.
+ */
+export declare function simplifyActionContext(ctx: ActionContext): SimpleActionContext;

package/src/dist/actionMiddlewares/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./actionSerialization";
+export * from "./actionTrackingMiddleware";
+export * from "./onActionMiddleware";
+export * from "./readonlyMiddleware";
+export * from "./transactionMiddleware";
+export * from "./undoMiddleware";