ai-workflows 2.1.3 → 2.4.0

package/dist/worker/topological-executor.d.ts

@@ -0,0 +1,282 @@
+/**
+ * TopologicalExecutor - Parallel step execution based on dependency graph
+ *
+ * Executes workflow steps in parallel while respecting dependency ordering.
+ * Uses topological sort to determine execution levels and runs steps
+ * within each level concurrently.
+ *
+ * Features:
+ * - Parallel execution of independent steps
+ * - Durable execution via Cloudflare Workflows step.do()
+ * - Progress callbacks for monitoring
+ * - Error handling with rollback support
+ * - Visualization helpers for debugging
+ *
+ * @example
+ * ```typescript
+ * import { TopologicalExecutor, DurableGraph } from 'ai-workflows/worker'
+ *
+ * // Create executor with steps
+ * const executor = new TopologicalExecutor()
+ *   .addStep('fetch-user', [], async (input) => {
+ *     return { userId: input.id }
+ *   })
+ *   .addStep('fetch-orders', ['fetch-user'], async (input, results) => {
+ *     return { orders: [] }
+ *   })
+ *   .addStep('fetch-prefs', ['fetch-user'], async (input, results) => {
+ *     return { prefs: {} }
+ *   })
+ *   .addStep('aggregate', ['fetch-orders', 'fetch-prefs'], async (input, results) => {
+ *     return { ...results['fetch-orders'], ...results['fetch-prefs'] }
+ *   })
+ *
+ * // Execute with durable workflow
+ * const result = await executor.run(step, { id: 'user-123' })
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { DependencyGraph, type DependencyType } from '../dependency-graph.js';
+import { type ExecutionLevel } from '../graph/topological-sort.js';
+import type { WorkflowStep, StepConfig } from './durable-step.js';
+/**
+ * Function signature for step execution
+ */
+export type StepExecutor<TInput = unknown, TOutput = unknown> = (input: TInput, previousResults: Record<string, unknown>, context: ExecutionContext) => Promise<TOutput>;
+/**
+ * Definition of a step in the execution graph
+ */
+export interface StepDefinition<TInput = unknown, TOutput = unknown> {
+    /** Unique step identifier */
+    id: string;
+    /** IDs of steps this step depends on */
+    dependencies: string[];
+    /** The step function to execute */
+    executor: StepExecutor<TInput, TOutput>;
+    /** Optional step configuration (retries, timeout) */
+    config: StepConfig | undefined;
+    /** Dependency types (hard/soft) */
+    dependencyTypes: Record<string, DependencyType> | undefined;
+}
+/**
+ * Context provided during step execution
+ */
+export interface ExecutionContext {
+    /** Current step ID */
+    stepId: string;
+    /** Current execution level */
+    level: number;
+    /** Total number of levels */
+    totalLevels: number;
+    /** Steps completed so far */
+    completedSteps: string[];
+    /** Attempt number for this step */
+    attempt: number;
+}
+/**
+ * Progress callback for monitoring execution
+ */
+export interface ProgressCallback {
+    /** Called when a level starts */
+    onLevelStart?: (level: number, steps: string[]) => void;
+    /** Called when a step starts */
+    onStepStart?: (stepId: string, level: number) => void;
+    /** Called when a step completes */
+    onStepComplete?: (stepId: string, level: number, result: unknown, duration: number) => void;
+    /** Called when a step fails */
+    onStepError?: (stepId: string, level: number, error: Error) => void;
+    /** Called when a level completes */
+    onLevelComplete?: (level: number, results: Record<string, unknown>) => void;
+}
+/**
+ * Result of executing the graph
+ */
+export interface ExecutionResult<T = Record<string, unknown>> {
+    /** All step results keyed by step ID */
+    results: T;
+    /** Execution metrics */
+    metrics: {
+        totalDuration: number;
+        levelDurations: number[];
+        stepDurations: Record<string, number>;
+        parallelEfficiency: number;
+    };
+    /** Steps that were skipped due to soft dependency failures */
+    skippedSteps: string[];
+    /** Execution order (actual order steps ran in) */
+    executionOrder: string[];
+}
+/**
+ * Configuration for TopologicalExecutor
+ */
+export interface ExecutorConfig {
+    /** Continue execution on step failure (for soft dependencies) */
+    continueOnError?: boolean;
+    /** Maximum concurrency per level (default: unlimited) */
+    maxConcurrency?: number;
+    /** Progress callbacks */
+    progress?: ProgressCallback;
+    /** Default step config */
+    defaultStepConfig?: StepConfig;
+}
+/**
+ * TopologicalExecutor - Execute steps in parallel based on dependency graph
+ *
+ * Provides parallel execution of workflow steps while respecting dependencies.
+ * Steps at the same execution level run concurrently, while levels execute
+ * sequentially.
+ */
+export declare class TopologicalExecutor<TInput = unknown> {
+    private steps;
+    private config;
+    constructor(config?: ExecutorConfig);
+    /**
+     * Add a step to the executor
+     *
+     * @param id - Unique step identifier
+     * @param dependencies - IDs of steps this step depends on
+     * @param executor - Function to execute
+     * @param config - Optional step configuration
+     * @returns this (for chaining)
+     */
+    addStep<TOutput>(id: string, dependencies: string[], executor: StepExecutor<TInput, TOutput>, config?: StepConfig): this;
+    /**
+     * Add a step with dependency type specification
+     */
+    addStepWithTypes<TOutput>(id: string, dependencies: Array<{
+        id: string;
+        type?: DependencyType;
+    }>, executor: StepExecutor<TInput, TOutput>, config?: StepConfig): this;
+    /**
+     * Get the dependency graph
+     */
+    getGraph(): DependencyGraph;
+    /**
+     * Get execution levels for parallel execution
+     */
+    getExecutionLevels(): ExecutionLevel[];
+    /**
+     * Validate the graph (check for cycles, missing deps)
+     */
+    validate(): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Execute the graph with durable semantics
+     *
+     * @param workflowStep - Cloudflare Workflows step object
+     * @param input - Input to pass to all steps
+     * @returns Execution result with all step outputs
+     */
+    run(workflowStep: WorkflowStep, input: TInput): Promise<ExecutionResult<Record<string, unknown>>>;
+    /**
+     * Execute a single step with durability
+     */
+    private executeStep;
+    /**
+     * Visualize the execution graph as DOT format
+     */
+    toDot(): string;
+    /**
+     * Get graph as JSON for debugging
+     */
+    toJSON(): {
+        steps: StepDefinition[];
+        levels: ExecutionLevel[];
+    };
+}
+/**
+ * DurableGraph - Dependency graph with durable execution support
+ *
+ * Extends DependencyGraph with execution capabilities using Cloudflare
+ * Workflows durability. Provides a higher-level API for building and
+ * executing workflow step graphs.
+ *
+ * @example
+ * ```typescript
+ * const graph = new DurableGraph<{ userId: string }>()
+ *   .node('fetch-user', async (input) => {
+ *     return await fetchUser(input.userId)
+ *   })
+ *   .node('fetch-orders', ['fetch-user'], async (input, results) => {
+ *     return await fetchOrders(results['fetch-user'].id)
+ *   })
+ *
+ * const result = await graph.execute(step, { userId: '123' })
+ * ```
+ */
+export declare class DurableGraph<TInput = unknown> {
+    private executor;
+    private nodeMetadata;
+    constructor(config?: ExecutorConfig);
+    /**
+     * Add a node (step) to the graph
+     *
+     * @param id - Unique node identifier
+     * @param executor - Function to execute (if no dependencies)
+     */
+    node<TOutput>(id: string, executor: StepExecutor<TInput, TOutput>): this;
+    /**
+     * Add a node with dependencies
+     *
+     * @param id - Unique node identifier
+     * @param dependencies - IDs of nodes this node depends on
+     * @param executor - Function to execute
+     */
+    node<TOutput>(id: string, dependencies: string[], executor: StepExecutor<TInput, TOutput>): this;
+    /**
+     * Add a node with dependencies and config
+     *
+     * @param id - Unique node identifier
+     * @param dependencies - IDs of nodes this node depends on
+     * @param executor - Function to execute
+     * @param config - Step configuration
+     */
+    node<TOutput>(id: string, dependencies: string[], executor: StepExecutor<TInput, TOutput>, config: StepConfig): this;
+    /**
+     * Add metadata to a node
+     */
+    describe(id: string, metadata: {
+        description?: string;
+        tags?: string[];
+    }): this;
+    /**
+     * Get execution levels
+     */
+    levels(): ExecutionLevel[];
+    /**
+     * Validate the graph
+     */
+    validate(): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Execute the graph with durable semantics
+     */
+    execute(workflowStep: WorkflowStep, input: TInput): Promise<ExecutionResult<Record<string, unknown>>>;
+    /**
+     * Get DOT visualization
+     */
+    toDot(): string;
+    /**
+     * Get as JSON
+     */
+    toJSON(): ReturnType<TopologicalExecutor<TInput>['toJSON']> & {
+        metadata: Record<string, {
+            description?: string;
+            tags?: string[];
+        }>;
+    };
+}
+/**
+ * Create a new TopologicalExecutor
+ */
+export declare function createExecutor<TInput = unknown>(config?: ExecutorConfig): TopologicalExecutor<TInput>;
+/**
+ * Create a new DurableGraph
+ */
+export declare function createGraph<TInput = unknown>(config?: ExecutorConfig): DurableGraph<TInput>;
+//# sourceMappingURL=topological-executor.d.ts.map

package/dist/worker/topological-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topological-executor.d.ts","sourceRoot":"","sources":["../../src/worker/topological-executor.ts"],"names":[],"mappings":"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"}

package/dist/worker/topological-executor.js

@@ -0,0 +1,396 @@
+/**
+ * TopologicalExecutor - Parallel step execution based on dependency graph
+ *
+ * Executes workflow steps in parallel while respecting dependency ordering.
+ * Uses topological sort to determine execution levels and runs steps
+ * within each level concurrently.
+ *
+ * Features:
+ * - Parallel execution of independent steps
+ * - Durable execution via Cloudflare Workflows step.do()
+ * - Progress callbacks for monitoring
+ * - Error handling with rollback support
+ * - Visualization helpers for debugging
+ *
+ * @example
+ * ```typescript
+ * import { TopologicalExecutor, DurableGraph } from 'ai-workflows/worker'
+ *
+ * // Create executor with steps
+ * const executor = new TopologicalExecutor()
+ *   .addStep('fetch-user', [], async (input) => {
+ *     return { userId: input.id }
+ *   })
+ *   .addStep('fetch-orders', ['fetch-user'], async (input, results) => {
+ *     return { orders: [] }
+ *   })
+ *   .addStep('fetch-prefs', ['fetch-user'], async (input, results) => {
+ *     return { prefs: {} }
+ *   })
+ *   .addStep('aggregate', ['fetch-orders', 'fetch-prefs'], async (input, results) => {
+ *     return { ...results['fetch-orders'], ...results['fetch-prefs'] }
+ *   })
+ *
+ * // Execute with durable workflow
+ * const result = await executor.run(step, { id: 'user-123' })
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { DependencyGraph, CircularDependencyError, MissingDependencyError, } from '../dependency-graph.js';
+import { topologicalSort, getExecutionLevels, CycleDetectedError, } from '../graph/topological-sort.js';
+// ============================================================================
+// TopologicalExecutor
+// ============================================================================
+/**
+ * TopologicalExecutor - Execute steps in parallel based on dependency graph
+ *
+ * Provides parallel execution of workflow steps while respecting dependencies.
+ * Steps at the same execution level run concurrently, while levels execute
+ * sequentially.
+ */
+export class TopologicalExecutor {
+    steps = new Map();
+    config;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    /**
+     * Add a step to the executor
+     *
+     * @param id - Unique step identifier
+     * @param dependencies - IDs of steps this step depends on
+     * @param executor - Function to execute
+     * @param config - Optional step configuration
+     * @returns this (for chaining)
+     */
+    addStep(id, dependencies, executor, config) {
+        this.steps.set(id, {
+            id,
+            dependencies,
+            executor: executor,
+            config: config ?? this.config.defaultStepConfig,
+            dependencyTypes: undefined,
+        });
+        return this;
+    }
+    /**
+     * Add a step with dependency type specification
+     */
+    addStepWithTypes(id, dependencies, executor, config) {
+        const depIds = dependencies.map((d) => d.id);
+        const depTypes = {};
+        for (const dep of dependencies) {
+            depTypes[dep.id] = dep.type ?? 'hard';
+        }
+        this.steps.set(id, {
+            id,
+            dependencies: depIds,
+            executor: executor,
+            config: config ?? this.config.defaultStepConfig,
+            dependencyTypes: depTypes,
+        });
+        return this;
+    }
+    /**
+     * Get the dependency graph
+     */
+    getGraph() {
+        const graph = new DependencyGraph();
+        // Add nodes in topological order to ensure dependencies exist
+        const nodes = Array.from(this.steps.values()).map((s) => ({
+            id: s.id,
+            dependencies: s.dependencies,
+        }));
+        const sorted = topologicalSort(nodes);
+        if (sorted.hasCycle) {
+            throw new CycleDetectedError(sorted.cyclePath ?? ['unknown']);
+        }
+        // Add nodes without dependencies first
+        for (const id of sorted.order) {
+            const step = this.steps.get(id);
+            if (step.dependencies.length === 0) {
+                graph.addNode(id);
+            }
+        }
+        // Add nodes with dependencies
+        for (const id of sorted.order) {
+            const step = this.steps.get(id);
+            if (step.dependencies.length > 0) {
+                const firstDep = step.dependencies[0];
+                const depType = firstDep !== undefined ? step.dependencyTypes?.[firstDep] ?? 'hard' : 'hard';
+                graph.addNode(id, {
+                    dependsOn: step.dependencies,
+                    type: depType,
+                });
+            }
+        }
+        return graph;
+    }
+    /**
+     * Get execution levels for parallel execution
+     */
+    getExecutionLevels() {
+        const nodes = Array.from(this.steps.values()).map((s) => ({
+            id: s.id,
+            dependencies: s.dependencies,
+        }));
+        return getExecutionLevels(nodes);
+    }
+    /**
+     * Validate the graph (check for cycles, missing deps)
+     */
+    validate() {
+        const errors = [];
+        const nodes = Array.from(this.steps.values()).map((s) => ({
+            id: s.id,
+            dependencies: s.dependencies,
+        }));
+        // Check for cycles
+        const result = topologicalSort(nodes);
+        if (result.hasCycle) {
+            errors.push(`Circular dependency detected: ${result.cyclePath?.join(' -> ')}`);
+        }
+        // Check for missing dependencies
+        const stepIds = new Set(this.steps.keys());
+        for (const step of this.steps.values()) {
+            for (const dep of step.dependencies) {
+                if (!stepIds.has(dep)) {
+                    errors.push(`Step '${step.id}' depends on missing step '${dep}'`);
+                }
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+        };
+    }
+    /**
+     * Execute the graph with durable semantics
+     *
+     * @param workflowStep - Cloudflare Workflows step object
+     * @param input - Input to pass to all steps
+     * @returns Execution result with all step outputs
+     */
+    async run(workflowStep, input) {
+        const validation = this.validate();
+        if (!validation.valid) {
+            throw new Error(`Invalid execution graph: ${validation.errors.join(', ')}`);
+        }
+        const levels = this.getExecutionLevels();
+        const results = {};
+        const stepDurations = {};
+        const levelDurations = [];
+        const skippedSteps = [];
+        const executionOrder = [];
+        const completedSteps = [];
+        const failedSteps = new Set();
+        const startTime = Date.now();
+        for (let levelIndex = 0; levelIndex < levels.length; levelIndex++) {
+            const level = levels[levelIndex];
+            const levelStartTime = Date.now();
+            this.config.progress?.onLevelStart?.(level.level, level.nodes);
+            // Filter steps that can run (all hard deps satisfied)
+            const runnableSteps = level.nodes.filter((stepId) => {
+                const step = this.steps.get(stepId);
+                const hardDeps = step.dependencies.filter((dep) => (step.dependencyTypes?.[dep] ?? 'hard') === 'hard');
+                return hardDeps.every((dep) => completedSteps.includes(dep));
+            });
+            // Skip steps whose hard dependencies failed
+            const stepsToSkip = level.nodes.filter((stepId) => !runnableSteps.includes(stepId));
+            for (const stepId of stepsToSkip) {
+                skippedSteps.push(stepId);
+                failedSteps.add(stepId);
+            }
+            // Execute runnable steps in parallel
+            const stepPromises = runnableSteps.map(async (stepId) => {
+                const step = this.steps.get(stepId);
+                const stepStartTime = Date.now();
+                this.config.progress?.onStepStart?.(stepId, level.level);
+                const context = {
+                    stepId,
+                    level: level.level,
+                    totalLevels: levels.length,
+                    completedSteps: [...completedSteps],
+                    attempt: 1,
+                };
+                try {
+                    const result = await this.executeStep(workflowStep, step, input, results, context);
+                    const duration = Date.now() - stepStartTime;
+                    results[stepId] = result;
+                    stepDurations[stepId] = duration;
+                    executionOrder.push(stepId);
+                    completedSteps.push(stepId);
+                    this.config.progress?.onStepComplete?.(stepId, level.level, result, duration);
+                    return { stepId, success: true, result };
+                }
+                catch (error) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    const duration = Date.now() - stepStartTime;
+                    stepDurations[stepId] = duration;
+                    failedSteps.add(stepId);
+                    this.config.progress?.onStepError?.(stepId, level.level, err);
+                    if (!this.config.continueOnError) {
+                        throw err;
+                    }
+                    return { stepId, success: false, error: err };
+                }
+            });
+            // Wait for all steps in this level
+            const levelResults = await Promise.all(stepPromises);
+            const levelDuration = Date.now() - levelStartTime;
+            levelDurations.push(levelDuration);
+            this.config.progress?.onLevelComplete?.(level.level, results);
+        }
+        const totalDuration = Date.now() - startTime;
+        // Calculate parallel efficiency
+        const sequentialTime = Object.values(stepDurations).reduce((a, b) => a + b, 0);
+        const parallelEfficiency = sequentialTime > 0 ? sequentialTime / totalDuration : 1;
+        return {
+            results,
+            metrics: {
+                totalDuration,
+                levelDurations,
+                stepDurations,
+                parallelEfficiency,
+            },
+            skippedSteps,
+            executionOrder,
+        };
+    }
+    /**
+     * Execute a single step with durability
+     */
+    async executeStep(workflowStep, step, input, previousResults, context) {
+        if (step.config) {
+            return workflowStep.do(step.id, step.config, async () => {
+                return step.executor(input, previousResults, context);
+            });
+        }
+        else {
+            return workflowStep.do(step.id, async () => {
+                return step.executor(input, previousResults, context);
+            });
+        }
+    }
+    /**
+     * Visualize the execution graph as DOT format
+     */
+    toDot() {
+        const graph = this.getGraph();
+        return graph.toDot();
+    }
+    /**
+     * Get graph as JSON for debugging
+     */
+    toJSON() {
+        return {
+            steps: Array.from(this.steps.values()),
+            levels: this.getExecutionLevels(),
+        };
+    }
+}
+// ============================================================================
+// DurableGraph
+// ============================================================================
+/**
+ * DurableGraph - Dependency graph with durable execution support
+ *
+ * Extends DependencyGraph with execution capabilities using Cloudflare
+ * Workflows durability. Provides a higher-level API for building and
+ * executing workflow step graphs.
+ *
+ * @example
+ * ```typescript
+ * const graph = new DurableGraph<{ userId: string }>()
+ *   .node('fetch-user', async (input) => {
+ *     return await fetchUser(input.userId)
+ *   })
+ *   .node('fetch-orders', ['fetch-user'], async (input, results) => {
+ *     return await fetchOrders(results['fetch-user'].id)
+ *   })
+ *
+ * const result = await graph.execute(step, { userId: '123' })
+ * ```
+ */
+export class DurableGraph {
+    executor;
+    nodeMetadata = new Map();
+    constructor(config = {}) {
+        this.executor = new TopologicalExecutor(config);
+    }
+    /**
+     * Implementation of node() overloads
+     */
+    node(id, depsOrExecutor, executorOrConfig, maybeConfig) {
+        if (typeof depsOrExecutor === 'function') {
+            // node(id, executor)
+            this.executor.addStep(id, [], depsOrExecutor);
+        }
+        else if (typeof executorOrConfig === 'function') {
+            // node(id, deps, executor) or node(id, deps, executor, config)
+            this.executor.addStep(id, depsOrExecutor, executorOrConfig, maybeConfig);
+        }
+        return this;
+    }
+    /**
+     * Add metadata to a node
+     */
+    describe(id, metadata) {
+        this.nodeMetadata.set(id, metadata);
+        return this;
+    }
+    /**
+     * Get execution levels
+     */
+    levels() {
+        return this.executor.getExecutionLevels();
+    }
+    /**
+     * Validate the graph
+     */
+    validate() {
+        return this.executor.validate();
+    }
+    /**
+     * Execute the graph with durable semantics
+     */
+    async execute(workflowStep, input) {
+        return this.executor.run(workflowStep, input);
+    }
+    /**
+     * Get DOT visualization
+     */
+    toDot() {
+        return this.executor.toDot();
+    }
+    /**
+     * Get as JSON
+     */
+    toJSON() {
+        const metadata = {};
+        for (const [id, meta] of this.nodeMetadata) {
+            metadata[id] = meta;
+        }
+        return {
+            ...this.executor.toJSON(),
+            metadata,
+        };
+    }
+}
+// ============================================================================
+// Convenience functions
+// ============================================================================
+/**
+ * Create a new TopologicalExecutor
+ */
+export function createExecutor(config) {
+    return new TopologicalExecutor(config);
+}
+/**
+ * Create a new DurableGraph
+ */
+export function createGraph(config) {
+    return new DurableGraph(config);
+}
+//# sourceMappingURL=topological-executor.js.map