@calmo/task-runner 3.4.0 → 3.5.0

package/README.md

@@ -13,30 +13,24 @@ A lightweight, type-safe, and domain-agnostic task orchestration engine. It reso
 - **Type-Safe Context**: Fully typed shared state using TypeScript Generics.
 - **Parallel Execution**: Automatically identifies and runs independent steps concurrently.
 - **Dependency Management**: Enforces execution order based on dependencies.
-- **Error Handling & Skipping**: robustly handles failures and automatically skips dependent steps.
-- **Event System**: Subscribe to lifecycle events (`workflowStart`, `taskStart`, `taskEnd`, etc.) for logging or monitoring.
-- **Runtime Validation**: Automatically detects circular dependencies and missing dependencies before execution loops.
-
-## Event System
-
-The `TaskRunner` implements an Observer Pattern, allowing you to subscribe to various lifecycle events.
-
-```typescript
-runner.on("taskStart", ({ step }) => {
-  console.log(`Starting step: ${step.name}`);
-});
-
-runner.on("taskEnd", ({ step, result }) => {
-  console.log(`Step ${step.name} finished with status: ${result.status}`);
-});
-```
+- **Automatic Retries**: Configurable retry logic for flaky tasks.
+- **Dry Run Mode**: Simulate workflow execution to verify dependency graphs.
+- **Visualization**: Generate Mermaid.js diagrams of your task graph.
+- **Event System**: Subscribe to lifecycle events for logging or monitoring.
+- **Runtime Validation**: Automatically detects circular dependencies and missing dependencies.
+- **Conditional Execution**: Skip tasks dynamically based on context state.
 
 ## Usage Example
 
-Here is a simple example showing how to define a context, create steps, and execute them.
+The library now provides a fluent `TaskRunnerBuilder` for easy configuration.
 
 ```typescript
-import { TaskRunner, TaskStep } from './src';
+import {
+  TaskRunnerBuilder,
+  TaskStep,
+  RetryingExecutionStrategy,
+  StandardExecutionStrategy
+} from "@calmo/task-runner";
 
 // 1. Define your domain-specific context
 interface ValidationContext {
@@ -49,48 +43,49 @@ interface ValidationContext {
 
 // 2. Define your steps
 const UrlFormatStep: TaskStep<ValidationContext> = {
-  name: 'UrlFormatStep',
+  name: "UrlFormatStep",
   run: async (ctx) => {
-    const valid = ctx.issueBody.includes('github.com');
-    return valid
-      ? { status: 'success' }
-      : { status: 'failure', error: 'Invalid URL' };
+    if (!ctx.issueBody.includes("github.com")) {
+      return { status: "failure", error: "Invalid URL" };
+    }
+    return { status: "success" };
   },
 };
 
 const DataLoaderStep: TaskStep<ValidationContext> = {
-  name: 'DataLoaderStep',
-  dependencies: ['UrlFormatStep'],
-  run: async (ctx) => {
-    // Simulate API call
-    ctx.prData = { additions: 20, ciStatus: 'success' };
-    return { status: 'success', message: 'Data fetched' };
+  name: "DataLoaderStep",
+  dependencies: ["UrlFormatStep"],
+  retry: {
+      attempts: 3,
+      delay: 1000,
+      backoff: "exponential"
   },
-};
-
-const MaxChangesStep: TaskStep<ValidationContext> = {
-  name: 'MaxChangesStep',
-  dependencies: ['DataLoaderStep'],
   run: async (ctx) => {
-    // Safe access because dependencies ensured execution order
-    if (!ctx.prData) return { status: 'failure', error: 'Missing PR Data' };
-
-    return ctx.prData.additions < 50
-      ? { status: 'success' }
-      : { status: 'failure', error: 'Too many changes' };
+    // Simulate API call
+    ctx.prData = { additions: 20, ciStatus: "success" };
+    return { status: "success", message: "Data fetched" };
   },
 };
 
-// 3. Execute the runner
+// 3. Configure and Build the Runner
 async function main() {
   const context: ValidationContext = {
-    issueBody: 'https://github.com/org/repo/pull/1',
+    issueBody: "https://github.com/org/repo/pull/1",
   };
 
-  const runner = new TaskRunner(context);
+  const runner = new TaskRunnerBuilder(context)
+    .useStrategy(new RetryingExecutionStrategy(new StandardExecutionStrategy()))
+    .on("taskStart", ({ step }) => console.log(`Starting: ${step.name}`))
+    .on("taskEnd", ({ step, result }) => console.log(`Finished: ${step.name} -> ${result.status}`))
+    .build();
 
-  const steps = [UrlFormatStep, DataLoaderStep, MaxChangesStep];
-  const results = await runner.execute(steps);
+  const steps = [UrlFormatStep, DataLoaderStep];
+  
+  // 4. Execute with options
+  const results = await runner.execute(steps, {
+      concurrency: 5, // Run up to 5 tasks in parallel
+      timeout: 30000  // 30s timeout for the whole workflow
+  });
 
   console.table(Object.fromEntries(results));
 }
@@ -98,67 +93,79 @@ async function main() {
 main();
 ```
 
-## Skip Propagation
+## Advanced Configuration
 
-If a task fails or is skipped, the `TaskRunner` automatically marks all subsequent tasks that depend on it as `skipped`. This ensures that your pipeline doesn't attempt to run steps with missing prerequisites, saving resources and preventing cascading errors.
+### Execution Strategies
 
-## Context Hydration
+The `TaskRunner` is built on top of composable execution strategies.
 
-One nice thing to do is to avoid optional parameters and excessive use of ```!``` operator, with task dependencies we can chain our steps and context usages to make sure steps are executed only when pre requisites are met.
+- **StandardExecutionStrategy**: The default strategy that simply runs the task.
+- **RetryingExecutionStrategy**: Wraps another strategy to add retry logic. Configured via the `retry` property on `TaskStep`.
+- **DryRunExecutionStrategy**: Simulates execution without running the actual task logic. Useful for validating your graph or testing conditions.
 
-This decouples **Data Loading** from **Business Logic**.
+You can set a strategy globally using the `TaskRunnerBuilder`:
 
-### Scenario: User Profile Validation
+```typescript
+runnerBuilder.useStrategy(new DryRunExecutionStrategy());
+```
+
+### Execution Options
 
-Imagine you need to validate if a user is a "Pro" member. You shouldn't mix the API fetching logic with the validation logic.
+When calling `execute`, you can provide a configuration object:
 
-1.  **Initial State**: The context starts with only a `userId`.
-2.  **Hydration Step**: A `UserLoaderStep` runs first. It fetches data from an API and attaches it to the context.
-3.  **Logic Step**: A `PremiumCheckStep` runs next. It doesn't need to know _how_ the data was fetched; it simply checks the `isPro` flag in the context.
+- **concurrency**: Limits the number of tasks running in parallel. Defaults to unlimited.
+- **timeout**: Sets a maximum execution time for the entire workflow.
+- **signal**: Accepts an `AbortSignal` to cancel the workflow programmatically.
+- **dryRun**: Overrides the current strategy with `DryRunExecutionStrategy` for this execution.
 
 ```typescript
-interface MyProjectContext {
-  rawInput: string;
-}
+await runner.execute(steps, {
+    concurrency: 2,
+    dryRun: true
+});
+```
 
-interface MyProjectFullContext extends MyProjectContext {
-  apiData: {
-    user: string;
-    isPro: boolean;
-  };
-}
+## Visualization
 
-// Step 1: Hydrate the context
-class UserLoaderStep implements TaskStep<MyProjectContext> {
-  name = 'UserLoaderStep';
-  async run(ctx: MyProjectContext & Partial<MyProjectFullContext>) {
-    // Fetch data and update context
-    ctx.apiData = { user: 'john_doe', isPro: true };
-    return { status: 'success' };
-  }
-}
+You can generate a [Mermaid.js](https://mermaid.js.org/) diagram to visualize your task dependencies.
 
-// Step 2: Use the hydrated data
-class PremiumCheckStep implements TaskStep<MyProjectContext> {
-  name = 'PremiumCheckStep';
-  dependencies = ['UserLoaderStep']; // Ensures data is ready
+```typescript
+import { TaskRunner } from "@calmo/task-runner";
 
-  async run(ctx: MyProjectFullContext) {
-    return ctx.apiData.isPro
-      ? { status: 'success' }
-      : { status: 'failure', error: 'User is not a Pro member' };
-  }
-}
+const graph = TaskRunner.getMermaidGraph(steps);
+console.log(graph);
+// Output: graph TD; A-->B; ...
 ```
 
-This approach allows `PremiumCheckStep` to be easily tested with mock data, as it doesn't depend on the actual API loader.
+## Skip Propagation
+
+If a task fails or is skipped, the `TaskRunner` automatically marks all subsequent tasks that depend on it as `skipped`. This ensures that your pipeline doesn't attempt to run steps with missing prerequisites.
+
+## Conditional Execution
+
+You can define a `condition` function for a task. If it returns `false`, the task is marked as `skipped`, and its dependencies are also skipped.
+
+```typescript
+const deployStep: TaskStep<MyContext> = {
+  name: "deploy",
+  condition: (ctx) => ctx.env === "production",
+  run: async () => {
+    // Deploy logic
+    return { status: "success" };
+  }
+};
+```
 
 ## Why I did this?
 
-In my company I have a Github Issue validation engine that checks **a lot** of stuff and I wanted to make a package that encapsulates the "validation engine" logic for use outside that niche case. I don't know if someone will find it useful but here it is.
+In my current job I have a Github Issue validation engine that checks **a lot** of stuff and I wanted to make a package that encapsulates the "validation engine" logic for use outside that use case. I also wanted to try to make a package that is not tied to a specific scenario. I don't know if someone will find it useful but here it is. 
+
+## AI Usage
+
+One of the reasons this project exists is to test 'vibe coding' tools, so yes, this is vibe coded (like, A LOT, I've added myself only specs and some conflict resolutions). This repository serves as a testbed for these tools. It's a way to create a real life scenario showcasing the capabilities of agentic AI development.
 
-## What is .gemini and .specify
+## Contributing and General Usage
 
-One of the reasons this project exists is to test 'code vibing' tools, so yes, this is vibe coded. My goal is to not touch the code and see if works.
+Feel free to open issues and PRs. I'm open to feedback and suggestions. I can't promise to act on them but I'll try my best. If you want to play with it, feel free to fork it, change it and use it in your own projects.
 
 ---