@rytejs/core 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { ZodType, z } from 'zod';
 
 interface WorkflowConfig {
+    modelVersion?: number;
     states: Record<string, ZodType>;
     commands: Record<string, ZodType>;
     events: Record<string, ZodType>;
@@ -29,7 +30,7 @@ type Workflow<TConfig extends WorkflowConfig = WorkflowConfig> = {
 }[StateNames<TConfig>];
 type PipelineError<TConfig extends WorkflowConfig = WorkflowConfig> = {
     category: "validation";
-    source: "command" | "state" | "event" | "transition";
+    source: "command" | "state" | "event" | "transition" | "restore";
     issues: z.core.$ZodIssue[];
     message: string;
 } | {
@@ -54,9 +55,9 @@ type DispatchResult<TConfig extends WorkflowConfig = WorkflowConfig> = {
 };
 /** Thrown internally when Zod validation fails during dispatch. */
 declare class ValidationError extends Error {
-    readonly source: "command" | "state" | "event" | "transition";
+    readonly source: "command" | "state" | "event" | "transition" | "restore";
     readonly issues: z.core.$ZodIssue[];
-    constructor(source: "command" | "state" | "event" | "transition", 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. */
 declare class DomainErrorSignal extends Error {
@@ -65,6 +66,17 @@ declare class DomainErrorSignal extends Error {
     constructor(code: string, data: unknown);
 }
 
+/** A plain, JSON-safe representation of a workflow's state. */
+interface WorkflowSnapshot<TConfig extends WorkflowConfig = WorkflowConfig> {
+    readonly id: string;
+    readonly definitionName: string;
+    readonly state: StateNames<TConfig>;
+    readonly data: unknown;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly modelVersion: number;
+}
+
 /** The result of defineWorkflow() — holds schemas and creates workflow instances. */
 interface WorkflowDefinition<TConfig extends WorkflowConfig = WorkflowConfig> {
     readonly config: TConfig;
@@ -78,6 +90,14 @@ interface WorkflowDefinition<TConfig extends WorkflowConfig = WorkflowConfig> {
     getEventSchema(eventName: string): ZodType;
     getErrorSchema(errorCode: string): ZodType;
     hasState(stateName: string): boolean;
+    snapshot(workflow: Workflow<TConfig>): WorkflowSnapshot<TConfig>;
+    restore(snapshot: WorkflowSnapshot<TConfig>): {
+        ok: true;
+        workflow: Workflow<TConfig>;
+    } | {
+        ok: false;
+        error: ValidationError;
+    };
 }
 /**
  * Creates a workflow definition from a name and Zod schema configuration.
@@ -125,6 +145,9 @@ interface Context<TConfig extends WorkflowConfig, TDeps, TState extends StateNam
 /** 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";
+
 /**
  * Koa-style middleware function with full context narrowing via defaults.
  *
@@ -134,11 +157,59 @@ type Handler<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TC
  */
 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 validated migration pipeline ready to transform snapshots. */
+interface MigrationPipeline<TConfig extends WorkflowConfig = WorkflowConfig> {
+    readonly definition: WorkflowDefinition<TConfig>;
+    readonly targetVersion: number;
+    readonly migrations: ReadonlyMap<number, MigrationFn>;
+}
+/** Result of migrate(). */
+type MigrateResult = {
+    ok: true;
+    snapshot: WorkflowSnapshot;
+} | {
+    ok: false;
+    error: MigrationError;
+};
+/** Options for migrate(). */
+interface MigrateOptions {
+    onStep?: (fromVersion: number, toVersion: number, snapshot: WorkflowSnapshot) => void;
+    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;
+    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.
+ */
+declare function defineMigrations<TConfig extends WorkflowConfig>(definition: WorkflowDefinition<TConfig>, migrationMap: Record<number, MigrationFn>): 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.
+ */
+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;
 };
+interface RouterOptions {
+    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>;
@@ -158,15 +229,26 @@ declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
     private singleStateBuilders;
     private multiStateBuilders;
     private wildcardHandlers;
-    constructor(definition: WorkflowDefinition<TConfig>, deps?: TDeps);
-    /** Adds global middleware or merges another router's handlers. */
-    use(middlewareOrRouter: ((ctx: Context<TConfig, TDeps>, next: () => Promise<void>) => Promise<void>) | WorkflowRouter<TConfig, TDeps>): this;
+    private hookRegistry;
+    private readonly onHookError;
+    constructor(definition: WorkflowDefinition<TConfig>, deps?: TDeps, options?: RouterOptions);
+    /** Adds global middleware, merges another router, or applies a 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. */
     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. */
+    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. */
-    on<C extends CommandNames<TConfig>>(_state: "*", command: C, ...fns: [
+    on<C extends CommandNames<TConfig>>(state: "*", command: C, ...fns: [
         ...AnyMiddleware[],
         (ctx: Context<TConfig, TDeps, StateNames<TConfig>, C>) => void | Promise<void>
     ]): this;
@@ -177,4 +259,14 @@ declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
     }): Promise<DispatchResult<TConfig>>;
 }
 
-export { type CommandNames, type CommandPayload, type Context, type ContextKey, type DispatchResult, DomainErrorSignal, type ErrorCodes, type ErrorData, type EventData, type EventNames, type Handler, type Middleware, type PipelineError, type StateData, type StateNames, ValidationError, type Workflow, type WorkflowConfig, type WorkflowDefinition, type WorkflowOf, WorkflowRouter, createKey, defineWorkflow };
+declare const PLUGIN_SYMBOL: unique symbol;
+/** A branded plugin function that can be passed to router.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(). */
+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. */
+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, 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 };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { ZodType, z } from 'zod';
 
 interface WorkflowConfig {
+    modelVersion?: number;
     states: Record<string, ZodType>;
     commands: Record<string, ZodType>;
     events: Record<string, ZodType>;
@@ -29,7 +30,7 @@ type Workflow<TConfig extends WorkflowConfig = WorkflowConfig> = {
 }[StateNames<TConfig>];
 type PipelineError<TConfig extends WorkflowConfig = WorkflowConfig> = {
     category: "validation";
-    source: "command" | "state" | "event" | "transition";
+    source: "command" | "state" | "event" | "transition" | "restore";
     issues: z.core.$ZodIssue[];
     message: string;
 } | {
@@ -54,9 +55,9 @@ type DispatchResult<TConfig extends WorkflowConfig = WorkflowConfig> = {
 };
 /** Thrown internally when Zod validation fails during dispatch. */
 declare class ValidationError extends Error {
-    readonly source: "command" | "state" | "event" | "transition";
+    readonly source: "command" | "state" | "event" | "transition" | "restore";
     readonly issues: z.core.$ZodIssue[];
-    constructor(source: "command" | "state" | "event" | "transition", 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. */
 declare class DomainErrorSignal extends Error {
@@ -65,6 +66,17 @@ declare class DomainErrorSignal extends Error {
     constructor(code: string, data: unknown);
 }
 
+/** A plain, JSON-safe representation of a workflow's state. */
+interface WorkflowSnapshot<TConfig extends WorkflowConfig = WorkflowConfig> {
+    readonly id: string;
+    readonly definitionName: string;
+    readonly state: StateNames<TConfig>;
+    readonly data: unknown;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly modelVersion: number;
+}
+
 /** The result of defineWorkflow() — holds schemas and creates workflow instances. */
 interface WorkflowDefinition<TConfig extends WorkflowConfig = WorkflowConfig> {
     readonly config: TConfig;
@@ -78,6 +90,14 @@ interface WorkflowDefinition<TConfig extends WorkflowConfig = WorkflowConfig> {
     getEventSchema(eventName: string): ZodType;
     getErrorSchema(errorCode: string): ZodType;
     hasState(stateName: string): boolean;
+    snapshot(workflow: Workflow<TConfig>): WorkflowSnapshot<TConfig>;
+    restore(snapshot: WorkflowSnapshot<TConfig>): {
+        ok: true;
+        workflow: Workflow<TConfig>;
+    } | {
+        ok: false;
+        error: ValidationError;
+    };
 }
 /**
  * Creates a workflow definition from a name and Zod schema configuration.
@@ -125,6 +145,9 @@ interface Context<TConfig extends WorkflowConfig, TDeps, TState extends StateNam
 /** 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";
+
 /**
  * Koa-style middleware function with full context narrowing via defaults.
  *
@@ -134,11 +157,59 @@ type Handler<TConfig extends WorkflowConfig, TDeps, TState extends StateNames<TC
  */
 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 validated migration pipeline ready to transform snapshots. */
+interface MigrationPipeline<TConfig extends WorkflowConfig = WorkflowConfig> {
+    readonly definition: WorkflowDefinition<TConfig>;
+    readonly targetVersion: number;
+    readonly migrations: ReadonlyMap<number, MigrationFn>;
+}
+/** Result of migrate(). */
+type MigrateResult = {
+    ok: true;
+    snapshot: WorkflowSnapshot;
+} | {
+    ok: false;
+    error: MigrationError;
+};
+/** Options for migrate(). */
+interface MigrateOptions {
+    onStep?: (fromVersion: number, toVersion: number, snapshot: WorkflowSnapshot) => void;
+    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;
+    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.
+ */
+declare function defineMigrations<TConfig extends WorkflowConfig>(definition: WorkflowDefinition<TConfig>, migrationMap: Record<number, MigrationFn>): 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.
+ */
+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;
 };
+interface RouterOptions {
+    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>;
@@ -158,15 +229,26 @@ declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
     private singleStateBuilders;
     private multiStateBuilders;
     private wildcardHandlers;
-    constructor(definition: WorkflowDefinition<TConfig>, deps?: TDeps);
-    /** Adds global middleware or merges another router's handlers. */
-    use(middlewareOrRouter: ((ctx: Context<TConfig, TDeps>, next: () => Promise<void>) => Promise<void>) | WorkflowRouter<TConfig, TDeps>): this;
+    private hookRegistry;
+    private readonly onHookError;
+    constructor(definition: WorkflowDefinition<TConfig>, deps?: TDeps, options?: RouterOptions);
+    /** Adds global middleware, merges another router, or applies a 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. */
     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. */
+    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. */
-    on<C extends CommandNames<TConfig>>(_state: "*", command: C, ...fns: [
+    on<C extends CommandNames<TConfig>>(state: "*", command: C, ...fns: [
         ...AnyMiddleware[],
         (ctx: Context<TConfig, TDeps, StateNames<TConfig>, C>) => void | Promise<void>
     ]): this;
@@ -177,4 +259,14 @@ declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
     }): Promise<DispatchResult<TConfig>>;
 }
 
-export { type CommandNames, type CommandPayload, type Context, type ContextKey, type DispatchResult, DomainErrorSignal, type ErrorCodes, type ErrorData, type EventData, type EventNames, type Handler, type Middleware, type PipelineError, type StateData, type StateNames, ValidationError, type Workflow, type WorkflowConfig, type WorkflowDefinition, type WorkflowOf, WorkflowRouter, createKey, defineWorkflow };
+declare const PLUGIN_SYMBOL: unique symbol;
+/** A branded plugin function that can be passed to router.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(). */
+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. */
+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, 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 };