mobx-keystone/dist/types/actionMiddlewares/actionTrackingMiddleware.d.ts

A MobX powered state management solution based on data trees with first class support for TypeScript, snapshots, patches and much more

import { ActionContext, ActionContextActionType } from '../action/context';
import { ActionMiddlewareDisposer } from '../action/middleware';
import { 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;