@fkws/klonk 0.0.18 → 0.0.21

package/README.md

@@ -90,6 +90,32 @@ When a task is skipped:
 
 This gives you Rust-like `Option` semantics using TypeScript's native `null` - no extra types needed!
 
+#### Task Retries
+
+When a task fails (`success: false`), it can be automatically retried. Retry behavior is configured on the `Machine` state or `Workflow`:
+
+```typescript
+// On a Machine state:
+Machine.create<MyState>()
+    .addState("fetch-data", node => node
+        .setPlaylist(p => p.addTask(...))
+        .retryDelayMs(500)   // Retry every 500ms
+        .retryLimit(3)       // Max 3 retries, then throw
+    )
+
+// On a Workflow:
+Workflow.create()
+    .addTrigger(myTrigger)
+    .retryDelayMs(1000)      // Retry every 1s (default)
+    .retryLimit(5)           // Max 5 retries
+    .setPlaylist(p => p.addTask(...))
+
+// Disable retries entirely:
+node.preventRetry()  // Task failures throw immediately
+```
+
+Default behavior: infinite retries at 1000ms delay. Use `.preventRetry()` to fail fast, or `.retryLimit(n)` to cap attempts.
+
 ### Trigger
 
 A `Trigger` is what kicks off a `Workflow`. It's an event source. Klonk can be extended with triggers for anything: file system events, webhooks, new database entries, messages in a queue, etc.
@@ -116,7 +142,7 @@ Machine.create<MyStateData>()
 Each state has:
 1. A `Playlist` that runs when the machine enters that state.
 2. A set of conditional `Transitions` to other states (with autocomplete!).
-3. Retry rules for when a transition fails to resolve.
+3. Retry rules for failed tasks and when no transition is available.
 
 The `Machine` carries a mutable `stateData` object that can be read from and written to by playlists and transition conditions throughout its execution.
 
@@ -128,7 +154,8 @@ The `Machine` carries a mutable `stateData` object that can be read from and wri
 
 Notes:
 - `stopAfter` counts states entered, including the initial state. For example, `stopAfter: 1` will run the initial state's playlist once and then stop; `stopAfter: 0` stops before entering the initial state.
-- Retries are independent of `stopAfter`. A state can retry its transition condition (with optional delay) without affecting the `stopAfter` count until a state transition actually occurs.
+- Transition retries are independent of `stopAfter`. A state can retry its transition condition (with optional delay) without affecting the `stopAfter` count until a state transition actually occurs.
+- Task retries use the same settings as transition retries. If a task fails and retries are enabled, it will retry until success or the limit is reached.
 
 ## Features
 

package/dist/index.cjs

@@ -60,7 +60,11 @@ class Playlist {
     this.finalizer = finalizer;
     return this;
   }
-  async run(source) {
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  async run(source, options = {}) {
+    const { retryDelay = 1000, maxRetries = false } = options;
     const outputs = {};
     for (const bundle of this.bundles) {
       const input = bundle.builder(source, outputs);
@@ -72,7 +76,21 @@ class Playlist {
       if (!isValid) {
         throw new Error(`Input validation failed for task '${bundle.task.ident}'`);
       }
-      const result = await bundle.task.run(input);
+      let result = await bundle.task.run(input);
+      if (!result.success) {
+        if (retryDelay === false) {
+          throw result.error ?? new Error(`Task '${bundle.task.ident}' failed and retries are disabled`);
+        }
+        let retries = 0;
+        while (!result.success) {
+          if (maxRetries !== false && retries >= maxRetries) {
+            throw result.error ?? new Error(`Task '${bundle.task.ident}' failed after ${retries} retries`);
+          }
+          await this.sleep(retryDelay);
+          retries++;
+          result = await bundle.task.run(input);
+        }
+      }
       outputs[bundle.task.ident] = result;
     }
     if (this.finalizer) {
@@ -86,19 +104,32 @@ class Playlist {
 class Workflow {
   playlist;
   triggers;
-  constructor(triggers, playlist) {
+  retry;
+  maxRetries;
+  constructor(triggers, playlist, retry = 1000, maxRetries = false) {
     this.triggers = triggers;
     this.playlist = playlist;
+    this.retry = retry;
+    this.maxRetries = maxRetries;
   }
   addTrigger(trigger) {
     const newTriggers = [...this.triggers, trigger];
     const newPlaylist = this.playlist;
-    return new Workflow(newTriggers, newPlaylist);
+    return new Workflow(newTriggers, newPlaylist, this.retry, this.maxRetries);
+  }
+  preventRetry() {
+    return new Workflow(this.triggers, this.playlist, false, this.maxRetries);
+  }
+  retryDelayMs(delayMs) {
+    return new Workflow(this.triggers, this.playlist, delayMs, this.maxRetries);
+  }
+  retryLimit(maxRetries) {
+    return new Workflow(this.triggers, this.playlist, this.retry, maxRetries);
   }
   setPlaylist(builder) {
     const initialPlaylist = new Playlist;
     const finalPlaylist = builder(initialPlaylist);
-    return new Workflow(this.triggers, finalPlaylist);
+    return new Workflow(this.triggers, finalPlaylist, this.retry, this.maxRetries);
   }
   async start({ interval = 5000, callback } = {}) {
     if (!this.playlist) {
@@ -107,12 +138,16 @@ class Workflow {
     for (const trigger of this.triggers) {
       await trigger.start();
     }
+    const runOptions = {
+      retryDelay: this.retry,
+      maxRetries: this.maxRetries
+    };
     const runTick = async () => {
       for (const trigger of this.triggers) {
         const event = trigger.poll();
         if (event) {
           try {
-            const outputs = await this.playlist.run(event);
+            const outputs = await this.playlist.run(event, runOptions);
             if (callback) {
               callback(event, outputs);
             }
@@ -398,7 +433,10 @@ class Machine {
     }
     let current = this.initialState;
     logger?.info({ phase: "progress", state: current.ident }, "Set initial state. Running playlist.");
-    await current.playlist.run(stateData);
+    await current.playlist.run(stateData, {
+      retryDelay: current.retry,
+      maxRetries: current.maxRetries
+    });
     transitionsCount = 1;
     visitedIdents.add(current.ident);
     if (options.stopAfter !== undefined && transitionsCount >= options.stopAfter) {
@@ -438,14 +476,17 @@ class Machine {
       }
       const resolvedNext = next;
       if (resolvedNext === this.initialState) {
-        if (options.mode !== "infinitely") {
+        if (options.mode === "roundtrip" || options.mode === "any") {
           logger?.info({ phase: "end", reason: "roundtrip" }, "Stop condition met.");
           return stateData;
         }
       }
       logger?.info({ phase: "progress", from: current.ident, to: resolvedNext.ident }, "Transitioning state.");
       current = resolvedNext;
-      await current.playlist.run(stateData);
+      await current.playlist.run(stateData, {
+        retryDelay: current.retry,
+        maxRetries: current.maxRetries
+      });
       visitedIdents.add(current.ident);
       transitionsCount++;
       if (options.stopAfter !== undefined && transitionsCount >= options.stopAfter) {

package/dist/index.d.ts

@@ -61,6 +61,15 @@ interface TaskBundle {
 	builder: (source: any, outputs: any) => any;
 }
 /**
+* Options for controlling task retry behavior during playlist execution.
+*/
+type PlaylistRunOptions = {
+	/** Delay in ms between retries, or false to disable retries (fail immediately on task failure). */
+	retryDelay?: number | false
+	/** Maximum number of retries per task, or false for unlimited retries. */
+	maxRetries?: number | false
+};
+/**
 * Returned by `Playlist.addTask()` - you must call `.input()` to provide the task's input builder.
 * 
 * If you see this type in an error message, it means you forgot to call `.input()` after `.addTask()`.
@@ -148,15 +157,25 @@ declare class Playlist<
 	*/
 	finally(finalizer: (source: SourceType, outputs: AllOutputTypes) => void | Promise<void>): this;
 	/**
+	* Sleep helper for retry delays.
+	*/
+	private sleep;
+	/**
 	* Execute all tasks in order, building each task's input via its builder
 	* and storing each result under the task's ident in the outputs map.
 	* If a builder returns `null`, the task is skipped and its output is `null`.
 	* If a task's `validateInput` returns false, execution stops with an error.
+	* 
+	* When a task fails (`success: false`):
+	* - If `retryDelay` is false, throws immediately
+	* - Otherwise, retries after `retryDelay` ms until success or `maxRetries` exhausted
+	* - If `maxRetries` is exhausted, throws an error
 	*
 	* @param source - The source object for this run (e.g., trigger event or machine state).
+	* @param options - Optional retry settings for failed tasks.
 	* @returns The aggregated, strongly-typed outputs map.
 	*/
-	run(source: SourceType): Promise<AllOutputTypes>;
+	run(source: SourceType, options?: PlaylistRunOptions): Promise<AllOutputTypes>;
 }
 /**
 * Event object produced by a `Trigger` and consumed by a `Workflow`.
@@ -223,6 +242,7 @@ declare abstract class Trigger<
 *
 * - Add triggers with `addTrigger`.
 * - Configure the playlist using `setPlaylist(p => p.addTask(...))`.
+* - Configure retry behavior with `retryDelayMs`, `retryLimit`, or `preventRetry`.
 * - Start polling with `start`, optionally receiving a callback when a run completes.
 *
 * See README Code Examples for building a full workflow.
@@ -232,7 +252,9 @@ declare abstract class Trigger<
 declare class Workflow<AllTriggerEvents extends TriggerEvent<string, any>> {
 	playlist: Playlist<any, AllTriggerEvents> | null;
 	triggers: Trigger<string, any>[];
-	constructor(triggers: Trigger<string, any>[], playlist: Playlist<any, AllTriggerEvents> | null);
+	retry: false | number;
+	maxRetries: false | number;
+	constructor(triggers: Trigger<string, any>[], playlist: Playlist<any, AllTriggerEvents> | null, retry?: false | number, maxRetries?: false | number);
 	/**
 	* Register a new trigger to feed events into the workflow.
 	* The resulting workflow type widens its `AllTriggerEvents` union accordingly.
@@ -247,6 +269,27 @@ declare class Workflow<AllTriggerEvents extends TriggerEvent<string, any>> {
 		TData
 	>(trigger: Trigger<TIdent, TData>): Workflow<AllTriggerEvents | TriggerEvent<TIdent, TData>>;
 	/**
+	* Disable retry behavior for failed tasks. Tasks that fail will throw immediately.
+	*
+	* @returns This workflow for chaining.
+	*/
+	preventRetry(): Workflow<AllTriggerEvents>;
+	/**
+	* Set the delay between retry attempts for failed tasks.
+	*
+	* @param delayMs - Delay in milliseconds between retries.
+	* @returns This workflow for chaining.
+	*/
+	retryDelayMs(delayMs: number): Workflow<AllTriggerEvents>;
+	/**
+	* Set the maximum number of retries for failed tasks.
+	* Use `preventRetry()` to disable retries entirely.
+	*
+	* @param maxRetries - Maximum number of retry attempts before throwing.
+	* @returns This workflow for chaining.
+	*/
+	retryLimit(maxRetries: number): Workflow<AllTriggerEvents>;
+	/**
 	* Configure the playlist by providing a builder that starts from an empty
 	* `Playlist<{}, AllTriggerEvents>` and returns your fully configured playlist.
 	*
@@ -532,4 +575,4 @@ type RunOptions = {
 	mode: "infinitely"
 	interval?: number
 });
-export { Workflow, TriggerEvent, Trigger, Task, StateNode, RunOptions, Railroad, Playlist, Machine };
+export { Workflow, TriggerEvent, Trigger, Task, StateNode, RunOptions, Railroad, PlaylistRunOptions, Playlist, Machine };

package/dist/index.js

@@ -19,7 +19,11 @@ class Playlist {
     this.finalizer = finalizer;
     return this;
   }
-  async run(source) {
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  async run(source, options = {}) {
+    const { retryDelay = 1000, maxRetries = false } = options;
     const outputs = {};
     for (const bundle of this.bundles) {
       const input = bundle.builder(source, outputs);
@@ -31,7 +35,21 @@ class Playlist {
       if (!isValid) {
         throw new Error(`Input validation failed for task '${bundle.task.ident}'`);
       }
-      const result = await bundle.task.run(input);
+      let result = await bundle.task.run(input);
+      if (!result.success) {
+        if (retryDelay === false) {
+          throw result.error ?? new Error(`Task '${bundle.task.ident}' failed and retries are disabled`);
+        }
+        let retries = 0;
+        while (!result.success) {
+          if (maxRetries !== false && retries >= maxRetries) {
+            throw result.error ?? new Error(`Task '${bundle.task.ident}' failed after ${retries} retries`);
+          }
+          await this.sleep(retryDelay);
+          retries++;
+          result = await bundle.task.run(input);
+        }
+      }
       outputs[bundle.task.ident] = result;
     }
     if (this.finalizer) {
@@ -45,19 +63,32 @@ class Playlist {
 class Workflow {
   playlist;
   triggers;
-  constructor(triggers, playlist) {
+  retry;
+  maxRetries;
+  constructor(triggers, playlist, retry = 1000, maxRetries = false) {
     this.triggers = triggers;
     this.playlist = playlist;
+    this.retry = retry;
+    this.maxRetries = maxRetries;
   }
   addTrigger(trigger) {
     const newTriggers = [...this.triggers, trigger];
     const newPlaylist = this.playlist;
-    return new Workflow(newTriggers, newPlaylist);
+    return new Workflow(newTriggers, newPlaylist, this.retry, this.maxRetries);
+  }
+  preventRetry() {
+    return new Workflow(this.triggers, this.playlist, false, this.maxRetries);
+  }
+  retryDelayMs(delayMs) {
+    return new Workflow(this.triggers, this.playlist, delayMs, this.maxRetries);
+  }
+  retryLimit(maxRetries) {
+    return new Workflow(this.triggers, this.playlist, this.retry, maxRetries);
   }
   setPlaylist(builder) {
     const initialPlaylist = new Playlist;
     const finalPlaylist = builder(initialPlaylist);
-    return new Workflow(this.triggers, finalPlaylist);
+    return new Workflow(this.triggers, finalPlaylist, this.retry, this.maxRetries);
   }
   async start({ interval = 5000, callback } = {}) {
     if (!this.playlist) {
@@ -66,12 +97,16 @@ class Workflow {
     for (const trigger of this.triggers) {
       await trigger.start();
     }
+    const runOptions = {
+      retryDelay: this.retry,
+      maxRetries: this.maxRetries
+    };
     const runTick = async () => {
       for (const trigger of this.triggers) {
         const event = trigger.poll();
         if (event) {
           try {
-            const outputs = await this.playlist.run(event);
+            const outputs = await this.playlist.run(event, runOptions);
             if (callback) {
               callback(event, outputs);
             }
@@ -357,7 +392,10 @@ class Machine {
     }
     let current = this.initialState;
     logger?.info({ phase: "progress", state: current.ident }, "Set initial state. Running playlist.");
-    await current.playlist.run(stateData);
+    await current.playlist.run(stateData, {
+      retryDelay: current.retry,
+      maxRetries: current.maxRetries
+    });
     transitionsCount = 1;
     visitedIdents.add(current.ident);
     if (options.stopAfter !== undefined && transitionsCount >= options.stopAfter) {
@@ -397,14 +435,17 @@ class Machine {
       }
       const resolvedNext = next;
       if (resolvedNext === this.initialState) {
-        if (options.mode !== "infinitely") {
+        if (options.mode === "roundtrip" || options.mode === "any") {
           logger?.info({ phase: "end", reason: "roundtrip" }, "Stop condition met.");
           return stateData;
         }
       }
       logger?.info({ phase: "progress", from: current.ident, to: resolvedNext.ident }, "Transitioning state.");
       current = resolvedNext;
-      await current.playlist.run(stateData);
+      await current.playlist.run(stateData, {
+        retryDelay: current.retry,
+        maxRetries: current.maxRetries
+      });
       visitedIdents.add(current.ident);
       transitionsCount++;
       if (options.stopAfter !== undefined && transitionsCount >= options.stopAfter) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fkws/klonk",
-  "version": "0.0.18",
+  "version": "0.0.21",
   "description": "A lightweight, extensible workflow automation engine for Node.js and Bun",
   "repository": "https://github.com/klar-web-services/klonk",
   "homepage": "https://klonk.dev",