@calmo/task-runner 1.2.1 → 1.2.2

package/dist/WorkflowExecutor.js

@@ -0,0 +1,89 @@
+/**
+ * Handles the execution of the workflow steps.
+ * @template TContext The shape of the shared context object.
+ */
+export class WorkflowExecutor {
+    context;
+    eventBus;
+    running = new Set();
+    /**
+     * @param context The shared context object.
+     * @param eventBus The event bus to emit events.
+     */
+    constructor(context, eventBus) {
+        this.context = context;
+        this.eventBus = eventBus;
+    }
+    /**
+     * Executes the given steps.
+     * @param steps The list of steps to execute.
+     * @returns A Promise that resolves to a map of task results.
+     */
+    async execute(steps) {
+        this.eventBus.emit("workflowStart", { context: this.context, steps });
+        const results = new Map();
+        const executingPromises = new Set();
+        // Helper to process pending steps and launch ready ones
+        const processPendingSteps = () => {
+            const pendingSteps = steps.filter((step) => !results.has(step.name) && !this.running.has(step.name));
+            // 1. Identify and mark skipped tasks
+            for (const step of pendingSteps) {
+                const deps = step.dependencies ?? [];
+                const failedDep = deps.find((dep) => results.has(dep) && results.get(dep)?.status !== "success");
+                if (failedDep) {
+                    const result = {
+                        status: "skipped",
+                        message: `Skipped due to failed dependency: ${failedDep}`,
+                    };
+                    results.set(step.name, result);
+                    this.eventBus.emit("taskSkipped", { step, result });
+                }
+            }
+            // Re-filter pending steps as some might have been skipped above
+            const readySteps = steps.filter((step) => {
+                if (results.has(step.name) || this.running.has(step.name))
+                    return false;
+                const deps = step.dependencies ?? [];
+                return deps.every((dep) => results.has(dep) && results.get(dep)?.status === "success");
+            });
+            // 2. Launch ready tasks
+            for (const step of readySteps) {
+                this.running.add(step.name);
+                this.eventBus.emit("taskStart", { step });
+                const taskPromise = (async () => {
+                    try {
+                        const result = await step.run(this.context);
+                        results.set(step.name, result);
+                    }
+                    catch (e) {
+                        results.set(step.name, {
+                            status: "failure",
+                            error: e instanceof Error ? e.message : String(e),
+                        });
+                    }
+                    finally {
+                        this.running.delete(step.name);
+                        const result = results.get(step.name);
+                        this.eventBus.emit("taskEnd", { step, result });
+                    }
+                })();
+                // Wrap the task promise to ensure we can track it in the Set
+                const trackedPromise = taskPromise.then(() => {
+                    executingPromises.delete(trackedPromise);
+                });
+                executingPromises.add(trackedPromise);
+            }
+        };
+        // Initial check to start independent tasks
+        processPendingSteps();
+        while (results.size < steps.length && executingPromises.size > 0) {
+            // Wait for the next task to finish
+            await Promise.race(executingPromises);
+            // After a task finishes, check for new work
+            processPendingSteps();
+        }
+        this.eventBus.emit("workflowEnd", { context: this.context, results });
+        return results;
+    }
+}
+//# sourceMappingURL=WorkflowExecutor.js.map

package/dist/WorkflowExecutor.js.map

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

package/dist/contracts/RunnerEvents.d.ts

@@ -0,0 +1,36 @@
+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.
+ */
+export type ListenerMap<TContext> = {
+    [K in keyof RunnerEventPayloads<TContext>]?: Set<RunnerEventListener<TContext, K>>;
+};

package/dist/contracts/RunnerEvents.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=RunnerEvents.js.map

package/dist/contracts/RunnerEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunnerEvents.js","sourceRoot":"","sources":["../../src/contracts/RunnerEvents.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calmo/task-runner",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "",
   "repository": {
     "type": "git",

package/src/EventBus.ts

@@ -0,0 +1,84 @@
+import {
+  ListenerMap,
+  RunnerEventListener,
+  RunnerEventPayloads,
+} from "./contracts/RunnerEvents.js";
+
+/**
+ * Manages event subscriptions and emissions for the TaskRunner.
+ * @template TContext The shape of the shared context object.
+ */
+export class EventBus<TContext> {
+  private listeners: ListenerMap<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.
+   */
+  public 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 {
+          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
+          );
+        }
+      }
+    }
+  }
+}

package/src/TaskRunner.ts

@@ -2,48 +2,12 @@ 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 { EventBus } from "./EventBus.js";
+import { WorkflowExecutor } from "./WorkflowExecutor.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>
-  >;
-};
+// Re-export types for backward compatibility
+export { RunnerEventPayloads, RunnerEventListener };
 
 /**
  * The main class that orchestrates the execution of a list of tasks
@@ -51,8 +15,7 @@ type ListenerMap<TContext> = {
  * @template TContext The shape of the shared context object.
  */
 export class TaskRunner<TContext> {
-  private running = new Set<string>();
-  private listeners: ListenerMap<TContext> = {};
+  private eventBus = new EventBus<TContext>();
   private validator = new TaskGraphValidator();
 
   /**
@@ -69,15 +32,7 @@ export class TaskRunner<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
-    );
+    this.eventBus.on(event, callback);
   }
 
   /**
@@ -89,38 +44,7 @@ export class TaskRunner<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
-          );
-        }
-      }
-    }
+    this.eventBus.off(event, callback);
   }
 
   /**
@@ -178,82 +102,7 @@ export class TaskRunner<TContext> {
       throw new Error(`${legacyMessage} | ${detailedMessage}`);
     }
 
-    this.emit("workflowStart", { context: this.context, steps });
-
-    const results = new Map<string, TaskResult>();
-    const executingPromises = new Set<Promise<void>>();
-
-    // Helper to process pending steps and launch ready ones
-    const processPendingSteps = () => {
-      const pendingSteps = steps.filter(
-        (step) => !results.has(step.name) && !this.running.has(step.name)
-      );
-
-      // 1. Identify and mark skipped tasks
-      for (const step of pendingSteps) {
-        const deps = step.dependencies ?? [];
-        const failedDep = deps.find(
-          (dep) => results.has(dep) && results.get(dep)?.status !== "success"
-        );
-        if (failedDep) {
-          const result: TaskResult = {
-            status: "skipped",
-            message: `Skipped due to failed dependency: ${failedDep}`,
-          };
-          results.set(step.name, result);
-          this.emit("taskSkipped", { step, result });
-        }
-      }
-
-      // Re-filter pending steps as some might have been skipped above
-      const readySteps = steps.filter((step) => {
-        if (results.has(step.name) || this.running.has(step.name)) return false;
-        const deps = step.dependencies ?? [];
-        return deps.every(
-          (dep) => results.has(dep) && results.get(dep)?.status === "success"
-        );
-      });
-
-      // 2. Launch ready tasks
-      for (const step of readySteps) {
-        this.running.add(step.name);
-        this.emit("taskStart", { step });
-
-        const taskPromise = (async () => {
-          try {
-            const result = await step.run(this.context);
-            results.set(step.name, result);
-          } catch (e) {
-            results.set(step.name, {
-              status: "failure",
-              error: e instanceof Error ? e.message : String(e),
-            });
-          } finally {
-            this.running.delete(step.name);
-            const result = results.get(step.name)!;
-            this.emit("taskEnd", { step, result });
-          }
-        })();
-
-        // Wrap the task promise to ensure we can track it in the Set
-        const trackedPromise = taskPromise.then(() => {
-          executingPromises.delete(trackedPromise);
-        });
-        executingPromises.add(trackedPromise);
-      }
-    };
-
-    // Initial check to start independent tasks
-    processPendingSteps();
-
-    while (results.size < steps.length && executingPromises.size > 0) {
-      // Wait for the next task to finish
-      await Promise.race(executingPromises);
-      // After a task finishes, check for new work
-      processPendingSteps();
-    }
-
-    this.emit("workflowEnd", { context: this.context, results });
-    return results;
+    const executor = new WorkflowExecutor(this.context, this.eventBus);
+    return executor.execute(steps);
   }
 }

package/src/WorkflowExecutor.ts

@@ -0,0 +1,105 @@
+import { TaskStep } from "./TaskStep.js";
+import { TaskResult } from "./TaskResult.js";
+import { EventBus } from "./EventBus.js";
+
+/**
+ * Handles the execution of the workflow steps.
+ * @template TContext The shape of the shared context object.
+ */
+export class WorkflowExecutor<TContext> {
+  private running = new Set<string>();
+
+  /**
+   * @param context The shared context object.
+   * @param eventBus The event bus to emit events.
+   */
+  constructor(
+    private context: TContext,
+    private eventBus: EventBus<TContext>
+  ) {}
+
+  /**
+   * Executes the given steps.
+   * @param steps The list of steps to execute.
+   * @returns A Promise that resolves to a map of task results.
+   */
+  async execute(steps: TaskStep<TContext>[]): Promise<Map<string, TaskResult>> {
+    this.eventBus.emit("workflowStart", { context: this.context, steps });
+
+    const results = new Map<string, TaskResult>();
+    const executingPromises = new Set<Promise<void>>();
+
+    // Helper to process pending steps and launch ready ones
+    const processPendingSteps = () => {
+      const pendingSteps = steps.filter(
+        (step) => !results.has(step.name) && !this.running.has(step.name)
+      );
+
+      // 1. Identify and mark skipped tasks
+      for (const step of pendingSteps) {
+        const deps = step.dependencies ?? [];
+        const failedDep = deps.find(
+          (dep) => results.has(dep) && results.get(dep)?.status !== "success"
+        );
+        if (failedDep) {
+          const result: TaskResult = {
+            status: "skipped",
+            message: `Skipped due to failed dependency: ${failedDep}`,
+          };
+          results.set(step.name, result);
+          this.eventBus.emit("taskSkipped", { step, result });
+        }
+      }
+
+      // Re-filter pending steps as some might have been skipped above
+      const readySteps = steps.filter((step) => {
+        if (results.has(step.name) || this.running.has(step.name)) return false;
+        const deps = step.dependencies ?? [];
+        return deps.every(
+          (dep) => results.has(dep) && results.get(dep)?.status === "success"
+        );
+      });
+
+      // 2. Launch ready tasks
+      for (const step of readySteps) {
+        this.running.add(step.name);
+        this.eventBus.emit("taskStart", { step });
+
+        const taskPromise = (async () => {
+          try {
+            const result = await step.run(this.context);
+            results.set(step.name, result);
+          } catch (e) {
+            results.set(step.name, {
+              status: "failure",
+              error: e instanceof Error ? e.message : String(e),
+            });
+          } finally {
+            this.running.delete(step.name);
+            const result = results.get(step.name)!;
+            this.eventBus.emit("taskEnd", { step, result });
+          }
+        })();
+
+        // Wrap the task promise to ensure we can track it in the Set
+        const trackedPromise = taskPromise.then(() => {
+          executingPromises.delete(trackedPromise);
+        });
+        executingPromises.add(trackedPromise);
+      }
+    };
+
+    // Initial check to start independent tasks
+    processPendingSteps();
+
+    while (results.size < steps.length && executingPromises.size > 0) {
+      // Wait for the next task to finish
+      await Promise.race(executingPromises);
+      // After a task finishes, check for new work
+      processPendingSteps();
+    }
+
+    this.eventBus.emit("workflowEnd", { context: this.context, results });
+    return results;
+  }
+}

package/src/contracts/RunnerEvents.ts

@@ -0,0 +1,44 @@
+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.
+ */
+export type ListenerMap<TContext> = {
+  [K in keyof RunnerEventPayloads<TContext>]?: Set<
+    RunnerEventListener<TContext, K>
+  >;
+};