mobx-state-tree 3.12.2 → 3.15.0

package/dist/middlewares/on-action.d.ts

@@ -1,79 +1,87 @@
-import { IDisposer, IAnyStateTreeNode } from "../internal";
-export interface ISerializedActionCall {
-    name: string;
-    path?: string;
-    args?: any[];
-}
-export interface IActionRecorder {
-    actions: ReadonlyArray<ISerializedActionCall>;
-    stop(): void;
-    replay(target: IAnyStateTreeNode): void;
-}
-/**
- * Applies an action or a series of actions in a single MobX transaction.
- * Does not return any value
- * Takes an action description as produced by the `onAction` middleware.
- *
- * @param target
- * @param actions
- */
-export declare function applyAction(target: IAnyStateTreeNode, actions: ISerializedActionCall | ISerializedActionCall[]): void;
-/**
- * Small abstraction around `onAction` and `applyAction`, attaches an action listener to a tree and records all the actions emitted.
- * Returns an recorder object with the following signature:
- *
- * Example:
- * ```ts
- * export interface IActionRecorder {
- *      // the recorded actions
- *      actions: ISerializedActionCall[]
- *      // stop recording actions
- *      stop(): any
- *      // apply all the recorded actions on the given object
- *      replay(target: IAnyStateTreeNode): any
- * }
- * ```
- *
- * @param subject
- * @returns
- */
-export declare function recordActions(subject: IAnyStateTreeNode): IActionRecorder;
-/**
- * Registers a function that will be invoked for each action that is called on the provided model instance, or to any of its children.
- * See [actions](https://github.com/mobxjs/mobx-state-tree#actions) for more details. onAction events are emitted only for the outermost called action in the stack.
- * Action can also be intercepted by middleware using addMiddleware to change the function call before it will be run.
- *
- * Not all action arguments might be serializable. For unserializable arguments, a struct like `{ $MST_UNSERIALIZABLE: true, type: "someType" }` will be generated.
- * MST Nodes are considered non-serializable as well (they could be serialized as there snapshot, but it is uncertain whether an replaying party will be able to handle such a non-instantiated snapshot).
- * Rather, when using `onAction` middleware, one should consider in passing arguments which are 1: an id, 2: a (relative) path, or 3: a snapshot. Instead of a real MST node.
- *
- * Example:
- * ```ts
- * const Todo = types.model({
- *   task: types.string
- * })
- *
- * const TodoStore = types.model({
- *   todos: types.array(Todo)
- * }).actions(self => ({
- *   add(todo) {
- *     self.todos.push(todo);
- *   }
- * }))
- *
- * const s = TodoStore.create({ todos: [] })
- *
- * let disposer = onAction(s, (call) => {
- *   console.log(call);
- * })
- *
- * s.add({ task: "Grab a coffee" })
- * // Logs: { name: "add", path: "", args: [{ task: "Grab a coffee" }] }
- * ```
- *
- * @param target
- * @param listener
- * @param attachAfter (default false) fires the listener *after* the action has executed instead of before.
- * @returns
- */
-export declare function onAction(target: IAnyStateTreeNode, listener: (call: ISerializedActionCall) => void, attachAfter?: boolean): IDisposer;
+import { IDisposer, IAnyStateTreeNode, IActionContext } from "../internal";
+export interface ISerializedActionCall {
+    name: string;
+    path?: string;
+    args?: any[];
+}
+export interface IActionRecorder {
+    actions: ReadonlyArray<ISerializedActionCall>;
+    readonly recording: boolean;
+    stop(): void;
+    resume(): void;
+    replay(target: IAnyStateTreeNode): void;
+}
+/**
+ * Applies an action or a series of actions in a single MobX transaction.
+ * Does not return any value
+ * Takes an action description as produced by the `onAction` middleware.
+ *
+ * @param target
+ * @param actions
+ */
+export declare function applyAction(target: IAnyStateTreeNode, actions: ISerializedActionCall | ISerializedActionCall[]): void;
+/**
+ * Small abstraction around `onAction` and `applyAction`, attaches an action listener to a tree and records all the actions emitted.
+ * Returns an recorder object with the following signature:
+ *
+ * Example:
+ * ```ts
+ * export interface IActionRecorder {
+ *      // the recorded actions
+ *      actions: ISerializedActionCall[]
+ *      // true if currently recording
+ *      recording: boolean
+ *      // stop recording actions
+ *      stop(): void
+ *      // resume recording actions
+ *      resume(): void
+ *      // apply all the recorded actions on the given object
+ *      replay(target: IAnyStateTreeNode): void
+ * }
+ * ```
+ *
+ * The optional filter function allows to skip recording certain actions.
+ *
+ * @param subject
+ * @returns
+ */
+export declare function recordActions(subject: IAnyStateTreeNode, filter?: (action: ISerializedActionCall, actionContext: IActionContext | undefined) => boolean): IActionRecorder;
+/**
+ * Registers a function that will be invoked for each action that is called on the provided model instance, or to any of its children.
+ * See [actions](https://github.com/mobxjs/mobx-state-tree#actions) for more details. onAction events are emitted only for the outermost called action in the stack.
+ * Action can also be intercepted by middleware using addMiddleware to change the function call before it will be run.
+ *
+ * Not all action arguments might be serializable. For unserializable arguments, a struct like `{ $MST_UNSERIALIZABLE: true, type: "someType" }` will be generated.
+ * MST Nodes are considered non-serializable as well (they could be serialized as there snapshot, but it is uncertain whether an replaying party will be able to handle such a non-instantiated snapshot).
+ * Rather, when using `onAction` middleware, one should consider in passing arguments which are 1: an id, 2: a (relative) path, or 3: a snapshot. Instead of a real MST node.
+ *
+ * Example:
+ * ```ts
+ * const Todo = types.model({
+ *   task: types.string
+ * })
+ *
+ * const TodoStore = types.model({
+ *   todos: types.array(Todo)
+ * }).actions(self => ({
+ *   add(todo) {
+ *     self.todos.push(todo);
+ *   }
+ * }))
+ *
+ * const s = TodoStore.create({ todos: [] })
+ *
+ * let disposer = onAction(s, (call) => {
+ *   console.log(call);
+ * })
+ *
+ * s.add({ task: "Grab a coffee" })
+ * // Logs: { name: "add", path: "", args: [{ task: "Grab a coffee" }] }
+ * ```
+ *
+ * @param target
+ * @param listener
+ * @param attachAfter (default false) fires the listener *after* the action has executed instead of before.
+ * @returns
+ */
+export declare function onAction(target: IAnyStateTreeNode, listener: (call: ISerializedActionCall) => void, attachAfter?: boolean): IDisposer;