Interface HandlerArgs

packages/machina/src/types.ts:111–147

 * ```
 */
export interface HandlerArgs<TCtx, TStateNames extends string = string> {
    /** The context (Fsm) or client object (BehavioralFsm) */
    ctx: TCtx;

    /**
     * The name of the input currently being handled.
     *
     * Typed as `string` rather than the inferred input union because:
     * 1. Inside a named handler you already know the input name
     * 2. In a catch-all (*) handler it could be anything
     * 3. Narrowing to the literal per-handler would require complex
     *    mapped types for zero practical benefit
     */
    inputName: string;

    /**
     * Defer the current input for replay after a future transition.
     * Erlang's selective receive, in JS form.
     *
     * @example
     * ```ts
     * // Replay on the next transition to any state
     * defer();
     *
     * // Replay only when entering "yellow"
     * defer({ until: "yellow" });
     * ```
     */
    defer(opts?: { until: TStateNames }): void;

    /**
     * Emit a custom event through the FSM's emitter.
     * Built-in events (transitioning, transitioned, etc.) are emitted
     * automatically by the FSM engine — this is for user-defined events.
     */
    emit(eventName: string, data?: unknown): void;
}

// -----------------------------------------------------------------------------
// Handler function type