@rytejs/core 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -2,8 +2,9 @@ import { ZodType, z } from 'zod';
 
 /**
  * Shape of the configuration object passed to {@link defineWorkflow}.
+ * Exported for internal package use only — not re-exported from index.ts.
  */
-interface WorkflowConfig {
+interface WorkflowConfigInput {
     /** Optional version number for schema migrations. Defaults to 1. */
     modelVersion?: number;
     /** Record of state names to Zod schemas defining their data shape. */
@@ -15,18 +16,39 @@ interface WorkflowConfig {
     /** Record of error codes to Zod schemas defining their data shape. */
     errors: Record<string, ZodType>;
 }
+/**
+ * Workflow configuration with pre-resolved types for IDE completion.
+ *
+ * Extends {@link WorkflowConfigInput} with a `_resolved` phantom type that
+ * caches `z.infer` results. This exists because Zod v4's `z.infer` uses
+ * conditional types that TypeScript defers in deep generic chains, breaking
+ * IDE autocomplete. The `_resolved` property is never set at runtime — it is
+ * populated at the type level by {@link defineWorkflow}'s return type.
+ */
+interface WorkflowConfig extends WorkflowConfigInput {
+    _resolved: {
+        states: Record<string, unknown>;
+        commands: Record<string, unknown>;
+        events: Record<string, unknown>;
+        errors: Record<string, unknown>;
+    };
+}
 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;
+/** Forces TypeScript to flatten a type for better IDE autocomplete. */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** Resolves the data type for a given state from pre-computed types. */
+type StateData<T extends WorkflowConfig, S extends StateNames<T>> = Prettify<T["_resolved"]["states"][S]>;
+/** Resolves the payload type for a given command from pre-computed types. */
+type CommandPayload<T extends WorkflowConfig, C extends CommandNames<T>> = Prettify<T["_resolved"]["commands"][C]>;
+/** Resolves the data type for a given event from pre-computed types. */
+type EventData<T extends WorkflowConfig, E extends EventNames<T>> = Prettify<T["_resolved"]["events"][E]>;
+/** Resolves the data type for a given error code from pre-computed types. */
+type ErrorData<T extends WorkflowConfig, C extends ErrorCodes<T>> = Prettify<T["_resolved"]["errors"][C]>;
 /** Workflow narrowed to a specific known state. */
 interface WorkflowOf<TConfig extends WorkflowConfig, S extends StateNames<TConfig>> {
     /** Unique workflow instance identifier. */
@@ -64,6 +86,11 @@ type PipelineError<TConfig extends WorkflowConfig = WorkflowConfig> = {
     category: "unexpected";
     error: unknown;
     message: string;
+} | {
+    category: "dependency";
+    name: string;
+    error: unknown;
+    message: string;
 };
 /** Return type of {@link WorkflowRouter.dispatch}. Discriminated union on `ok`. */
 type DispatchResult<TConfig extends WorkflowConfig = WorkflowConfig> = {
@@ -137,7 +164,7 @@ interface WorkflowDefinition<TConfig extends WorkflowConfig = WorkflowConfig> {
      */
     createWorkflow<S extends StateNames<TConfig>>(id: string, config: {
         initialState: S;
-        data: z.infer<TConfig["states"][S]>;
+        data: StateData<TConfig, S>;
     }): WorkflowOf<TConfig, S>;
     /**
      * Returns the Zod schema for a given state name.
@@ -201,7 +228,22 @@ interface WorkflowDefinition<TConfig extends WorkflowConfig = WorkflowConfig> {
  * @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>;
+declare function defineWorkflow<const TConfig extends WorkflowConfigInput>(name: string, config: TConfig): WorkflowDefinition<TConfig & {
+    _resolved: {
+        states: {
+            [K in keyof TConfig["states"]]: z.infer<TConfig["states"][K]>;
+        };
+        commands: {
+            [K in keyof TConfig["commands"]]: z.infer<TConfig["commands"][K]>;
+        };
+        events: {
+            [K in keyof TConfig["events"]]: z.infer<TConfig["events"][K]>;
+        };
+        errors: {
+            [K in keyof TConfig["errors"]]: z.infer<TConfig["errors"][K]>;
+        };
+    };
+}>;
 
 /** A phantom-typed key for type-safe middleware state storage via {@link Context.set} and {@link Context.get}. */
 interface ContextKey<T> {
@@ -391,12 +433,16 @@ type HandlerEntry = {
 interface RouterOptions {
     /** Callback invoked when a lifecycle hook throws. Defaults to `console.error`. */
     onHookError?: (error: unknown) => void;
+    /** Wrap deps in a Proxy to catch dependency errors. Defaults to `true`. */
+    wrapDeps?: boolean;
 }
 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;
+    constructor();
+    on<C extends CommandNames<TConfig>>(command: C, handler: (ctx: Context<TConfig, TDeps, TState, C>) => 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.
@@ -413,6 +459,7 @@ declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
     private wildcardHandlers;
     private hookRegistry;
     private readonly onHookError;
+    private readonly wrapDeps;
     /**
      * @param definition - The workflow definition describing states, commands, events, and errors
      * @param deps - Dependencies injected into every handler context
@@ -449,7 +496,14 @@ declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
      * 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
+     * @param handler - The terminal handler
+     */
+    on<C extends CommandNames<TConfig>>(state: "*", command: C, handler: (ctx: Context<TConfig, TDeps, StateNames<TConfig>, C>) => void | Promise<void>): this;
+    /**
+     * Registers a wildcard handler that matches any state, with inline middleware.
+     * @param state - Must be `"*"` to match all states
+     * @param command - The command name to handle
+     * @param fns - Inline middleware followed by the terminal handler
      */
     on<C extends CommandNames<TConfig>>(state: "*", command: C, ...fns: [
         ...AnyMiddleware[],

package/dist/index.d.ts

@@ -2,8 +2,9 @@ import { ZodType, z } from 'zod';
 
 /**
  * Shape of the configuration object passed to {@link defineWorkflow}.
+ * Exported for internal package use only — not re-exported from index.ts.
  */
-interface WorkflowConfig {
+interface WorkflowConfigInput {
     /** Optional version number for schema migrations. Defaults to 1. */
     modelVersion?: number;
     /** Record of state names to Zod schemas defining their data shape. */
@@ -15,18 +16,39 @@ interface WorkflowConfig {
     /** Record of error codes to Zod schemas defining their data shape. */
     errors: Record<string, ZodType>;
 }
+/**
+ * Workflow configuration with pre-resolved types for IDE completion.
+ *
+ * Extends {@link WorkflowConfigInput} with a `_resolved` phantom type that
+ * caches `z.infer` results. This exists because Zod v4's `z.infer` uses
+ * conditional types that TypeScript defers in deep generic chains, breaking
+ * IDE autocomplete. The `_resolved` property is never set at runtime — it is
+ * populated at the type level by {@link defineWorkflow}'s return type.
+ */
+interface WorkflowConfig extends WorkflowConfigInput {
+    _resolved: {
+        states: Record<string, unknown>;
+        commands: Record<string, unknown>;
+        events: Record<string, unknown>;
+        errors: Record<string, unknown>;
+    };
+}
 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;
+/** Forces TypeScript to flatten a type for better IDE autocomplete. */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/** Resolves the data type for a given state from pre-computed types. */
+type StateData<T extends WorkflowConfig, S extends StateNames<T>> = Prettify<T["_resolved"]["states"][S]>;
+/** Resolves the payload type for a given command from pre-computed types. */
+type CommandPayload<T extends WorkflowConfig, C extends CommandNames<T>> = Prettify<T["_resolved"]["commands"][C]>;
+/** Resolves the data type for a given event from pre-computed types. */
+type EventData<T extends WorkflowConfig, E extends EventNames<T>> = Prettify<T["_resolved"]["events"][E]>;
+/** Resolves the data type for a given error code from pre-computed types. */
+type ErrorData<T extends WorkflowConfig, C extends ErrorCodes<T>> = Prettify<T["_resolved"]["errors"][C]>;
 /** Workflow narrowed to a specific known state. */
 interface WorkflowOf<TConfig extends WorkflowConfig, S extends StateNames<TConfig>> {
     /** Unique workflow instance identifier. */
@@ -64,6 +86,11 @@ type PipelineError<TConfig extends WorkflowConfig = WorkflowConfig> = {
     category: "unexpected";
     error: unknown;
     message: string;
+} | {
+    category: "dependency";
+    name: string;
+    error: unknown;
+    message: string;
 };
 /** Return type of {@link WorkflowRouter.dispatch}. Discriminated union on `ok`. */
 type DispatchResult<TConfig extends WorkflowConfig = WorkflowConfig> = {
@@ -137,7 +164,7 @@ interface WorkflowDefinition<TConfig extends WorkflowConfig = WorkflowConfig> {
      */
     createWorkflow<S extends StateNames<TConfig>>(id: string, config: {
         initialState: S;
-        data: z.infer<TConfig["states"][S]>;
+        data: StateData<TConfig, S>;
     }): WorkflowOf<TConfig, S>;
     /**
      * Returns the Zod schema for a given state name.
@@ -201,7 +228,22 @@ interface WorkflowDefinition<TConfig extends WorkflowConfig = WorkflowConfig> {
  * @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>;
+declare function defineWorkflow<const TConfig extends WorkflowConfigInput>(name: string, config: TConfig): WorkflowDefinition<TConfig & {
+    _resolved: {
+        states: {
+            [K in keyof TConfig["states"]]: z.infer<TConfig["states"][K]>;
+        };
+        commands: {
+            [K in keyof TConfig["commands"]]: z.infer<TConfig["commands"][K]>;
+        };
+        events: {
+            [K in keyof TConfig["events"]]: z.infer<TConfig["events"][K]>;
+        };
+        errors: {
+            [K in keyof TConfig["errors"]]: z.infer<TConfig["errors"][K]>;
+        };
+    };
+}>;
 
 /** A phantom-typed key for type-safe middleware state storage via {@link Context.set} and {@link Context.get}. */
 interface ContextKey<T> {
@@ -391,12 +433,16 @@ type HandlerEntry = {
 interface RouterOptions {
     /** Callback invoked when a lifecycle hook throws. Defaults to `console.error`. */
     onHookError?: (error: unknown) => void;
+    /** Wrap deps in a Proxy to catch dependency errors. Defaults to `true`. */
+    wrapDeps?: boolean;
 }
 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;
+    constructor();
+    on<C extends CommandNames<TConfig>>(command: C, handler: (ctx: Context<TConfig, TDeps, TState, C>) => 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.
@@ -413,6 +459,7 @@ declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
     private wildcardHandlers;
     private hookRegistry;
     private readonly onHookError;
+    private readonly wrapDeps;
     /**
      * @param definition - The workflow definition describing states, commands, events, and errors
      * @param deps - Dependencies injected into every handler context
@@ -449,7 +496,14 @@ declare class WorkflowRouter<TConfig extends WorkflowConfig, TDeps = {}> {
      * 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
+     * @param handler - The terminal handler
+     */
+    on<C extends CommandNames<TConfig>>(state: "*", command: C, handler: (ctx: Context<TConfig, TDeps, StateNames<TConfig>, C>) => void | Promise<void>): this;
+    /**
+     * Registers a wildcard handler that matches any state, with inline middleware.
+     * @param state - Must be `"*"` to match all states
+     * @param command - The command name to handle
+     * @param fns - Inline middleware followed by the terminal handler
      */
     on<C extends CommandNames<TConfig>>(state: "*", command: C, ...fns: [
         ...AnyMiddleware[],

package/dist/index.js

@@ -15,6 +15,15 @@ var DomainErrorSignal = class extends Error {
     this.name = "DomainErrorSignal";
   }
 };
+var DependencyErrorSignal = class extends Error {
+  constructor(depName, error) {
+    const original = error instanceof Error ? error.message : String(error);
+    super(`Dependency "${depName}" failed: ${original}`);
+    this.depName = depName;
+    this.error = error;
+    this.name = "DependencyErrorSignal";
+  }
+};
 
 // src/definition.ts
 function defineWorkflow(name, config) {
@@ -38,6 +47,7 @@ function defineWorkflow(name, config) {
         data: result.data,
         createdAt: now,
         updatedAt: now
+        // biome-ignore lint/suspicious/noExplicitAny: narrowed by the public overload's generic S parameter
       };
     },
     getStateSchema(stateName) {
@@ -106,6 +116,7 @@ function defineWorkflow(name, config) {
           createdAt: new Date(snap.createdAt),
           updatedAt: new Date(snap.updatedAt)
         }
+        // biome-ignore lint/suspicious/noExplicitAny: Prettify<any> produces { [x: string]: any } instead of any, making unknown data incompatible
       };
     }
   };
@@ -256,8 +267,75 @@ function compose(middleware) {
   };
 }
 
+// src/wrap-deps.ts
+function createDepProxy(obj, depName) {
+  return new Proxy(obj, {
+    get(target, prop, receiver) {
+      if (typeof prop === "symbol") {
+        return Reflect.get(target, prop, receiver);
+      }
+      const value = Reflect.get(target, prop, receiver);
+      if (value === null || value === void 0) {
+        return value;
+      }
+      if (typeof value === "function") {
+        return (...args) => {
+          try {
+            const result = value.apply(target, args);
+            if (result != null && typeof result === "object" && typeof result.then === "function") {
+              return result.catch((err) => {
+                throw new DependencyErrorSignal(depName, err);
+              });
+            }
+            return result;
+          } catch (err) {
+            throw new DependencyErrorSignal(depName, err);
+          }
+        };
+      }
+      if (typeof value === "object") {
+        return createDepProxy(value, depName);
+      }
+      return value;
+    }
+  });
+}
+function wrapDeps(deps) {
+  return new Proxy(deps, {
+    get(target, prop, receiver) {
+      if (typeof prop === "symbol") {
+        return Reflect.get(target, prop, receiver);
+      }
+      const value = Reflect.get(target, prop, receiver);
+      if (value === null || value === void 0) {
+        return value;
+      }
+      const depName = String(prop);
+      if (typeof value === "function") {
+        return (...args) => {
+          try {
+            const result = value.apply(target, args);
+            if (result != null && typeof result === "object" && typeof result.then === "function") {
+              return result.catch((err) => {
+                throw new DependencyErrorSignal(depName, err);
+              });
+            }
+            return result;
+          } catch (err) {
+            throw new DependencyErrorSignal(depName, err);
+          }
+        };
+      }
+      if (typeof value === "object") {
+        return createDepProxy(value, depName);
+      }
+      return value;
+    }
+  });
+}
+
 // src/context.ts
-function createContext(definition, originalWorkflow, command, deps) {
+function createContext(definition, originalWorkflow, command, deps, options) {
   let mutableState = originalWorkflow.state;
   let mutableData = {
     ...originalWorkflow.data
@@ -267,7 +345,7 @@ function createContext(definition, originalWorkflow, command, deps) {
   const ctx = {
     command,
     workflow: originalWorkflow,
-    deps,
+    deps: options?.wrapDeps !== false && deps != null && typeof deps === "object" ? wrapDeps(deps) : deps,
     get data() {
       return { ...mutableData };
     },
@@ -385,7 +463,12 @@ var StateBuilder = class {
   middleware = [];
   /** @internal */
   handlers = /* @__PURE__ */ new Map();
-  on = (command, ...fns) => {
+  constructor() {
+    this.on = this.on.bind(this);
+    this.use = this.use.bind(this);
+  }
+  // Implementation
+  on(command, ...fns) {
     if (fns.length === 0) throw new Error("on() requires at least a handler");
     const handler = fns.pop();
     const inlineMiddleware = fns;
@@ -394,11 +477,11 @@ var StateBuilder = class {
     };
     this.handlers.set(command, { inlineMiddleware, handler: wrappedHandler });
     return this;
-  };
-  use = (middleware) => {
+  }
+  use(middleware) {
     this.middleware.push(middleware);
     return this;
-  };
+  }
 };
 var WorkflowRouter = class _WorkflowRouter {
   /**
@@ -410,6 +493,7 @@ var WorkflowRouter = class _WorkflowRouter {
     this.definition = definition;
     this.deps = deps;
     this.onHookError = options.onHookError ?? console.error;
+    this.wrapDeps = options.wrapDeps !== false;
   }
   globalMiddleware = [];
   // biome-ignore lint/suspicious/noExplicitAny: type erasure — builders store handlers for different state types
@@ -419,6 +503,7 @@ var WorkflowRouter = class _WorkflowRouter {
   wildcardHandlers = /* @__PURE__ */ new Map();
   hookRegistry = new HookRegistry();
   onHookError;
+  wrapDeps;
   /**
    * Adds global middleware, merges another router, or applies a plugin.
    * @param arg - A middleware function, another {@link WorkflowRouter} to merge, or a {@link Plugin}
@@ -588,7 +673,8 @@ var WorkflowRouter = class _WorkflowRouter {
       this.definition,
       workflow,
       validatedCommand,
-      this.deps
+      this.deps,
+      { wrapDeps: this.wrapDeps }
     );
     await this.hookRegistry.emit("dispatch:start", this.onHookError, ctx);
     try {
@@ -636,6 +722,16 @@ var WorkflowRouter = class _WorkflowRouter {
             message: err.message
           }
         };
+      } else if (err instanceof DependencyErrorSignal) {
+        result = {
+          ok: false,
+          error: {
+            category: "dependency",
+            name: err.depName,
+            error: err.error,
+            message: err.message
+          }
+        };
       } else {
         result = {
           ok: false,