flowcraft 1.0.0 → 2.0.0

package/dist/types-U76Ukj96.d.ts

@@ -1,609 +0,0 @@
-import { Context, ContextKey, ContextLens } from './context.js';
-import { Logger } from './logger.js';
-
-/**
- * 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;
-};
-type PredecessorIdMap = Map<string, string[]>;
-type OriginalPredecessorIdMap = Map<string, string[]>;
-/**
- * A serializable, static representation of a compiled workflow graph.
- * This is the "blueprint" that can be stored and shared across distributed workers.
- */
-interface WorkflowBlueprint {
-    /** The final, flattened list of node definitions. */
-    nodes: GraphNode[];
-    /** The final, flattened list of edge definitions. */
-    edges: GraphEdge[];
-    /** A map of all node IDs to their direct predecessor count. */
-    predecessorCountMap: Record<string, number>;
-    /** A map of all node IDs to their logical data-producing predecessors. */
-    originalPredecessorIdMap: Record<string, string[]>;
-    /** The ID of the node where the flow should start. */
-    startNodeId: string;
-}
-/**
- * The result of a `GraphBuilder.buildBlueprint()` call, containing the serializable blueprint.
- */
-interface BlueprintBuildResult {
-    /** The serializable blueprint of the workflow. */
-    blueprint: WorkflowBlueprint;
-}
-/**
- * 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>;
-    /** A map of all node `id`s to an array of their predecessor `id`s. */
-    predecessorIdMap: PredecessorIdMap;
-    /**
-     * A map of all node `id`s to an array of their original (un-namespaced) predecessor `id`s.
-     * This represents the logical dependencies of the graph before flattening.
-     * Note: For sub-workflow nodes, their direct predecessors will be the logical terminal nodes
-     * from *within* that sub-workflow, reflecting the data flow.
-     */
-    originalPredecessorIdMap: OriginalPredecessorIdMap;
-}
-/**
- * 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>;
-/**
- * An interface for an object that can resolve a sub-workflow definition by its ID.
- */
-interface SubWorkflowResolver {
-    getGraph: (id: number | string) => WorkflowGraph | undefined;
-}
-/**
- * Options for configuring the `GraphBuilder`.
- */
-interface GraphBuilderOptions {
-    /**
-     * An array of node type names that should be treated as sub-workflows.
-     * When the builder encounters a node whose type is in this list, it will
-     * attempt to use the `subWorkflowResolver` to fetch and inline the corresponding graph.
-     * @example ['sub-flow', 'reusable-task-group']
-     */
-    subWorkflowNodeTypes?: string[];
-    /**
-     * An object that provides the logic for retrieving a sub-workflow's graph definition.
-     * This is required if the graph contains any nodes whose types are listed in `subWorkflowNodeTypes`.
-     * The `getGraph` method will be called with the `workflowId` from the node's data payload.
-     */
-    subWorkflowResolver?: SubWorkflowResolver;
-    /**
-     * An array of node `type` strings whose outgoing edges represent mutually
-     * exclusive conditional paths, not parallel branches.
-     */
-    conditionalNodeTypes?: 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, TContext extends Context = Context> {
-    /** 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 | TPostRes | typeof DEFAULT_ACTION | typeof FILTER_FAILED, AbstractNode<any, any, TContext>[]>;
-    /** The original graph definition for this node, if created by a GraphBuilder. */
-    graphData?: GraphNode;
-    /** A flag indicating that this node is a container and should be passed through by distributed executors. */
-    isPassthrough: boolean;
-    /**
-     * Gets the original, un-prefixed ID of the node from its graph definition.
-     * This is useful for sub-workflow nodes where the runtime ID might be namespaced (e.g., 'parent:child').
-     */
-    get originalId(): string;
-    /**
-     * 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 or nodes 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. If multiple nodes are provided, it returns the first one.
-     */
-    next<NextNode extends AbstractNode<any, any>>(node: NextNode | 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<TContext>): 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, TContext extends Context = Context> extends AbstractNode<PostRes, TParams, TContext> {
-    /** 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, TContext>): 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, TContext>): 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, TContext>): 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, TContext>): Promise<ExecRes>;
-    /**
-     * The internal retry-aware execution logic for the `exec` phase.
-     * @internal
-     */
-    _exec(args: NodeArgs<PrepRes, void, TParams, TContext>): Promise<ExecRes>;
-    /**
-     * The internal method that executes the node's full lifecycle.
-     * @internal
-     */
-    _run({ ctx, params, signal, logger, executor, visitedInParallel }: NodeRunContext<TContext>): 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: TContext, 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, TContext>;
-    /**
-     * 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, TContext>;
-    /**
-     * 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, TContext>;
-    /**
-     * 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, TContext>;
-    /**
-     * 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, TContext>;
-}
-
-/**
- * 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, TContext extends Context = Context> extends Node<PrepRes, ExecRes, ExecRes, TParams, TContext> {
-    /** 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, TContext>);
-    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, TContext>>(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, TContext>): 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, TContext>): 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: TContext, 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, TContext> | undefined;
-    /**
-     * Retrieves all unique nodes within the flow's graph.
-     * @internal
-     */
-    getAllNodes(): Set<AbstractNode>;
-}
-
-/**
- * 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>;
-    /**
-     * Determines the next node to execute based on the action returned by the current node.
-     * @param curr The current node.
-     * @param action The action returned by the current node.
-     * @returns The next node to execute, or undefined if no further action is required.
-     */
-    getNextNode: (curr: AbstractNode, action: any) => AbstractNode | undefined;
-}
-/**
- * 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, TContext extends Context = Context> {
-    /** The shared, mutable context for the workflow run. */
-    ctx: TContext;
-    /** 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 actual node instance being executed. */
-    node?: AbstractNode;
-    /** A shared set to track visited nodes within a parallel block, preventing race conditions. @internal */
-    visitedInParallel?: Set<AbstractNode>;
-}
-/**
- * The context object passed to a node's internal `_run` method.
- * @internal
- */
-interface NodeRunContext<TContext extends Context = Context> {
-    ctx: TContext;
-    params: Params;
-    signal?: AbortSignal;
-    logger: Logger;
-    executor?: IExecutor;
-    /** A shared set to track visited nodes within a parallel block. @internal */
-    visitedInParallel?: Set<AbstractNode>;
-}
-/** 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>;
-
-export { AbstractNode as A, type BlueprintBuildResult as B, DEFAULT_ACTION as D, Flow as F, type GraphEdge as G, type IExecutor as I, type MiddlewareNext as M, Node as N, type OriginalPredecessorIdMap as O, type Params as P, type RunOptions as R, type SubWorkflowResolver as S, type TypedGraphNode as T, type WorkflowBlueprint as W, FILTER_FAILED as a, type NodeArgs as b, type NodeRunContext as c, type NodeOptions as d, type Middleware as e, type NodeTypeMap as f, type NodeConstructorOptions as g, type TypedWorkflowGraph as h, type TypedNodeRegistry as i, type PredecessorIdMap as j, type BuildResult as k, type GraphNode as l, type WorkflowGraph as m, type NodeRegistry as n, type GraphBuilderOptions as o, type InternalRunOptions as p };

package/dist/utils/analysis.d.ts

@@ -1,75 +0,0 @@
-import { f as NodeTypeMap, T as TypedGraphNode, h as TypedWorkflowGraph, m as WorkflowGraph, l as GraphNode } from '../types-U76Ukj96.js';
-import '../context.js';
-import '../logger.js';
-
-/** 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.
- * A single rule can now return multiple errors for a single node.
- *
- * @param filter A predicate to select which nodes this rule applies to.
- * @param check A function that validates a selected node. It can return a single
- *   ValidationError, an array of them, or null if the node is valid.
- * @returns A Validator function.
- */
-declare function createNodeRule<T extends NodeTypeMap>(filter: (node: TypedGraphNode<T>) => boolean, check: (node: TypedGraphNode<T> & {
-    inDegree: number;
-    outDegree: number;
-}) => ValidationError | ValidationError[] | null | undefined): Validator<T>;
-declare function createNodeRule(filter: (node: GraphNode) => boolean, check: (node: GraphNode & {
-    inDegree: number;
-    outDegree: number;
-}) => ValidationError | ValidationError[] | null | undefined): Validator;
-/**
- * A built-in validator that reports any cycles found in the graph.
- */
-declare const checkForCycles: Validator;
-
-export { type GraphAnalysis, type ValidationError, type Validator, analyzeGraph, checkForCycles, createNodeRule, isNodeType };