@calmo/task-runner 3.3.0 → 3.4.1

package/src/EventBus.ts

@@ -61,23 +61,25 @@ export class EventBus<TContext> {
       | undefined;
     if (listeners) {
       for (const listener of listeners) {
-        try {
-          const result = listener(data);
-          if (result instanceof Promise) {
-            result.catch((error) => {
-              console.error(
-                `Error in event listener for ${String(event)}:`,
-                error
-              );
-            });
+        Promise.resolve().then(() => {
+          try {
+            const result = listener(data);
+            if (result instanceof Promise) {
+              result.catch((error) => {
+                console.error(
+                  `Error in event listener for ${String(event)}:`,
+                  error
+                );
+              });
+            }
+          } catch (error) {
+            // Prevent listener errors from bubbling up
+            console.error(
+              `Error in event listener for ${String(event)}:`,
+              error
+            );
           }
-        } catch (error) {
-          // Prevent listener errors from bubbling up
-          console.error(
-            `Error in event listener for ${String(event)}:`,
-            error
-          );
-        }
+        });
       }
     }
   }

package/src/TaskGraph.ts

@@ -2,18 +2,18 @@
  * Represents a single task in the task graph.
  */
 export interface Task {
-    /** Unique identifier for the task. */
-    id: string;
-    /** An array of task IDs that this task directly depends on. */
-    dependencies: string[];
-    /** Allows for any other properties specific to the task's payload or configuration. */
-    [key: string]: unknown;
+  /** Unique identifier for the task. */
+  id: string;
+  /** An array of task IDs that this task directly depends on. */
+  dependencies: string[];
+  /** Allows for any other properties specific to the task's payload or configuration. */
+  [key: string]: unknown;
 }
 
 /**
  * Represents the entire collection of tasks and their interdependencies.
  */
 export interface TaskGraph {
-    /** An array of tasks that make up the graph. */
-    tasks: Task[];
+  /** An array of tasks that make up the graph. */
+  tasks: Task[];
 }

package/src/TaskGraphValidationError.ts

@@ -0,0 +1,15 @@
+import { ValidationResult } from "./contracts/ValidationResult.js";
+
+/**
+ * Error thrown when a task graph fails validation.
+ * Contains the validation result with detailed error information.
+ */
+export class TaskGraphValidationError extends Error {
+  constructor(
+    public result: ValidationResult,
+    message: string
+  ) {
+    super(message);
+    this.name = "TaskGraphValidationError";
+  }
+}

package/src/TaskGraphValidator.ts

@@ -4,160 +4,165 @@ import { ValidationError } from "./contracts/ValidationError.js";
 import { TaskGraph } from "./TaskGraph.js";
 
 export class TaskGraphValidator implements ITaskGraphValidator {
-    /**
-     * Validates a given task graph for structural integrity.
-     * Checks for:
-     * 1. Duplicate task IDs.
-     * 2. Missing dependencies (tasks that depend on non-existent IDs).
-     * 3. Circular dependencies (cycles in the graph).
-     *
-     * @param taskGraph The task graph to validate.
-     * @returns A ValidationResult object indicating the outcome of the validation.
-     */
-    validate(taskGraph: TaskGraph): ValidationResult {
-        const errors: ValidationError[] = [];
-
-        // 1. Check for duplicate tasks
-        const taskIds = new Set<string>();
-        for (const task of taskGraph.tasks) {
-            if (taskIds.has(task.id)) {
-                errors.push({
-                    type: "duplicate_task",
-                    message: `Duplicate task detected with ID: ${task.id}`,
-                    details: { taskId: task.id }
-                });
-            } else {
-                taskIds.add(task.id);
-            }
-        }
+  /**
+   * Validates a given task graph for structural integrity.
+   * Checks for:
+   * 1. Duplicate task IDs.
+   * 2. Missing dependencies (tasks that depend on non-existent IDs).
+   * 3. Circular dependencies (cycles in the graph).
+   *
+   * @param taskGraph The task graph to validate.
+   * @returns A ValidationResult object indicating the outcome of the validation.
+   */
+  validate(taskGraph: TaskGraph): ValidationResult {
+    const errors: ValidationError[] = [];
+
+    // 1. Check for duplicate tasks
+    const taskIds = new Set<string>();
+    for (const task of taskGraph.tasks) {
+      if (taskIds.has(task.id)) {
+        errors.push({
+          type: "duplicate_task",
+          message: `Duplicate task detected with ID: ${task.id}`,
+          details: { taskId: task.id },
+        });
+      } else {
+        taskIds.add(task.id);
+      }
+    }
 
-        // 2. Check for missing dependencies
-        for (const task of taskGraph.tasks) {
-            for (const dependenceId of task.dependencies) {
-                if (!taskIds.has(dependenceId)) {
-                    errors.push({
-                        type: "missing_dependency",
-                        message: `Task '${task.id}' depends on missing task '${dependenceId}'`,
-                        details: { taskId: task.id, missingDependencyId: dependenceId }
-                    });
-                }
-            }
+    // 2. Check for missing dependencies
+    for (const task of taskGraph.tasks) {
+      for (const dependenceId of task.dependencies) {
+        if (!taskIds.has(dependenceId)) {
+          errors.push({
+            type: "missing_dependency",
+            message: `Task '${task.id}' depends on missing task '${dependenceId}'`,
+            details: { taskId: task.id, missingDependencyId: dependenceId },
+          });
         }
+      }
+    }
 
-        // 3. Check for cycles
-        // Only run cycle detection if there are no missing dependencies, otherwise we might chase non-existent nodes.
-        const hasMissingDependencies = errors.some(e => e.type === "missing_dependency");
+    // 3. Check for cycles
+    // Only run cycle detection if there are no missing dependencies, otherwise we might chase non-existent nodes.
+    const hasMissingDependencies = errors.some(
+      (e) => e.type === "missing_dependency"
+    );
+
+    if (hasMissingDependencies) {
+      return {
+        isValid: errors.length === 0,
+        errors,
+      };
+    }
 
-        if (hasMissingDependencies) {
-            return {
-                isValid: errors.length === 0,
-                errors
-            };
-        }
+    // Build adjacency list
+    const adjacencyList = new Map<string, string[]>();
+    for (const task of taskGraph.tasks) {
+      adjacencyList.set(task.id, task.dependencies);
+    }
 
-        // Build adjacency list
-        const adjacencyList = new Map<string, string[]>();
-        for (const task of taskGraph.tasks) {
-            adjacencyList.set(task.id, task.dependencies);
-        }
+    const visited = new Set<string>();
+    const recursionStack = new Set<string>();
+
+    for (const task of taskGraph.tasks) {
+      if (visited.has(task.id)) {
+        continue;
+      }
+
+      const path: string[] = [];
+      if (
+        this.detectCycle(task.id, path, visited, recursionStack, adjacencyList)
+      ) {
+        // Extract the actual cycle from the path
+        // The path might look like A -> B -> C -> B (if we started at A and found cycle B-C-B)
+        const cycleStart = path[path.length - 1];
+        const cycleStartIndex = path.indexOf(cycleStart);
+        const cyclePath = path.slice(cycleStartIndex);
+
+        errors.push({
+          type: "cycle",
+          message: `Cycle detected: ${cyclePath.join(" -> ")}`,
+          details: { cyclePath },
+        });
+        // Break after first cycle found to avoid spamming similar errors
+        break;
+      }
+    }
 
-        const visited = new Set<string>();
-        const recursionStack = new Set<string>();
-
-        for (const task of taskGraph.tasks) {
-            if (visited.has(task.id)) {
-                continue;
-            }
-
-            const path: string[] = [];
-            if (this.detectCycle(task.id, path, visited, recursionStack, adjacencyList)) {
-                // Extract the actual cycle from the path
-                // The path might look like A -> B -> C -> B (if we started at A and found cycle B-C-B)
-                const cycleStart = path[path.length - 1];
-                const cycleStartIndex = path.indexOf(cycleStart);
-                const cyclePath = path.slice(cycleStartIndex);
-
-                errors.push({
-                    type: "cycle",
-                    message: `Cycle detected: ${cyclePath.join(" -> ")}`,
-                    details: { cyclePath }
-                });
-                // Break after first cycle found to avoid spamming similar errors
-                break;
-            }
+    return {
+      isValid: errors.length === 0,
+      errors,
+    };
+  }
+
+  /**
+   * Creates a human-readable error message from a validation result.
+   * @param result The validation result containing errors.
+   * @returns A formatted error string.
+   */
+  createErrorMessage(result: ValidationResult): string {
+    const errorDetails = result.errors.map((e) => e.message);
+    return `Task graph validation failed: ${errorDetails.join("; ")}`;
+  }
+
+  private detectCycle(
+    startTaskId: string,
+    path: string[],
+    visited: Set<string>,
+    recursionStack: Set<string>,
+    adjacencyList: Map<string, string[]>
+  ): boolean {
+    // Use an explicit stack to avoid maximum call stack size exceeded errors
+    const stack: { taskId: string; index: number; dependencies: string[] }[] =
+      [];
+
+    visited.add(startTaskId);
+    recursionStack.add(startTaskId);
+    path.push(startTaskId);
+
+    stack.push({
+      taskId: startTaskId,
+      index: 0,
+      /* v8 ignore next */
+      dependencies: adjacencyList.get(startTaskId) ?? [],
+    });
+
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      const { taskId, dependencies } = frame;
+
+      if (frame.index < dependencies.length) {
+        const dependenceId = dependencies[frame.index];
+        frame.index++;
+
+        if (recursionStack.has(dependenceId)) {
+          // Cycle detected
+          path.push(dependenceId);
+          return true;
         }
 
-        return {
-            isValid: errors.length === 0,
-            errors
-        };
-    }
-
-    /**
-     * Creates a human-readable error message from a validation result.
-     * @param result The validation result containing errors.
-     * @returns A formatted error string.
-     */
-    createErrorMessage(result: ValidationResult): string {
-        const errorDetails = result.errors.map(e => e.message);
-        return `Task graph validation failed: ${errorDetails.join("; ")}`;
-    }
+        if (!visited.has(dependenceId)) {
+          visited.add(dependenceId);
+          recursionStack.add(dependenceId);
+          path.push(dependenceId);
 
-    private detectCycle(
-        startTaskId: string,
-        path: string[],
-        visited: Set<string>,
-        recursionStack: Set<string>,
-        adjacencyList: Map<string, string[]>
-    ): boolean {
-        // Use an explicit stack to avoid maximum call stack size exceeded errors
-        const stack: { taskId: string; index: number; dependencies: string[] }[] = [];
-
-        visited.add(startTaskId);
-        recursionStack.add(startTaskId);
-        path.push(startTaskId);
-
-        stack.push({
-            taskId: startTaskId,
+          stack.push({
+            taskId: dependenceId,
             index: 0,
             /* v8 ignore next */
-            dependencies: adjacencyList.get(startTaskId) ?? []
-        });
-
-        while (stack.length > 0) {
-            const frame = stack[stack.length - 1];
-            const { taskId, dependencies } = frame;
-
-            if (frame.index < dependencies.length) {
-                const dependenceId = dependencies[frame.index];
-                frame.index++;
-
-                if (recursionStack.has(dependenceId)) {
-                    // Cycle detected
-                    path.push(dependenceId);
-                    return true;
-                }
-
-                if (!visited.has(dependenceId)) {
-                    visited.add(dependenceId);
-                    recursionStack.add(dependenceId);
-                    path.push(dependenceId);
-
-                    stack.push({
-                        taskId: dependenceId,
-                        index: 0,
-                        /* v8 ignore next */
-                        dependencies: adjacencyList.get(dependenceId) ?? []
-                    });
-                }
-            } else {
-                // Finished all dependencies for this node
-                recursionStack.delete(taskId);
-                path.pop();
-                stack.pop();
-            }
+            dependencies: adjacencyList.get(dependenceId) ?? [],
+          });
         }
-
-        return false;
+      } else {
+        // Finished all dependencies for this node
+        recursionStack.delete(taskId);
+        path.pop();
+        stack.pop();
+      }
     }
+
+    return false;
+  }
 }

package/src/TaskRunner.ts

@@ -2,11 +2,15 @@ import { TaskStep } from "./TaskStep.js";
 import { TaskResult } from "./TaskResult.js";
 import { TaskGraphValidator } from "./TaskGraphValidator.js";
 import { TaskGraph } from "./TaskGraph.js";
-import { RunnerEventPayloads, RunnerEventListener } from "./contracts/RunnerEvents.js";
+import {
+  RunnerEventPayloads,
+  RunnerEventListener,
+} from "./contracts/RunnerEvents.js";
 import { EventBus } from "./EventBus.js";
 import { WorkflowExecutor } from "./WorkflowExecutor.js";
 import { TaskRunnerExecutionConfig } from "./TaskRunnerExecutionConfig.js";
 import { TaskStateManager } from "./TaskStateManager.js";
+import { TaskGraphValidationError } from "./TaskGraphValidationError.js";
 import { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
 import { StandardExecutionStrategy } from "./strategies/StandardExecutionStrategy.js";
 import { RetryingExecutionStrategy } from "./strategies/RetryingExecutionStrategy.js";
@@ -23,9 +27,8 @@ export { RunnerEventPayloads, RunnerEventListener, TaskRunnerExecutionConfig };
 export class TaskRunner<TContext> {
   private eventBus = new EventBus<TContext>();
   private validator = new TaskGraphValidator();
-  private executionStrategy: IExecutionStrategy<TContext> = new RetryingExecutionStrategy(
-    new StandardExecutionStrategy()
-  );
+  private executionStrategy: IExecutionStrategy<TContext> =
+    new RetryingExecutionStrategy(new StandardExecutionStrategy());
 
   /**
    * @param context The shared context object to be passed to each task.
@@ -84,7 +87,6 @@ export class TaskRunner<TContext> {
     const safeId = (name: string) => JSON.stringify(name);
     const sanitize = (name: string) => this.sanitizeMermaidId(name);
 
-
     // Add all nodes first to ensure they exist
     for (const step of steps) {
       // Using the name as both ID and Label for simplicity
@@ -97,9 +99,7 @@ export class TaskRunner<TContext> {
     for (const step of steps) {
       if (step.dependencies) {
         for (const dep of step.dependencies) {
-          graphLines.push(
-            `  ${sanitize(dep)} --> ${sanitize(step.name)}`
-          );
+          graphLines.push(`  ${sanitize(dep)} --> ${sanitize(step.name)}`);
         }
       }
     }
@@ -138,7 +138,10 @@ export class TaskRunner<TContext> {
 
     const validationResult = this.validator.validate(taskGraph);
     if (!validationResult.isValid) {
-      throw new Error(this.validator.createErrorMessage(validationResult));
+      throw new TaskGraphValidationError(
+        validationResult,
+        this.validator.createErrorMessage(validationResult)
+      );
     }
 
     const stateManager = new TaskStateManager(this.eventBus);
@@ -158,40 +161,42 @@ export class TaskRunner<TContext> {
 
     // We need to handle the timeout cleanup properly.
     if (config?.timeout !== undefined) {
-       const controller = new AbortController();
-       const timeoutId = setTimeout(() => {
-         controller.abort(new Error(`Workflow timed out after ${config.timeout}ms`));
-       }, config.timeout);
-
-       let effectiveSignal = controller.signal;
-       let onAbort: (() => void) | undefined;
-
-       // Handle combination of signals if user provided one
-       if (config.signal) {
-          if (config.signal.aborted) {
-             // If already aborted, use it directly (WorkflowExecutor handles early abort)
-             // We can cancel timeout immediately
-             clearTimeout(timeoutId);
-             effectiveSignal = config.signal;
-          } else {
-             // Listen to user signal to abort our controller
-             onAbort = () => {
-                controller.abort(config.signal?.reason);
-             };
-             config.signal.addEventListener("abort", onAbort);
-          }
-       }
-
-       try {
-         return await executor.execute(steps, effectiveSignal);
-       } finally {
-         clearTimeout(timeoutId);
-         if (config.signal && onAbort) {
-            config.signal.removeEventListener("abort", onAbort);
-         }
-       }
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => {
+        controller.abort(
+          new Error(`Workflow timed out after ${config.timeout}ms`)
+        );
+      }, config.timeout);
+
+      let effectiveSignal = controller.signal;
+      let onAbort: (() => void) | undefined;
+
+      // Handle combination of signals if user provided one
+      if (config.signal) {
+        if (config.signal.aborted) {
+          // If already aborted, use it directly (WorkflowExecutor handles early abort)
+          // We can cancel timeout immediately
+          clearTimeout(timeoutId);
+          effectiveSignal = config.signal;
+        } else {
+          // Listen to user signal to abort our controller
+          onAbort = () => {
+            controller.abort(config.signal?.reason);
+          };
+          config.signal.addEventListener("abort", onAbort);
+        }
+      }
+
+      try {
+        return await executor.execute(steps, effectiveSignal);
+      } finally {
+        clearTimeout(timeoutId);
+        if (config.signal && onAbort) {
+          config.signal.removeEventListener("abort", onAbort);
+        }
+      }
     } else {
-       return executor.execute(steps, config?.signal);
+      return executor.execute(steps, config?.signal);
     }
   }
 }

package/src/TaskRunnerBuilder.ts

@@ -1,5 +1,8 @@
 import { TaskRunner } from "./TaskRunner.js";
-import { RunnerEventPayloads, RunnerEventListener } from "./contracts/RunnerEvents.js";
+import {
+  RunnerEventPayloads,
+  RunnerEventListener,
+} from "./contracts/RunnerEvents.js";
 import { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
 
 /**
@@ -9,7 +12,10 @@ export class TaskRunnerBuilder<TContext> {
   private context: TContext;
   private strategy?: IExecutionStrategy<TContext>;
   private listeners: {
-    [K in keyof RunnerEventPayloads<TContext>]?: RunnerEventListener<TContext, K>[];
+    [K in keyof RunnerEventPayloads<TContext>]?: RunnerEventListener<
+      TContext,
+      K
+    >[];
   } = {};
 
   /**
@@ -57,7 +63,9 @@ export class TaskRunnerBuilder<TContext> {
       runner.setExecutionStrategy(this.strategy);
     }
 
-    (Object.keys(this.listeners) as Array<keyof RunnerEventPayloads<TContext>>).forEach((event) => {
+    (
+      Object.keys(this.listeners) as Array<keyof RunnerEventPayloads<TContext>>
+    ).forEach((event) => {
       const callbacks = this.listeners[event];
       // callbacks is always defined because we are iterating keys of the object
       callbacks!.forEach((callback) =>

package/src/WorkflowExecutor.ts

@@ -41,7 +41,9 @@ export class WorkflowExecutor<TContext> {
 
     // Check if already aborted
     if (signal?.aborted) {
-      this.stateManager.cancelAllPending("Workflow cancelled before execution started.");
+      this.stateManager.cancelAllPending(
+        "Workflow cancelled before execution started."
+      );
       const results = this.stateManager.getResults();
       this.eventBus.emit("workflowEnd", { context: this.context, results });
       return results;
@@ -55,7 +57,7 @@ export class WorkflowExecutor<TContext> {
     };
 
     if (signal) {
-       signal.addEventListener("abort", onAbort);
+      signal.addEventListener("abort", onAbort);
     }
 
     try {
@@ -77,10 +79,10 @@ export class WorkflowExecutor<TContext> {
         }
 
         if (signal?.aborted) {
-           this.stateManager.cancelAllPending("Workflow cancelled.");
+          this.stateManager.cancelAllPending("Workflow cancelled.");
         } else {
-           // After a task finishes, check for new work
-           this.processLoop(executingPromises, signal);
+          // After a task finishes, check for new work
+          this.processLoop(executingPromises, signal);
         }
       }
 
@@ -124,14 +126,15 @@ export class WorkflowExecutor<TContext> {
 
       this.stateManager.markRunning(step);
 
-      const taskPromise = this.strategy.execute(step, this.context, signal)
+      const taskPromise = this.strategy
+        .execute(step, this.context, signal)
         .then((result) => {
-            this.stateManager.markCompleted(step, result);
+          this.stateManager.markCompleted(step, result);
         })
         .finally(() => {
-             executingPromises.delete(taskPromise);
-             // When a task finishes, we try to run more
-             this.processLoop(executingPromises, signal);
+          executingPromises.delete(taskPromise);
+          // When a task finishes, we try to run more
+          this.processLoop(executingPromises, signal);
         });
 
       executingPromises.add(taskPromise);

package/src/contracts/ITaskGraphValidator.ts

@@ -5,17 +5,17 @@ import { ValidationResult } from "./ValidationResult.js";
  * Defines the interface for a task graph validator.
  */
 export interface ITaskGraphValidator {
-    /**
-     * Validates a given task graph for structural integrity.
-     * @param taskGraph The task graph to validate.
-     * @returns A ValidationResult object indicating the outcome of the validation.
-     */
-    validate(taskGraph: TaskGraph): ValidationResult;
+  /**
+   * Validates a given task graph for structural integrity.
+   * @param taskGraph The task graph to validate.
+   * @returns A ValidationResult object indicating the outcome of the validation.
+   */
+  validate(taskGraph: TaskGraph): ValidationResult;
 
-    /**
-     * Creates a human-readable error message from a validation result.
-     * @param result The validation result containing errors.
-     * @returns A formatted error string.
-     */
-    createErrorMessage(result: ValidationResult): string;
+  /**
+   * Creates a human-readable error message from a validation result.
+   * @param result The validation result containing errors.
+   * @returns A formatted error string.
+   */
+  createErrorMessage(result: ValidationResult): string;
 }

package/src/contracts/ValidationError.ts

@@ -2,10 +2,10 @@
  * Describes a specific validation error found in the task graph.
  */
 export interface ValidationError {
-    /** The type of validation error. */
-    type: "cycle" | "missing_dependency" | "duplicate_task";
-    /** A human-readable message describing the error. */
-    message: string;
-    /** Optional detailed information about the error, e.g., the cycle path, or the task with a missing dependency. */
-    details?: unknown;
+  /** The type of validation error. */
+  type: "cycle" | "missing_dependency" | "duplicate_task";
+  /** A human-readable message describing the error. */
+  message: string;
+  /** Optional detailed information about the error, e.g., the cycle path, or the task with a missing dependency. */
+  details?: unknown;
 }