@rytejs/core 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -1,33 +1,52 @@
 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";
@@ -41,7 +60,12 @@ type PipelineError<TConfig extends WorkflowConfig = WorkflowConfig> = {
     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>;
@@ -53,44 +77,115 @@ type DispatchResult<TConfig extends WorkflowConfig = WorkflowConfig> = {
     ok: false;
     error: PipelineError<TConfig>;
 };
-/** Thrown internally when Zod validation fails during dispatch. */
+/**
+ * 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. */
+/**
+ * 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. */
+/** 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 defineWorkflow() — holds schemas and creates workflow instances. */
+/**
+ * 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>;
@@ -101,42 +196,88 @@ interface WorkflowDefinition<TConfig extends WorkflowConfig = WorkflowConfig> {
 }
 /**
  * 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. */
+/** 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/retrieving values in context. */
+/**
+ * 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>;
@@ -157,6 +298,84 @@ type HookEvent = "dispatch:start" | "dispatch:end" | "transition" | "error" | "e
  */
 type Middleware<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TConfig> = StateNames<TConfig>, TCommand extends CommandNames<TConfig> = CommandNames<TConfig>> = (ctx: Context<TConfig, TDeps, TState, TCommand>, next: () => Promise<void>) => Promise<void>;
 
+/** A function that transforms a snapshot's data from one version to the next. */
+type MigrationFn = (snapshot: WorkflowSnapshot) => WorkflowSnapshot;
+/** A migration entry — either a bare {@link MigrationFn} or an object with a description. */
+type MigrationEntry = MigrationFn | {
+    description: string;
+    up: MigrationFn;
+};
+/** Internal normalized migration step with optional description. */
+interface NormalizedMigration {
+    fn: MigrationFn;
+    description?: string;
+}
+/** A validated migration pipeline ready to transform snapshots. */
+interface MigrationPipeline<TConfig extends WorkflowConfig = WorkflowConfig> {
+    /** The workflow definition this pipeline belongs to. */
+    readonly definition: WorkflowDefinition<TConfig>;
+    /** The target schema version to migrate snapshots to. */
+    readonly targetVersion: number;
+    /** Map of version number to normalized migration step. */
+    readonly migrations: ReadonlyMap<number, NormalizedMigration>;
+}
+/** Result of {@link migrate}. */
+type MigrateResult = {
+    ok: true;
+    snapshot: WorkflowSnapshot;
+} | {
+    ok: false;
+    error: MigrationError;
+};
+/** Options for {@link migrate}. */
+interface MigrateOptions {
+    /**
+     * Called after each successful migration step.
+     * @param fromVersion - The version before this step
+     * @param toVersion - The version after this step
+     * @param snapshot - The snapshot after this step
+     * @param description - Optional description from the migration entry
+     */
+    onStep?: (fromVersion: number, toVersion: number, snapshot: WorkflowSnapshot, description?: string) => void;
+    /**
+     * Called when a migration step fails.
+     * @param error - The {@link MigrationError} describing the failure
+     */
+    onError?: (error: MigrationError) => void;
+}
+/** Error thrown when a migration step fails. */
+declare class MigrationError extends Error {
+    readonly fromVersion: number;
+    readonly toVersion: number;
+    readonly cause: unknown;
+    /**
+     * @param fromVersion - The schema version the migration started from
+     * @param toVersion - The schema version the migration was attempting to reach
+     * @param cause - The underlying error that caused the failure
+     */
+    constructor(fromVersion: number, toVersion: number, cause: unknown);
+}
+/**
+ * Creates a validated migration pipeline from a definition and version-keyed transform functions.
+ * Each key is the target version — the function transforms from (key - 1) to key.
+ *
+ * @param definition - The workflow definition the migrations belong to
+ * @param migrationMap - A record mapping target version numbers to {@link MigrationEntry} values
+ * @returns A validated {@link MigrationPipeline} ready for use with {@link migrate}
+ * @throws If migration keys are not sequential from 2 to the definition's `modelVersion`, or if the highest key does not match `modelVersion`
+ */
+declare function defineMigrations<TConfig extends WorkflowConfig>(definition: WorkflowDefinition<TConfig>, migrationMap: Record<number, MigrationEntry>): MigrationPipeline<TConfig>;
+/**
+ * Runs the migration chain from the snapshot's modelVersion to the pipeline's targetVersion.
+ * Returns a Result. Auto-stamps modelVersion after each step.
+ *
+ * @param pipeline - The {@link MigrationPipeline} created by {@link defineMigrations}
+ * @param snapshot - The workflow snapshot to migrate
+ * @param options - Optional callbacks for step progress and error reporting
+ * @returns A {@link MigrateResult} with the migrated snapshot on success, or a {@link MigrationError} on failure
+ */
+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.
@@ -168,14 +387,16 @@ 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;
+    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.
@@ -192,14 +413,30 @@ declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
     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. */
+    /**
+     * 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. */
+    /**
+     * 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. */
+    /**
+     * 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;
@@ -208,12 +445,22 @@ declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
         type: EventNames<TConfig>;
         data: unknown;
     }, workflow: Workflow<TConfig>) => void | Promise<void>): this;
-    /** Registers a wildcard handler that matches any state. */
+    /**
+     * 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. */
+    /**
+     * 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;
@@ -221,13 +468,23 @@ declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
 }
 
 declare const PLUGIN_SYMBOL: unique symbol;
-/** A branded plugin function that can be passed to router.use(). */
+/** 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 router.use(). */
+/**
+ * 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. */
+/**
+ * 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 PipelineError, type Plugin, type ReadonlyContext, type RouterOptions, type StateData, type StateNames, ValidationError, type Workflow, type WorkflowConfig, type WorkflowDefinition, type WorkflowOf, WorkflowRouter, type WorkflowSnapshot, createKey, definePlugin, defineWorkflow, isPlugin };
+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 };