@fkws/klonk 0.0.6 → 0.0.8

package/README.md

@@ -1,4 +1,16 @@
-# Klonk
+![Klonk](./.github/assets/logo-full.png)
+
+---
+
+![npm version](https://img.shields.io/npm/v/@fkws/klonk)
+![npm downloads](https://img.shields.io/npm/dm/@fkws/klonk)
+[![codecov](https://codecov.io/gh/klar-web-services/klonk/branch/main/graph/badge.svg?token=2R145SOCWH)](https://codecov.io/gh/klar-web-services/klonk)
+---
+
+![License](https://img.shields.io/github/license/klar-web-services/klonk)
+
+---
+
 *A code-first, type-safe automation engine for TypeScript.*
 
 ## Introduction

package/dist/index.cjs

@@ -451,25 +451,20 @@ class Machine {
           }
           retries++;
         }
-        if (!next) {
-          logger?.info({ phase: "end" }, "No next state after retries, run complete.");
-          return stateData;
-        }
       }
-      if (next === this.initialState) {
+      const resolvedNext = next;
+      if (resolvedNext === this.initialState) {
         logger?.info({ phase: "end" }, "Next state is initial state, run complete.");
         return stateData;
       }
-      logger?.info({ phase: "progress", from: current.ident, to: next.ident }, "Transitioning state.");
-      current = next;
+      logger?.info({ phase: "progress", from: current.ident, to: resolvedNext.ident }, "Transitioning state.");
+      current = resolvedNext;
       await current.playlist.run(stateData);
-      if (current.ident)
-        visitedIdents.add(current.ident);
+      visitedIdents.add(current.ident);
       if (visitedIdents.size >= allStates.length) {
         logger?.info({ phase: "end" }, "All reachable states visited, run complete.");
         return stateData;
       }
     }
-    return stateData;
   }
 }

package/dist/index.d.ts

@@ -1,3 +1,14 @@
+/**
+* A simple discriminated-union result type used by Tasks.
+* Prefer returning a `Railroad` from `Task.run` instead of throwing exceptions.
+*
+* Example:
+* - Success: `{ success: true, data: value }`
+* - Failure: `{ success: false, error }`
+*
+* @template OutputType - The success payload type.
+* @template ErrorType - Optional error payload type (default `Error`).
+*/
 type Railroad<
 	OutputType,
 	ErrorType = Error
@@ -8,20 +19,55 @@ type Railroad<
 	readonly success: false
 	readonly error: ErrorType
 };
+/**
+* Base class for all executable units in Klonk.
+* Implement `validateInput` for runtime checks and `run` for the actual work.
+*
+* The type parameters power Klonk's autocomplete across Playlists and Workflows:
+* - `InputType` is inferred at call sites when you build a Playlist.
+* - `OutputType` becomes available to subsequent tasks under this task's `ident`.
+* - `IdentType` should be a string literal to provide strongly-typed keys in outputs.
+*
+* See README Code Examples for end-to-end usage in Playlists and Machines.
+*
+* @template InputType - Runtime input shape expected by the task.
+* @template OutputType - Result shape produced by the task.
+* @template IdentType - Unique task identifier (use a string literal).
+*/
 declare abstract class Task<
 	InputType,
 	OutputType,
 	IdentType extends string
 > {
 	ident: IdentType;
+	/**
+	* Unique identifier for the task. Also used as the key in Playlist outputs.
+	*/
 	constructor(ident: IdentType);
+	/**
+	* Execute the task logic.
+	* Return a `Railroad` to encode success or failure without throwing.
+	*
+	* @param input - The input object provided by the Playlist builder.
+	* @returns A `Railroad` containing output data on success, or an error on failure.
+	*/
 	abstract run(input: InputType): Promise<Railroad<OutputType>>;
 }
+/**
+* Function used to build the input for a Task from the Playlist context.
+*
+* @template SourceType - The source object passed to `run` (e.g., trigger event or machine state).
+* @template AllOutputTypes - Accumulated outputs from previously executed tasks.
+* @template TaskInputType - Concrete input type required by the target Task.
+*/
 type InputBuilder<
 	SourceType,
 	AllOutputTypes,
 	TaskInputType
 > = (source: SourceType, outputs: AllOutputTypes) => TaskInputType;
+/**
+* @internal Internal assembly type that couples a task with its input builder.
+*/
 interface Machine<
 	SourceType,
 	AllOutputTypes,
@@ -32,14 +78,56 @@ interface Machine<
 	task: Task<TaskInputType, TaskOutputType, IdentType>;
 	builder: InputBuilder<SourceType, AllOutputTypes, TaskInputType>;
 }
+/**
+* Prevent TypeScript from inferring `T` from a builder argument so that the
+* task definition remains the source of truth. Useful for preserving safety
+* when chaining `.addTask` calls.
+*/
 type NoInfer<T> = [T][T extends any ? 0 : never];
+/**
+* An ordered sequence of Tasks executed with strong type inference.
+*
+* As tasks are added via `.addTask`, their outputs are merged into the
+* accumulated `AllOutputTypes` map using the task's `ident` as a key. The
+* next task's input builder receives both the original `source` and the
+* strongly-typed `outputs` from all previous tasks.
+*
+* Typical sources:
+* - Workflow: the trigger event object.
+* - Machine: the current mutable state object.
+*
+* See README Code Examples for how to chain tasks and consume outputs.
+*
+* @template AllOutputTypes - Map of task idents to their `Railroad<Output>` results.
+* @template SourceType - The source object provided to `run`.
+*/
 declare class Playlist<
 	AllOutputTypes extends Record<string, any>,
 	SourceType = unknown
 > {
+	/**
+	* Internal list of task + builder pairs in the order they will run.
+	*/
 	machines: Machine<any, any, any, any, string>[];
+	/**
+	* Optional finalizer invoked after all tasks complete (successfully or not).
+	*/
 	finalizer?: (source: SourceType, outputs: Record<string, any>) => void | Promise<void>;
 	constructor(machines?: Machine<any, any, any, any, string>[], finalizer?: (source: SourceType, outputs: Record<string, any>) => void | Promise<void>);
+	/**
+	* Append a task to the end of the playlist.
+	*
+	* The task's `ident` is used as a key in the aggregated `outputs` object made
+	* available to subsequent builders. The value under that key is the task's
+	* `Railroad<Output>` result, enabling type-safe success/error handling.
+	*
+	* @template TaskInputType - Input required by the task.
+	* @template TaskOutputType - Output produced by the task.
+	* @template IdentType - The task's ident (string literal recommended).
+	* @param task - The task instance to run at this step.
+	* @param builder - Function that builds the task input from `source` and prior `outputs`.
+	* @returns A new Playlist with the output map extended to include this task's result.
+	*/
 	addTask<
 		TaskInputType,
 		TaskOutputType,
@@ -47,9 +135,35 @@ declare class Playlist<
 	>(task: Task<TaskInputType, TaskOutputType, IdentType> & {
 		ident: IdentType
 	}, builder: (source: SourceType, outputs: AllOutputTypes) => NoInfer<TaskInputType>): Playlist<AllOutputTypes & { [K in IdentType] : Railroad<TaskOutputType> }, SourceType>;
+	/**
+	* Register a callback to run after the playlist finishes. Use this hook to
+	* react to the last task or to adjust machine state before a transition.
+	*
+	* Note: The callback receives the strongly-typed `outputs` object.
+	*
+	* @param finalizer - Callback executed once after all tasks complete.
+	* @returns This playlist for chaining.
+	*/
 	finally(finalizer: (source: SourceType, outputs: AllOutputTypes) => void | Promise<void>): this;
+	/**
+	* 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 task's `validateInput` returns false, execution stops with an error.
+	*
+	* @param source - The source object for this run (e.g., trigger event or machine state).
+	* @returns The aggregated, strongly-typed outputs map.
+	*/
 	run(source: SourceType): Promise<AllOutputTypes>;
 }
+/**
+* Event object produced by a `Trigger` and consumed by a `Workflow`.
+*
+* - `triggerIdent` lets a workflow that has multiple triggers disambiguate the source.
+* - `data` is the trigger-specific payload (e.g., webhook body, file metadata, etc.).
+*
+* @template IdentType - Trigger identifier (use a string literal).
+* @template T - Payload type emitted by this trigger.
+*/
 type TriggerEvent<
 	IdentType extends string,
 	T
@@ -57,6 +171,9 @@ type TriggerEvent<
 	triggerIdent: IdentType
 	data: T
 };
+/**
+* @internal Small FIFO queue used by Triggers to buffer events.
+*/
 declare class EventQueue<TEventType> {
 	size: number;
 	queue: TEventType[];
@@ -71,11 +188,46 @@ declare abstract class Trigger<
 > {
 	readonly ident: IdentType;
 	protected readonly queue: EventQueue<TriggerEvent<IdentType, TData>>;
+	/**
+	* Base class for event sources that feed Workflows.
+	* Implementations should acquire resources in `start` and release them in `stop`.
+	* Use `pushEvent` to enqueue new events; Workflows poll with `poll`.
+	*
+	* @param ident - Unique identifier for this trigger (use a string literal).
+	* @param queueSize - Max events buffered (oldest are dropped when at capacity). Default: 50.
+	*/
 	constructor(ident: IdentType, queueSize?: number);
+	/**
+	* Stop the trigger and release any resources.
+	*/
 	abstract stop(): Promise<void>;
+	/**
+	* Enqueue an event for consumption by a Workflow.
+	* Protected to avoid manual emission from outside trigger implementations.
+	*
+	* @param data - Event payload emitted by this trigger.
+	*/
 	protected pushEvent(data: TData): void;
+	/**
+	* Retrieve the next event in the buffer (or null if none available).
+	* Workflows call this in their polling loop.
+	*/
 	poll(): TriggerEvent<IdentType, TData> | null;
 }
+/**
+* Connects one or more `Trigger`s to a `Playlist`.
+* When a trigger emits an event, the playlist runs with that event as `source`.
+*
+* - Add triggers with `addTrigger`.
+* - Configure the playlist using `setPlaylist(p => p.addTask(...))`.
+* - Start polling with `start`, optionally receiving a callback when a run completes.
+*
+* See README Code Examples for building a full workflow.
+*
+* @template AllTriggerEvents - Union of all trigger event shapes in this workflow.
+* @template TAllOutputs - Aggregated outputs map shape produced by the playlist.
+* @template TPlaylist - Concrete playlist type or `null` before configuration.
+*/
 declare class Workflow<
 	AllTriggerEvents extends TriggerEvent<string, any>,
 	TAllOutputs extends Record<string, any>,
@@ -84,24 +236,65 @@ declare class Workflow<
 	playlist: TPlaylist;
 	triggers: Trigger<string, any>[];
 	constructor(triggers: Trigger<string, any>[], playlist: TPlaylist);
+	/**
+	* Register a new trigger to feed events into the workflow.
+	* The resulting workflow type widens its `AllTriggerEvents` union accordingly.
+	*
+	* @template TIdent - Trigger ident (string literal recommended).
+	* @template TData - Payload type emitted by the trigger.
+	* @param trigger - The trigger instance to add.
+	* @returns A new Workflow instance with updated event type.
+	*/
 	addTrigger<
 		const TIdent extends string,
 		TData
 	>(trigger: Trigger<TIdent, TData>): Workflow<AllTriggerEvents | TriggerEvent<TIdent, TData>, TAllOutputs, Playlist<TAllOutputs, AllTriggerEvents | TriggerEvent<TIdent, TData>> | null>;
+	/**
+	* Configure the playlist by providing a builder that starts from an empty
+	* `Playlist<{}, AllTriggerEvents>` and returns your fully configured playlist.
+	*
+	* This method ensures type inference flows from your tasks and idents into
+	* the resulting `TBuilderOutputs` map used by the workflow's callback.
+	*
+	* @template TBuilderOutputs - Aggregated outputs map (deduced from your tasks).
+	* @template TFinalPlaylist - Concrete playlist type returned by the builder.
+	* @param builder - Receives an empty playlist and must return a configured one.
+	* @returns A new Workflow with the concrete playlist and output types.
+	*/
 	setPlaylist<
 		TBuilderOutputs extends Record<string, any>,
 		TFinalPlaylist extends Playlist<TBuilderOutputs, AllTriggerEvents>
 	>(builder: (p: Playlist<{}, AllTriggerEvents>) => TFinalPlaylist): Workflow<AllTriggerEvents, TBuilderOutputs, TFinalPlaylist>;
+	/**
+	* Begin polling triggers and run the playlist whenever an event is available.
+	* The loop uses `setTimeout` with the given `interval` and returns immediately.
+	*
+	* @param interval - Polling interval in milliseconds (default 5000ms).
+	* @param callback - Optional callback executed after each successful playlist run.
+	* @throws If called before a playlist is configured.
+	*/
 	start({ interval, callback }?: {
 		interval?: number
 		callback?: (source: AllTriggerEvents, outputs: TAllOutputs) => any
 	}): Promise<void>;
+	/**
+	* Create a new, empty workflow. Add triggers and set a playlist before starting.
+	*/
 	static create(): Workflow<never, {}, null>;
 }
 import { Logger } from "pino";
+/**
+* A weighted, conditional edge to a target state.
+* Transitions are evaluated in descending `weight` order, then by insertion order.
+*
+* @template TStateData - Mutable state shared across the machine.
+*/
 type Transition<TStateData> = {
+	/** Target state node, resolved during `finalize`. */
 	to: StateNode<TStateData> | null
+	/** Async predicate that decides whether to take this transition. */
 	condition: (stateData: TStateData) => Promise<boolean>
+	/** Higher values are tried first; defaults to 0. */
 	weight?: number
 };
 /**

package/dist/index.js

@@ -397,26 +397,21 @@ class Machine {
           }
           retries++;
         }
-        if (!next) {
-          logger?.info({ phase: "end" }, "No next state after retries, run complete.");
-          return stateData;
-        }
       }
-      if (next === this.initialState) {
+      const resolvedNext = next;
+      if (resolvedNext === this.initialState) {
         logger?.info({ phase: "end" }, "Next state is initial state, run complete.");
         return stateData;
       }
-      logger?.info({ phase: "progress", from: current.ident, to: next.ident }, "Transitioning state.");
-      current = next;
+      logger?.info({ phase: "progress", from: current.ident, to: resolvedNext.ident }, "Transitioning state.");
+      current = resolvedNext;
       await current.playlist.run(stateData);
-      if (current.ident)
-        visitedIdents.add(current.ident);
+      visitedIdents.add(current.ident);
       if (visitedIdents.size >= allStates.length) {
         logger?.info({ phase: "end" }, "All reachable states visited, run complete.");
         return stateData;
       }
     }
-    return stateData;
   }
 }
 export {

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@fkws/klonk",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "A lightweight, extensible workflow automation engine for Node.js and Bun",
+  "repository": "https://github.com/klar-web-services/klonk",
   "module": "dist/index.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,6 +26,9 @@
     "start": "bun index.ts",
     "build": "bunx rimraf dist && bunup",
     "prepublishOnly": "bun run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "release": "bun scripts/release.js",
     "release:patch": "bun scripts/release.js patch",
     "release:minor": "bun scripts/release.js minor",
@@ -41,7 +45,9 @@
   "devDependencies": {
     "@types/bun": "latest",
     "@types/node": "latest",
-    "bunup": "^0.6.2"
+    "@vitest/coverage-v8": "^4.0.3",
+    "bunup": "^0.6.2",
+    "vitest": "^4.0.3"
   },
   "peerDependencies": {
     "typescript": "^5"