@rytejs/core 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -1,293 +1,14 @@
-import { ZodType, z } from 'zod';
-
-/**
- * Shape of the configuration object passed to {@link defineWorkflow}.
- */
-interface WorkflowConfig {
-    /** Optional version number for schema migrations. Defaults to 1. */
-    modelVersion?: number;
-    /** Record of state names to Zod schemas defining their data shape. */
-    states: Record<string, ZodType>;
-    /** Record of command names to Zod schemas defining their payload shape. */
-    commands: Record<string, ZodType>;
-    /** Record of event names to Zod schemas defining their data shape. */
-    events: Record<string, ZodType>;
-    /** Record of error codes to Zod schemas defining their data shape. */
-    errors: Record<string, ZodType>;
-}
-type StateNames<T extends WorkflowConfig> = keyof T["states"] & string;
-type CommandNames<T extends WorkflowConfig> = keyof T["commands"] & string;
-type EventNames<T extends WorkflowConfig> = keyof T["events"] & string;
-type ErrorCodes<T extends WorkflowConfig> = keyof T["errors"] & string;
-/** Infers the data type for a given state. */
-type StateData<T extends WorkflowConfig, S extends StateNames<T>> = T["states"][S] extends ZodType ? z.infer<T["states"][S]> : never;
-/** Infers the payload type for a given command. */
-type CommandPayload<T extends WorkflowConfig, C extends CommandNames<T>> = T["commands"][C] extends ZodType ? z.infer<T["commands"][C]> : never;
-/** Infers the data type for a given event. */
-type EventData<T extends WorkflowConfig, E extends EventNames<T>> = T["events"][E] extends ZodType ? z.infer<T["events"][E]> : never;
-/** Infers the data type for a given error code. */
-type ErrorData<T extends WorkflowConfig, C extends ErrorCodes<T>> = T["errors"][C] extends ZodType ? z.infer<T["errors"][C]> : never;
-/** Workflow narrowed to a specific known state. */
-interface WorkflowOf<TConfig extends WorkflowConfig, S extends StateNames<TConfig>> {
-    /** Unique workflow instance identifier. */
-    readonly id: string;
-    /** Name of the workflow definition this instance belongs to. */
-    readonly definitionName: string;
-    /** Current state name. */
-    readonly state: S;
-    /** State data, typed according to the state's Zod schema. */
-    readonly data: StateData<TConfig, S>;
-    /** Timestamp of workflow creation. */
-    readonly createdAt: Date;
-    /** Timestamp of last state change. */
-    readonly updatedAt: Date;
-}
-/** Discriminated union of all possible workflow states — checking .state narrows .data. */
-type Workflow<TConfig extends WorkflowConfig = WorkflowConfig> = {
-    [S in StateNames<TConfig>]: WorkflowOf<TConfig, S>;
-}[StateNames<TConfig>];
-/** Discriminated union of all pipeline error types on `category`. */
-type PipelineError<TConfig extends WorkflowConfig = WorkflowConfig> = {
-    category: "validation";
-    source: "command" | "state" | "event" | "transition" | "restore";
-    issues: z.core.$ZodIssue[];
-    message: string;
-} | {
-    category: "domain";
-    code: ErrorCodes<TConfig>;
-    data: ErrorData<TConfig, ErrorCodes<TConfig>>;
-} | {
-    category: "router";
-    code: "NO_HANDLER" | "UNKNOWN_STATE";
-    message: string;
-} | {
-    category: "unexpected";
-    error: unknown;
-    message: string;
-};
-/** Return type of {@link WorkflowRouter.dispatch}. Discriminated union on `ok`. */
-type DispatchResult<TConfig extends WorkflowConfig = WorkflowConfig> = {
-    ok: true;
-    workflow: Workflow<TConfig>;
-    events: Array<{
-        type: EventNames<TConfig>;
-        data: unknown;
-    }>;
-} | {
-    ok: false;
-    error: PipelineError<TConfig>;
-};
-/**
- * Thrown internally when Zod validation fails during dispatch.
- * Caught by the router and returned as a validation error in {@link DispatchResult}.
- *
- * @param source - Which validation stage failed
- * @param issues - Array of Zod validation issues
- */
-declare class ValidationError extends Error {
-    readonly source: "command" | "state" | "event" | "transition" | "restore";
-    readonly issues: z.core.$ZodIssue[];
-    constructor(source: "command" | "state" | "event" | "transition" | "restore", issues: z.core.$ZodIssue[]);
-}
-/**
- * Thrown internally when a handler calls `ctx.error()`.
- * Caught by the router and returned as a domain error in {@link DispatchResult}.
- *
- * @param code - The error code string
- * @param data - The error data payload
- */
-declare class DomainErrorSignal extends Error {
-    readonly code: string;
-    readonly data: unknown;
-    constructor(code: string, data: unknown);
-}
-
-/** A plain, JSON-safe representation of a workflow's state for serialization and storage. */
-interface WorkflowSnapshot<TConfig extends WorkflowConfig = WorkflowConfig> {
-    /** Unique workflow instance identifier. */
-    readonly id: string;
-    /** Name of the workflow definition. */
-    readonly definitionName: string;
-    /** Current state name. */
-    readonly state: StateNames<TConfig>;
-    /** State data (untyped — validated on {@link WorkflowDefinition.restore}). */
-    readonly data: unknown;
-    /** ISO 8601 timestamp of workflow creation. */
-    readonly createdAt: string;
-    /** ISO 8601 timestamp of last state change. */
-    readonly updatedAt: string;
-    /** Schema version number for migration support. */
-    readonly modelVersion: number;
-}
-
-/**
- * The result of {@link defineWorkflow} — holds schemas and creates workflow instances.
- */
-interface WorkflowDefinition<TConfig extends WorkflowConfig = WorkflowConfig> {
-    /** The raw Zod schema configuration. */
-    readonly config: TConfig;
-    /** The workflow definition name. */
-    readonly name: string;
-    /**
-     * Creates a new workflow instance in a given initial state.
-     *
-     * @param id - Unique identifier for this workflow instance
-     * @param config - Object containing `initialState` and the corresponding `data`
-     * @returns A {@link WorkflowOf} narrowed to the initial state
-     */
-    createWorkflow<S extends StateNames<TConfig>>(id: string, config: {
-        initialState: S;
-        data: z.infer<TConfig["states"][S]>;
-    }): WorkflowOf<TConfig, S>;
-    /**
-     * Returns the Zod schema for a given state name.
-     *
-     * @param stateName - The state name to look up
-     * @throws If the state name is not found in the config
-     */
-    getStateSchema(stateName: string): ZodType;
-    /**
-     * Returns the Zod schema for a given command name.
-     *
-     * @param commandName - The command name to look up
-     * @throws If the command name is not found in the config
-     */
-    getCommandSchema(commandName: string): ZodType;
-    /**
-     * Returns the Zod schema for a given event name.
-     *
-     * @param eventName - The event name to look up
-     * @throws If the event name is not found in the config
-     */
-    getEventSchema(eventName: string): ZodType;
-    /**
-     * Returns the Zod schema for a given error code.
-     *
-     * @param errorCode - The error code to look up
-     * @throws If the error code is not found in the config
-     */
-    getErrorSchema(errorCode: string): ZodType;
-    /**
-     * Returns `true` if the given state name exists in the config.
-     *
-     * @param stateName - The state name to check
-     */
-    hasState(stateName: string): boolean;
-    /**
-     * Serializes a workflow instance into a plain, JSON-safe snapshot.
-     *
-     * @param workflow - The workflow instance to serialize
-     * @returns A {@link WorkflowSnapshot} representing the current state
-     */
-    snapshot(workflow: Workflow<TConfig>): WorkflowSnapshot<TConfig>;
-    /**
-     * Restores a workflow instance from a plain snapshot, validating the state data.
-     *
-     * @param snapshot - The snapshot to restore from
-     * @returns A result object: `{ ok: true, workflow }` or `{ ok: false, error }`
-     */
-    restore(snapshot: WorkflowSnapshot<TConfig>): {
-        ok: true;
-        workflow: Workflow<TConfig>;
-    } | {
-        ok: false;
-        error: ValidationError;
-    };
-}
-/**
- * Creates a workflow definition from a name and Zod schema configuration.
- *
- * @param name - Unique name for this workflow type
- * @param config - Object with `states`, `commands`, `events`, `errors` — each a record of Zod schemas
- * @returns A {@link WorkflowDefinition} with methods for creating instances and accessing schemas
- */
-declare function defineWorkflow<const TConfig extends WorkflowConfig>(name: string, config: TConfig): WorkflowDefinition<TConfig>;
-
-/** A phantom-typed key for type-safe middleware state storage via {@link Context.set} and {@link Context.get}. */
-interface ContextKey<T> {
-    /** @internal Phantom type brand — not used at runtime. */
-    readonly _phantom: T;
-    /** Internal symbol providing uniqueness. */
-    readonly id: symbol;
-}
-/**
- * Creates a unique typed key for storing and retrieving values in context.
- *
- * @param name - Debug label (uniqueness comes from an internal `Symbol`)
- * @returns A {@link ContextKey} for use with `ctx.set()`, `ctx.get()`, and `ctx.getOrNull()`
- */
-declare function createKey<T>(name: string): ContextKey<T>;
-
-/** Mutable context flowing through the middleware pipeline during dispatch. */
-interface Context<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig> = StateNames<TConfig>, TCommand extends CommandNames<TConfig> = CommandNames<TConfig>> {
-    /** The command being dispatched, with type and validated payload. */
-    readonly command: {
-        readonly type: TCommand;
-        readonly payload: CommandPayload<TConfig, TCommand>;
-    };
-    /** The original workflow before any mutations. */
-    readonly workflow: WorkflowOf<TConfig, TState>;
-    /** Dependencies injected via the router constructor. */
-    readonly deps: TDeps;
-    /** Current state data (reflects mutations from {@link update}). */
-    readonly data: StateData<TConfig, TState>;
-    /**
-     * Merges partial data into the current state. Validates against the state's Zod schema.
-     * @param data - Partial state data to merge
-     */
-    update(data: Partial<StateData<TConfig, TState>>): void;
-    /**
-     * Transitions the workflow to a new state with new data. Validates against the target state's Zod schema.
-     * @param target - Target state name
-     * @param data - Data for the target state
-     */
-    transition<Target extends StateNames<TConfig>>(target: Target, data: StateData<TConfig, Target>): void;
-    /**
-     * Emits a domain event. Validates event data against the event's Zod schema.
-     * @param event - Event with type and data
-     */
-    emit<E extends EventNames<TConfig>>(event: {
-        type: E;
-        data: EventData<TConfig, E>;
-    }): void;
-    /** Accumulated events emitted during this dispatch. */
-    readonly events: ReadonlyArray<{
-        type: EventNames<TConfig>;
-        data: unknown;
-    }>;
-    /**
-     * Signals a domain error. Validates error data and throws internally (caught by the router).
-     * @param err - Error with code and data
-     */
-    error<C extends ErrorCodes<TConfig>>(err: {
-        code: C;
-        data: ErrorData<TConfig, C>;
-    }): never;
-    /**
-     * Stores a value in context-scoped middleware state.
-     * @param key - A {@link ContextKey} created via {@link createKey}
-     * @param value - The value to store
-     */
-    set<T>(key: ContextKey<T>, value: T): void;
-    /**
-     * Retrieves a value from context-scoped middleware state. Throws if not set.
-     * @param key - A {@link ContextKey} created via {@link createKey}
-     */
-    get<T>(key: ContextKey<T>): T;
-    /**
-     * Retrieves a value from context-scoped middleware state, or `undefined` if not set.
-     * @param key - A {@link ContextKey} created via {@link createKey}
-     */
-    getOrNull<T>(key: ContextKey<T>): T | undefined;
-    /** @internal — not part of the handler API */
-    getWorkflowSnapshot(): Workflow<TConfig>;
-}
+import { C as Context, W as WorkflowDefinition } from './plugin-DHN3Pk52.js';
+export { a as ContextKey, G as GenericPlugin, P as Plugin, R as ReadonlyContext, b as RouterOptions, c as WorkflowRouter, d as createKey, e as defineGenericPlugin, f as definePlugin, g as defineWorkflow, i as isPlugin } from './plugin-DHN3Pk52.js';
+import { W as WorkflowConfig, S as StateNames, C as CommandNames, a as WorkflowSnapshot } from './snapshot-D5iZubCz.js';
+export { b as CommandPayload, c as ConfigOf, D as DispatchResult, d as DomainErrorSignal, E as ErrorCodes, e as ErrorData, f as EventData, g as EventNames, P as PipelineError, h as StateData, V as ValidationError, i as Workflow, j as WorkflowOf } from './snapshot-D5iZubCz.js';
+import 'zod';
 
 /** Terminal handler function — receives fully typed context with state and command narrowing. */
 type Handler<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig>, TCommand extends CommandNames<TConfig>> = (ctx: Context<TConfig, TDeps, TState, TCommand>) => void | Promise<void>;
 
 /** The lifecycle hook event names. */
-type HookEvent = "dispatch:start" | "dispatch:end" | "transition" | "error" | "event";
+type HookEvent = "dispatch:start" | "dispatch:end" | "pipeline:start" | "pipeline:end" | "transition" | "error" | "event";
 
 /**
  * Koa-style middleware function with full context narrowing via defaults.
@@ -376,115 +97,4 @@ declare function defineMigrations<TConfig extends WorkflowConfig>(definition: Wo
  */
 declare function migrate<TConfig extends WorkflowConfig>(pipeline: MigrationPipeline<TConfig>, snapshot: WorkflowSnapshot, options?: MigrateOptions): MigrateResult;
 
-/**
- * Read-only subset of Context for hook callbacks.
- * Includes context-key access (set/get) but excludes dispatch mutation methods.
- */
-type ReadonlyContext<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig> = StateNames<TConfig>, TCommand extends CommandNames<TConfig> = CommandNames<TConfig>> = Omit<Context<TConfig, TDeps, TState, TCommand>, "update" | "transition" | "emit" | "error" | "getWorkflowSnapshot">;
-
-type AnyMiddleware = (ctx: any, next: () => Promise<void>) => Promise<void>;
-type HandlerEntry = {
-    inlineMiddleware: AnyMiddleware[];
-    handler: AnyMiddleware;
-};
-/** Options for the {@link WorkflowRouter} constructor. */
-interface RouterOptions {
-    /** Callback invoked when a lifecycle hook throws. Defaults to `console.error`. */
-    onHookError?: (error: unknown) => void;
-}
-declare class StateBuilder<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig>> {
-    /** @internal */ readonly middleware: AnyMiddleware[];
-    /** @internal */ readonly handlers: Map<string, HandlerEntry>;
-    on: <C extends CommandNames<TConfig>>(command: C, ...fns: [...AnyMiddleware[], (ctx: Context<TConfig, TDeps, TState, C>) => void | Promise<void>]) => this;
-    use: (middleware: (ctx: Context<TConfig, TDeps, TState>, next: () => Promise<void>) => Promise<void>) => this;
-}
-/**
- * Routes commands to handlers based on workflow state.
- *
- * Supports global middleware, state-scoped middleware, inline middleware,
- * wildcard handlers, and multi-state handlers.
- */
-declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
-    private readonly definition;
-    private readonly deps;
-    private globalMiddleware;
-    private singleStateBuilders;
-    private multiStateBuilders;
-    private wildcardHandlers;
-    private hookRegistry;
-    private readonly onHookError;
-    /**
-     * @param definition - The workflow definition describing states, commands, events, and errors
-     * @param deps - Dependencies injected into every handler context
-     * @param options - Router configuration options
-     */
-    constructor(definition: WorkflowDefinition<TConfig>, deps?: TDeps, options?: RouterOptions);
-    /**
-     * Adds global middleware, merges another router, or applies a plugin.
-     * @param arg - A middleware function, another {@link WorkflowRouter} to merge, or a {@link Plugin}
-     */
-    use(arg: ((ctx: Context<TConfig, TDeps>, next: () => Promise<void>) => Promise<void>) | WorkflowRouter<TConfig, TDeps> | Plugin<TConfig, TDeps>): this;
-    private merge;
-    private mergeStateBuilders;
-    /**
-     * Registers handlers for one or more states.
-     * @param name - A state name or array of state names to register handlers for
-     * @param setup - Callback that receives a state builder to register commands and middleware
-     */
-    state<P extends StateNames<TConfig> | readonly StateNames<TConfig>[]>(name: P, setup: (state: StateBuilder<TConfig, TDeps, P extends readonly (infer S)[] ? S & StateNames<TConfig> : P & StateNames<TConfig>>) => void): this;
-    /**
-     * Registers a lifecycle hook callback.
-     * @param event - The lifecycle event name
-     * @param callback - The callback to invoke when the event fires
-     */
-    on(event: "dispatch:start", callback: (ctx: ReadonlyContext<TConfig, TDeps>) => void | Promise<void>): this;
-    on(event: "dispatch:end", callback: (ctx: ReadonlyContext<TConfig, TDeps>, result: DispatchResult<TConfig>) => void | Promise<void>): this;
-    on(event: "transition", callback: (from: StateNames<TConfig>, to: StateNames<TConfig>, workflow: Workflow<TConfig>) => void | Promise<void>): this;
-    on(event: "error", callback: (error: PipelineError<TConfig>, ctx: ReadonlyContext<TConfig, TDeps>) => void | Promise<void>): this;
-    on(event: "event", callback: (event: {
-        type: EventNames<TConfig>;
-        data: unknown;
-    }, workflow: Workflow<TConfig>) => void | Promise<void>): this;
-    /**
-     * Registers a wildcard handler that matches any state.
-     * @param state - Must be `"*"` to match all states
-     * @param command - The command name to handle
-     * @param fns - Optional inline middleware followed by the terminal handler
-     */
-    on<C extends CommandNames<TConfig>>(state: "*", command: C, ...fns: [
-        ...AnyMiddleware[],
-        (ctx: Context<TConfig, TDeps, StateNames<TConfig>, C>) => void | Promise<void>
-    ]): this;
-    /**
-     * Dispatches a command to the appropriate handler and returns the result.
-     * @param workflow - The current workflow instance to dispatch against
-     * @param command - The command with its type and payload
-     * @returns A {@link DispatchResult} indicating success or failure with the updated workflow and events
-     */
-    dispatch(workflow: Workflow<TConfig>, command: {
-        type: CommandNames<TConfig>;
-        payload: unknown;
-    }): Promise<DispatchResult<TConfig>>;
-}
-
-declare const PLUGIN_SYMBOL: unique symbol;
-/** A branded plugin function that can be passed to {@link WorkflowRouter.use}. */
-type Plugin<TConfig extends WorkflowConfig, TDeps> = ((router: WorkflowRouter<TConfig, TDeps>) => void) & {
-    readonly [PLUGIN_SYMBOL]: true;
-};
-/**
- * Brands a function as a Ryte plugin for use with {@link WorkflowRouter.use}.
- *
- * @param fn - A function that configures a router (adds handlers, middleware, hooks)
- * @returns A branded {@link Plugin} function
- */
-declare function definePlugin<TConfig extends WorkflowConfig, TDeps>(fn: (router: WorkflowRouter<TConfig, TDeps>) => void): Plugin<TConfig, TDeps>;
-/**
- * Checks whether a value is a branded Ryte plugin.
- *
- * @param value - The value to check
- * @returns `true` if the value is a {@link Plugin}
- */
-declare function isPlugin(value: unknown): value is Plugin<WorkflowConfig, unknown>;
-
-export { type CommandNames, type CommandPayload, type Context, type ContextKey, type DispatchResult, DomainErrorSignal, type ErrorCodes, type ErrorData, type EventData, type EventNames, type Handler, type HookEvent, type Middleware, type MigrateOptions, type MigrateResult, type MigrationEntry, MigrationError, type MigrationFn, type MigrationPipeline, type PipelineError, type Plugin, type ReadonlyContext, type RouterOptions, type StateData, type StateNames, ValidationError, type Workflow, type WorkflowConfig, type WorkflowDefinition, type WorkflowOf, WorkflowRouter, type WorkflowSnapshot, createKey, defineMigrations, definePlugin, defineWorkflow, isPlugin, migrate };
+export { CommandNames, Context, type Handler, type HookEvent, type Middleware, type MigrateOptions, type MigrateResult, type MigrationEntry, MigrationError, type MigrationFn, type MigrationPipeline, StateNames, WorkflowConfig, WorkflowDefinition, WorkflowSnapshot, defineMigrations, migrate };