ai-workflows 2.1.3 → 2.4.0

package/src/graph/topological-sort.ts

@@ -86,9 +86,7 @@ export class MissingNodeError extends Error {
   referencedBy: string
 
   constructor(missingNode: string, referencedBy: string) {
-    super(
-      `Missing dependency '${missingNode}' referenced by '${referencedBy}'`
-    )
+    super(`Missing dependency '${missingNode}' referenced by '${referencedBy}'`)
     this.name = 'MissingNodeError'
     this.missingNode = missingNode
     this.referencedBy = referencedBy
@@ -168,9 +166,7 @@ export function topologicalSortKahn(
 
   // Start with nodes that have no dependencies (in-degree 0)
   // Sort alphabetically for determinism
-  const queue: string[] = [...nodeSet]
-    .filter((id) => inDegreesCopy.get(id) === 0)
-    .sort()
+  const queue: string[] = [...nodeSet].filter((id) => inDegreesCopy.get(id) === 0).sort()
 
   while (queue.length > 0) {
     // Sort queue for deterministic ordering
@@ -293,7 +289,7 @@ export function topologicalSortDFS(
   return {
     order: hasCycle ? order : order, // DFS produces correct order
     hasCycle,
-    cyclePath,
+    ...(cyclePath !== undefined && { cyclePath }),
   }
 }
 
@@ -318,7 +314,9 @@ export function topologicalSort(
     // Kahn's algorithm doesn't provide cycle path, so detect it separately
     if (result.hasCycle) {
       const dfsResult = topologicalSortDFS(nodes, options)
-      result.cyclePath = dfsResult.cyclePath
+      if (dfsResult.cyclePath !== undefined) {
+        result = { ...result, cyclePath: dfsResult.cyclePath }
+      }
     }
   } else {
     result = topologicalSortDFS(nodes, options)

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'
 
@@ -160,6 +172,63 @@ export {
   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,

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

@@ -54,7 +54,7 @@ export function registerEventHandler(
     event,
     handler,
     source: handler.toString(),
-    dependencies,
+    ...(dependencies !== undefined && { dependencies }),
   })
 }
 
@@ -105,20 +105,19 @@ export function createTypedOnProxy(registerCallback: OnProxyRegistrationCallback
       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 {
+    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> = {}
+      const eventTarget: Record<
+        string,
+        (handler: EventHandler, dependencies?: DependencyConfig) => void
+      > = {}
       return new Proxy(eventTarget, createNounHandler(noun)) as NounEventProxy
-    }
+    },
   }
 
   // Create and return the typed OnProxy