ai-workflows 2.1.1 → 2.3.0

package/src/every.ts

@@ -9,7 +9,16 @@
  *   every('first Monday of the month at 9am', $ => { ... })
  */
 
-import type { ScheduleHandler, ScheduleRegistration, ScheduleInterval } from './types.js'
+import type {
+  ScheduleHandler,
+  ScheduleRegistration,
+  ScheduleInterval,
+  EveryProxyTarget,
+  EveryProxy,
+  EveryProxyHandler,
+  DayScheduleProxyHandler,
+} from './types.js'
+import { PLURAL_UNITS, isPluralUnitKey } from './types.js'
 
 /**
  * Registry of schedule handlers
@@ -151,65 +160,125 @@ export async function toCron(description: string): Promise<string> {
 }
 
 /**
- * Create the `every` proxy
+ * Schedule registration callback type
+ * Used by createTypedEveryProxy to customize handler registration
  */
-function createEveryProxy() {
-  const handler = {
-    get(_target: unknown, prop: string) {
+export type EveryProxyRegistrationCallback = (
+  interval: ScheduleInterval,
+  handler: ScheduleHandler
+) => void
+
+/**
+ * Create a typed EveryProxy with proper TypeScript generics
+ *
+ * This factory function creates a callable proxy that supports:
+ *   - Direct calls: every('natural language', handler)
+ *   - Simple patterns: every.hour(handler)
+ *   - Day + time: every.Monday.at9am(handler)
+ *   - Intervals: every.minutes(30)(handler)
+ *
+ * @param registerCallback - Function called when a handler is registered
+ * @returns A properly typed EveryProxy
+ *
+ * @example
+ * ```ts
+ * // Create proxy with custom registration
+ * const myEvery = createTypedEveryProxy((interval, handler) => {
+ *   myRegistry.push({ interval, handler })
+ * })
+ *
+ * myEvery.hour(handler) // Properly typed!
+ * myEvery.Monday.at9am(handler) // Chained access typed!
+ * ```
+ */
+export function createTypedEveryProxy(registerCallback: EveryProxyRegistrationCallback): EveryProxy {
+  // Create typed handler for day schedule patterns with time modifiers
+  const createDayScheduleHandler = (
+    pattern: string,
+    prop: string
+  ): DayScheduleProxyHandler => ({
+    get(
+      _target: (handler: ScheduleHandler) => void,
+      timeKey: string,
+      _receiver: unknown
+    ): ((handler: ScheduleHandler) => void) | undefined {
+      const time = TIME_PATTERNS[timeKey]
+      if (time) {
+        const cron = combineWithTime(pattern, time)
+        return (handlerFn: ScheduleHandler) => {
+          registerCallback({ type: 'cron', expression: cron, natural: `${prop}.${timeKey}` }, handlerFn)
+        }
+      }
+      return undefined
+    },
+    apply(
+      _target: (handler: ScheduleHandler) => void,
+      _thisArg: unknown,
+      args: [ScheduleHandler]
+    ): void {
+      registerCallback({ type: 'cron', expression: pattern, natural: prop }, args[0])
+    }
+  })
+
+  // Create the main EveryProxy handler
+  const everyHandler: EveryProxyHandler = {
+    get(
+      _target: EveryProxyTarget,
+      prop: string,
+      _receiver: unknown
+    ): unknown {
       // Check if it's a known pattern
       const pattern = KNOWN_PATTERNS[prop]
       if (pattern) {
         // Return an object that can either be called directly or have time accessors
         const result = (handlerFn: ScheduleHandler) => {
-          registerScheduleHandler({ type: 'cron', expression: pattern, natural: prop }, handlerFn)
+          registerCallback({ type: 'cron', expression: pattern, natural: prop }, handlerFn)
         }
-        // Add time accessors
-        return new Proxy(result, {
-          get(_t, timeKey: string) {
-            const time = TIME_PATTERNS[timeKey]
-            if (time) {
-              const cron = combineWithTime(pattern, time)
-              return (handlerFn: ScheduleHandler) => {
-                registerScheduleHandler({ type: 'cron', expression: cron, natural: `${prop}.${timeKey}` }, handlerFn)
-              }
-            }
-            return undefined
-          },
-          apply(_t, _thisArg, args) {
-            registerScheduleHandler({ type: 'cron', expression: pattern, natural: prop }, args[0])
-          }
-        })
+        // Add time accessors with typed handler
+        return new Proxy(result, createDayScheduleHandler(pattern, prop))
       }
 
       // Check for plural time units (e.g., seconds(5), minutes(30))
-      const pluralUnits: Record<string, string> = {
-        seconds: 'second',
-        minutes: 'minute',
-        hours: 'hour',
-        days: 'day',
-        weeks: 'week',
-      }
-      if (pluralUnits[prop]) {
+      // Using type guard and typed constant for type-safe interval creation
+      if (isPluralUnitKey(prop)) {
+        const intervalType = PLURAL_UNITS[prop]
         return (value: number) => (handlerFn: ScheduleHandler) => {
-          registerScheduleHandler({ type: pluralUnits[prop] as any, value, natural: `${value} ${prop}` }, handlerFn)
+          registerCallback({ type: intervalType, value, natural: `${value} ${prop}` }, handlerFn)
         }
       }
 
       return undefined
     },
 
-    apply(_target: unknown, _thisArg: unknown, args: unknown[]) {
+    apply(
+      _target: EveryProxyTarget,
+      _thisArg: unknown,
+      args: [string, ScheduleHandler]
+    ): void {
       // Called as every('natural language description', handler)
-      const [description, handler] = args as [string, ScheduleHandler]
+      const [description, handler] = args
 
       if (typeof description === 'string' && typeof handler === 'function') {
         // Register with natural language - will be converted to cron at runtime
-        registerScheduleHandler({ type: 'natural', description }, handler)
+        registerCallback({ type: 'natural', description }, handler)
       }
     }
   }
 
-  return new Proxy(function() {} as any, handler)
+  // Create callable target with proper typing
+  // The function serves as the Proxy target - actual behavior is in the handler's apply trap
+  const target: EveryProxyTarget = function(_description: string, _handler: ScheduleHandler) {}
+  return new Proxy(target, everyHandler) as EveryProxy
+}
+
+/**
+ * Create the `every` proxy using the global schedule registry
+ *
+ * This is the default implementation that uses registerScheduleHandler
+ * for backward compatibility with the standalone `every` export.
+ */
+function createEveryProxy(): EveryProxy {
+  return createTypedEveryProxy(registerScheduleHandler)
 }
 
 /**

package/src/graph/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Graph algorithms for workflow execution ordering
+ *
+ * Provides topological sorting and execution level grouping for
+ * managing workflow step dependencies.
+ */
+
+export {
+  topologicalSort,
+  topologicalSortKahn,
+  topologicalSortDFS,
+  getExecutionLevels,
+  CycleDetectedError,
+  MissingNodeError,
+  type SortableNode,
+  type ExecutionLevel,
+  type TopologicalSortOptions,
+  type TopologicalSortResult,
+} from './topological-sort.js'

package/src/graph/topological-sort.ts

@@ -0,0 +1,412 @@
+/**
+ * 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 !== undefined && { 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)
+      if (dfsResult.cyclePath !== undefined) {
+        result = { ...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
+}