ai-workflows 2.0.2 → 2.1.3

package/src/graph/topological-sort.ts

@@ -0,0 +1,414 @@
+/**
+ * Topological Sort Implementation for Workflow Execution Ordering
+ *
+ * Provides multiple algorithms for topologically sorting workflow steps:
+ * - Kahn's algorithm (BFS-based, good for detecting cycles)
+ * - DFS-based algorithm (classic approach, provides cycle path)
+ *
+ * Features:
+ * - Cycle detection with path reporting
+ * - Parallel execution level grouping
+ * - Stable, deterministic ordering
+ * - Support for missing dependency handling
+ */
+
+/**
+ * A node that can be topologically sorted
+ */
+export interface SortableNode {
+  /** Unique identifier for the node */
+  id: string
+  /** IDs of nodes this node depends on */
+  dependencies: string[]
+}
+
+/**
+ * Execution level containing nodes that can run in parallel
+ */
+export interface ExecutionLevel {
+  /** Level number (0 = no dependencies, 1 = depends on level 0, etc.) */
+  level: number
+  /** Node IDs that can run concurrently at this level */
+  nodes: string[]
+}
+
+/**
+ * Options for topological sort
+ */
+export interface TopologicalSortOptions {
+  /** Throw CycleDetectedError instead of returning hasCycle: true (default: false) */
+  throwOnCycle?: boolean
+  /** Which algorithm to use (default: 'kahn') */
+  algorithm?: 'kahn' | 'dfs'
+  /** Throw on missing dependencies (default: false) */
+  strict?: boolean
+}
+
+/**
+ * Result of topological sort operation
+ */
+export interface TopologicalSortResult {
+  /** Sorted node IDs in execution order */
+  order: string[]
+  /** Whether a cycle was detected */
+  hasCycle: boolean
+  /** Path of nodes forming the cycle (if detected) */
+  cyclePath?: string[]
+  /** Additional metadata from the algorithm */
+  metadata?: {
+    /** In-degrees for each node (Kahn's algorithm) */
+    inDegrees?: Record<string, number>
+  }
+}
+
+/**
+ * Error thrown when a cycle is detected in the dependency graph
+ */
+export class CycleDetectedError extends Error {
+  /** The path of nodes forming the cycle */
+  cyclePath: string[]
+
+  constructor(cyclePath: string[]) {
+    const pathStr = cyclePath.join(' -> ')
+    super(`Cycle detected in dependency graph: ${pathStr}`)
+    this.name = 'CycleDetectedError'
+    this.cyclePath = cyclePath
+  }
+}
+
+/**
+ * Error thrown when a dependency references a non-existent node
+ */
+export class MissingNodeError extends Error {
+  /** The missing node ID */
+  missingNode: string
+  /** The node that references the missing node */
+  referencedBy: string
+
+  constructor(missingNode: string, referencedBy: string) {
+    super(
+      `Missing dependency '${missingNode}' referenced by '${referencedBy}'`
+    )
+    this.name = 'MissingNodeError'
+    this.missingNode = missingNode
+    this.referencedBy = referencedBy
+  }
+}
+
+/**
+ * Build adjacency list and compute in-degrees for Kahn's algorithm
+ */
+function buildGraph(
+  nodes: SortableNode[],
+  strict: boolean
+): {
+  adjacencyList: Map<string, string[]>
+  inDegrees: Map<string, number>
+  nodeSet: Set<string>
+} {
+  const nodeSet = new Set(nodes.map((n) => n.id))
+  const adjacencyList = new Map<string, string[]>()
+  const inDegrees = new Map<string, number>()
+
+  // Initialize all nodes
+  for (const node of nodes) {
+    adjacencyList.set(node.id, [])
+    inDegrees.set(node.id, 0)
+  }
+
+  // Build edges (dependency -> dependent)
+  for (const node of nodes) {
+    // Deduplicate dependencies
+    const uniqueDeps = [...new Set(node.dependencies)]
+
+    for (const dep of uniqueDeps) {
+      if (!nodeSet.has(dep)) {
+        if (strict) {
+          throw new MissingNodeError(dep, node.id)
+        }
+        // Skip missing dependencies in non-strict mode
+        continue
+      }
+
+      // Add edge from dependency to this node
+      adjacencyList.get(dep)!.push(node.id)
+      inDegrees.set(node.id, inDegrees.get(node.id)! + 1)
+    }
+  }
+
+  return { adjacencyList, inDegrees, nodeSet }
+}
+
+/**
+ * Topological sort using Kahn's algorithm (BFS-based)
+ *
+ * Algorithm:
+ * 1. Calculate in-degree for each node
+ * 2. Add all nodes with in-degree 0 to queue
+ * 3. While queue not empty:
+ *    - Remove node from queue, add to result
+ *    - Decrease in-degree of all dependents
+ *    - Add nodes with in-degree 0 to queue
+ * 4. If result size < node count, cycle exists
+ */
+export function topologicalSortKahn(
+  nodes: SortableNode[],
+  options: TopologicalSortOptions = {}
+): TopologicalSortResult {
+  const { strict = false } = options
+
+  if (nodes.length === 0) {
+    return { order: [], hasCycle: false }
+  }
+
+  const { adjacencyList, inDegrees, nodeSet } = buildGraph(nodes, strict)
+
+  const order: string[] = []
+  const inDegreesCopy = new Map(inDegrees)
+
+  // 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()
+
+  while (queue.length > 0) {
+    // Sort queue for deterministic ordering
+    queue.sort()
+    const current = queue.shift()!
+    order.push(current)
+
+    // Decrease in-degree for all dependents
+    for (const dependent of adjacencyList.get(current) || []) {
+      const newDegree = inDegreesCopy.get(dependent)! - 1
+      inDegreesCopy.set(dependent, newDegree)
+
+      if (newDegree === 0) {
+        queue.push(dependent)
+      }
+    }
+  }
+
+  // If we didn't process all nodes, there's a cycle
+  const hasCycle = order.length < nodeSet.size
+
+  // Convert in-degrees to record
+  const inDegreesRecord: Record<string, number> = {}
+  for (const [id, degree] of inDegrees) {
+    inDegreesRecord[id] = degree
+  }
+
+  return {
+    order,
+    hasCycle,
+    metadata: {
+      inDegrees: inDegreesRecord,
+    },
+  }
+}
+
+/**
+ * Topological sort using DFS-based algorithm
+ *
+ * Algorithm:
+ * 1. For each unvisited node:
+ *    - Mark as "in progress"
+ *    - Recursively visit all dependencies
+ *    - Mark as "visited" and add to result (in reverse)
+ * 2. If we encounter a node "in progress", we found a cycle
+ */
+export function topologicalSortDFS(
+  nodes: SortableNode[],
+  options: TopologicalSortOptions = {}
+): TopologicalSortResult {
+  const { strict = false } = options
+
+  if (nodes.length === 0) {
+    return { order: [], hasCycle: false }
+  }
+
+  const nodeMap = new Map(nodes.map((n) => [n.id, n]))
+  const nodeSet = new Set(nodes.map((n) => n.id))
+
+  const visited = new Set<string>()
+  const inProgress = new Set<string>()
+  const order: string[] = []
+  let cyclePath: string[] | undefined
+
+  function dfs(nodeId: string, path: string[]): boolean {
+    if (inProgress.has(nodeId)) {
+      // Found a cycle - construct the cycle path
+      const cycleStart = path.indexOf(nodeId)
+      cyclePath = [...path.slice(cycleStart), nodeId]
+      return true // Cycle detected
+    }
+
+    if (visited.has(nodeId)) {
+      return false // Already processed
+    }
+
+    inProgress.add(nodeId)
+    path.push(nodeId)
+
+    const node = nodeMap.get(nodeId)
+    if (node) {
+      // Deduplicate and sort dependencies for determinism
+      const uniqueDeps = [...new Set(node.dependencies)].sort()
+
+      for (const dep of uniqueDeps) {
+        if (!nodeSet.has(dep)) {
+          if (strict) {
+            throw new MissingNodeError(dep, nodeId)
+          }
+          continue // Skip missing deps in non-strict mode
+        }
+
+        if (dfs(dep, path)) {
+          return true // Propagate cycle detection
+        }
+      }
+    }
+
+    path.pop()
+    inProgress.delete(nodeId)
+    visited.add(nodeId)
+    order.push(nodeId)
+
+    return false
+  }
+
+  // Process nodes in sorted order for determinism
+  const sortedNodeIds = [...nodeSet].sort()
+
+  for (const nodeId of sortedNodeIds) {
+    if (!visited.has(nodeId)) {
+      if (dfs(nodeId, [])) {
+        break // Stop on first cycle
+      }
+    }
+  }
+
+  const hasCycle = cyclePath !== undefined
+
+  return {
+    order: hasCycle ? order : order, // DFS produces correct order
+    hasCycle,
+    cyclePath,
+  }
+}
+
+/**
+ * Main topological sort function with algorithm selection
+ *
+ * @param nodes - Array of nodes to sort
+ * @param options - Sort options
+ * @returns Sorted result with order and cycle information
+ */
+export function topologicalSort(
+  nodes: SortableNode[],
+  options: TopologicalSortOptions = {}
+): TopologicalSortResult {
+  const { algorithm = 'dfs', throwOnCycle = false } = options
+
+  let result: TopologicalSortResult
+
+  if (algorithm === 'kahn') {
+    result = topologicalSortKahn(nodes, options)
+
+    // Kahn's algorithm doesn't provide cycle path, so detect it separately
+    if (result.hasCycle) {
+      const dfsResult = topologicalSortDFS(nodes, options)
+      result.cyclePath = dfsResult.cyclePath
+    }
+  } else {
+    result = topologicalSortDFS(nodes, options)
+  }
+
+  if (result.hasCycle && throwOnCycle) {
+    throw new CycleDetectedError(result.cyclePath || ['unknown'])
+  }
+
+  return result
+}
+
+/**
+ * Get execution levels for parallel execution
+ *
+ * Groups nodes by their execution level:
+ * - Level 0: Nodes with no dependencies
+ * - Level N: Nodes whose dependencies are all at level < N
+ *
+ * @param nodes - Array of nodes to analyze
+ * @returns Array of execution levels, sorted by level number
+ * @throws CycleDetectedError if a cycle is detected
+ */
+export function getExecutionLevels(nodes: SortableNode[]): ExecutionLevel[] {
+  if (nodes.length === 0) {
+    return []
+  }
+
+  // First, verify no cycles exist
+  const sortResult = topologicalSort(nodes, { throwOnCycle: true })
+
+  const nodeMap = new Map(nodes.map((n) => [n.id, n]))
+  const nodeSet = new Set(nodes.map((n) => n.id))
+  const levels = new Map<string, number>()
+
+  // Calculate level for each node
+  function calculateLevel(nodeId: string): number {
+    if (levels.has(nodeId)) {
+      return levels.get(nodeId)!
+    }
+
+    const node = nodeMap.get(nodeId)
+    if (!node) {
+      return 0
+    }
+
+    // Filter to only existing dependencies
+    const validDeps = node.dependencies.filter((d) => nodeSet.has(d))
+
+    if (validDeps.length === 0) {
+      levels.set(nodeId, 0)
+      return 0
+    }
+
+    let maxDepLevel = -1
+    for (const dep of validDeps) {
+      const depLevel = calculateLevel(dep)
+      maxDepLevel = Math.max(maxDepLevel, depLevel)
+    }
+
+    const level = maxDepLevel + 1
+    levels.set(nodeId, level)
+    return level
+  }
+
+  // Calculate levels for all nodes
+  for (const node of nodes) {
+    calculateLevel(node.id)
+  }
+
+  // Group nodes by level
+  const levelGroups = new Map<number, string[]>()
+  for (const [nodeId, level] of levels) {
+    if (!levelGroups.has(level)) {
+      levelGroups.set(level, [])
+    }
+    levelGroups.get(level)!.push(nodeId)
+  }
+
+  // Convert to sorted array of ExecutionLevels
+  const result: ExecutionLevel[] = []
+  const sortedLevels = [...levelGroups.keys()].sort((a, b) => a - b)
+
+  for (const level of sortedLevels) {
+    result.push({
+      level,
+      // Sort nodes within level for determinism
+      nodes: levelGroups.get(level)!.sort(),
+    })
+  }
+
+  return result
+}

package/src/index.js

@@ -0,0 +1,71 @@
+/**
+ * ai-workflows - Event-driven workflows with $ context
+ *
+ * @example
+ * ```ts
+ * import { Workflow } from 'ai-workflows'
+ *
+ * // Create a workflow with $ context
+ * const workflow = Workflow($ => {
+ *   // Register event handlers
+ *   $.on.Customer.created(async (customer, $) => {
+ *     $.log('New customer:', customer.name)
+ *     await $.send('Email.welcome', { to: customer.email })
+ *   })
+ *
+ *   $.on.Order.completed(async (order, $) => {
+ *     $.log('Order completed:', order.id)
+ *   })
+ *
+ *   // Register scheduled tasks
+ *   $.every.hour(async ($) => {
+ *     $.log('Hourly check')
+ *   })
+ *
+ *   $.every.Monday.at9am(async ($) => {
+ *     $.log('Weekly standup reminder')
+ *   })
+ *
+ *   $.every.minutes(30)(async ($) => {
+ *     $.log('Every 30 minutes')
+ *   })
+ *
+ *   // Natural language scheduling
+ *   $.every('first Monday of the month', async ($) => {
+ *     $.log('Monthly report')
+ *   })
+ * })
+ *
+ * // Start the workflow
+ * await workflow.start()
+ *
+ * // Emit events
+ * await workflow.send('Customer.created', { name: 'John', email: 'john@example.com' })
+ * ```
+ *
+ * @example
+ * // Alternative: Use standalone on/every for global registration
+ * ```ts
+ * import { on, every, send } from 'ai-workflows'
+ *
+ * on.Customer.created(async (customer, $) => {
+ *   await $.send('Email.welcome', { to: customer.email })
+ * })
+ *
+ * every.hour(async ($) => {
+ *   $.log('Hourly task')
+ * })
+ *
+ * await send('Customer.created', { name: 'John' })
+ * ```
+ */
+// Main Workflow API
+export { Workflow, createTestContext, parseEvent } from './workflow.js';
+// Standalone event handling (for global registration)
+export { on, registerEventHandler, getEventHandlers, clearEventHandlers } from './on.js';
+// Standalone scheduling (for global registration)
+export { every, registerScheduleHandler, getScheduleHandlers, clearScheduleHandlers, setCronConverter, toCron, intervalToMs, formatInterval, } from './every.js';
+// Event emission
+export { send, getEventBus } from './send.js';
+// Context
+export { createWorkflowContext, createIsolatedContext } from './context.js';

package/src/index.ts

@@ -84,6 +84,82 @@ 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'
+
 // Types
 export type {
   EventHandler,
@@ -103,4 +179,6 @@ export type {
   DatabaseContext,
   ActionData,
   ArtifactData,
+  DependencyConfig,
+  DependencyType,
 } from './types.js'

package/src/on.js

@@ -0,0 +1,79 @@
+/**
+ * Event handler registration using on.Noun.event syntax
+ *
+ * Usage:
+ *   on.Customer.created(customer => { ... })
+ *   on.Order.completed(order => { ... })
+ *   on.Payment.failed(payment => { ... })
+ */
+/**
+ * Registry of event handlers
+ */
+const eventRegistry = [];
+/**
+ * Get all registered event handlers
+ */
+export function getEventHandlers() {
+    return [...eventRegistry];
+}
+/**
+ * Clear all registered event handlers
+ */
+export function clearEventHandlers() {
+    eventRegistry.length = 0;
+}
+/**
+ * Register an event handler directly
+ */
+export function registerEventHandler(noun, event, handler) {
+    eventRegistry.push({
+        noun,
+        event,
+        handler,
+        source: handler.toString(),
+    });
+}
+/**
+ * Create the `on` proxy
+ *
+ * This creates a proxy that allows:
+ *   on.Customer.created(handler)
+ *   on.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
+ */
+function createOnProxy() {
+    return new Proxy({}, {
+        get(_target, noun) {
+            // Return a proxy for the event level
+            return new Proxy({}, {
+                get(_eventTarget, event) {
+                    // Return a function that registers the handler
+                    return (handler) => {
+                        registerEventHandler(noun, event, handler);
+                    };
+                }
+            });
+        }
+    });
+}
+/**
+ * The `on` object for registering event handlers
+ *
+ * @example
+ * ```ts
+ * import { on } from 'ai-workflows'
+ *
+ * on.Customer.created(async (customer, $) => {
+ *   $.log('Customer created:', customer.name)
+ *   await $.send('Email.welcome', { to: customer.email })
+ * })
+ *
+ * on.Order.completed(async (order, $) => {
+ *   $.log('Order completed:', order.id)
+ * })
+ * ```
+ */
+export const on = createOnProxy();