flowcraft 1.0.0-beta.8 → 1.0.0

package/dist/index.d.ts

@@ -1,1056 +1,16 @@
-/**
- * A type-safe, opaque key for storing and retrieving values from the Context.
- * Using a `ContextKey` provides compile-time safety for your workflow's state.
- * @template T The type of the value this key refers to.
- */
-type ContextKey<T> = symbol & {
-    __type: T;
-};
-/**
- * Creates a new, unique `ContextKey` for type-safe access to the `Context`.
- * @template T The type of the value this key will hold.
- * @param description An optional description for debugging purposes (e.g., in logs or test snapshots).
- * @returns A unique `ContextKey<T>`.
- */
-declare const contextKey: <T>(description?: string) => ContextKey<T>;
-/**
- * Defines the interface for the shared context object passed through the workflow.
- * It acts as the shared memory for all nodes in a flow. It supports both
- * type-safe `ContextKey`s and flexible `string` keys.
- */
-interface Context {
-    /** Retrieves a value from the context. */
-    get: (<T>(key: ContextKey<T>) => T | undefined) & (<T = any>(key: string) => T | undefined);
-    /** Stores a value in the context. */
-    set: (<T>(key: ContextKey<T>, value: T) => this) & ((key: string, value: any) => this);
-    /** Checks if a key exists in the context. */
-    has: ((key: ContextKey<any>) => boolean) & ((key: string) => boolean);
-    /** Returns an iterator of all [key, value] pairs in the context. */
-    entries: () => IterableIterator<[any, any]>;
-}
-/**
- * The default, `Map`-based implementation of the `Context` interface.
- */
-declare class TypedContext implements Context {
-    private data;
-    /**
-     * @param initialData An optional iterable (like an array of `[key, value]` pairs)
-     * to initialize the context with.
-     */
-    constructor(initialData?: Iterable<readonly [ContextKey<any> | string, any]> | null);
-    get(key: ContextKey<any> | string): any;
-    set(key: ContextKey<any> | string, value: any): this;
-    has(key: ContextKey<any> | string): boolean;
-    entries(): IterableIterator<[any, any]>;
-}
-/** A function that takes a `Context` and returns a (potentially new) `Context`. */
-type ContextTransform = (ctx: Context) => Context;
-/**
- * A "lens" provides a way to "focus" on a single key in the `Context`,
- * creating reusable, type-safe functions to get, set, or update its value.
- * @template T The type of the value the lens focuses on.
- */
-interface ContextLens<T> {
-    /** Retrieves the value for the key from the context. */
-    get: (ctx: Context) => T | undefined;
-    /** Returns a `ContextTransform` function that will set the key to the provided value. */
-    set: (value: T) => ContextTransform;
-    /** Returns a `ContextTransform` function that updates the key's value based on its current value. */
-    update: (fn: (current: T | undefined) => T) => ContextTransform;
-}
-/**
- * Creates a `ContextLens` object for a specific `ContextKey`.
- * This is the entry point for functional context manipulation.
- *
- * @example
- * const NAME = contextKey<string>('name')
- * const nameLens = lens(NAME)
- * const setNameTransform = nameLens.set('Alice') // This is a function: (ctx) => ctx.set(NAME, 'Alice')
- *
- * @param key The `ContextKey` to focus on.
- * @returns A `ContextLens<T>` object with `.get()`, `.set()`, and `.update()` methods.
- */
-declare function lens<T>(key: ContextKey<T>): ContextLens<T>;
-/**
- * Composes multiple `ContextTransform` functions into a single `ContextTransform` function.
- * The transformations are applied in the order they are provided.
- *
- * @param transforms A sequence of `ContextTransform` functions.
- * @returns A single function that applies all transformations.
- */
-declare function composeContext(...transforms: ContextTransform[]): ContextTransform;
-
-/**
- * Defines the interface for a logger that can be used by the workflow engine.
- * This allows for plugging in any logging library (e.g., Pino, Winston).
- */
-interface Logger {
-    debug: (message: string, context?: object) => void;
-    info: (message: string, context?: object) => void;
-    warn: (message: string, context?: object) => void;
-    error: (message: string, context?: object) => void;
-}
-/**
- * A logger implementation that performs no action (a "no-op" logger).
- * This is the default logger used by the framework if none is provided,
- * making Flowcraft silent out-of-the-box.
- */
-declare class NullLogger implements Logger {
-    debug(): void;
-    info(): void;
-    warn(): void;
-    error(): void;
-}
-type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-/**
- * A default logger implementation that writes messages to the `console`.
- * It supports a minimum log level to control verbosity.
- */
-declare class ConsoleLogger implements Logger {
-    private minLevel;
-    /**
-     * @param options Configuration for the logger.
-     * @param options.level The minimum level of messages to log. Defaults to 'info'.
-     */
-    constructor(options?: {
-        level?: LogLevel;
-    });
-    private log;
-    debug(message: string, context?: object): void;
-    info(message: string, context?: object): void;
-    warn(message: string, context?: object): void;
-    error(message: string, context?: object): void;
-}
-
-/**
- * Defines the contract for a workflow execution engine.
- * An executor is responsible for taking a `Flow` definition and running it,
- * orchestrating the traversal of the node graph.
- */
-interface IExecutor {
-    /**
-     * Executes a given flow with a specific context and options.
-     * @param flow The `Flow` instance to execute.
-     * @param context The shared `Context` for the workflow run.
-     * @param options Runtime options, which can include a logger, abort controller, or initial params.
-     * @returns A promise that resolves with the final action of the workflow, or another result
-     * depending on the executor's implementation (e.g., a job ID for a distributed executor).
-     */
-    run: <T>(flow: Flow<any, T>, context: Context, options?: RunOptions) => Promise<T>;
-}
-/**
- * Internal, normalized run options used by executors.
- * @internal
- */
-interface InternalRunOptions {
-    logger: Logger;
-    signal?: AbortSignal;
-    params: Params;
-    executor: IExecutor;
-}
-
-/** A generic type for key-value parameters. */
-type Params = Record<string, any>;
-/** The default action returned by a node for linear progression. */
-declare const DEFAULT_ACTION: unique symbol;
-/** The action returned by a `.filter()` node when the predicate fails. */
-declare const FILTER_FAILED: unique symbol;
-/**
- * The standard arguments object passed to a node's lifecycle methods.
- * @template PrepRes The type of the `prepRes` property.
- * @template ExecRes The type of the `execRes` property.
- * @template TParams The type for the node's static parameters.
- */
-interface NodeArgs<PrepRes = any, ExecRes = any, TParams extends Params = Params> {
-    /** The shared, mutable context for the workflow run. */
-    ctx: Context;
-    /** The static parameters for the node, merged from the node and flow's `withParams`. */
-    params: TParams;
-    /** An `AbortController` to gracefully cancel the workflow. */
-    controller?: AbortController;
-    /** An `AbortSignal` for handling cancellation. */
-    signal?: AbortSignal;
-    /** The logger instance for the workflow run. */
-    logger: Logger;
-    /** The result of the `prep` phase. */
-    prepRes: PrepRes;
-    /** The result of the `exec` phase. */
-    execRes: ExecRes;
-    /** The final error object, available only in `execFallback`. */
-    error?: Error;
-    /** The name of the Node's constructor, for logging. */
-    name?: string;
-    /** A reference to the current `IExecutor` running the flow. */
-    executor?: IExecutor;
-}
-/**
- * The context object passed to a node's internal `_run` method.
- * @internal
- */
-interface NodeRunContext {
-    ctx: Context;
-    params: Params;
-    signal?: AbortSignal;
-    logger: Logger;
-    executor?: IExecutor;
-}
-/** Options for configuring a `Node` instance. */
-interface NodeOptions {
-    /** The total number of times the `exec` phase will be attempted. Defaults to `1`. */
-    maxRetries?: number;
-    /** The time in milliseconds to wait between failed `exec` attempts. Defaults to `0`. */
-    wait?: number;
-}
-/** Options for running a top-level `Flow`. */
-interface RunOptions {
-    /** An `AbortController` to gracefully cancel the workflow. */
-    controller?: AbortController;
-    /** An `AbortSignal` for handling cancellation. */
-    signal?: AbortSignal;
-    /** A `Logger` instance to receive logs from the execution engine. */
-    logger?: Logger;
-    /** Top-level parameters to be merged into the context for the entire run. */
-    params?: Params;
-    /** A custom `IExecutor` instance to run the workflow. Defaults to `InMemoryExecutor`. */
-    executor?: IExecutor;
-}
-/** The function signature for the `next` function passed to middleware. */
-type MiddlewareNext<T = any> = (args: NodeArgs) => Promise<T>;
-/** The function signature for a middleware function. */
-type Middleware<T = any> = (args: NodeArgs, next: MiddlewareNext<T>) => Promise<T>;
-
-/**
- * Defines the schema for all custom node types within a specific workflow application.
- *
- * It is a map where each key is a string identifier for a node `type`
- * (e.g., `'llm-process'`), and the value is an object defining the expected
- * shape of that node's `data` payload.
- *
- * By creating an application-specific interface that extends `NodeTypeMap`,
- * you enable compile-time validation and autocompletion for your declarative
- * graph definitions. This type is the central generic constraint used by
- * `TypedWorkflowGraph`, `TypedNodeRegistry`, and `GraphBuilder` to provide a
- * fully type-safe development experience.
- *
- * @example
- * // 1. Define the data payloads for your application's nodes.
- * interface MyAppNodeTypeMap extends NodeTypeMap {
- *   'api-call': { url: string; retries: number };
- *   'data-transform': { mode: 'uppercase' | 'lowercase' };
- *   'output': { destination: string };
- * }
- *
- * // 2. Use it to create a type-safe graph definition.
- * const myGraph: TypedWorkflowGraph<MyAppNodeTypeMap> = {
- *   nodes: [
- *     // TypeScript will validate that `data` matches the 'api-call' schema.
- *     { id: 'fetch', type: 'api-call', data: { url: '/users', retries: 3 } },
- *     // TypeScript would throw an error on the following line:
- *     { id: 'bad', type: 'api-call', data: { path: '/users' } } // Missing 'url' and 'retries'
- *   ],
- *   edges: [],
- * };
- */
-interface NodeTypeMap {
-    [key: string]: Record<string, any>;
-}
-/**
- * The standard options object passed to a Node's constructor by the `GraphBuilder`.
- * @template TData The type of the `data` payload for this specific node.
- * @template TContext The type of the dependency injection context.
- */
-interface NodeConstructorOptions<TData, _TContext = object> extends NodeOptions {
-    /** The `data` payload from the graph definition, with `nodeId` injected for logging/debugging. */
-    data: TData & {
-        nodeId: string;
-    };
-    /** A context object containing any dependencies injected into the `GraphBuilder` constructor. */
-    [key: string]: any;
-}
-/**
- * Represents a single, type-safe node within a declarative workflow graph.
- * This is a discriminated union based on the `type` property, ensuring that
- * the `data` payload matches the node's type as defined in the `TypedNodeRegistry`.
- * @template T The `NodeTypeMap` that defines all possible node types and their data schemas.
- */
-type TypedGraphNode<T extends {
-    [K in keyof T]: Record<string, any>;
-}> = {
-    [K in keyof T]: {
-        /** A unique identifier for the node within the graph. */
-        id: string;
-        /** The type of the node, used to look up the corresponding Node class in the registry. */
-        type: K;
-        /** A flexible data object that must match the schema defined in the `NodeTypeMap` for this type. */
-        data: T[K];
-        /** A config object to configure the node's behavior. */
-        config?: NodeOptions;
-    };
-}[keyof T];
-/**
- * Represents a directed edge connecting two nodes in a workflow graph.
- */
-interface GraphEdge {
-    /** The `id` of the source node. */
-    source: string;
-    /** The `id` of the target node. */
-    target: string;
-    /** The action from the source node that triggers this edge. Defaults to `DEFAULT_ACTION`. */
-    action?: string;
-}
-/**
- * Defines the structure of a type-safe, declarative workflow graph.
- * @template T The `NodeTypeMap` that validates the graph's node definitions.
- */
-interface TypedWorkflowGraph<T extends {
-    [K in keyof T]: Record<string, any>;
-}> {
-    /** An array of node definitions. */
-    nodes: TypedGraphNode<T>[];
-    /** An array of edge definitions that connect the nodes. */
-    edges: GraphEdge[];
-}
-/**
- * A type-safe registry that maps a node type string to its corresponding `Node` constructor.
- * @template TNodeMap The `NodeTypeMap` that defines all possible node types and their data schemas.
- * @template TContext The type of the dependency injection context passed to each constructor.
- */
-type TypedNodeRegistry<TNodeMap extends NodeTypeMap, TContext = object> = {
-    [K in keyof TNodeMap as string extends K ? never : number extends K ? never : K]: new (options: NodeConstructorOptions<TNodeMap[K], TContext> & TContext) => AbstractNode;
-};
-/**
- * The result of a successful `GraphBuilder.build()` call.
- */
-interface BuildResult {
-    /** The fully wired, executable `Flow` instance. */
-    flow: Flow;
-    /** A map of all created node instances, keyed by their `id` from the graph definition. */
-    nodeMap: Map<string, AbstractNode>;
-    /** A map of all node `id`s to their predecessor count. */
-    predecessorCountMap: Map<string, number>;
-}
-/**
- * Represents a node within the workflow graph.
- * This is a simpler (UNTYPED) version of the `TypedGraphNode` type
- */
-interface GraphNode {
-    /** A unique identifier for the node within the graph. */
-    id: string;
-    /** The type of the node, used to look up the corresponding Node class in the registry. */
-    type: string;
-    /** A flexible data object that must match the schema defined in the `NodeTypeMap` for this type. */
-    data?: Record<string, any>;
-    /** A config object to configure the node's behavior. */
-    config?: NodeOptions;
-}
-/**
- * Defines the structure of a workflow graph.
- * This is a simpler (UNTYPED) version of the `TypedWorkflowGraph` type
- */
-interface WorkflowGraph {
-    nodes: GraphNode[];
-    edges: GraphEdge[];
-}
-/**
- * A permissive (UNTYPED) registry that maps a node type string to a constructor.
- * This is a simpler (UNTYPED) version of the `TypedNodeRegistry` type
- */
-type NodeRegistry = Map<string, new (...args: any[]) => AbstractNode>;
-interface GraphBuilderOptions {
-    subWorkflowNodeTypes?: string[];
-}
-
-/**
- * The abstract base class for all executable units in a workflow.
- * It provides the core structure for connecting nodes into a graph.
- *
- * @template TPostRes The type for the action returned by the node's `post` method.
- * @template TParams The type for the node's static parameters.
- */
-declare abstract class AbstractNode<TPostRes = any, TParams extends Params = Params> {
-    /** A unique identifier for this node instance, often set by the GraphBuilder. */
-    id?: number | string;
-    /** A key-value store for static parameters that configure the node's behavior. */
-    params: TParams;
-    /** A map of successor nodes, keyed by the action that triggers the transition. */
-    successors: Map<string | typeof DEFAULT_ACTION | typeof FILTER_FAILED | TPostRes, AbstractNode<any, any>>;
-    /** The original graph definition for this node, if created by a GraphBuilder. */
-    graphData?: GraphNode;
-    /**
-     * Sets a unique identifier for this node instance.
-     * Primarily used by the GraphBuilder for wiring and debugging.
-     * @param id The unique ID for the node.
-     * @returns The node instance for chaining.
-     */
-    withId(id: number | string): this;
-    /**
-     * Attaches the original graph definition data to the node instance.
-     * @internal
-     * @param data The graph node definition.
-     * @returns The node instance for chaining.
-     */
-    withGraphData(data: GraphNode): this;
-    /**
-     * Sets or merges static parameters for the node. These parameters are available
-     * via `args.params` in the node's lifecycle methods.
-     * @param params The parameters to merge into the node's existing parameters.
-     * @returns The node instance for chaining.
-     */
-    withParams(params: Partial<TParams>): this;
-    /**
-     * Defines the next node in the sequence for a given action.
-     * This is the primary method for constructing a workflow graph.
-     *
-     * @param node The successor node to execute next.
-     * @param action The action from this node's `post` method that triggers
-     * the transition. Defaults to `DEFAULT_ACTION` for linear flows.
-     * @returns The successor node instance, allowing for further chaining.
-     */
-    next<NextNode extends AbstractNode<any, any>>(node: NextNode, action?: TPostRes | string | typeof DEFAULT_ACTION | typeof FILTER_FAILED): NextNode;
-    /**
-     * The internal method that executes the node's full lifecycle.
-     * It is called by an `IExecutor`.
-     * @internal
-     */
-    abstract _run(ctx: NodeRunContext): Promise<TPostRes>;
-}
-/**
- * The fundamental building block of a workflow, representing a single unit of work.
- * It features a three-phase lifecycle, retry logic, and a fluent API for creating
- * data processing pipelines.
- *
- * @template PrepRes The type of data returned by the `prep` phase.
- * @template ExecRes The type of data returned by the `exec` phase.
- * @template PostRes The type of the action returned by the `post` phase.
- * @template TParams The type for the node's static parameters.
- */
-declare class Node<PrepRes = any, ExecRes = any, PostRes = any, TParams extends Params = Params> extends AbstractNode<PostRes, TParams> {
-    /** The total number of times the `exec` phase will be attempted. */
-    maxRetries: number;
-    /** The time in milliseconds to wait between failed `exec` attempts. */
-    wait: number;
-    /**
-     * @param options Configuration options for the node's behavior.
-     * @param options.maxRetries Total number of `exec` attempts. Defaults to `1`.
-     * @param options.wait Milliseconds to wait between failed `exec` attempts. Defaults to `0`.
-     */
-    constructor(options?: NodeOptions);
-    protected _wrapError(e: any, phase: 'prep' | 'exec' | 'post'): Error;
-    /**
-     * (Lifecycle) Prepares data for execution. Runs once before `exec`.
-     * This is the ideal place to read data from the `Context`.
-     * @param args The arguments for the node, including `ctx` and `params`.
-     * @returns The data required by the `exec` phase.
-     */
-    prep(args: NodeArgs<void, void, TParams>): Promise<PrepRes>;
-    /**
-     * (Lifecycle) Performs the core, isolated logic of the node.
-     * This is the only phase that is retried on failure. It should not access the `Context` directly.
-     * @param args The arguments for the node, including `prepRes`.
-     * @returns The result of the execution.
-     */
-    exec(args: NodeArgs<PrepRes, void, TParams>): Promise<ExecRes>;
-    /**
-     * (Lifecycle) Processes results and determines the next step. Runs once after `exec` succeeds.
-     * This is the ideal place to write data to the `Context`.
-     * @param args The arguments for the node, including `execRes`.
-     * @returns An "action" string to determine which successor to execute next. Defaults to `DEFAULT_ACTION`.
-     */
-    post(args: NodeArgs<PrepRes, ExecRes, TParams>): Promise<PostRes>;
-    /**
-     * (Lifecycle) A fallback that runs if all `exec` retries fail.
-     * If not implemented, the final error will be re-thrown, halting the workflow.
-     * @param args The arguments for the node, including the final `error` that caused the failure.
-     * @returns A fallback result of type `ExecRes`, allowing the workflow to recover and continue.
-     */
-    execFallback(args: NodeArgs<PrepRes, void, TParams>): Promise<ExecRes>;
-    /**
-     * The internal retry-aware execution logic for the `exec` phase.
-     * @internal
-     */
-    _exec(args: NodeArgs<PrepRes, void, TParams>): Promise<ExecRes>;
-    /**
-     * The internal method that executes the node's full lifecycle.
-     * @internal
-     */
-    _run({ ctx, params, signal, logger, executor }: NodeRunContext): Promise<PostRes>;
-    /**
-     * Runs the node as a standalone unit, independent of a larger flow.
-     * This is useful for testing individual nodes in isolation.
-     *
-     * @param ctx The shared workflow context.
-     * @param options Runtime options like a logger or abort controller.
-     * @returns The result of the node's `post` method (its action).
-     */
-    run(ctx: Context, options?: RunOptions): Promise<PostRes>;
-    /**
-     * Creates a new node that transforms the result of this node's `exec` phase.
-     *
-     * @remarks
-     * This method returns a **new** `Node` instance and does not modify the original.
-     * The new node inherits the original's `prep` method. The original `post` method
-     * is discarded as it is incompatible with the new result type.
-     *
-     * @example
-     * const fetchUserNode = new FetchUserNode() // returns { id: 1, name: 'Alice' }
-     * const getUserNameNode = fetchUserNode.map(user => user.name) // returns 'Alice'
-     *
-     * @param fn A sync or async function to transform the execution result from `ExecRes` to `NewRes`.
-     * @returns A new `Node` instance with the transformed output type.
-     */
-    map<NewRes>(fn: (result: ExecRes) => NewRes | Promise<NewRes>): Node<PrepRes, NewRes, any, TParams>;
-    /**
-     * Creates a new node that stores the result of this node's `exec` phase in the `Context`.
-     * This is a common terminal operation for a data processing chain.
-     *
-     * @remarks
-     * This method returns a **new** `Node` instance and does not modify the original.
-     *
-     * @example
-     * const USER_NAME = contextKey<string>('user_name')
-     * const workflow = new FetchUserNode()
-     *   .map(user => user.name)
-     *   .toContext(USER_NAME)
-     *
-     * @param key The type-safe `ContextKey` to use for storing the result.
-     * @returns A new `Node` instance that performs the context update in its `post` phase.
-     */
-    toContext(key: ContextKey<ExecRes>): Node<PrepRes, ExecRes, any, TParams>;
-    /**
-     * Creates a new node that acts as a conditional gate based on the `exec` result.
-     * If the predicate returns `true`, the node returns `DEFAULT_ACTION`.
-     * If it returns `false`, the node returns `FILTER_FAILED`, enabling branching.
-     *
-     * @remarks
-     * This method returns a **new** `Node` instance and does not modify the original.
-     *
-     * @example
-     * const checkAdminNode = new FetchUserNode().filter(user => user.isAdmin)
-     *
-     * checkAdminNode.next(adminOnlyNode, DEFAULT_ACTION)
-     * checkAdminNode.next(accessDeniedNode, FILTER_FAILED)
-     *
-     * @param predicate A sync or async function that returns `true` or `false`.
-     * @returns A new `Node` instance that implements the filter logic.
-     */
-    filter(predicate: (result: ExecRes) => boolean | Promise<boolean>): Node<PrepRes, ExecRes, any, TParams>;
-    /**
-     * Creates a new node that performs a side effect with the `exec` result,
-     * but passes the original result through unmodified. Ideal for logging or debugging.
-     *
-     * @remarks
-     * This method returns a **new** `Node` instance and does not modify the original.
-     *
-     * @example
-     * const workflow = new FetchUserNode()
-     *   .tap(user => console.log('Fetched User:', user))
-     *   .map(user => user.id)
-     *
-     * @param fn A function to call with the execution result for its side effect.
-     * @returns A new `Node` instance that wraps the original.
-     */
-    tap(fn: (result: ExecRes) => void | Promise<void>): Node<PrepRes, ExecRes, PostRes, TParams>;
-    /**
-     * Creates a new node that applies a context mutation using a lens before executing.
-     * This allows for declaratively setting or updating context as part of a fluent chain.
-     *
-     * @remarks
-     * This method returns a **new** `Node` instance and does not modify the original.
-     *
-     * @example
-     * const VALUE = contextKey<number>('value')
-     * const valueLens = lens(VALUE)
-     *
-     * const nodeWithLens = new SomeNode().withLens(valueLens, 42) // Sets VALUE to 42 before SomeNode runs
-     *
-     * @param lens The `ContextLens` to use for the operation.
-     * @param value The value to set in the context via the lens.
-     * @returns A new `Node` instance that applies the context change.
-     */
-    withLens<T>(lens: ContextLens<T>, value: T): Node<PrepRes, ExecRes, PostRes, TParams>;
-}
-/**
- * A special type of `Node` that orchestrates a graph of other nodes.
- * It can contain its own middleware and can be composed within other flows.
- *
- * @template PrepRes The type of data returned by the `prep` phase.
- * @template ExecRes The type of data returned by the `exec` phase (the final action).
- * @template TParams The type for the flow's static parameters.
- */
-declare class Flow<PrepRes = any, ExecRes = any, TParams extends Params = Params> extends Node<PrepRes, ExecRes, ExecRes, TParams> {
-    /** The first node to be executed in this flow's graph. */
-    startNode?: AbstractNode<any, any>;
-    /** An array of middleware functions to be applied to every node within this flow. */
-    middleware: Middleware[];
-    /**
-     * @param start An optional node to start the flow with.
-     */
-    constructor(start?: AbstractNode<any, any>);
-    protected _wrapError(e: any, phase: 'prep' | 'exec' | 'post'): Error;
-    /**
-     * Adds a middleware function to this flow. Middleware will be executed in the
-     * order it is added, wrapping the execution of every node within this flow.
-     * @param fn The middleware function to add.
-     * @returns The `Flow` instance for chaining.
-     */
-    use(fn: Middleware): this;
-    /**
-     * Sets the starting node of the flow's graph.
-     * @param start The node to start with.
-     * @returns The start node instance, allowing for further chaining (`.next()`).
-     */
-    start<StartNode extends AbstractNode<any, any>>(start: StartNode): StartNode;
-    /**
-     * (Lifecycle) Executes this flow's internal graph when it is used as a sub-flow
-     * (a node within a larger flow).
-     * @internal
-     * @param args The arguments for the node, passed down from the parent executor.
-     * @returns The final action returned by the last node in this flow's graph.
-     */
-    exec(args: NodeArgs<any, any, TParams>): Promise<ExecRes>;
-    /**
-     * (Lifecycle) The post-execution step for a `Flow` node. It simply passes through
-     * the final action from its internal graph execution (`execRes`).
-     * @internal
-     */
-    post({ execRes }: NodeArgs<PrepRes, ExecRes, TParams>): Promise<ExecRes>;
-    /**
-     * Runs the entire flow as a top-level entry point.
-     * @param ctx The shared workflow context.
-     * @param options Runtime options like a logger, abort controller, or a custom executor.
-     * @returns The final action returned by the last node in the flow.
-     */
-    run(ctx: Context, options?: RunOptions): Promise<ExecRes>;
-    /**
-     * Finds a node within the flow's graph by its unique ID.
-     *
-     * This method performs a breadth-first search starting from the `startNode`.
-     * It is a convenient way to get a reference to a specific node instance
-     * for debugging or dynamic modifications.
-     *
-     * @remarks
-     * This performs a graph traversal on each call, which has a time complexity
-     * proportional to the number of nodes and edges in the graph (O(V+E)). For
-     * performance-critical applications or flows built with `GraphBuilder`,
-     * it is more efficient to use the `nodeMap` returned by `GraphBuilder.build()`.
-     *
-     * @param id The unique ID of the node to find (set via `.withId()` or by the `GraphBuilder`).
-     * @returns The `AbstractNode` instance if found, otherwise `undefined`.
-     */
-    getNodeById(id: string | number): AbstractNode<any, any> | undefined;
-}
-
-/**
- * Error thrown when a workflow is gracefully aborted via an `AbortSignal`.
- * This error is caught by the execution engine to halt the flow.
- */
-declare class AbortError extends Error {
-    constructor(message?: string);
-}
-/**
- * A custom error class for failures within a workflow, providing additional
- * context about where and when the error occurred.
- */
-declare class WorkflowError extends Error {
-    readonly nodeName: string;
-    readonly phase: 'prep' | 'exec' | 'post';
-    readonly originalError?: Error;
-    /**
-     * @param message The error message.
-     * @param nodeName The name of the `Node` class where the error occurred.
-     * @param phase The lifecycle phase (`'prep'`, `'exec'`, or `'post'`) where the error was thrown.
-     * @param originalError The underlying error that was caught and wrapped.
-     */
-    constructor(message: string, nodeName: string, phase: 'prep' | 'exec' | 'post', originalError?: Error);
-}
-
-/**
- * A type-safe helper function for creating a `TypedNodeRegistry`.
- * This function preserves the strong typing of the registry object, enabling
- * compile-time validation of `TypedWorkflowGraph` definitions.
- *
- * @param registry The registry object, where keys are node types and values are `Node` constructors.
- * @returns The same registry object, correctly typed for use with `GraphBuilder`.
- */
-declare function createNodeRegistry<TNodeMap extends NodeTypeMap, TContext = object>(registry: TypedNodeRegistry<TNodeMap, TContext>): TypedNodeRegistry<TNodeMap, TContext>;
-/**
- * Constructs an executable `Flow` from a declarative `WorkflowGraph` definition.
- * @template TNodeMap A `NodeTypeMap` for validating type-safe graph definitions.
- * @template TContext The shape of the dependency injection context object.
- */
-declare class GraphBuilder<TNodeMap extends NodeTypeMap, TContext extends {
-    registry?: any;
-} = object> {
-    private nodeOptionsContext;
-    private registry;
-    private subWorkflowNodeTypes;
-    private logger;
-    /**
-     * @param registry A type-safe object or a `Map` where keys are node `type` strings and
-     * values are the corresponding `Node` class constructors. For type-safety, use `createNodeRegistry`.
-     * @param nodeOptionsContext An optional object that is passed to every node's
-     * constructor, useful for dependency injection (e.g., passing a database client or the builder itself).
-     */
-    constructor(registry: TypedNodeRegistry<TNodeMap, TContext>, nodeOptionsContext?: TContext, options?: GraphBuilderOptions, logger?: Logger);
-    constructor(registry: NodeRegistry, nodeOptionsContext?: Record<string, any>, options?: GraphBuilderOptions, logger?: Logger);
-    private _logMermaid;
-    private _flattenGraph;
-    /**
-     * Builds a runnable `Flow` from a graph definition.
-     * @param graph The `WorkflowGraph` object describing the flow.
-     * @returns A `BuildResult` object containing the executable `flow` and a `nodeMap`.
-     */
-    build(graph: TypedWorkflowGraph<TNodeMap>): BuildResult;
-    build(graph: WorkflowGraph): BuildResult;
-    /**
-     * Finds the first node where all parallel branches converge.
-     * Uses a Breadth-First Search to guarantee finding the nearest convergence point.
-     * @param parallelNodes - The set of nodes running in parallel.
-     * @param edgeGroups - The map of all graph edges.
-     * @returns The convergence node, or undefined if they never converge.
-     * @private
-     */
-    private _findConvergenceNode;
-}
-
-/**
- * A type for a pure function that can be executed within a `Node`,
- * typically taking the node's `params` as input.
- * @template TIn The input type, corresponding to `params`.
- * @template TOut The output type, which becomes the node's `execRes`.
- */
-type NodeFunction<TIn = any, TOut = any> = (input: TIn) => TOut | Promise<TOut>;
-/**
- * A type for a function that operates on the shared `Context` in addition
- * to the node's `params`.
- * @template TIn The input type, corresponding to `params`.
- * @template TOut The output type, which becomes the node's `execRes`.
- */
-type ContextFunction<TIn = any, TOut = any> = (ctx: Context, input: TIn) => TOut | Promise<TOut>;
-/**
- * Creates a `Node` from a simple, pure function that transforms an input to an output.
- * The node's `params` object is passed as the input to the function.
- *
- * @example
- * const add = (n: number) => mapNode<{ value: number }, number>(params => params.value + n)
- * const add5Node = add(5) // A reusable node that adds 5 to its input parameter.
- *
- * @param fn A function that takes an input object and returns a result.
- * @returns A new `Node` instance that wraps the function.
- */
-declare function mapNode<TIn extends Params, TOut>(fn: NodeFunction<TIn, TOut>): Node<void, TOut, any, TIn>;
-/**
- * Creates a `Node` from a function that requires access to the shared `Context`.
- * Both the `Context` and the node's `params` are passed as arguments to the function.
- *
- * @example
- * const greeter = contextNode((ctx, params: { name: string }) => {
- *   const language = ctx.get(LANGUAGE_KEY) || 'en'
- *   return language === 'en' ? `Hello, ${params.name}` : `Hola, ${params.name}`
- * })
- *
- * @param fn A function that takes the context and an input object, and returns a result.
- * @returns A new `Node` instance that wraps the function.
- */
-declare function contextNode<TIn extends Params, TOut>(fn: ContextFunction<TIn, TOut>): Node<void, TOut, any, TIn>;
-/**
- * Creates a `Node` that declaratively applies a series of transformations to the `Context`.
- * This is a "side-effect" node used purely for state management; its logic runs in the `prep` phase,
- * and it does not produce an `exec` output.
- *
- * @example
- * const USER_ID = contextKey<string>('user_id')
- * const userLens = lens(USER_ID)
- * const setupUserContext = (userId: string) => transformNode(userLens.set(userId))
- *
- * @param transforms A sequence of `ContextTransform` functions (e.g., from a lens) to apply.
- * @returns A new `Node` instance that will mutate the context when executed.
- */
-declare function transformNode(...transforms: ContextTransform[]): Node;
-/**
- * A functional-style alias for `SequenceFlow`. It constructs a linear workflow
- * where each node executes in the order it is provided.
- *
- * @example
- * const mathPipeline = pipeline(addNode(5), multiplyNode(2))
- *
- * @param nodes A sequence of `Node` instances to chain together.
- * @returns A `Flow` instance representing the linear sequence.
- */
-declare function pipeline(...nodes: Node[]): Flow;
-/**
- * A classic functional composition utility. It takes two functions, `f` and `g`,
- * and returns a new function that computes `f(g(x))`.
- *
- * This is a general-purpose helper, not a `Node` builder itself, but it can be
- * used to create more complex `NodeFunction`s to pass to `mapNode`.
- *
- * @example
- * const add5 = (x: number) => x + 5
- * const multiply2 = (x: number) => x * 2
- * const add5ThenMultiply2 = compose(multiply2, add5) // equivalent to: x => (x + 5) * 2
- *
- * @param f The outer function, which receives the result of `g`.
- * @param g The inner function, which receives the initial input.
- * @returns A new `NodeFunction` that combines both operations.
- */
-declare function compose<A, B, C>(f: NodeFunction<B, C>, g: NodeFunction<A, B>): NodeFunction<A, C>;
-
-/**
- * A `Flow` that creates a linear workflow from a sequence of nodes,
- * automatically chaining them in order.
- */
-declare class SequenceFlow<PrepRes = any, ExecRes = any> extends Flow<PrepRes, ExecRes> {
-    /**
-     * @param nodes A sequence of `Node` or `Flow` instances to be executed in order.
-     */
-    constructor(...nodes: AbstractNode[]);
-}
-/**
- * A `Flow` that executes a collection of different nodes concurrently.
- * This is the core of the "fan-out, fan-in" pattern for structural parallelism.
- * After all parallel branches complete, the flow can proceed to a single successor.
- */
-declare class ParallelFlow extends Flow<any, void> {
-    protected nodesToRun: AbstractNode[];
-    /**
-     * @param nodesToRun The array of nodes to execute concurrently.
-     */
-    constructor(nodesToRun: AbstractNode[]);
-    /**
-     * Orchestrates the parallel execution of all nodes.
-     * @internal
-     */
-    exec({ ctx, params, signal, logger, executor }: NodeArgs): Promise<void>;
-}
-/**
- * An abstract `Flow` that processes a collection of items sequentially, one by one.
- * Subclasses must implement the `prep` method to provide the items and the
- * `nodeToRun` property to define the processing logic for each item.
- */
-declare abstract class BatchFlow<T = any> extends Flow<Iterable<T>, null> {
-    /**
-     * The `Node` instance that will be executed for each item in the batch.
-     * This must be implemented by any subclass.
-     */
-    protected abstract nodeToRun: AbstractNode;
-    constructor();
-    /**
-     * (Abstract) Prepares the list of items to be processed.
-     * This method is called once before the batch processing begins.
-     * @param _args The arguments for the node, including `ctx` and `params`.
-     * @returns An array or iterable of parameter objects, one for each item.
-     * The `nodeToRun` will be executed once for each of these objects.
-     */
-    prep(_args: NodeArgs): Promise<Iterable<any>>;
-    /**
-     * Orchestrates the sequential execution of `nodeToRun` for each item.
-     * @internal
-     */
-    exec(args: NodeArgs): Promise<null>;
-}
-/**
- * An abstract `Flow` that processes a collection of items concurrently.
- * Subclasses must implement the `prep` method to provide the items and the
- * `nodeToRun` property to define the processing logic for each item.
- * This provides a significant performance boost for I/O-bound tasks.
- */
-declare abstract class ParallelBatchFlow<T = any> extends Flow<Iterable<T>, PromiseSettledResult<any>[]> {
-    /**
-     * The `Node` instance that will be executed concurrently for each item in the batch.
-     * This must be implemented by any subclass.
-     */
-    protected abstract nodeToRun: AbstractNode;
-    constructor();
-    /**
-     * (Abstract) Prepares the list of items to be processed.
-     * This method is called once before the batch processing begins.
-     * @param _args The arguments for the node, including `ctx` and `params`.
-     * @returns An array or iterable of parameter objects, one for each item.
-     * The `nodeToRun` will be executed concurrently for each of these objects.
-     */
-    prep(_args: NodeArgs): Promise<Iterable<any>>;
-    /**
-     * Orchestrates the parallel execution of `nodeToRun` for each item.
-     * @internal
-     */
-    exec(args: NodeArgs<any, void>): Promise<PromiseSettledResult<any>[]>;
-}
-/**
- * Creates a flow that applies a mapping function to each item in a collection in parallel
- * and returns a new array containing the results.
- *
- * @example
- * const numbers = [1, 2, 3];
- * const double = (n: number) => n * 2;
- * const processingFlow = mapCollection(numbers, double);
- * // When run, processingFlow's result will be [2, 4, 6]
- *
- * @param items The initial array of items of type `T`.
- * @param fn An async or sync function that transforms an item from type `T` to type `U`.
- * @returns A `Flow` instance that, when run, will output an array of type `U[]`.
- */
-declare function mapCollection<T, U>(items: T[], fn: NodeFunction<T, U>): Flow<void, U[]>;
-/**
- * Creates a flow that filters a collection based on a predicate function,
- * returning a new array containing only the items that pass the predicate.
- * The predicate is applied to all items concurrently.
- *
- * @example
- * const users = [{ id: 1, admin: true }, { id: 2, admin: false }];
- * const isAdmin = async (user: { admin: boolean }) => user.admin;
- * const adminFilterFlow = filterCollection(users, isAdmin);
- * // When run, the result will be [{ id: 1, admin: true }]
- *
- * @param items The initial array of items of type `T`.
- * @param predicate An async or sync function that returns `true` or `false` for an item.
- * @returns A `Flow` instance that, when run, will output a filtered array of type `T[]`.
- */
-declare function filterCollection<T>(items: T[], predicate: (item: T) => boolean | Promise<boolean>): Flow<void, T[]>;
-/**
- * Creates a flow that reduces a collection to a single value by executing a
- * reducer function sequentially for each item, similar to `Array.prototype.reduce()`.
- *
- * @example
- * const numbers = [1, 2, 3, 4];
- * const sumReducer = (acc: number, val: number) => acc + val;
- * const sumFlow = reduceCollection(numbers, sumReducer, 0);
- * // When run, the result will be 10.
- *
- * @param items The array of items to be reduced.
- * @param reducer An async or sync function that processes the accumulator and the current item.
- * @param initialValue The initial value for the accumulator.
- * @returns A `Flow` instance that, when run, will output the final accumulated value of type `U`.
- */
-declare function reduceCollection<T, U>(items: T[], reducer: (accumulator: U, item: T) => U | Promise<U>, initialValue: U): Flow<void, U>;
-
-/**
- * The default executor that runs a workflow within a single, in-memory process.
- * This class contains the core logic for traversing a workflow graph, applying middleware,
- * and handling node execution.
- */
-declare class InMemoryExecutor implements IExecutor {
-    /**
-     * A stateless, reusable method that orchestrates the traversal of a graph.
-     * It is called by `run()` for top-level flows and by `Flow.exec()` for sub-flows.
-     * @param startNode The node where the graph traversal begins.
-     * @param flowMiddleware The middleware array from the containing flow.
-     * @param context The shared workflow context.
-     * @param options The internal, normalized run options.
-     * @returns The final action from the last executed node in the graph.
-     * @internal
-     */
-    _orch<T = any>(startNode: AbstractNode, flowMiddleware: Middleware[], context: Context, options: InternalRunOptions): Promise<T>;
-    /**
-     * Executes a given flow with a specific context and options.
-     * This is the main entry point for the in-memory execution engine.
-     * @param flow The Flow instance to execute.
-     * @param context The shared context for the workflow.
-     * @param options Runtime options, including a logger, abort controller, or initial params.
-     * @returns A promise that resolves with the final action of the workflow.
-     */
-    run<T>(flow: Flow<any, T>, context: Context, options?: RunOptions): Promise<T>;
-    run(flow: Flow, context: Context, options?: RunOptions): Promise<any>;
-    /**
-     * Determines the next node to execute based on the action returned by the current node.
-     * @internal
-     */
-    getNextNode(curr: AbstractNode, action: any, logger: Logger): AbstractNode | undefined;
-}
-
-/** The rich metadata object returned by the analyzeGraph function. */
-interface GraphAnalysis<T extends NodeTypeMap = any> {
-    /** A map of all nodes, keyed by ID, augmented with their connection degrees. */
-    nodes: Map<string, TypedGraphNode<T> & {
-        inDegree: number;
-        outDegree: number;
-    }>;
-    /** An array of all node IDs in the graph. */
-    allNodeIds: string[];
-    /** An array of node IDs that have no incoming edges. */
-    startNodeIds: string[];
-    /** A list of cycles found in the graph. Each cycle is an array of node IDs. */
-    cycles: string[][];
-}
-/** A standard structure for reporting a single validation error. */
-interface ValidationError {
-    /** The ID of the node where the error occurred, if applicable. */
-    nodeId?: string;
-    /** A category for the error, e.g., 'CycleDetected', 'ConnectionRuleViolation'. */
-    type: string;
-    /** A human-readable message explaining the validation failure. */
-    message: string;
-}
-/**
- * A function that takes a graph analysis and the original graph,
- * and returns an array of validation errors.
- */
-type Validator<T extends NodeTypeMap = any> = (analysis: GraphAnalysis<T>, graph: TypedWorkflowGraph<T>) => ValidationError[];
-/**
- * A helper function that creates a type guard for filtering nodes by their type.
- * This simplifies writing type-safe validation rules by removing the need for
- * verbose, explicit type guard syntax.
- *
- * @param type The literal string of the node type to check for.
- * @returns A type guard function that narrows the node to its specific type.
- */
-declare function isNodeType<T extends NodeTypeMap, K extends keyof T>(type: K): (node: TypedGraphNode<T>) => node is TypedGraphNode<T> & {
-    type: K;
-};
-/**
- * Analyzes a declarative workflow graph definition to extract structural metadata.
- * This is a lightweight, static utility that does not instantiate any nodes.
- *
- * @param graph The WorkflowGraph object containing nodes and edges.
- * @returns A GraphAnalysis object containing nodes with degree counts, start nodes, and any cycles.
- */
-declare function analyzeGraph<T extends NodeTypeMap>(graph: TypedWorkflowGraph<T>): GraphAnalysis<T>;
-declare function analyzeGraph(graph: WorkflowGraph): GraphAnalysis;
-/**
- * Factory for creating a generic, reusable validator that checks node properties.
- *
- * @param description A human-readable description of the rule for error messages.
- * @param filter A predicate to select which nodes this rule applies to.
- * @param check A function that validates the properties of a selected node.
- * @returns A Validator function.
- */
-declare function createNodeRule<T extends NodeTypeMap>(description: string, filter: (node: TypedGraphNode<T>) => boolean, check: (node: TypedGraphNode<T> & {
-    inDegree: number;
-    outDegree: number;
-}) => {
-    valid: boolean;
-    message?: string;
-}): Validator<T>;
-declare function createNodeRule(description: string, filter: (node: GraphNode) => boolean, check: (node: GraphNode & {
-    inDegree: number;
-    outDegree: number;
-}) => {
-    valid: boolean;
-    message?: string;
-}): Validator;
-/**
- * A built-in validator that reports any cycles found in the graph.
- */
-declare const checkForCycles: Validator;
-
-/**
- * Generates a Mermaid graph definition from a `Flow` instance.
- * ...
- */
-declare function generateMermaidGraph(flow: Flow): string;
-
-/**
- * An abortable `sleep` utility that pauses execution for a specified duration.
- * It will reject with an `AbortError` if the provided `AbortSignal` is triggered.
- * @param ms The number of milliseconds to sleep.
- * @param signal An optional `AbortSignal` to listen for cancellation.
- */
-declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
-
-/**
- * Composes a chain of middleware functions around a node's execution.
- * @internal
- */
-declare function applyMiddleware<T = any>(middleware: Middleware<T>[], nodeToRun: AbstractNode): MiddlewareNext<T>;
-
-export { AbortError, AbstractNode, BatchFlow, type BuildResult, ConsoleLogger, type Context, type ContextFunction, type ContextKey, type ContextLens, type ContextTransform, DEFAULT_ACTION, FILTER_FAILED, Flow, type GraphAnalysis, GraphBuilder, type GraphBuilderOptions, type GraphEdge, type GraphNode, type IExecutor, InMemoryExecutor, type InternalRunOptions, type Logger, type Middleware, type MiddlewareNext, Node, type NodeArgs, type NodeConstructorOptions, type NodeFunction, type NodeOptions, type NodeRegistry, type NodeRunContext, type NodeTypeMap, NullLogger, ParallelBatchFlow, ParallelFlow, type Params, type RunOptions, SequenceFlow, TypedContext, type TypedGraphNode, type TypedNodeRegistry, type TypedWorkflowGraph, type ValidationError, type Validator, WorkflowError, type WorkflowGraph, analyzeGraph, applyMiddleware, checkForCycles, compose, composeContext, contextKey, contextNode, createNodeRegistry, createNodeRule, filterCollection, generateMermaidGraph, isNodeType, lens, mapCollection, mapNode, pipeline, reduceCollection, sleep, transformNode };
+export { A as AbstractNode, B as BlueprintBuildResult, k as BuildResult, D as DEFAULT_ACTION, a as FILTER_FAILED, F as Flow, o as GraphBuilderOptions, G as GraphEdge, l as GraphNode, I as IExecutor, p as InternalRunOptions, e as Middleware, M as MiddlewareNext, N as Node, b as NodeArgs, g as NodeConstructorOptions, d as NodeOptions, n as NodeRegistry, c as NodeRunContext, f as NodeTypeMap, O as OriginalPredecessorIdMap, P as Params, j as PredecessorIdMap, R as RunOptions, S as SubWorkflowResolver, T as TypedGraphNode, i as TypedNodeRegistry, h as TypedWorkflowGraph, W as WorkflowBlueprint, m as WorkflowGraph } from './types-U76Ukj96.js';
+export { ExecNode, PostNode, PreNode } from './workflow/node-patterns.js';
+export { Context, ContextKey, ContextLens, ContextTransform, TypedContext, composeContext, contextKey, lens } from './context.js';
+export { AbortError, FatalWorkflowError, WorkflowError } from './errors.js';
+export { ConsoleLogger, Logger, NullLogger } from './logger.js';
+export { GraphBuilder, createNodeRegistry } from './builder/graph/graph.js';
+export { ConditionalJoinNode, InputMappingNode, OutputMappingNode, ParallelBranchContainer, SubWorkflowContainerNode } from './builder/graph/internal-nodes.js';
+export { BlueprintExecutor } from './builder/graph/runner.js';
+export { BatchFlow, ParallelBatchFlow, ParallelFlow, SequenceFlow, filterCollection, mapCollection, reduceCollection } from './builder/patterns.js';
+export { InMemoryExecutor } from './executors/in-memory.js';
+export { ContextFunction, NodeFunction, compose, contextNode, mapNode, pipeline, transformNode } from './functions.js';
+export { GraphAnalysis, ValidationError, Validator, analyzeGraph, checkForCycles, createNodeRule, isNodeType } from './utils/analysis.js';
+export { generateMermaidFromBlueprint, generateMermaidGraph } from './utils/mermaid.js';
+export { applyMiddleware } from './utils/middleware.js';
+export { sanitizeGraph } from './utils/sanitize.js';
+export { sleep } from './utils/sleep.js';