@moostjs/event-wf/dist/index.d.ts

@moostjs/event-wf

import { TWorkflowSchema, TWorkflowSpy, TFlowOutput } from '@prostojs/wf';
export { StepRetriableError, TFlowOutput, TWorkflowSchema } from '@prostojs/wf';
import { WooksWf, TWooksWfOptions, WfOutletTriggerConfig, TWfRunOptions } from '@wooksjs/event-wf';
export { WfFinishedResponse, WfOutletTokenConfig, WfOutletTriggerConfig, WfOutletTriggerDeps, WfPauseRequest, createEmailOutlet, createHttpOutlet, createOutletHandler, handleWfOutletRequest, swapStrategy, useWfFinished, useWfOutlet, useWfState, useWfStrategy, wfKind } from '@wooksjs/event-wf';
import { TMoostAdapter, Moost, TMoostAdapterOptions } from 'moost';
export { EncapsulatedStateStrategy, HandleStateStrategy, WfOutlet, WfOutletRequest, WfOutletResult, WfState, WfStateStore, WfStateStoreMemory, WfStateStrategy, outlet, outletEmail, outletHttp } from '@prostojs/wf/outlets';

/**
 * Registers a method as a workflow step handler.
 *
 * @param path - Step identifier used in workflow schemas. Defaults to the method name.
 *
 * @example
 * ```ts
 * @Step('validate')
 * validateInput(@WorkflowParam('input') data: unknown) {
 *   return schema.parse(data)
 * }
 * ```
 */
declare function Step(path?: string): MethodDecorator;
/**
 * Registers a method as a workflow flow entry point.
 * Use with `@WorkflowSchema` to define the step sequence.
 *
 * @param path - Workflow identifier. Defaults to the method name.
 *
 * @example
 * ```ts
 * @Workflow('onboarding')
 * @WorkflowSchema([{ step: 'validate' }, { step: 'save' }])
 * onboarding() {}
 * ```
 */
declare function Workflow(path?: string): MethodDecorator;
/**
 * Attaches a workflow schema (step sequence) to a `@Workflow` method.
 *
 * @param schema - Array of step definitions composing the workflow.
 */
declare function WorkflowSchema<T>(schema: TWorkflowSchema<T>): MethodDecorator;
/**
 * Sets TTL (in ms) for the workflow state when this step pauses.
 * The adapter wraps the step handler to set `expires` on the outlet signal,
 * which is then passed to `strategy.persist(state, { ttl })`.
 *
 * @param ttlMs - Time-to-live in milliseconds for the paused state token.
 *
 * @example
 * ```ts
 * @Step('send-invite')
 * @StepTTL(60 * 60 * 1000) // 1 hour
 * async sendInvite(@WorkflowParam('context') ctx: any) {
 *   return outletEmail(ctx.email, 'invite')
 * }
 * ```
 */
declare function StepTTL(ttlMs: number): MethodDecorator;
/**
 * Parameter decorator that resolves a workflow context value into a step handler argument.
 *
 * @param name - The workflow value to resolve:
 *   - `'state'` — Full workflow state object
 *   - `'resume'` — Whether the workflow is being resumed
 *   - `'indexes'` — Current step indexes
 *   - `'schemaId'` — Active workflow schema identifier
 *   - `'stepId'` — Current step identifier
 *   - `'context'` — Workflow context data
 *   - `'input'` — Input passed to `start()` or `resume()`
 *
 * @example
 * ```ts
 * @Step('process')
 * handle(@WorkflowParam('input') data: string, @WorkflowParam('context') ctx: MyCtx) { }
 * ```
 */
declare const WorkflowParam: (name: "resume" | "indexes" | "schemaId" | "stepId" | "context" | "input" | "state") => ParameterDecorator & PropertyDecorator;

/** Metadata attached to a workflow handler by the adapter. */
interface TWfHandlerMeta {
    path: string;
}
/**
 * Moost adapter for workflow events. Wraps `@wooksjs/event-wf` to register
 * `@Step` and `@Workflow` handlers with full Moost DI and interceptor support.
 *
 * @template T - Workflow context type.
 * @template IR - Intermediate result type.
 *
 * @example
 * ```ts
 * const wf = new MoostWf()
 * app.adapter(wf).controllers(MyWorkflows).init()
 * const result = await wf.start('my-flow', {}, { input })
 * ```
 */
declare class MoostWf<T = any, IR = any> implements TMoostAdapter<TWfHandlerMeta> {
    protected opts?: (WooksWf<T, IR> | TWooksWfOptions) | undefined;
    private readonly debug?;
    readonly name = "workflow";
    protected wfApp: WooksWf<T, IR>;
    constructor(opts?: (WooksWf<T, IR> | TWooksWfOptions) | undefined, debug?: boolean | undefined);
    onNotFound(): Promise<unknown>;
    protected moost?: Moost;
    protected toInit: (() => void)[];
    onInit(moost: Moost): void;
    /** Returns the underlying `WooksWf` application instance. */
    getWfApp(): WooksWf<T, IR>;
    /** Attaches a spy function that observes workflow step executions. */
    attachSpy<I>(fn: TWorkflowSpy<T, I, IR>): () => void;
    /** Detaches a previously attached workflow spy. */
    detachSpy<I>(fn: TWorkflowSpy<T, I, IR>): void;
    /**
     * Handles an outlet trigger request within an HTTP handler.
     *
     * Reads `wfid` (workflow ID) and `wfs` (state token) from the HTTP request,
     * starts or resumes the workflow, and dispatches pauses to registered outlets.
     *
     * Must be called from within an HTTP event context (e.g. a `@Post` handler)
     * so that wooks HTTP composables are available.
     *
     * @param config - Outlet trigger configuration (allowed workflows, state strategy, outlets, etc.)
     * @returns The outlet result (form payload + token), finished response, or error.
     */
    handleOutlet(config: WfOutletTriggerConfig): Promise<unknown>;
    /**
     * Starts a new workflow execution.
     *
     * @param schemaId - Identifier of the registered workflow schema.
     * @param initialContext - Initial context data for the workflow.
     * @param opts - Optional run options: `input` for the first step, `eventContext`
     *   to link this run to a parent event scope (e.g. an HTTP request), and
     *   `strategy.name` to pick the initial state strategy. Passing a bare
     *   `input` value (legacy positional form) is no longer supported — wrap it
     *   in `{ input }`.
     */
    start<I>(schemaId: string, initialContext: T, opts?: TWfRunOptions<I, T, IR>): Promise<TFlowOutput<T, I, IR>>;
    /**
     * Resumes a previously paused workflow from a saved state.
     *
     * @param state - Saved workflow state containing schema, context, and step indexes.
     * @param opts - Optional run options: `input` for the resumed step, `eventContext`
     *   for parent-chain composable access, and `strategy.name` for the strategy
     *   that loaded this state. Legacy positional `input` is no longer supported.
     */
    resume<I>(state: {
        schemaId: string;
        context: T;
        indexes: number[];
    }, opts?: TWfRunOptions<I, T, IR>): Promise<TFlowOutput<T, I, IR>>;
    bindHandler<T extends object = object>(opts: TMoostAdapterOptions<TWfHandlerMeta, T>): void;
}

export { MoostWf, Step, StepTTL, Workflow, WorkflowParam, WorkflowSchema };
export type { TWfHandlerMeta };