@fkws/klonk 0.0.21 → 0.0.23

package/README.md

@@ -20,15 +20,14 @@
 
 ## Introduction
 
-Klonk is a code-first, type-safe automation engine designed with developer experience as a top priority. It provides powerful, composable primitives to build complex workflows and state machines with world-class autocomplete and type inference. If you've ever wanted to build event-driven automations or a stateful agent, but in code, with all the benefits of TypeScript, Klonk is for you.
+Klonk is a code-first, type-safe automation engine. It provides composable primitives to build workflows and state machines with autocomplete and type inference. If you've ever wanted to build event-driven automations or a stateful agent in code, with all the benefits of TypeScript, Klonk is for you.
 
-![Code](./.github/assets/blurry.png)
 ![Skip to code examples ->](https://github.com/klar-web-services/klonk?tab=readme-ov-file#code-examples)
 
 The two main features are **Workflows** and **Machines**.
 
-- **Workflows**: Combine triggers with a series of tasks (a `Playlist`) to automate processes. Perfect for event-driven automation, like "when a file is added to Dropbox, parse it, and create an entry in Notion."
-- **Machines**: Create finite state machines where each state has its own `Playlist` of tasks and conditional transitions to other states. Ideal for building agents, multi-step processes, or any system with complex, stateful logic.
+- **Workflows**: Combine triggers with a series of tasks (a `Playlist`) to automate processes. Example: "when a file is added to Dropbox, parse it, and create an entry in Notion."
+- **Machines**: Finite state machines where each state has its own `Playlist` of tasks and conditional transitions to other states. Useful for agents, multi-step processes, or systems with stateful logic.
 
 ## Installation
 
@@ -38,9 +37,98 @@ bun add @fkws/klonk
 npm i @fkws/klonk
 ```
 
+### Compatibility
+
+| Requirement | Support |
+|-------------|---------|
+| **Runtimes** | Node.js 18+, Bun 1.0+, Deno (via npm specifier, best-effort) |
+| **Module** | ESM (native) and CJS (via bundled `/dist`) |
+| **TypeScript** | 5.0+ (required for full type inference) |
+| **Dependencies** | Zero runtime dependencies |
+
+**Status:** Pre-1.0, API may change between minor versions. Aiming for stability by 1.0.
+
+## Quickstart
+
+Copy-paste this to see Klonk in action. One trigger, two tasks, fully typed outputs:
+
+```typescript
+import { Task, Trigger, Workflow, Railroad, isOk } from "@fkws/klonk";
+
+// 1. Define two simple tasks
+class FetchUser<I extends string> extends Task<{ userId: string }, { name: string; email: string }, I> {
+  async validateInput(input: { userId: string }) { return !!input.userId; }
+  async run(input: { userId: string }): Promise<Railroad<{ name: string; email: string }>> {
+    if (input.userId !== "123") return { success: false, error: new Error("User not found") };
+    return { success: true, data: { name: "Alice", email: "alice@example.com" } };
+  }
+}
+
+class SendEmail<I extends string> extends Task<{ to: string; subject: string }, { sent: boolean }, I> {
+  async validateInput(input: { to: string; subject: string }) { return !!input.to; }
+  async run(input: { to: string; subject: string }): Promise<Railroad<{ sent: boolean }>> {
+    console.log(`📧 Sending "${input.subject}" to ${input.to}`);
+    return { success: true, data: { sent: true } };
+  }
+}
+
+// 2. Create a trigger (fires once with a userId)
+class ManualTrigger<I extends string> extends Trigger<I, { userId: string }> {
+  async start() { this.pushEvent({ userId: "123" }); }
+  async stop() {}
+}
+
+// 3. Wire it up: trigger → playlist with typed outputs
+const workflow = Workflow.create()
+  .addTrigger(new ManualTrigger("manual"))
+  .setPlaylist(p => p
+    .addTask(new FetchUser("fetch-user"))
+    .input((source) => ({ userId: source.data.userId }))  // ← source.data is typed!
+
+    .addTask(new SendEmail("send-email"))
+    .input((source, outputs) => {
+      // outputs["fetch-user"] is typed as Railroad<{ name, email }> | null
+      const user = outputs["fetch-user"];
+      if (!user || !isOk(user)) return null;  // skip if failed
+      return { to: user.data.email, subject: `Welcome, ${user.data.name}!` };
+    })
+  );
+
+workflow.start({ callback: (src, out) => console.log("✅ Done!", out) });
+```
+
+**What you just saw:**
+- `source.data.userId` is typed from the trigger
+- `outputs["fetch-user"]` is typed by the task's ident string literal
+- `user.data.email` is narrowed after the `isOk()` check
+
+## TypeScript Magic Moment
+
+Klonk's type inference isn't marketing. Here's proof:
+
+```typescript
+import { Machine } from "@fkws/klonk";
+
+// Declare states upfront → autocomplete for ALL transitions
+const machine = Machine.create<{ count: number }>()
+  .withStates("idle", "processing", "done")  // ← These drive autocomplete
+  .addState("idle", node => node
+    .setPlaylist(p => p/* ... */)
+    .addTransition({
+      to: "processing",  // ← Type "pro" and your IDE suggests "processing"
+      condition: async () => true,
+      weight: 1
+    })
+    // @ts-expect-error - "typo-state" is not a valid state
+    .addTransition({ to: "typo-state", condition: async () => true, weight: 1 })
+  , { initial: true });
+```
+
+The `withStates<...>()` pattern means **you can't transition to a state that doesn't exist**. TypeScript catches it at compile time, not runtime.
+
 ## Core Concepts
 
-At the heart of Klonk are a few key concepts that work together.
+Klonk has a few concepts that work together.
 
 ### Task
 
@@ -48,20 +136,61 @@ 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, where success travels the "happy path" and errors get shunted to the "error track". Combined with TypeScript's type narrowing, you get explicit error handling without exceptions. If you like Rust's `Result`, you'll feel 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:
+A `Playlist` is a sequence of `Tasks` executed in order. 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 +201,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" };
@@ -114,7 +245,7 @@ Workflow.create()
 node.preventRetry()  // Task failures throw immediately
 ```
 
-Default behavior: infinite retries at 1000ms delay. Use `.preventRetry()` to fail fast, or `.retryLimit(n)` to cap attempts.
+Default behavior: infinite retries at 1000ms delay. This is designed for long-running daemons and background workers where resilience matters. **For request/response contexts** (APIs, CLIs, one-shot scripts), set `.retryLimit(n)` to cap attempts or use `.preventRetry()` to fail fast.
 
 ### Trigger
 
@@ -126,11 +257,11 @@ A `Workflow` connects one or more `Triggers` to a `Playlist`. When a trigger fir
 
 ### Machine
 
-A `Machine` is a finite state machine. You build it by declaring all state identifiers upfront with `.withStates<...>()`, then adding states with `.addState()`:
+A `Machine` is a finite state machine. You build it by declaring all state identifiers upfront with `.withStates(...)`, then adding states with `.addState()`:
 
 ```typescript
 Machine.create<MyStateData>()
-    .withStates<"idle" | "running" | "complete">()  // Declare all states
+    .withStates("idle", "running", "complete")  // Declare all states
     .addState("idle", node => node
         .setPlaylist(p => p.addTask(...).input(...))
         .addTransition({ to: "running", condition: ..., weight: 1 })  // Autocomplete!
@@ -159,14 +290,14 @@ Notes:
 
 ## Features
 
-- **Type-Safe & Autocompleted**: Klonk leverages TypeScript's inference to provide a world-class developer experience. The inputs and outputs of every step are strongly typed, so you'll know at compile time if your logic is sound.
-- **Code-First**: Define your automations directly in TypeScript. No YAML, no drag-and-drop UIs. Just the full power of a real programming language.
-- **Composable & Extensible**: The core primitives (`Task`, `Trigger`) are simple abstract classes, making it easy to create your own reusable components and integrations.
+- **Type-Safe & Autocompleted**: Klonk uses TypeScript's inference so the inputs and outputs of every step are strongly typed. You'll know at compile time if your logic is sound.
+- **Code-First**: Define your automations directly in TypeScript. No YAML, no drag-and-drop UIs.
+- **Composable & Extensible**: The core primitives (`Task`, `Trigger`) are simple abstract classes, so you can create your own reusable components.
 - **Flexible Execution**: `Machines` run with configurable modes via `run(state, options)`: `any`, `leaf`, `roundtrip`, or `infinitely` (with optional `interval`).
 
 ## Klonkworks: Pre-built Components
 
-Coming soon(ish)! Klonkworks will be a large collection of pre-built Tasks, Triggers, and integrations. This will allow you to quickly assemble powerful automations that connect to a wide variety of services, often without needing to build your own components from scratch.
+Coming soon(ish)! Klonkworks will be a collection of pre-built Tasks, Triggers, and integrations that connect to various services, so you don't have to build everything from scratch.
 
 ## Code Examples
 
@@ -277,13 +408,13 @@ export class IntervalTrigger<TIdent extends string> extends Trigger<TIdent, { no
 <details>
 <summary><b>Building a Workflow</b></summary>
 
-Workflows are perfect for event-driven automations. This example creates a workflow that triggers when a new invoice PDF is added to a Dropbox folder. It then parses the invoice and creates a new item in a Notion database.
+Workflows work well for event-driven automations. This example triggers when a new invoice PDF is added to a Dropbox folder, parses the invoice, and creates a new item in a Notion database.
 
 Notice the fluent `.addTask(task).input(builder)` syntax - each task's input builder has access to `source` (trigger data) and `outputs` (all previous task results), with full type inference!
 
 ```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.
@@ -337,17 +468,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');
             }
 
@@ -372,7 +503,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;
@@ -403,12 +534,12 @@ workflow.start({
 <details>
 <summary><b>Building a Machine</b></summary>
 
-`Machines` are ideal for building complex, stateful agents. This example shows an AI agent that takes a user's query, refines it, performs a web search, and generates a final response.
+`Machines` work well for stateful agents. This example shows an AI agent that takes a user's query, refines it, performs a web search, and generates a response.
 
 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"
@@ -442,7 +573,7 @@ const client = new OpenRouterClient(process.env.OPENROUTER_API_KEY!)
 const webSearchAgent = Machine
     .create<StateData>()
     // Declare all states upfront for transition autocomplete
-    .withStates<"refine_and_extract" | "search_web" | "generate_response">()
+    .withStates("refine_and_extract", "search_web", "generate_response")
     .addState("refine_and_extract", node => node
         .setPlaylist(p => p
             // Refine the user's input
@@ -457,17 +588,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;
                 }
             })
@@ -492,7 +623,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;
                 }
             })
@@ -515,7 +646,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");
             })
@@ -542,20 +673,30 @@ console.log(state.finalResponse);
 
 ## Type System
 
-Klonk's type system is designed to be minimal yet powerful. Here's what makes it tick:
+Klonk's type system is minimal. Here's how it works:
 
 ### Core Types
 
 | 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:
@@ -570,7 +711,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,
@@ -165,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) {
@@ -330,7 +357,7 @@ class Machine {
   static create() {
     return new Machine;
   }
-  withStates() {
+  withStates(..._states) {
     return this;
   }
   finalize({

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.
@@ -432,7 +463,7 @@ declare class StateNode<
 	next(data: TStateData): Promise<StateNode<TStateData> | null>;
 }
 /**
-* Returned by `Machine.create()` - you must call `.withStates<...>()` to declare state idents.
+* Returned by `Machine.create()` - you must call `.withStates(...)` to declare state idents.
 * 
 * This ensures all state identifiers are known upfront for full transition autocomplete.
 */
@@ -441,17 +472,18 @@ interface MachineNeedsStates<TStateData> {
 	* Declare all state identifiers that will be used in this machine.
 	* This enables full autocomplete for transition targets.
 	* 
-	* @template TIdents - Union of all state idents (e.g., `"idle" | "running" | "complete"`).
+	* @param states - All state idents as string arguments. If omitted, any string is allowed (useful for tests).
 	* @returns The machine, ready for adding states.
 	* 
 	* @example
 	* Machine.create<MyState>()
-	*     .withStates<"idle" | "running" | "complete">()
+	*     .withStates("idle", "running", "complete")
 	*     .addState("idle", node => node
 	*         .addTransition({ to: "running", ... })  // Autocomplete works!
 	*     )
 	*/
-	withStates<TIdents extends string>(): Machine<TStateData, TIdents>;
+	withStates(): Machine<TStateData, string>;
+	withStates<const T extends readonly string[]>(...states: T): Machine<TStateData, T[number]>;
 }
 /**
 * A finite state machine that coordinates execution of `StateNode` playlists
@@ -487,7 +519,7 @@ declare class Machine<
 	*/
 	private sleep;
 	/**
-	* Create a new Machine. You must call `.withStates<...>()` next to declare
+	* Create a new Machine. You must call `.withStates(...)` next to declare
 	* all state identifiers before adding states.
 	*
 	* @template TStateData - The shape of the mutable state carried through the machine.
@@ -495,7 +527,7 @@ declare class Machine<
 	* 
 	* @example
 	* Machine.create<MyState>()
-	*     .withStates<"idle" | "running">()
+	*     .withStates("idle", "running")
 	*     .addState("idle", node => ...)
 	*/
 	static create<TStateData>(): MachineNeedsStates<TStateData>;
@@ -505,7 +537,7 @@ declare class Machine<
 	* 
 	* @internal
 	*/
-	withStates<TIdents extends string>(): Machine<TStateData, TIdents>;
+	withStates<const T extends readonly string[]>(..._states: T): Machine<TStateData, T[number]>;
 	/**
 	* Finalize the machine by resolving state transitions and locking configuration.
 	* Must be called before `start` or `run`.
@@ -541,9 +573,9 @@ declare class Machine<
 	*         .addTransition({ to: "idle", condition: async () => true, weight: 1 })
 	*     )
 	*/
-	addState<const TIdent extends string>(ident: TIdent, builder: (node: StateNode<TStateData, TIdent, AllStateIdents | TIdent>) => StateNode<TStateData, TIdent, AllStateIdents | TIdent>, options?: {
+	addState<const TIdent extends AllStateIdents>(ident: TIdent, builder: (node: StateNode<TStateData, TIdent, AllStateIdents>) => StateNode<TStateData, TIdent, AllStateIdents>, options?: {
 		initial?: boolean
-	}): Machine<TStateData, AllStateIdents | TIdent>;
+	}): Machine<TStateData, AllStateIdents>;
 	/**
 	* Attach a logger to this machine. If the machine has an initial state set,
 	* the logger will be propagated to all currently reachable states.
@@ -575,4 +607,4 @@ type RunOptions = {
 	mode: "infinitely"
 	interval?: number
 });
-export { Workflow, TriggerEvent, Trigger, Task, StateNode, RunOptions, Railroad, PlaylistRunOptions, Playlist, Machine };
+export { unwrapOrElse, unwrapOr, unwrap, isOk, isErr, Workflow, TriggerEvent, Trigger, Task, StateNode, RunOptions, Railroad, PlaylistRunOptions, Playlist, Machine };

package/dist/index.js

@@ -124,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) {
@@ -289,7 +311,7 @@ class Machine {
   static create() {
     return new Machine;
   }
-  withStates() {
+  withStates(..._states) {
     return this;
   }
   finalize({
@@ -465,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.21",
+  "version": "0.0.23",
   "description": "A lightweight, extensible workflow automation engine for Node.js and Bun",
   "repository": "https://github.com/klar-web-services/klonk",
   "homepage": "https://klonk.dev",