@calmo/task-runner 4.1.0 → 4.3.0

package/src/TaskRunner.ts

@@ -14,11 +14,10 @@ import { TaskGraphValidationError } from "./TaskGraphValidationError.js";
 import { IExecutionStrategy } from "./strategies/IExecutionStrategy.js";
 import { StandardExecutionStrategy } from "./strategies/StandardExecutionStrategy.js";
 import { RetryingExecutionStrategy } from "./strategies/RetryingExecutionStrategy.js";
+import { Plugin } from "./contracts/Plugin.js";
+import { PluginManager } from "./PluginManager.js";
 import { DryRunExecutionStrategy } from "./strategies/DryRunExecutionStrategy.js";
 
-// Re-export types for backward compatibility
-export { RunnerEventPayloads, RunnerEventListener, TaskRunnerExecutionConfig };
-
 /**
  * The main class that orchestrates the execution of a list of tasks
  * based on their dependencies, with support for parallel execution.
@@ -30,10 +29,14 @@ export class TaskRunner<TContext> {
   private executionStrategy: IExecutionStrategy<TContext> =
     new RetryingExecutionStrategy(new StandardExecutionStrategy());
 
+  private pluginManager: PluginManager<TContext>;
+
   /**
    * @param context The shared context object to be passed to each task.
    */
-  constructor(private context: TContext) {}
+  constructor(private context: TContext) {
+    this.pluginManager = new PluginManager({ events: this.eventBus });
+  }
 
   /**
    * Subscribe to an event.
@@ -56,17 +59,25 @@ export class TaskRunner<TContext> {
     event: K,
     callback: RunnerEventListener<TContext, K>
   ): void {
-    /* v8 ignore next 1 */
     this.eventBus.off(event, callback);
   }
 
+  /**
+   * Registers a plugin.
+   * @param plugin The plugin to register.
+   * @returns The TaskRunner instance for chaining.
+   */
+  public use(plugin: Plugin<TContext>): this {
+    this.pluginManager.use(plugin);
+    return this;
+  }
+
   /**
    * Sets the execution strategy to be used.
    * @param strategy The execution strategy.
    * @returns The TaskRunner instance for chaining.
    */
   public setExecutionStrategy(strategy: IExecutionStrategy<TContext>): this {
-    /* v8 ignore next 2 */
     this.executionStrategy = strategy;
     return this;
   }
@@ -77,14 +88,16 @@ export class TaskRunner<TContext> {
    * @returns A string containing the Mermaid graph definition.
    */
   public static getMermaidGraph<T>(steps: TaskStep<T>[]): string {
-    const graphLines = ["graph TD"];
+    const nodeLines: string[] = ["graph TD"];
+    const edgeLines = new Set<string>();
     const idMap = new Map<string, string>();
     const usedIds = new Set<string>();
     const baseIdCounters = new Map<string, number>();
 
     const getUniqueId = (name: string) => {
-      if (idMap.has(name)) {
-        return idMap.get(name)!;
+      const existingId = idMap.get(name);
+      if (existingId !== undefined) {
+        return existingId;
       }
 
       const sanitized = this.sanitizeMermaidId(name);
@@ -112,30 +125,31 @@ export class TaskRunner<TContext> {
       return uniqueId;
     };
 
-    // Pre-calculate IDs for all steps to ensure stable generation order
-    // We sort steps by name to ensure deterministic ID generation regardless of input order if names clash
-    // But input order is usually significant in graph definition, so we'll stick to input order.
-    // However, we must process all step NAMES first.
-    for (const step of steps) {
-      getUniqueId(step.name);
-    }
+    // Process nodes and edges in a single pass over input steps
+    const processedNodes = new Set<string>();
+    for (let i = 0; i < steps.length; i++) {
+      const step = steps[i];
+      const name = step.name;
+      const stepId = getUniqueId(name);
 
-    for (const step of steps) {
-      const stepId = getUniqueId(step.name);
-      graphLines.push(`  ${stepId}[${JSON.stringify(step.name)}]`);
-    }
+      const sizeBefore = processedNodes.size;
+      processedNodes.add(stepId);
+
+      if (processedNodes.size !== sizeBefore) {
+        const escapedName = name.replaceAll("\"", "&quot;");
+        nodeLines.push(`  ${stepId}["${escapedName}"]`);
+      }
 
-    for (const step of steps) {
       if (step.dependencies) {
-        const stepId = getUniqueId(step.name);
-        for (const dep of step.dependencies) {
-          const depId = getUniqueId(dep);
-          graphLines.push(`  ${depId} --> ${stepId}`);
+        const deps = step.dependencies;
+        for (let j = 0; j < deps.length; j++) {
+          const depId = getUniqueId(deps[j]);
+          edgeLines.add(`  ${depId} --> ${stepId}`);
         }
       }
     }
 
-    return [...new Set(graphLines)].join("\n");
+    return nodeLines.concat([...edgeLines]).join("\n");
   }
 
   /**
@@ -159,6 +173,9 @@ export class TaskRunner<TContext> {
     steps: TaskStep<TContext>[],
     config?: TaskRunnerExecutionConfig
   ): Promise<Map<string, TaskResult>> {
+    // Initialize plugins
+    await this.pluginManager.initialize();
+
     // Validate the task graph before execution
     const taskGraph: TaskGraph = {
       tasks: steps.map((step) => ({
@@ -197,9 +214,9 @@ export class TaskRunner<TContext> {
         config.timeout,
         config.signal
       );
-    } else {
-      return executor.execute(steps, config?.signal);
     }
+
+    return executor.execute(steps, config?.signal);
   }
 
   /**

package/src/TaskStateManager.ts

@@ -15,6 +15,7 @@ export class TaskStateManager<TContext> {
   private dependencyGraph = new Map<string, TaskStep<TContext>[]>();
   private dependencyCounts = new Map<string, number>();
   private readyQueue: TaskStep<TContext>[] = [];
+  private taskDefinitions = new Map<string, TaskStep<TContext>>();
 
   constructor(private eventBus: EventBus<TContext>) {}
 
@@ -30,8 +31,10 @@ export class TaskStateManager<TContext> {
 
     this.dependencyGraph.clear();
     this.dependencyCounts.clear();
+    this.taskDefinitions.clear();
 
     for (const step of steps) {
+      this.taskDefinitions.set(step.name, step);
       const deps = step.dependencies ?? [];
       this.dependencyCounts.set(step.name, deps.length);
 
@@ -39,10 +42,12 @@ export class TaskStateManager<TContext> {
         this.readyQueue.push(step);
       } else {
         for (const dep of deps) {
-          if (!this.dependencyGraph.has(dep)) {
-            this.dependencyGraph.set(dep, []);
+          let dependents = this.dependencyGraph.get(dep);
+          if (dependents === undefined) {
+            dependents = [];
+            this.dependencyGraph.set(dep, dependents);
           }
-          this.dependencyGraph.get(dep)!.push(step);
+          dependents.push(step);
         }
       }
     }
@@ -54,7 +59,7 @@ export class TaskStateManager<TContext> {
    * @returns An array of tasks that are ready to run.
    */
   processDependencies(): TaskStep<TContext>[] {
-    const toRun = [...this.readyQueue];
+    const toRun = this.readyQueue;
     this.readyQueue = [];
 
     // Remove them from pendingSteps as they are now handed off to the executor
@@ -87,6 +92,13 @@ export class TaskStateManager<TContext> {
 
     if (result.status === "success") {
       this.handleSuccess(step.name);
+    } else if (result.status === "failure") {
+      // If continueOnError is true, treat as success for dependents to unblock the workflow
+      if (this.taskDefinitions.get(step.name)?.continueOnError) {
+        this.handleSuccess(step.name);
+      } else {
+        this.cascadeFailure(step.name);
+      }
     } else {
       this.cascadeFailure(step.name);
     }
@@ -188,11 +200,13 @@ export class TaskStateManager<TContext> {
    */
   private cascadeFailure(failedStepName: string): void {
     const queue = [failedStepName];
+    // Optimization: Use index pointer instead of shift() to avoid O(N) array re-indexing
+    let head = 0;
     // Use a set to track visited nodes in this cascade pass to avoid redundant processing,
     // although checking results.has() in internalMarkSkipped also prevents it.
 
-    while (queue.length > 0) {
-      const currentName = queue.shift()!;
+    while (head < queue.length) {
+      const currentName = queue[head++];
       const dependents = this.dependencyGraph.get(currentName);
 
       if (!dependents) continue;

package/src/TaskStep.ts

@@ -25,6 +25,20 @@ export interface TaskStep<TContext> {
    */
   priority?: number;
 
+  /**
+   * Optional flag to indicate that the workflow should continue even if this task fails.
+   * If true, dependent tasks will execute as if this task succeeded.
+   * The task result will still be marked as "failure".
+   * Default is false.
+   */
+  continueOnError?: boolean;
+
+  /**
+   * Optional maximum execution time in milliseconds.
+   * If the task runs longer than this, it will be cancelled and marked as failed.
+   */
+  timeout?: number;
+
   /**
    * The core logic of the task.
    * @param context The shared context object, allowing for state to be passed between tasks.

package/src/WorkflowExecutor.ts

@@ -63,8 +63,22 @@ export class WorkflowExecutor<TContext> {
     }
 
     try {
+      // Create a signal mechanism to wait for any task completion
+      let signalResolver!: () => void;
+      let signalPromise = new Promise<void>((resolve) => {
+        signalResolver = resolve;
+      });
+
+      const signalWork = () => {
+        signalResolver();
+        // Reset the promise for the next wait
+        signalPromise = new Promise<void>((resolve) => {
+          signalResolver = resolve;
+        });
+      };
+
       // Initial pass
-      this.processLoop(executingPromises, signal);
+      this.processLoop(executingPromises, signalWork, signal);
 
       while (
         this.stateManager.hasPendingTasks() ||
@@ -78,16 +92,13 @@ export class WorkflowExecutor<TContext> {
           break;
         } else {
           // Wait for the next task to finish
-          await Promise.race(executingPromises);
+          await signalPromise;
         }
 
         if (signal?.aborted) {
           this.stateManager.cancelAllPending(
             ExecutionConstants.WORKFLOW_CANCELLED
           );
-        } else {
-          // After a task finishes, check for new work
-          this.processLoop(executingPromises, signal);
         }
       }
 
@@ -109,6 +120,7 @@ export class WorkflowExecutor<TContext> {
    */
   private processLoop(
     executingPromises: Set<Promise<void>>,
+    signalWork: () => void,
     signal?: AbortSignal
   ): void {
     const newlyReady = this.stateManager.processDependencies();
@@ -129,12 +141,13 @@ export class WorkflowExecutor<TContext> {
 
       const step = this.readyQueue.pop()!;
 
-      const taskPromise = this.executeTaskStep(step, signal)
-        .finally(() => {
-          executingPromises.delete(taskPromise);
-          // When a task finishes, we try to run more
-          this.processLoop(executingPromises, signal);
-        });
+      const taskPromise = this.executeTaskStep(step, signal).finally(() => {
+        executingPromises.delete(taskPromise);
+        // When a task finishes, we try to run more
+        this.processLoop(executingPromises, signalWork, signal);
+        // Signal that a task has completed
+        signalWork();
+      });
 
       executingPromises.add(taskPromise);
     }

package/src/contracts/Plugin.ts

@@ -0,0 +1,32 @@
+import { EventBus } from "../EventBus.js";
+
+/**
+ * Context provided to a plugin during installation.
+ * exposes capabilities to hook into the runner lifecycle and context.
+ */
+export interface PluginContext<TContext> {
+  /**
+   * The event bus instance to subscribe to runner events.
+   */
+  events: EventBus<TContext>;
+}
+
+/**
+ * Interface that all plugins must implement.
+ */
+export interface Plugin<TContext> {
+  /**
+   * Unique name of the plugin.
+   */
+  name: string;
+  /**
+   * Semantic version of the plugin.
+   */
+  version: string;
+  /**
+   * Called when the plugin is installed into the runner.
+   * This is where the plugin should subscribe to events or perform setup.
+   * @param context The plugin context exposing runner capabilities.
+   */
+  install(context: PluginContext<TContext>): void | Promise<void>;
+}

package/src/strategies/DryRunExecutionStrategy.ts

@@ -22,9 +22,9 @@ export class DryRunExecutionStrategy<
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     _signal?: AbortSignal
   ): Promise<TaskResult> {
-    return Promise.resolve({
+    return {
       status: "success",
       message: "Dry run: simulated success " + step.name,
-    });
+    };
   }
 }

package/src/strategies/StandardExecutionStrategy.ts

@@ -13,8 +13,51 @@ export class StandardExecutionStrategy<
     context: TContext,
     signal?: AbortSignal
   ): Promise<TaskResult> {
+    if (!step.timeout) {
+      try {
+        return await step.run(context, signal);
+      } catch (e) {
+        // Check if error is due to abort
+        if (
+          signal?.aborted &&
+          ((e instanceof Error && e.name === "AbortError") ||
+            signal.reason === e)
+        ) {
+          return {
+            status: "cancelled",
+            message: "Task cancelled during execution",
+          };
+        }
+        return {
+          status: "failure",
+          error: e instanceof Error ? e.message : String(e),
+        };
+      }
+    }
+
+    const abortController = new AbortController();
+    const timeoutSignal = signal
+      ? AbortSignal.any([signal, abortController.signal])
+      : abortController.signal;
+
+    let timer: NodeJS.Timeout | undefined;
+    let resolveTimeout!: (value: TaskResult) => void;
+
     try {
-      return await step.run(context, signal);
+      const timeoutPromise = new Promise<TaskResult>((resolve) => {
+        resolveTimeout = resolve;
+        timer = setTimeout(() => {
+          abortController.abort(new Error("Timeout"));
+          resolve({
+            status: "failure",
+            error: `Task timed out after ${step.timeout}ms`,
+          });
+        }, step.timeout);
+      });
+
+      const taskPromise = step.run(context, timeoutSignal);
+
+      return await Promise.race([taskPromise, timeoutPromise]);
     } catch (e) {
       // Check if error is due to abort
       if (
@@ -30,6 +73,10 @@ export class StandardExecutionStrategy<
         status: "failure",
         error: e instanceof Error ? e.message : String(e),
       };
+    } finally {
+      clearTimeout(timer);
+      // Settle the timeout promise to avoid memory leaks from Promise.race
+      resolveTimeout({ status: "cancelled" } as TaskResult);
     }
   }
 }