@fkws/klonk 0.0.19 → 0.0.22

package/README.md

@@ -48,20 +48,65 @@ A `Task` is the smallest unit of work. It's an abstract class with two main meth
 - `validateInput(input)`: Runtime validation of the task's input (on top of strong typing).
 - `run(input)`: Executes the task's logic.
 
-Tasks use a `Railroad` return type, which is a simple discriminated union for handling success and error states without throwing exceptions. Shoutout to Rust!
+Tasks use a `Railroad` return type - a discriminated union for handling success and error states without throwing exceptions. Inspired by Rust's `Result<T, E>` type, it comes with familiar helper functions like `unwrap()`, `unwrapOr()`, and more.
+
+### Railroad (Rust-inspired Result Type)
+
+`Railroad<T>` is Klonk's version of Rust's `Result<T, E>`. It's a discriminated union that forces you to handle both success and error cases:
+
+```typescript
+type Railroad<T> = 
+    | { success: true, data: T }
+    | { success: false, error: Error }
+```
+
+#### Helper Functions
+
+Klonk provides Rust-inspired helper functions for working with `Railroad`:
+
+```typescript
+import { unwrap, unwrapOr, unwrapOrElse, isOk, isErr } from "@fkws/klonk";
+
+// unwrap: Get data or throw error (like Rust's .unwrap())
+const data = unwrap(result);  // Returns T or throws
+
+// unwrapOr: Get data or return a default value
+const data = unwrapOr(result, defaultValue);  // Returns T
+
+// unwrapOrElse: Get data or compute a fallback from the error
+const data = unwrapOrElse(result, (err) => computeFallback(err));
+
+// isOk / isErr: Type guards for narrowing
+if (isOk(result)) {
+    console.log(result.data);  // TypeScript knows it's success
+}
+if (isErr(result)) {
+    console.log(result.error);  // TypeScript knows it's error
+}
+```
+
+#### Why Railroad?
+
+The name "Railroad" comes from Railway Oriented Programming - a functional approach where success travels the "happy path" and errors get shunted to the "error track". Combined with TypeScript's type narrowing, you get:
+
+- **No uncaught exceptions** - errors are values, not thrown
+- **Explicit error handling** - the type system forces you to handle failures
+- **Familiar patterns** - if you love Rust's `Result`, you'll feel right at home
 
 ### Playlist
 
 A `Playlist` is a sequence of `Tasks` executed in order. The magic of a `Playlist` is that each task has access to the outputs of all previous tasks, in a fully type-safe way. You build a `Playlist` by chaining `.addTask().input()` calls:
 
 ```typescript
+import { isOk } from "@fkws/klonk";
+
 playlist
     .addTask(new FetchTask("fetch"))
     .input((source) => ({ url: source.targetUrl }))
     .addTask(new ParseTask("parse"))
     .input((source, outputs) => ({
-        // Full autocomplete! outputs.fetch?.success, outputs.fetch?.data, etc.
-        html: outputs.fetch?.success ? outputs.fetch.data.body : ""
+        // Use isOk for Rust-style type narrowing!
+        html: outputs.fetch && isOk(outputs.fetch) ? outputs.fetch.data.body : ""
     }))
 ```
 
@@ -72,11 +117,13 @@ playlist
 Need to conditionally skip a task? Just return `null` from the input builder:
 
 ```typescript
+import { isOk } from "@fkws/klonk";
+
 playlist
     .addTask(new NotifyTask("notify"))
     .input((source, outputs) => {
-        // Skip notification if previous task failed
-        if (!outputs.fetch?.success) {
+        // Skip notification if previous task failed - using isOk!
+        if (!outputs.fetch || !isOk(outputs.fetch)) {
             return null;  // Task will be skipped!
         }
         return { message: "Success!", level: "info" };
@@ -90,6 +137,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 +189,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 +201,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
 
@@ -256,7 +330,7 @@ Notice the fluent `.addTask(task).input(builder)` syntax - each task's input bui
 
 ```typescript
 import { z } from 'zod';
-import { Workflow } from '@fkws/klonk';
+import { Workflow, isOk } from '@fkws/klonk';
 
 // The following example requires tasks, integrations and a trigger.
 // Soon, you will be able to import these from @fkws/klonkworks.
@@ -310,17 +384,17 @@ const workflow = Workflow.create()
             // Access outputs of previous tasks - fully typed!
             // Check for null (skipped) and success
             const downloadResult = outputs['download-invoice-pdf'];
-            if (!downloadResult?.success) {
+            if (!downloadResult || !isOk(downloadResult)) {
                 throw downloadResult?.error ?? new Error('Failed to download invoice PDF');
             }
 
             const payeesResult = outputs['get-payees'];
-            if (!payeesResult?.success) {
+            if (!payeesResult || !isOk(payeesResult)) {
                 throw payeesResult?.error ?? new Error('Failed to load payees');
             }
 
             const expenseTypesResult = outputs['get-expense-types'];
-            if (!expenseTypesResult?.success) {
+            if (!expenseTypesResult || !isOk(expenseTypesResult)) {
                 throw expenseTypesResult?.error ?? new Error('Failed to load expense types');
             }
 
@@ -345,7 +419,7 @@ const workflow = Workflow.create()
         .addTask(new TACreateNotionDatabaseItem("create-notion-invoice", notionProvider))
         .input((source, outputs) => {
             const invoiceResult = outputs['parse-invoice'];
-            if (!invoiceResult?.success) {
+            if (!invoiceResult || !isOk(invoiceResult)) {
                 throw invoiceResult?.error ?? new Error('Failed to parse invoice');
             }
             const invoiceData = invoiceResult.data;
@@ -381,7 +455,7 @@ workflow.start({
 The `Machine` manages a `StateData` object. Each `StateNode`'s `Playlist` can modify this state, and the `Transitions` between states use it to decide which state to move to next.
 
 ```typescript
-import { Machine } from "@fkws/klonk"
+import { Machine, isOk } from "@fkws/klonk"
 import { OpenRouterClient } from "./tasks/common/OpenrouterClient" 
 import { Model } from "./tasks/common/models"
 import { TABasicTextInference } from "./tasks/TABasicTextInference"
@@ -430,17 +504,17 @@ const webSearchAgent = Machine
             // Extract search terms from refined input
             .addTask(new TABasicTextInference("extract_search_terms", client))
             .input((state, outputs) => ({
-                inputText: `Original: ${state.input}\n\nRefined: ${outputs.refine?.success ? outputs.refine.data.text : state.input}`,
+                inputText: `Original: ${state.input}\n\nRefined: ${outputs.refine && isOk(outputs.refine) ? outputs.refine.data.text : state.input}`,
                 model: state.model ?? "openai/gpt-5.2",
                 instructions: `Extract one short web search query from the user request and refined prompt.`
             }))
 
-            // Update state with results
+            // Update state with results - using isOk for type narrowing
             .finally((state, outputs) => {
-                if (outputs.refine?.success) {
+                if (outputs.refine && isOk(outputs.refine)) {
                     state.refinedInput = outputs.refine.data.text;
                 }
-                if (outputs.extract_search_terms?.success) {
+                if (outputs.extract_search_terms && isOk(outputs.extract_search_terms)) {
                     state.searchTerm = outputs.extract_search_terms.data.text;
                 }
             })
@@ -465,7 +539,7 @@ const webSearchAgent = Machine
                 query: state.searchTerm!
             }))
             .finally((state, outputs) => {
-                if (outputs.search?.success) {
+                if (outputs.search && isOk(outputs.search)) {
                     state.searchResults = outputs.search.data;
                 }
             })
@@ -488,7 +562,7 @@ const webSearchAgent = Machine
                                Write a professional response.`
             }))
             .finally((state, outputs) => {
-                state.finalResponse = outputs.generate_response?.success
+                state.finalResponse = outputs.generate_response && isOk(outputs.generate_response)
                     ? outputs.generate_response.data.text
                     : "Sorry, an error occurred: " + (outputs.generate_response?.error ?? "unknown");
             })
@@ -522,13 +596,23 @@ Klonk's type system is designed to be minimal yet powerful. Here's what makes it
 | Type | Parameters | Purpose |
 |------|------------|---------|
 | `Task<Input, Output, Ident>` | Input shape, output shape, string literal ident | Base class for all tasks |
-| `Railroad<Output>` | Success data type | Discriminated union for success/error results |
+| `Railroad<Output>` | Success data type | Discriminated union for success/error results (like Rust's `Result`) |
 | `Playlist<AllOutputs, Source>` | Accumulated output map, source data type | Ordered task sequence with typed chaining |
 | `Trigger<Ident, Data>` | String literal ident, event payload type | Event source for workflows |
 | `Workflow<Events>` | Union of trigger event types | Connects triggers to playlists |
 | `Machine<StateData, AllStateIdents>` | Mutable state shape, union of state idents | Finite state machine with typed transitions |
 | `StateNode<StateData, Ident, AllStateIdents>` | State shape, this node's ident, all valid transition targets | Individual state with playlist and transitions |
 
+### Railroad Helper Functions
+
+| Function | Signature | Behavior |
+|----------|-----------|----------|
+| `unwrap(r)` | `Railroad<T> → T` | Returns data or throws error |
+| `unwrapOr(r, default)` | `Railroad<T>, T → T` | Returns data or default value |
+| `unwrapOrElse(r, fn)` | `Railroad<T>, (E) → T → T` | Returns data or result of fn(error) |
+| `isOk(r)` | `Railroad<T> → boolean` | Type guard for success case |
+| `isErr(r)` | `Railroad<T> → boolean` | Type guard for error case |
+
 ### How Output Chaining Works
 
 When you add a task to a playlist, Klonk extends the output type:
@@ -543,7 +627,7 @@ Playlist<{ fetch: Railroad<FetchOutput> | null }, Source>
 // Now outputs include both: { fetch: ..., parse: Railroad<ParseOutput> | null }
 ```
 
-The `| null` accounts for the possibility that a task was skipped (when its input builder returns `null`). This is why you'll use optional chaining like `outputs.fetch?.success` - TypeScript knows the output could be `null` if the task was skipped!
+The `| null` accounts for the possibility that a task was skipped (when its input builder returns `null`). This is why you'll check for null before using `isOk()` - for example: `outputs.fetch && isOk(outputs.fetch)`. TypeScript then narrows the type so you can safely access `.data`!
 
 This maps cleanly to Rust's types:
 | Rust | Klonk (TypeScript) |

package/dist/index.cjs

@@ -30,6 +30,11 @@ var __export = (target, all) => {
 // src/index.ts
 var exports_src = {};
 __export(exports_src, {
+  unwrapOrElse: () => unwrapOrElse,
+  unwrapOr: () => unwrapOr,
+  unwrap: () => unwrap,
+  isOk: () => isOk,
+  isErr: () => isErr,
   Workflow: () => Workflow,
   Trigger: () => Trigger,
   Task: () => Task,
@@ -60,7 +65,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 +81,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 +109,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 +143,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);
             }
@@ -130,6 +170,28 @@ class Workflow {
   }
 }
 // src/prototypes/Task.ts
+function isOk(r) {
+  return r.success === true;
+}
+function isErr(r) {
+  return r.success === false;
+}
+function unwrap(r) {
+  if (r.success)
+    return r.data;
+  throw r.error;
+}
+function unwrapOr(r, defaultValue) {
+  if (r.success)
+    return r.data;
+  return defaultValue;
+}
+function unwrapOrElse(r, fn) {
+  if (r.success)
+    return r.data;
+  return fn(r.error);
+}
+
 class Task {
   ident;
   constructor(ident) {
@@ -398,7 +460,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) {
@@ -445,7 +510,10 @@ class Machine {
       }
       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

@@ -19,6 +19,37 @@ type Railroad<
 	readonly success: false
 	readonly error: ErrorType
 };
+/** Type guard: returns true if the Railroad is a success */
+declare function isOk<
+	T,
+	E
+>(r: Railroad<T, E>): r is {
+	success: true
+	data: T
+};
+/** Type guard: returns true if the Railroad is an error */
+declare function isErr<
+	T,
+	E
+>(r: Railroad<T, E>): r is {
+	success: false
+	error: E
+};
+/** Returns the data if success, throws the error if failure (like Rust's unwrap) */
+declare function unwrap<
+	T,
+	E
+>(r: Railroad<T, E>): T;
+/** Returns the data if success, or the default value if failure */
+declare function unwrapOr<
+	T,
+	E
+>(r: Railroad<T, E>, defaultValue: T): T;
+/** Returns the data if success, or calls the function with the error if failure */
+declare function unwrapOrElse<
+	T,
+	E
+>(r: Railroad<T, E>, fn: (error: E) => T): T;
 /**
 * Base class for all executable units in Klonk.
 * Implement `validateInput` for runtime checks and `run` for the actual work.
@@ -61,6 +92,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 +188,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 +273,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 +283,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 +300,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 +606,4 @@ type RunOptions = {
 	mode: "infinitely"
 	interval?: number
 });
-export { Workflow, TriggerEvent, Trigger, Task, StateNode, RunOptions, Railroad, Playlist, Machine };
+export { unwrapOrElse, unwrapOr, unwrap, isOk, isErr, 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);
             }
@@ -89,6 +124,28 @@ class Workflow {
   }
 }
 // src/prototypes/Task.ts
+function isOk(r) {
+  return r.success === true;
+}
+function isErr(r) {
+  return r.success === false;
+}
+function unwrap(r) {
+  if (r.success)
+    return r.data;
+  throw r.error;
+}
+function unwrapOr(r, defaultValue) {
+  if (r.success)
+    return r.data;
+  return defaultValue;
+}
+function unwrapOrElse(r, fn) {
+  if (r.success)
+    return r.data;
+  return fn(r.error);
+}
+
 class Task {
   ident;
   constructor(ident) {
@@ -357,7 +414,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) {
@@ -404,7 +464,10 @@ class Machine {
       }
       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) {
@@ -424,6 +487,11 @@ class Machine {
   }
 }
 export {
+  unwrapOrElse,
+  unwrapOr,
+  unwrap,
+  isOk,
+  isErr,
   Workflow,
   Trigger,
   Task,

package/package.json

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