@fkws/klonk 0.0.22 → 0.0.24

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
 
@@ -87,15 +175,11 @@ if (isErr(result)) {
 
 #### 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
+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";
@@ -161,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
 
@@ -173,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!
@@ -206,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
 
@@ -324,7 +408,7 @@ 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!
 
@@ -450,7 +534,7 @@ 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.
 
@@ -489,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
@@ -589,7 +673,7 @@ 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
 

package/dist/index.cjs

@@ -357,7 +357,7 @@ class Machine {
   static create() {
     return new Machine;
   }
-  withStates() {
+  withStates(..._states) {
     return this;
   }
   finalize({

package/dist/index.d.ts

@@ -24,16 +24,16 @@ declare function isOk<
 	T,
 	E
 >(r: Railroad<T, E>): r is {
-	success: true
-	data: T
+	readonly success: true
+	readonly 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
+	readonly success: false
+	readonly error: E
 };
 /** Returns the data if success, throws the error if failure (like Rust's unwrap) */
 declare function unwrap<
@@ -463,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.
 */
@@ -472,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
@@ -518,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.
@@ -526,7 +527,7 @@ declare class Machine<
 	* 
 	* @example
 	* Machine.create<MyState>()
-	*     .withStates<"idle" | "running">()
+	*     .withStates("idle", "running")
 	*     .addState("idle", node => ...)
 	*/
 	static create<TStateData>(): MachineNeedsStates<TStateData>;
@@ -536,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`.
@@ -572,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.

package/dist/index.js

@@ -311,7 +311,7 @@ class Machine {
   static create() {
     return new Machine;
   }
-  withStates() {
+  withStates(..._states) {
     return this;
   }
   finalize({

package/package.json

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