@calmo/task-runner 1.0.1 → 1.1.1

package/src/TaskRunner.ts

@@ -1,6 +1,48 @@
 import { TaskStep } from "./TaskStep.js";
 import { TaskResult } from "./TaskResult.js";
 
+/**
+ * Define the payload for every possible event in the lifecycle.
+ */
+export interface RunnerEventPayloads<TContext> {
+  workflowStart: {
+    context: TContext;
+    steps: TaskStep<TContext>[];
+  };
+  workflowEnd: {
+    context: TContext;
+    results: Map<string, TaskResult>;
+  };
+  taskStart: {
+    step: TaskStep<TContext>;
+  };
+  taskEnd: {
+    step: TaskStep<TContext>;
+    result: TaskResult;
+  };
+  taskSkipped: {
+    step: TaskStep<TContext>;
+    result: TaskResult;
+  };
+}
+
+/**
+ * A generic listener type that maps the event key to its specific payload.
+ */
+export type RunnerEventListener<
+  TContext,
+  K extends keyof RunnerEventPayloads<TContext>,
+> = (data: RunnerEventPayloads<TContext>[K]) => void | Promise<void>;
+
+/**
+ * Helper type for the listeners map to avoid private access issues in generic contexts.
+ */
+type ListenerMap<TContext> = {
+  [K in keyof RunnerEventPayloads<TContext>]?: Set<
+    RunnerEventListener<TContext, K>
+  >;
+};
+
 /**
  * The main class that orchestrates the execution of a list of tasks
  * based on their dependencies, with support for parallel execution.
@@ -8,12 +50,76 @@ import { TaskResult } from "./TaskResult.js";
  */
 export class TaskRunner<TContext> {
   private running = new Set<string>();
+  private listeners: ListenerMap<TContext> = {};
 
   /**
    * @param context The shared context object to be passed to each task.
    */
   constructor(private context: TContext) {}
 
+  /**
+   * Subscribe to an event.
+   * @param event The event name.
+   * @param callback The callback to execute when the event is emitted.
+   */
+  public on<K extends keyof RunnerEventPayloads<TContext>>(
+    event: K,
+    callback: RunnerEventListener<TContext, K>
+  ): void {
+    if (!this.listeners[event]) {
+      // Type assertion needed because TypeScript cannot verify that the generic K
+      // matches the specific key in the mapped type during assignment.
+      this.listeners[event] = new Set() as unknown as ListenerMap<TContext>[K];
+    }
+    // Type assertion needed to tell TS that this specific Set matches the callback type
+    (this.listeners[event] as Set<RunnerEventListener<TContext, K>>).add(
+      callback
+    );
+  }
+
+  /**
+   * Unsubscribe from an event.
+   * @param event The event name.
+   * @param callback The callback to remove.
+   */
+  public off<K extends keyof RunnerEventPayloads<TContext>>(
+    event: K,
+    callback: RunnerEventListener<TContext, K>
+  ): void {
+    if (this.listeners[event]) {
+      (this.listeners[event] as Set<RunnerEventListener<TContext, K>>).delete(
+        callback
+      );
+    }
+  }
+
+  /**
+   * Emit an event to all subscribers.
+   * @param event The event name.
+   * @param data The payload for the event.
+   */
+  private emit<K extends keyof RunnerEventPayloads<TContext>>(
+    event: K,
+    data: RunnerEventPayloads<TContext>[K]
+  ): void {
+    const listeners = this.listeners[event] as
+      | Set<RunnerEventListener<TContext, K>>
+      | undefined;
+    if (listeners) {
+      for (const listener of listeners) {
+        try {
+          listener(data);
+        } catch (error) {
+          // Prevent listener errors from bubbling up
+          console.error(
+            `Error in event listener for ${String(event)}:`,
+            error
+          );
+        }
+      }
+    }
+  }
+
   /**
    * Executes a list of tasks, respecting their dependencies and running
    * independent tasks in parallel.
@@ -22,6 +128,8 @@ export class TaskRunner<TContext> {
    * and values are the corresponding TaskResult objects.
    */
   async execute(steps: TaskStep<TContext>[]): Promise<Map<string, TaskResult>> {
+    this.emit("workflowStart", { context: this.context, steps });
+
     const results = new Map<string, TaskResult>();
 
     while (results.size < steps.length) {
@@ -44,10 +152,12 @@ export class TaskRunner<TContext> {
           (dep) => results.has(dep) && results.get(dep)?.status !== "success"
         );
         if (failedDep) {
-          results.set(step.name, {
+          const result: TaskResult = {
             status: "skipped",
             message: `Skipped due to failed dependency: ${failedDep}`,
-          });
+          };
+          results.set(step.name, result);
+          this.emit("taskSkipped", { step, result });
         }
       }
 
@@ -66,6 +176,7 @@ export class TaskRunner<TContext> {
       await Promise.all(
         readySteps.map(async (step) => {
           this.running.add(step.name);
+          this.emit("taskStart", { step });
           try {
             const result = await step.run(this.context);
             results.set(step.name, result);
@@ -76,11 +187,14 @@ export class TaskRunner<TContext> {
             });
           } finally {
             this.running.delete(step.name);
+            const result = results.get(step.name)!;
+            this.emit("taskEnd", { step, result });
           }
         })
       );
     }
 
+    this.emit("workflowEnd", { context: this.context, results });
     return results;
   }
 }

package/test-report.xml

@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<testsuites name="vitest tests" tests="19" failures="0" errors="0" time="0.135083259">
+    <testsuite name="tests/ComplexScenario.test.ts" timestamp="2026-01-18T03:50:46.197Z" hostname="runnervmmtnos" tests="2" failures="0" errors="0" skipped="0" time="0.009883356">
+        <testcase classname="tests/ComplexScenario.test.ts" name="Complex Scenario Integration Tests &gt; 1. All steps execute when all succeed and context is hydrated" time="0.006132912">
+            <system-out>
+Running StepA
+Running StepB
+Running StepC
+
+Running StepD
+Running StepF
+
+Running StepE
+Running StepG
+
+            </system-out>
+        </testcase>
+        <testcase classname="tests/ComplexScenario.test.ts" name="Complex Scenario Integration Tests &gt; 2. The &apos;skip&apos; propagation works as intended if something breaks up in the tree" time="0.00153012">
+        </testcase>
+    </testsuite>
+    <testsuite name="tests/TaskRunner.test.ts" timestamp="2026-01-18T03:50:46.199Z" hostname="runnervmmtnos" tests="10" failures="0" errors="0" skipped="0" time="0.109323687">
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should run tasks in the correct sequential order" time="0.002455516">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should handle an empty list of tasks gracefully" time="0.000305152">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should run independent tasks in parallel" time="0.100731975">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should skip dependent tasks if a root task fails" time="0.00046882">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should throw an error for &apos;circular dependency&apos;" time="0.00185594">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should throw an error for &apos;missing dependency&apos;" time="0.000228108">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should handle tasks that throw an error during execution" time="0.000243576">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should skip tasks whose dependencies are skipped" time="0.000262202">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should handle tasks that throw a non-Error object during execution" time="0.000268865">
+        </testcase>
+        <testcase classname="tests/TaskRunner.test.ts" name="TaskRunner &gt; should handle duplicate steps where one gets skipped due to failed dependency" time="0.00040515">
+        </testcase>
+    </testsuite>
+    <testsuite name="tests/TaskRunnerEvents.test.ts" timestamp="2026-01-18T03:50:46.201Z" hostname="runnervmmtnos" tests="7" failures="0" errors="0" skipped="0" time="0.015876216">
+        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should fire all lifecycle events in a successful run" time="0.004415742">
+        </testcase>
+        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should fire taskSkipped event when dependency fails" time="0.005824924">
+        </testcase>
+        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should not crash if a listener throws an error" time="0.001840071">
+        </testcase>
+        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should fire workflow events even for empty step list" time="0.000423804">
+        </testcase>
+        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should handle unsubscribe correctly" time="0.000460765">
+        </testcase>
+        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should safely handle off() when no listeners exist" time="0.000210355">
+        </testcase>
+        <testcase classname="tests/TaskRunnerEvents.test.ts" name="TaskRunner Events &gt; should support multiple listeners for the same event" time="0.000482585">
+        </testcase>
+    </testsuite>
+</testsuites>

package/tsconfig.test.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "."
+  },
+  "include": ["src/**/*", "tests/**/*"]
+}