@fkws/klonk 0.0.4

package/dist/index.d.ts

@@ -0,0 +1,301 @@
+type Railroad<
+	OutputType,
+	ErrorType = Error
+> = {
+	readonly success: true
+	readonly data: OutputType
+} | {
+	readonly success: false
+	readonly error: ErrorType
+};
+declare abstract class Task<
+	InputType,
+	OutputType,
+	IdentType extends string
+> {
+	ident: IdentType;
+	constructor(ident: IdentType);
+	abstract run(input: InputType): Promise<Railroad<OutputType>>;
+}
+type InputBuilder<
+	SourceType,
+	AllOutputTypes,
+	TaskInputType
+> = (source: SourceType, outputs: AllOutputTypes) => TaskInputType;
+interface Machine<
+	SourceType,
+	AllOutputTypes,
+	TaskInputType,
+	TaskOutputType,
+	IdentType extends string
+> {
+	task: Task<TaskInputType, TaskOutputType, IdentType>;
+	builder: InputBuilder<SourceType, AllOutputTypes, TaskInputType>;
+}
+type NoInfer<T> = [T][T extends any ? 0 : never];
+declare class Playlist<
+	AllOutputTypes extends Record<string, any>,
+	SourceType = unknown
+> {
+	machines: Machine<any, any, any, any, string>[];
+	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>);
+	addTask<
+		TaskInputType,
+		TaskOutputType,
+		const IdentType extends string
+	>(task: Task<TaskInputType, TaskOutputType, IdentType> & {
+		ident: IdentType
+	}, builder: (source: SourceType, outputs: AllOutputTypes) => NoInfer<TaskInputType>): Playlist<AllOutputTypes & { [K in IdentType] : Railroad<TaskOutputType> }, SourceType>;
+	finally(finalizer: (source: SourceType, outputs: AllOutputTypes) => void | Promise<void>): this;
+	run(source: SourceType): Promise<AllOutputTypes>;
+}
+type TriggerEvent<
+	IdentType extends string,
+	T
+> = {
+	triggerIdent: IdentType
+	data: T
+};
+declare class EventQueue<TEventType> {
+	size: number;
+	queue: TEventType[];
+	constructor(size: number);
+	push(item: TEventType): void;
+	shift(): TEventType | undefined;
+	get length(): number;
+}
+declare abstract class Trigger<
+	IdentType extends string,
+	TData
+> {
+	readonly ident: IdentType;
+	protected readonly queue: EventQueue<TriggerEvent<IdentType, TData>>;
+	constructor(ident: IdentType, queueSize?: number);
+	abstract stop(): Promise<void>;
+	protected pushEvent(data: TData): void;
+	poll(): TriggerEvent<IdentType, TData> | null;
+}
+declare class Workflow<
+	AllTriggerEvents extends TriggerEvent<string, any>,
+	TAllOutputs extends Record<string, any>,
+	TPlaylist extends Playlist<TAllOutputs, AllTriggerEvents> | null
+> {
+	playlist: TPlaylist;
+	triggers: Trigger<string, any>[];
+	constructor(triggers: Trigger<string, any>[], playlist: TPlaylist);
+	addTrigger<
+		const TIdent extends string,
+		TData
+	>(trigger: Trigger<TIdent, TData>): Workflow<AllTriggerEvents | TriggerEvent<TIdent, TData>, TAllOutputs, Playlist<TAllOutputs, AllTriggerEvents | TriggerEvent<TIdent, TData>> | null>;
+	setPlaylist<
+		TBuilderOutputs extends Record<string, any>,
+		TFinalPlaylist extends Playlist<TBuilderOutputs, AllTriggerEvents>
+	>(builder: (p: Playlist<{}, AllTriggerEvents>) => TFinalPlaylist): Workflow<AllTriggerEvents, TBuilderOutputs, TFinalPlaylist>;
+	start({ interval, callback }?: {
+		interval?: number
+		callback?: (source: AllTriggerEvents, outputs: TAllOutputs) => any
+	}): Promise<void>;
+	static create(): Workflow<never, {}, null>;
+}
+import { Logger } from "pino";
+type Transition<TStateData> = {
+	to: StateNode<TStateData> | null
+	condition: (stateData: TStateData) => Promise<boolean>
+	weight?: number
+};
+/**
+* A node in the finite state machine.
+* Each node owns a `Playlist` that is executed upon entering the node and
+* contains weighted conditional transitions to other nodes.
+*
+* @template TStateData - The shape of the external mutable state carried through the machine.
+*/
+declare class StateNode<TStateData> {
+	transitions?: Transition<TStateData>[];
+	playlist: Playlist<any, TStateData>;
+	timeToNextTick: number;
+	ident: string;
+	tempTransitions?: {
+		to: string
+		condition: (stateData: TStateData) => Promise<boolean>
+		weight: number
+	}[];
+	retry: false | number;
+	maxRetries: false | number;
+	/**
+	* Create a `StateNode`.
+	*
+	* @param transitions - The resolved transitions from this node.
+	* @param playlist - The playlist to run when the node is entered.
+	*/
+	constructor(transitions: Transition<TStateData>[], playlist: Playlist<any, TStateData>);
+	/**
+	* Convenience factory for a new `StateNode` with no transitions and an empty playlist.
+	*
+	* @template TStateData
+	* @returns A new, unconfigured `StateNode`.
+	*/
+	static create<TStateData>(): StateNode<TStateData>;
+	/**
+	* Queue a transition to be resolved later during machine finalization.
+	* Use the target node `ident` instead of a direct reference; it will be
+	* resolved to a node instance by the machine.
+	*
+	* @param to - Target state `ident`.
+	* @param condition - Async predicate that decides if the transition should fire.
+	* @param weight - Higher weight wins when multiple conditions are true; ties keep insertion order.
+	* @returns This node for chaining.
+	*/
+	addTransition({ to, condition, weight }: {
+		to: string
+		condition: (stateData: TStateData) => Promise<boolean>
+		weight: number
+	}): StateNode<TStateData>;
+	/**
+	* Set or build the playlist that runs when entering this node.
+	*
+	* Overload 1: supply an already constructed `Playlist`.
+	* Overload 2: supply a builder function receiving an empty `Playlist` and returning a configured one.
+	*
+	* @param arg - Either a `Playlist` instance or a builder function that returns one.
+	* @returns This node for chaining.
+	*/
+	setPlaylist(playlist: Playlist<any, TStateData>): StateNode<TStateData>;
+	setPlaylist<
+		TBuilderOutputs extends Record<string, any>,
+		TFinalPlaylist extends Playlist<TBuilderOutputs, TStateData>
+	>(builder: (p: Playlist<{}, TStateData>) => TFinalPlaylist): StateNode<TStateData>;
+	/**
+	* Disable retry behavior for this node during `Machine.run` when no transition is available.
+	*
+	* @returns This node for chaining.
+	*/
+	preventRetry(): StateNode<TStateData>;
+	/**
+	* Set the delay between retry attempts for this node during `Machine.run`.
+	*
+	* @param delayMs - Delay in milliseconds between retries.
+	* @returns This node for chaining.
+	*/
+	retryDelayMs(delayMs: number): StateNode<TStateData>;
+	/**
+	* Set the maximum number of retries for this node during `Machine.run`.
+	* Use `preventRetry()` to disable retries entirely.
+	*
+	* @param maxRetries - Maximum number of retry attempts before giving up.
+	* @returns This node for chaining.
+	*/
+	retryLimit(maxRetries: number): StateNode<TStateData>;
+	/**
+	* Assign a unique identifier for this node. Required for transition resolution.
+	*
+	* @param ident - Unique node identifier.
+	* @returns This node for chaining.
+	*/
+	setIdent(ident: string): StateNode<TStateData>;
+	/**
+	* Depth-first search for a node by `ident` within the reachable subgraph from this node.
+	*
+	* @param ident - Identifier to search for.
+	* @param visited - Internal cycle-prevention list; callers can ignore.
+	* @returns The matching node or `null` if not found.
+	*/
+	getByIdent(ident: string, visited?: string[]): StateNode<TStateData> | null;
+	/**
+	* Evaluate transitions and select the next node.
+	* Transitions are considered in order of descending weight, with insertion order as a tie-breaker.
+	*
+	* @param data - Current external state used by transition conditions.
+	* @returns The next node if a condition passes; otherwise `null`.
+	*/
+	next(data: TStateData): Promise<StateNode<TStateData> | null>;
+}
+/**
+* A finite state machine that coordinates execution of `StateNode` playlists
+* and transitions between them based on async conditions.
+*
+* @template TStateData - The shape of the external mutable state carried through the machine.
+*/
+declare class Machine2<TStateData> {
+	initialState: StateNode<TStateData> | null;
+	statesToCreate: StateNode<TStateData>[];
+	private currentState;
+	finalized: boolean;
+	logger?: Logger;
+	ident?: string;
+	/**
+	* Compute the set of reachable states starting from the initial state.
+	* Used by `run` to determine completion once all states have been visited.
+	*
+	* @returns An array of reachable `StateNode`s.
+	*/
+	private getAllStates;
+	/**
+	* Sleep helper used for retry delays.
+	*
+	* @param ms - Milliseconds to wait.
+	* @returns A promise that resolves after the delay.
+	*/
+	private sleep;
+	/**
+	* Convenience factory for a new `Machine`.
+	*
+	* @template TStateData
+	* @returns A new unfinalized machine instance.
+	*/
+	static create<TStateData>(): Machine2<TStateData>;
+	/**
+	* Finalize the machine by resolving state transitions and locking configuration.
+	* Must be called before `start` or `run`.
+	*
+	* @param options - Finalization options.
+	* @param options.verbose - Enable pino logging for the machine lifecycle.
+	* @param options.ident - Optional fixed identifier; if omitted, a UUID is generated.
+	* @returns This machine for chaining.
+	* @throws If there is no initial state, no states have been added, a state is missing an ident, or idents are duplicated.
+	*/
+	finalize({ verbose, ident }?: {
+		verbose?: boolean
+		ident?: string
+	}): Machine2<TStateData>;
+	/**
+	* Add a state to the machine.
+	*
+	* @param state - The state node to add.
+	* @param options - Options controlling how the state is added.
+	* @param options.initial - If true, marks this state as the initial state.
+	* @returns This machine for chaining.
+	*/
+	addState(state: StateNode<TStateData>, options?: {
+		initial?: boolean
+	}): Machine2<TStateData>;
+	/**
+	* Start the machine in a repeated tick loop. Executes the current state's playlist,
+	* evaluates transitions, and schedules the next tick with `setTimeout`.
+	* The method returns immediately after initializing the loop.
+	*
+	* @param stateData - Mutable external state provided to playlists and transition conditions.
+	* @param options - Start options.
+	* @param options.interval - Tick interval in milliseconds (default 1000ms).
+	* @returns A promise that resolves once the loop has been initiated.
+	* @throws If the machine has not been finalized or no initial state is set.
+	*/
+	start(stateData: TStateData, options?: {
+		interval?: number
+	}): Promise<void>;
+	/**
+	* Run the machine synchronously until it reaches a terminal condition:
+	* - A leaf state (no transitions)
+	* - No transition and retries disabled
+	* - Retry limit exhausted
+	* - Returning to the initial state
+	* - All reachable states have been visited
+	*
+	* @param stateData - Mutable external state provided to playlists and transition conditions.
+	* @returns A promise that resolves once the run completes.
+	* @throws If the machine has not been finalized or no initial state is set.
+	*/
+	run(stateData: TStateData): Promise<TStateData>;
+}
+export { Workflow, TriggerEvent, Trigger, Task, StateNode, Railroad, Playlist, Machine2 as Machine };