ai-workflows 2.1.1 → 2.3.0

package/src/index.ts

@@ -63,6 +63,18 @@
 // Main Workflow API
 export { Workflow, createTestContext, parseEvent, type WorkflowInstance } from './workflow.js'
 
+// WorkflowRuntime - single owner of the `$` runtime contract
+// (composes cascade-context, database-context, on/send/every internally).
+// New callers should reach for createWorkflowRuntime() to understand exactly
+// what `$` contains end-to-end. The Workflow() function wraps a runtime with
+// schedule/timer lifecycle; for tests, runtime.dispatch() is the canonical
+// surface.
+export {
+  createWorkflowRuntime,
+  type WorkflowRuntime,
+  type WorkflowRuntimeOptions,
+} from './runtime.js'
+
 // Standalone event handling (for global registration)
 export { on, registerEventHandler, getEventHandlers, clearEventHandlers } from './on.js'
 
@@ -84,6 +96,139 @@ export { send, getEventBus } from './send.js'
 // Context
 export { createWorkflowContext, createIsolatedContext } from './context.js'
 
+// Cascade Context - Correlation IDs and step metadata
+export {
+  createCascadeContext,
+  recordStep,
+  withCascadeContext,
+  type CascadeContext,
+  type CascadeStep,
+  type CascadeContextOptions,
+  type SerializedCascadeContext,
+  type SerializedCascadeStep,
+  type TraceContext,
+  type FiveWHEvent,
+  type StepStatus,
+} from './cascade-context.js'
+
+// Dependency Graph
+export {
+  DependencyGraph,
+  CircularDependencyError,
+  MissingDependencyError,
+  type GraphNode,
+  type ParallelGroup,
+  type GraphJSON,
+  type EventRegistrationWithDeps,
+} from './dependency-graph.js'
+
+// Topological Sort - Execution ordering algorithms
+export {
+  topologicalSort,
+  topologicalSortKahn,
+  topologicalSortDFS,
+  getExecutionLevels,
+  CycleDetectedError,
+  MissingNodeError,
+  type SortableNode,
+  type ExecutionLevel,
+  type TopologicalSortOptions,
+  type TopologicalSortResult,
+} from './graph/topological-sort.js'
+
+// Barrier/Join Semantics - Parallel step coordination
+export {
+  Barrier,
+  BarrierTimeoutError,
+  createBarrier,
+  waitForAll,
+  waitForAny,
+  withConcurrencyLimit,
+  type BarrierOptions,
+  type BarrierProgress,
+  type BarrierResult,
+  type WaitForAllOptions,
+  type WaitForAnyOptions,
+  type WaitForAnyResult,
+  type ConcurrencyOptions,
+} from './barrier.js'
+
+// Cascade Executor - code -> generative -> agentic -> human pattern
+export {
+  CascadeExecutor,
+  CascadeTimeoutError,
+  TierSkippedError,
+  AllTiersFailedError,
+  TIER_ORDER,
+  DEFAULT_TIER_TIMEOUTS,
+  type CapabilityTier,
+  type TierHandler,
+  type TierContext,
+  type TierResult,
+  type TierRetryConfig,
+  type CascadeConfig,
+  type CascadeResult,
+  type CascadeMetrics,
+  type SkipCondition,
+} from './cascade-executor.js'
+
+// DurableStep - Cloudflare Workflows step wrapper
+export {
+  DurableStep,
+  StepContext as DurableStepContext,
+  type StepConfig,
+  type StepMetadata,
+  type RetryConfig as DurableRetryConfig,
+  type WorkflowStep,
+  type StepFunction as DurableStepFunction,
+  // Cascade types
+  DurableCascadeStep,
+  AllTiersFailed,
+  CascadeTimeout,
+  DEFAULT_CASCADE_TIMEOUTS,
+  CASCADE_TIER_ORDER,
+  type CascadeTier,
+  type CascadeConfig as DurableCascadeConfig,
+  type CascadeTierConfig,
+  type CascadeTierResult,
+  type CascadeResult as DurableCascadeResult,
+  type CascadeContext as DurableCascadeContext,
+  type CascadeTierContext,
+  type AiBinding,
+  type HumanReviewRequest,
+  type CodeTierHandler,
+  type AiTierHandler,
+  type HumanTierHandler,
+} from './worker/durable-step.js'
+
+// WorkflowBuilder DSL - Fluent API for building durable workflows
+export {
+  workflow,
+  WorkflowBuilder,
+  type StepDefinition,
+  type StepChain,
+  type ConditionalChain,
+  type LoopChain,
+  type BuiltWorkflow,
+  type StepContext,
+  type RetryConfig,
+  type StepFunction,
+  type ConditionFunction,
+  type ErrorHandler,
+  type LoopOptions,
+  type ForEachOptions,
+} from './workflow-builder.js'
+
+// WorkflowStateAdapter - Persistent state storage
+export {
+  WorkflowStateAdapter,
+  type PersistedWorkflowState,
+  type StepCheckpoint,
+  type WorkflowHistoryEntry as StateHistoryEntry,
+  type SnapshotInfo,
+  type DatabaseConnection,
+} from './worker/state-adapter.js'
+
 // Types
 export type {
   EventHandler,
@@ -103,4 +248,6 @@ export type {
   DatabaseContext,
   ActionData,
   ArtifactData,
+  DependencyConfig,
+  DependencyType,
 } from './types.js'

package/src/logger.ts

@@ -0,0 +1,148 @@
+/**
+ * Configurable Logger Interface
+ *
+ * Provides a pluggable logging abstraction for ai-workflows.
+ * By default uses console.log/warn/error, but can be replaced
+ * with any logging implementation.
+ *
+ * @example
+ * ```ts
+ * import { setLogger, getLogger } from 'ai-workflows'
+ *
+ * // Use default console logger
+ * const logger = getLogger()
+ * logger.log('[workflow] Starting', { workflowId: '123' })
+ *
+ * // Set a custom logger
+ * setLogger({
+ *   log: (msg, data) => winston.info(msg, data),
+ *   warn: (msg, data) => winston.warn(msg, data),
+ *   error: (msg, error) => winston.error(msg, { error }),
+ * })
+ *
+ * // Disable logging
+ * setLogger({
+ *   log: () => {},
+ *   warn: () => {},
+ *   error: () => {},
+ * })
+ * ```
+ */
+
+/**
+ * Logger interface for ai-workflows
+ *
+ * Implementations must provide log, warn, and error methods.
+ * Data parameter is optional and can be any value for context.
+ */
+export interface Logger {
+  /**
+   * Log informational messages
+   * @param msg - The log message
+   * @param data - Optional data for context
+   */
+  log(msg: string, data?: unknown): void
+
+  /**
+   * Log warning messages
+   * @param msg - The warning message
+   * @param data - Optional data for context
+   */
+  warn(msg: string, data?: unknown): void
+
+  /**
+   * Log error messages
+   * @param msg - The error message
+   * @param error - Optional error object or data
+   */
+  error(msg: string, error?: unknown): void
+}
+
+/**
+ * Default console logger implementation
+ *
+ * Uses console.log, console.warn, and console.error.
+ */
+export const consoleLogger: Logger = {
+  log(msg: string, data?: unknown): void {
+    if (data !== undefined) {
+      console.log(msg, data)
+    } else {
+      console.log(msg)
+    }
+  },
+
+  warn(msg: string, data?: unknown): void {
+    if (data !== undefined) {
+      console.warn(msg, data)
+    } else {
+      console.warn(msg)
+    }
+  },
+
+  error(msg: string, error?: unknown): void {
+    if (error !== undefined) {
+      console.error(msg, error)
+    } else {
+      console.error(msg)
+    }
+  },
+}
+
+/**
+ * No-op logger that discards all messages
+ *
+ * Useful for silencing logs in tests or production.
+ */
+export const noopLogger: Logger = {
+  log(): void {},
+  warn(): void {},
+  error(): void {},
+}
+
+/**
+ * Current logger instance
+ * Defaults to consoleLogger
+ */
+let currentLogger: Logger = consoleLogger
+
+/**
+ * Get the current logger instance
+ *
+ * @returns The current Logger implementation
+ */
+export function getLogger(): Logger {
+  return currentLogger
+}
+
+/**
+ * Set the logger implementation
+ *
+ * @param logger - The Logger implementation to use
+ *
+ * @example
+ * ```ts
+ * // Use a custom logger
+ * setLogger({
+ *   log: (msg, data) => myLogger.info(msg, data),
+ *   warn: (msg, data) => myLogger.warn(msg, data),
+ *   error: (msg, error) => myLogger.error(msg, { error }),
+ * })
+ *
+ * // Disable logging
+ * setLogger(noopLogger)
+ *
+ * // Reset to console
+ * setLogger(consoleLogger)
+ * ```
+ */
+export function setLogger(logger: Logger): void {
+  currentLogger = logger
+}
+
+/**
+ * Reset the logger to the default console logger
+ */
+export function resetLogger(): void {
+  currentLogger = consoleLogger
+}

package/src/on.ts

@@ -5,9 +5,21 @@
  *   on.Customer.created(customer => { ... })
  *   on.Order.completed(order => { ... })
  *   on.Payment.failed(payment => { ... })
+ *
+ * With dependencies:
+ *   on.Step2.complete(handler, { dependsOn: 'Step1.complete' })
+ *   on.Step3.complete(handler, { dependsOn: ['Step1.complete', 'Step2.complete'] })
  */
 
-import type { EventHandler, EventRegistration } from './types.js'
+import type {
+  EventHandler,
+  EventRegistration,
+  DependencyConfig,
+  OnProxy,
+  NounEventProxy,
+  OnProxyHandler,
+  NounEventProxyHandler,
+} from './types.js'
 
 /**
  * Registry of event handlers
@@ -34,50 +46,93 @@ export function clearEventHandlers(): void {
 export function registerEventHandler(
   noun: string,
   event: string,
-  handler: EventHandler
+  handler: EventHandler,
+  dependencies?: DependencyConfig
 ): void {
   eventRegistry.push({
     noun,
     event,
     handler,
     source: handler.toString(),
+    ...(dependencies !== undefined && { dependencies }),
   })
 }
 
 /**
- * Event proxy type for on.Noun.event pattern
+ * Handler registration callback type
+ * Used by createTypedOnProxy to customize handler registration
  */
-type EventProxy = {
-  [noun: string]: {
-    [event: string]: (handler: EventHandler) => void
-  }
-}
+export type OnProxyRegistrationCallback = (
+  noun: string,
+  event: string,
+  handler: EventHandler,
+  dependencies?: DependencyConfig
+) => void
 
 /**
- * Create the `on` proxy
+ * Create a typed OnProxy with proper TypeScript generics
  *
- * This creates a proxy that allows:
- *   on.Customer.created(handler)
- *   on.Order.shipped(handler)
+ * This factory function creates a two-level proxy that allows:
+ *   proxy.Customer.created(handler)
+ *   proxy.Order.shipped(handler)
  *
  * The first property access captures the noun (Customer, Order)
  * The second property access captures the event (created, shipped)
- * The function call registers the handler
+ * The function call invokes the registration callback
+ *
+ * @param registerCallback - Function called when a handler is registered
+ * @returns A properly typed OnProxy
+ *
+ * @example
+ * ```ts
+ * // Create proxy with custom registration
+ * const myOn = createTypedOnProxy((noun, event, handler, deps) => {
+ *   myRegistry.push({ noun, event, handler, deps })
+ * })
+ *
+ * myOn.Customer.created(handler) // Properly typed!
+ * ```
  */
-function createOnProxy(): EventProxy {
-  return new Proxy({} as EventProxy, {
-    get(_target, noun: string) {
-      // Return a proxy for the event level
-      return new Proxy({}, {
-        get(_eventTarget, event: string) {
-          // Return a function that registers the handler
-          return (handler: EventHandler) => {
-            registerEventHandler(noun, event, handler)
-          }
-        }
-      })
-    }
+export function createTypedOnProxy(registerCallback: OnProxyRegistrationCallback): OnProxy {
+  // Create typed handler for the noun level (event accessors)
+  const createNounHandler = (noun: string): NounEventProxyHandler => ({
+    get(
+      _target: Record<string, (handler: EventHandler, dependencies?: DependencyConfig) => void>,
+      event: string,
+      _receiver: unknown
+    ): (handler: EventHandler, dependencies?: DependencyConfig) => void {
+      // Return a function that registers the handler with optional dependencies
+      return (handler: EventHandler, dependencies?: DependencyConfig) => {
+        registerCallback(noun, event, handler, dependencies)
+      }
+    },
   })
+
+  // Create typed handler for the top-level proxy (noun accessors)
+  const onHandler: OnProxyHandler = {
+    get(_target: Record<string, NounEventProxy>, noun: string, _receiver: unknown): NounEventProxy {
+      // Return a proxy for the event level with typed handler
+      const eventTarget: Record<
+        string,
+        (handler: EventHandler, dependencies?: DependencyConfig) => void
+      > = {}
+      return new Proxy(eventTarget, createNounHandler(noun)) as NounEventProxy
+    },
+  }
+
+  // Create and return the typed OnProxy
+  const target: Record<string, NounEventProxy> = {}
+  return new Proxy(target, onHandler) as OnProxy
+}
+
+/**
+ * Create the `on` proxy using the global event registry
+ *
+ * This is the default implementation that uses registerEventHandler
+ * for backward compatibility with the standalone `on` export.
+ */
+function createOnProxy(): OnProxy {
+  return createTypedOnProxy(registerEventHandler)
 }
 
 /**