flowcraft 2.2.0 → 2.3.1

package/dist/testing/stepper.d.ts

@@ -0,0 +1,79 @@
+import { W as WorkflowState, G as GraphTraverser, J as WorkflowResult, c as FlowRuntime, g as WorkflowBlueprint, n as NodeFunction, o as NodeClass } from '../types-ezHUBdpL.js';
+import '../errors.js';
+import '../container.js';
+
+/**
+ * Represents the controlled, step-by-step execution of a workflow.
+ * Returned by the `createStepper` utility.
+ */
+interface IWorkflowStepper<TContext extends Record<string, any>> {
+    /** The current state of the workflow. Can be inspected after each step. */
+    readonly state: WorkflowState<TContext>;
+    /** The graph traverser instance. Can be used to inspect the frontier or completed nodes. */
+    readonly traverser: GraphTraverser;
+    /**
+     * Executes the next "turn" or batch of ready nodes in the workflow.
+     * @param options Optional configuration for this specific step, like a cancellation signal.
+     * @returns A `WorkflowResult` representing the state after the step, or `null` if the workflow has already completed.
+     */
+    next(options?: {
+        signal?: AbortSignal;
+        concurrency?: number;
+    }): Promise<WorkflowResult<TContext> | null>;
+    /**
+     * Reverts the workflow to its previous state.
+     * @returns The `WorkflowResult` of the previous state, or `null` if there is no history to revert to.
+     */
+    prev(): Promise<WorkflowResult<TContext> | null>;
+    /**
+     * Resets the stepper to its initial state, clearing all progress and history.
+     */
+    reset(): void;
+    /**
+     * A convenience method to check if the workflow has any more steps to run.
+     * @returns `true` if the workflow is complete or stalled, `false` otherwise.
+     */
+    isDone(): boolean;
+}
+/**
+ * A test utility that creates a stepper to execute a workflow one "turn" at a time.
+ * This is invaluable for debugging and writing fine-grained tests where you need to
+ * assert the state of the workflow after each logical step.
+ *
+ * @example
+ * // In your test file
+ * it('should correctly execute step-by-step', async () => {
+ *   const runtime = new FlowRuntime({ ... });
+ *   const flow = createFlow('test')
+ *     .node('a', async () => ({ output: 10 }))
+ *     .node('b', async ({ input }) => ({ output: input * 2 }))
+ *     .edge('a', 'b');
+ *
+ *   const stepper = await createStepper(runtime, flow.toBlueprint(), flow.getFunctionRegistry());
+ *
+ *   // First step (executes node 'a')
+ *   const result1 = await stepper.next();
+ *   expect(stepper.isDone()).toBe(false);
+ *   expect(result1.status).toBe('stalled');
+ *   expect(result1.context._outputs.a).toBe(10);
+ *
+ *   // Second step (executes node 'b')
+ *   const result2 = await stepper.next();
+ *   expect(stepper.isDone()).toBe(true);
+ *   expect(result2.status).toBe('completed');
+ *   expect(result2.context._outputs.b).toBe(20);
+ *
+ *   // Final step (no more work)
+ *   const result3 = await stepper.next();
+ *   expect(result3).toBeNull();
+ * });
+ *
+ * @param runtime The `FlowRuntime` instance, used for its configuration.
+ * @param blueprint The `WorkflowBlueprint` to execute.
+ * @param functionRegistry The function registry from createFlow, containing the node implementations.
+ * @param initialState The initial state for the workflow run.
+ * @returns A Promise that resolves to an `IWorkflowStepper` instance.
+ */
+declare function createStepper<TContext extends Record<string, any>, TDependencies extends Record<string, any>>(runtime: FlowRuntime<TContext, TDependencies>, blueprint: WorkflowBlueprint, functionRegistry: Map<string, NodeFunction | NodeClass>, initialState?: Partial<TContext>): Promise<IWorkflowStepper<TContext>>;
+
+export { type IWorkflowStepper, createStepper };

package/dist/testing/stepper.js

@@ -0,0 +1,11 @@
+export { createStepper } from '../chunk-XNRIM27H.js';
+import '../chunk-G53CSLBF.js';
+import '../chunk-G5BGBPFP.js';
+import '../chunk-233SESC2.js';
+import '../chunk-HAZ26F3P.js';
+import '../chunk-FRKO3WX4.js';
+import '../chunk-CD4FUZOJ.js';
+import '../chunk-R3HQXIEL.js';
+import '../chunk-BCRWXTWX.js';
+//# sourceMappingURL=stepper.js.map
+//# sourceMappingURL=stepper.js.map

package/dist/testing/stepper.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"stepper.js"}

package/dist/types-ezHUBdpL.d.ts

@@ -0,0 +1,564 @@
+import { FlowcraftError } from './errors.js';
+import { DIContainer } from './container.js';
+
+/** A type guard to reliably distinguish a NodeClass from a NodeFunction. */
+declare function isNodeClass(impl: any): impl is NodeClass;
+/**
+ * A structured, class-based node for complex logic with a safe, granular lifecycle.
+ * This class is generic, allowing implementations to specify the exact context
+ * and dependency types they expect.
+ */
+declare abstract class BaseNode<TContext extends Record<string, any> = Record<string, any>, TDependencies extends RuntimeDependencies = RuntimeDependencies, TInput = any, TOutput = any, TAction extends string = string> {
+    protected params?: Record<string, any> | undefined;
+    protected nodeId?: string | undefined;
+    /**
+     * @param params Static parameters for this node instance, passed from the blueprint.
+     * @param nodeId The ID of the node in the blueprint.
+     */
+    constructor(params?: Record<string, any> | undefined, nodeId?: string | undefined);
+    /**
+     * Phase 1: Gathers and prepares data for execution. This phase is NOT retried on failure.
+     * @param context The node's execution context.
+     * @returns The data needed for the `exec` phase.
+     */
+    prep(context: NodeContext<TContext, TDependencies, TInput>): Promise<any>;
+    /**
+     * Phase 2: Performs the core, isolated logic. This is the ONLY phase that is retried.
+     * @param prepResult The data returned from the `prep` phase.
+     * @param context The node's execution context.
+     */
+    abstract exec(prepResult: any, context: NodeContext<TContext, TDependencies, TInput>): Promise<Omit<NodeResult<TOutput, TAction>, 'error'>>;
+    /**
+     * Phase 3: Processes the result and saves state. This phase is NOT retried.
+     * @param execResult The successful result from the `exec` or `fallback` phase.
+     * @param _context The node's execution context.
+     */
+    post(execResult: Omit<NodeResult<TOutput, TAction>, 'error'>, _context: NodeContext<TContext, TDependencies, TInput>): Promise<NodeResult<TOutput, TAction>>;
+    /**
+     * An optional safety net that runs if all `exec` retries fail.
+     * @param error The final error from the last `exec` attempt.
+     * @param _context The node's execution context.
+     */
+    fallback(error: Error, _context: NodeContext<TContext, TDependencies, TInput>): Promise<Omit<NodeResult<TOutput, TAction>, 'error'>>;
+    /**
+     * An optional cleanup phase for non-retriable errors that occur outside the main `exec` method.
+     * This method is invoked in a `finally` block or equivalent construct if a fatal, unhandled exception occurs in the `prep`, `exec`, or `post` phases.
+     * Allows nodes to perform crucial cleanup, such as closing database connections or releasing locks.
+     * @param _error The error that caused the failure.
+     * @param _context The node's execution context.
+     */
+    recover(_error: Error, _context: NodeContext<TContext, TDependencies, TInput>): Promise<void>;
+}
+
+declare class WorkflowState<TContext extends Record<string, any>> {
+    private _completedNodes;
+    private errors;
+    private anyFallbackExecuted;
+    private context;
+    private _isAwaiting;
+    private _awaitingNodeIds;
+    constructor(initialData: Partial<TContext>);
+    addCompletedNode(nodeId: string, output: any): Promise<void>;
+    addError(nodeId: string, error: Error): void;
+    clearError(nodeId: string): void;
+    markFallbackExecuted(): void;
+    getContext(): IAsyncContext<TContext>;
+    getCompletedNodes(): Set<string>;
+    getErrors(): WorkflowError[];
+    getAnyFallbackExecuted(): boolean;
+    markAsAwaiting(nodeId: string): void;
+    isAwaiting(): boolean;
+    getAwaitingNodeIds(): string[];
+    clearAwaiting(nodeId?: string): void;
+    getStatus(isTraversalComplete?: boolean): WorkflowResult['status'];
+    toResult(serializer: ISerializer): Promise<WorkflowResult<TContext>>;
+}
+
+interface ExecutionStrategy {
+    execute: (nodeDef: NodeDefinition, context: NodeContext<any, any, any>, executionId?: string, signal?: AbortSignal) => Promise<NodeResult<any, any>>;
+}
+declare class FunctionNodeExecutor implements ExecutionStrategy {
+    private implementation;
+    private maxRetries;
+    private eventBus;
+    constructor(implementation: NodeFunction, maxRetries: number, eventBus: IEventBus);
+    execute(nodeDef: NodeDefinition, context: NodeContext<any, any, any>, executionId?: string, signal?: AbortSignal): Promise<NodeResult<any, any>>;
+}
+declare class ClassNodeExecutor implements ExecutionStrategy {
+    private implementation;
+    private maxRetries;
+    private eventBus;
+    constructor(implementation: NodeClass, maxRetries: number, eventBus: IEventBus);
+    execute(nodeDef: NodeDefinition, context: NodeContext<any, any, any>, executionId?: string, signal?: AbortSignal): Promise<NodeResult<any, any>>;
+}
+type NodeExecutionResult = {
+    status: 'success';
+    result: NodeResult<any, any>;
+} | {
+    status: 'failed_with_fallback';
+    fallbackNodeId: string;
+    error: FlowcraftError;
+} | {
+    status: 'failed';
+    error: FlowcraftError;
+};
+interface NodeExecutorConfig<TContext extends Record<string, any>, TDependencies extends Record<string, any>> {
+    context: ExecutionContext<TContext, TDependencies>;
+    nodeDef: NodeDefinition;
+    strategy: ExecutionStrategy;
+}
+declare class NodeExecutor<TContext extends Record<string, any>, TDependencies extends Record<string, any>> {
+    private context;
+    private nodeDef;
+    private strategy;
+    constructor(config: NodeExecutorConfig<TContext, TDependencies>);
+    execute(input: any): Promise<NodeExecutionResult>;
+}
+
+interface ReadyNode {
+    nodeId: string;
+    nodeDef: NodeDefinition;
+}
+declare class GraphTraverser {
+    private frontier;
+    private allPredecessors;
+    private dynamicBlueprint;
+    private completedNodes;
+    constructor(blueprint: WorkflowBlueprint, isStrictMode?: boolean);
+    /**
+     * Clears all nodes from the execution frontier.
+     */
+    clearFrontier(): void;
+    /**
+     * Creates and initializes a GraphTraverser from a saved workflow state.
+     * This is the correct way to prepare a traverser for a `resume` operation.
+     * @param blueprint The workflow blueprint.
+     * @param state The workflow state being resumed.
+     * @returns A configured GraphTraverser instance.
+     */
+    static fromState(blueprint: WorkflowBlueprint, state: WorkflowState<any>): GraphTraverser;
+    private isFallbackNode;
+    private getEffectiveJoinStrategy;
+    getReadyNodes(): ReadyNode[];
+    hasMoreWork(): boolean;
+    markNodeCompleted(nodeId: string, result: NodeResult<any, any>, nextNodes: NodeDefinition[]): void;
+    getAllNodeIds(): Set<string>;
+    getFallbackNodeIds(): Set<string>;
+    getCompletedNodes(): Set<string>;
+    getDynamicBlueprint(): WorkflowBlueprint;
+    getAllPredecessors(): Map<string, Set<string>>;
+    addDynamicNode(_nodeId: string, dynamicNode: NodeDefinition, predecessorId: string, gatherNodeId?: string): void;
+    /**
+     * Manually adds a node ID back to the execution frontier.
+     * Used by orchestrators that need fine-grained control over steps.
+     * @param nodeId The ID of the node to add to the frontier.
+     */
+    addToFrontier(nodeId: string): void;
+}
+
+type NodeExecutorFactory = (context: ExecutionContext<any, any>) => (nodeId: string) => NodeExecutor<any, any>;
+interface ExecutionServices {
+    determineNextNodes: (blueprint: WorkflowBlueprint, nodeId: string, result: NodeResult<any, any>, context: ContextImplementation<any>, executionId?: string) => Promise<{
+        node: NodeDefinition;
+        edge: EdgeDefinition;
+    }[]>;
+    applyEdgeTransform: (edge: EdgeDefinition, sourceResult: NodeResult<any, any>, targetNode: NodeDefinition, context: ContextImplementation<any>, allPredecessors?: Map<string, Set<string>>) => Promise<void>;
+    resolveNodeInput: (nodeId: string, blueprint: WorkflowBlueprint, context: any) => Promise<any>;
+}
+interface IOrchestrator {
+    run(context: ExecutionContext<any, any>, traverser: GraphTraverser): Promise<WorkflowResult<any>>;
+}
+
+interface IRuntime<TContext extends Record<string, any> = Record<string, any>, TDependencies extends RuntimeDependencies = RuntimeDependencies> {
+    options: RuntimeOptions<TDependencies>;
+    registry: Map<string, NodeFunction | NodeClass>;
+    executeNode: (blueprint: WorkflowBlueprint, nodeId: string, state: WorkflowState<TContext>, allPredecessors?: Map<string, Set<string>>, functionRegistry?: Map<string, any>, executionId?: string, signal?: AbortSignal) => Promise<NodeResult>;
+    determineNextNodes: (blueprint: WorkflowBlueprint, nodeId: string, result: NodeResult, context: ContextImplementation<TContext>, executionId?: string) => Promise<{
+        node: NodeDefinition;
+        edge: EdgeDefinition;
+    }[]>;
+    applyEdgeTransform: (edge: EdgeDefinition, sourceResult: NodeResult, targetNode: NodeDefinition, context: ContextImplementation<TContext>, allPredecessors?: Map<string, Set<string>>) => Promise<void>;
+    createForSubflow: (subBlueprint: WorkflowBlueprint, initialSubState: Partial<TContext>, executionId: string, signal?: AbortSignal) => ExecutionContext<TContext, TDependencies>;
+    getExecutorForNode: (nodeId: string, context: ExecutionContext<TContext, TDependencies>) => NodeExecutor<TContext, TDependencies>;
+}
+
+declare class FlowRuntime<TContext extends Record<string, any>, TDependencies extends Record<string, any>> implements IRuntime<TContext, TDependencies> {
+    private container;
+    registry: Map<string, NodeFunction | NodeClass>;
+    private blueprints;
+    dependencies: TDependencies;
+    logger: ILogger;
+    eventBus: IEventBus;
+    serializer: ISerializer;
+    middleware: Middleware[];
+    evaluator: IEvaluator;
+    private analysisCache;
+    orchestrator: IOrchestrator;
+    options: RuntimeOptions<TDependencies>;
+    private readonly logicHandler;
+    private readonly executorFactory;
+    constructor(container: DIContainer, options?: RuntimeOptions<TDependencies>);
+    constructor(options: RuntimeOptions<TDependencies>);
+    private _setupExecutionContext;
+    run(blueprint: WorkflowBlueprint, initialState?: Partial<TContext> | string, options?: {
+        functionRegistry?: Map<string, any>;
+        strict?: boolean;
+        signal?: AbortSignal;
+        concurrency?: number;
+    }): Promise<WorkflowResult<TContext>>;
+    private _setupResumedExecutionContext;
+    resume(blueprint: WorkflowBlueprint, serializedContext: string, resumeData: {
+        output?: any;
+        action?: string;
+    }, nodeId?: string, options?: {
+        functionRegistry?: Map<string, any>;
+        strict?: boolean;
+        signal?: AbortSignal;
+        concurrency?: number;
+    }): Promise<WorkflowResult<TContext>>;
+    _createExecutionRegistry(dynamicRegistry?: Map<string, any>): Map<string, NodeFunction | NodeClass>;
+    executeNode(blueprint: WorkflowBlueprint, nodeId: string, state: WorkflowState<TContext>, _allPredecessors?: Map<string, Set<string>>, functionRegistry?: Map<string, any>, executionId?: string, signal?: AbortSignal): Promise<NodeResult<any, any>>;
+    getExecutorForNode(nodeId: string, context: ExecutionContext<TContext, TDependencies>): any;
+    createForSubflow(subBlueprint: WorkflowBlueprint, initialSubState: Partial<TContext>, executionId: string, signal?: AbortSignal): ExecutionContext<TContext, TDependencies>;
+    determineNextNodes(blueprint: WorkflowBlueprint, nodeId: string, result: NodeResult<any, any>, context: ContextImplementation<TContext>, executionId?: string): Promise<{
+        node: NodeDefinition;
+        edge: EdgeDefinition;
+    }[]>;
+    applyEdgeTransform(edge: EdgeDefinition, sourceResult: NodeResult<any, any>, targetNode: NodeDefinition, context: ContextImplementation<TContext>, allPredecessors?: Map<string, Set<string>>): Promise<void>;
+    resolveNodeInput(nodeId: string, blueprint: WorkflowBlueprint, context: ContextImplementation<TContext>): Promise<any>;
+}
+
+/**
+ * A container for all state and dependencies of a single workflow execution.
+ * This object is created once per `run` and passed through the execution stack.
+ */
+declare class ExecutionContext<TContext extends Record<string, any>, TDependencies extends RuntimeDependencies> {
+    readonly blueprint: WorkflowBlueprint;
+    readonly state: WorkflowState<TContext>;
+    readonly nodeRegistry: Map<string, NodeFunction | NodeClass>;
+    readonly executionId: string;
+    readonly runtime: FlowRuntime<TContext, TDependencies>;
+    readonly services: {
+        logger: ILogger;
+        eventBus: IEventBus;
+        serializer: ISerializer;
+        evaluator: IEvaluator;
+        middleware: Middleware[];
+        dependencies: TDependencies;
+    };
+    readonly signal?: AbortSignal | undefined;
+    readonly concurrency?: number | undefined;
+    constructor(blueprint: WorkflowBlueprint, state: WorkflowState<TContext>, nodeRegistry: Map<string, NodeFunction | NodeClass>, executionId: string, runtime: FlowRuntime<TContext, TDependencies>, // A reference back to the runtime for orchestrating subflows
+    services: {
+        logger: ILogger;
+        eventBus: IEventBus;
+        serializer: ISerializer;
+        evaluator: IEvaluator;
+        middleware: Middleware[];
+        dependencies: TDependencies;
+    }, signal?: AbortSignal | undefined, concurrency?: number | undefined);
+    createForSubflow(subBlueprint: WorkflowBlueprint, initialSubState: Partial<TContext>): ExecutionContext<TContext, TDependencies>;
+}
+
+/** The central, serializable representation of a workflow. */
+interface WorkflowBlueprint {
+    id: string;
+    nodes: NodeDefinition[];
+    edges: EdgeDefinition[];
+    metadata?: Record<string, any>;
+}
+/** Defines a single step in the workflow. */
+interface NodeDefinition {
+    id: string;
+    /** A key that resolves to an implementation in a registry. */
+    uses: string;
+    /** Static parameters for the node. */
+    params?: Record<string, any>;
+    /** Maps context data to this node's `input`. */
+    inputs?: string | Record<string, string>;
+    /** Configuration for retries, timeouts, etc. */
+    config?: NodeConfig;
+}
+/** Defines the connection and data flow between two nodes. */
+interface EdgeDefinition {
+    source: string;
+    target: string;
+    /** An 'action' from the source node that triggers this edge. */
+    action?: string;
+    /** A condition that must be met for this edge to be taken. */
+    condition?: string;
+    /** A string expression to transform the data before passing it to the target node. */
+    transform?: string;
+}
+/** Configuration for a node's resiliency and behavior. */
+interface NodeConfig {
+    maxRetries?: number;
+    retryDelay?: number;
+    timeout?: number;
+    /** The `uses` key of another node implementation for fallback. */
+    fallback?: string;
+    /** Determines how a node with multiple incoming edges should be triggered. */
+    joinStrategy?: 'all' | 'any';
+}
+/** The required return type for any node implementation. */
+interface NodeResult<TOutput = any, TAction extends string = string> {
+    output?: TOutput;
+    action?: TAction;
+    error?: {
+        message: string;
+        [key: string]: any;
+    };
+    /** Allows a node to dynamically schedule new nodes for the orchestrator to execute. */
+    dynamicNodes?: NodeDefinition[];
+    /** Internal flag: Indicates that this result came from a fallback execution. */
+    _fallbackExecuted?: boolean;
+}
+/** The context object passed to every node's execution logic. */
+interface NodeContext<TContext extends Record<string, any> = Record<string, any>, TDependencies extends RuntimeDependencies = RuntimeDependencies, TInput = any> {
+    /** The async-only interface for interacting with the workflow's state. */
+    context: IAsyncContext<TContext>;
+    /** The primary input data for this node, typically from its predecessor. */
+    input?: TInput;
+    /** Static parameters defined in the blueprint. */
+    params: Record<string, any>;
+    /** Shared, runtime-level dependencies (e.g., database clients, loggers). */
+    dependencies: TDependencies & {
+        runtime: ExecutionContext<TContext, TDependencies>;
+        workflowState: WorkflowState<TContext>;
+    };
+    /** A signal to gracefully cancel long-running node operations. */
+    signal?: AbortSignal;
+}
+/** A simple function-based node implementation. */
+type NodeFunction<TContext extends Record<string, any> = Record<string, any>, TDependencies extends RuntimeDependencies = RuntimeDependencies, TInput = any, TOutput = any, TAction extends string = string> = (context: NodeContext<TContext, TDependencies, TInput>) => Promise<NodeResult<TOutput, TAction>>;
+/** Represents a constructor for any concrete class that extends the abstract BaseNode. */
+type NodeClass<TContext extends Record<string, any> = Record<string, any>, TDependencies extends RuntimeDependencies = RuntimeDependencies, TInput = any, TOutput = any, TAction extends string = string> = new (params?: Record<string, any>, nodeId?: string) => BaseNode<TContext, TDependencies, TInput, TOutput, TAction>;
+/** A union of all possible node implementation types. */
+type NodeImplementation = NodeFunction | NodeClass;
+/** A registry mapping node types to their implementations. */
+type NodeRegistry = Record<string, NodeImplementation>;
+/** A discriminated union for all possible context implementations. */
+type ContextImplementation<T extends Record<string, any>> = ISyncContext<T> | IAsyncContext<T>;
+/** The synchronous context interface for high-performance, in-memory state. */
+interface ISyncContext<TContext extends Record<string, any> = Record<string, any>> {
+    readonly type: 'sync';
+    get<K extends keyof TContext>(key: K): TContext[K] | undefined;
+    get(key: string): any | undefined;
+    set<K extends keyof TContext>(key: K, value: TContext[K]): void;
+    set(key: string, value: any): void;
+    has<K extends keyof TContext>(key: K): boolean;
+    has(key: string): boolean;
+    delete<K extends keyof TContext>(key: K): boolean;
+    delete(key: string): boolean;
+    toJSON: () => Record<string, any>;
+}
+/** The asynchronous context interface for remote or distributed state. */
+interface IAsyncContext<TContext extends Record<string, any> = Record<string, any>> {
+    readonly type: 'async';
+    get<K extends keyof TContext>(key: K): Promise<TContext[K] | undefined>;
+    get(key: string): Promise<any | undefined>;
+    set<K extends keyof TContext>(key: K, value: TContext[K]): Promise<void>;
+    set(key: string, value: any): Promise<void>;
+    has<K extends keyof TContext>(key: K): Promise<boolean>;
+    has(key: string): Promise<boolean>;
+    delete<K extends keyof TContext>(key: K): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    toJSON: () => Promise<Record<string, any>>;
+}
+/** Generic for any set of dependencies. */
+interface RuntimeDependencies {
+    [key: string]: any;
+}
+/** Configuration options for the FlowRuntime. */
+interface RuntimeOptions<TDependencies extends RuntimeDependencies = RuntimeDependencies> {
+    /** A registry of globally available node implementations. */
+    registry?: Record<string, NodeFunction | NodeClass | typeof BaseNode>;
+    /** A registry of all available workflow blueprints for subflow execution. */
+    blueprints?: Record<string, WorkflowBlueprint>;
+    /** Shared dependencies to be injected into every node. */
+    dependencies?: TDependencies;
+    /** A pluggable logger for consistent output. */
+    logger?: ILogger;
+    /** A pluggable event bus for observability. */
+    eventBus?: IEventBus;
+    /**
+     * A pluggable evaluator for edge conditions and transforms.
+     * @default new PropertyEvaluator() - A safe evaluator for simple property access.
+     * For complex logic, provide a custom implementation or use the `UnsafeEvaluator`
+     * (not recommended for production).
+     */
+    evaluator?: IEvaluator;
+    /** An array of middleware to wrap node execution. */
+    middleware?: Middleware[];
+    /** A pluggable serializer for handling complex data types in the context. */
+    serializer?: ISerializer;
+    /** A flag to enforce strictness in the workflow. */
+    strict?: boolean;
+}
+/** Interface for a pluggable expression evaluator for conditions and transforms. */
+interface IEvaluator {
+    evaluate: (expression: string, context: Record<string, any>) => any;
+}
+/** Interface for a pluggable logger. */
+interface ILogger {
+    debug: (message: string, meta?: Record<string, any>) => void;
+    info: (message: string, meta?: Record<string, any>) => void;
+    warn: (message: string, meta?: Record<string, any>) => void;
+    error: (message: string, meta?: Record<string, any>) => void;
+}
+/** Structured event types for detailed execution tracing. */
+type FlowcraftEvent = {
+    type: 'workflow:start';
+    payload: {
+        blueprintId: string;
+        executionId: string;
+    };
+} | {
+    type: 'workflow:resume';
+    payload: {
+        blueprintId: string;
+        executionId: string;
+    };
+} | {
+    type: 'workflow:stall';
+    payload: {
+        blueprintId: string;
+        executionId: string;
+        remainingNodes: number;
+    };
+} | {
+    type: 'workflow:pause';
+    payload: {
+        blueprintId: string;
+        executionId: string;
+    };
+} | {
+    type: 'workflow:finish';
+    payload: {
+        blueprintId: string;
+        executionId: string;
+        status: string;
+        errors?: WorkflowError[];
+    };
+} | {
+    type: 'node:start';
+    payload: {
+        nodeId: string;
+        executionId: string;
+        input: any;
+        blueprintId: string;
+    };
+} | {
+    type: 'node:finish';
+    payload: {
+        nodeId: string;
+        result: NodeResult;
+        executionId: string;
+        blueprintId: string;
+    };
+} | {
+    type: 'node:error';
+    payload: {
+        nodeId: string;
+        error: FlowcraftError;
+        executionId: string;
+        blueprintId: string;
+    };
+} | {
+    type: 'node:fallback';
+    payload: {
+        nodeId: string;
+        executionId: string;
+        fallback: string;
+        blueprintId: string;
+    };
+} | {
+    type: 'node:retry';
+    payload: {
+        nodeId: string;
+        attempt: number;
+        executionId: string;
+        blueprintId: string;
+    };
+} | {
+    type: 'node:skipped';
+    payload: {
+        nodeId: string;
+        edge: EdgeDefinition;
+        executionId: string;
+        blueprintId: string;
+    };
+} | {
+    type: 'edge:evaluate';
+    payload: {
+        source: string;
+        target: string;
+        condition?: string;
+        result: boolean;
+    };
+} | {
+    type: 'context:change';
+    payload: {
+        sourceNode: string;
+        key: string;
+        value: any;
+    };
+} | {
+    type: 'batch:start';
+    payload: {
+        batchId: string;
+        scatterNodeId: string;
+        workerNodeIds: string[];
+    };
+} | {
+    type: 'batch:finish';
+    payload: {
+        batchId: string;
+        gatherNodeId: string;
+        results: any[];
+    };
+};
+/** Interface for a pluggable event bus. */
+interface IEventBus {
+    emit: (event: FlowcraftEvent) => void | Promise<void>;
+}
+/** Interface for a pluggable serializer. */
+interface ISerializer {
+    serialize: (data: Record<string, any>) => string;
+    deserialize: (text: string) => Record<string, any>;
+}
+/** Interface for middleware to handle cross-cutting concerns. */
+interface Middleware<TContext extends Record<string, any> = Record<string, any>> {
+    beforeNode?: (ctx: ContextImplementation<TContext>, nodeId: string) => void | Promise<void>;
+    afterNode?: (ctx: ContextImplementation<TContext>, nodeId: string, result: NodeResult | undefined, error: Error | undefined) => void | Promise<void>;
+    aroundNode?: (ctx: ContextImplementation<TContext>, nodeId: string, next: () => Promise<NodeResult>) => Promise<NodeResult>;
+}
+/** A structured error object returned from a failed workflow execution. */
+interface WorkflowError extends FlowcraftError {
+    timestamp: string;
+    originalError?: any;
+}
+/** The status of a workflow execution. */
+type WorkflowStatus = 'completed' | 'failed' | 'stalled' | 'cancelled' | 'awaiting';
+/** The final result of a workflow execution. */
+interface WorkflowResult<TContext = Record<string, any>> {
+    context: TContext;
+    serializedContext: string;
+    status: WorkflowStatus;
+    errors?: WorkflowError[];
+}
+/** A graph representation of a workflow blueprint. */
+interface UIGraph {
+    nodes: Array<Partial<NodeDefinition> & {
+        id: string;
+        data?: Record<string, any>;
+        type?: string;
+    }>;
+    edges: Array<Partial<EdgeDefinition> & {
+        source: string;
+        target: string;
+        data?: Record<string, any>;
+    }>;
+}
+
+export { type ISerializer as A, BaseNode as B, ClassNodeExecutor as C, type WorkflowError as D, type ExecutionStrategy as E, FunctionNodeExecutor as F, GraphTraverser as G, type WorkflowStatus as H, type IOrchestrator as I, type WorkflowResult as J, ExecutionContext as K, type Middleware as M, type NodeExecutionResult as N, type ReadyNode as R, type UIGraph as U, WorkflowState as W, type NodeExecutorConfig as a, NodeExecutor as b, FlowRuntime as c, type NodeExecutorFactory as d, type ExecutionServices as e, type IRuntime as f, type WorkflowBlueprint as g, type NodeDefinition as h, isNodeClass as i, type EdgeDefinition as j, type NodeConfig as k, type NodeResult as l, type NodeContext as m, type NodeFunction as n, type NodeClass as o, type NodeImplementation as p, type NodeRegistry as q, type ContextImplementation as r, type ISyncContext as s, type IAsyncContext as t, type RuntimeDependencies as u, type RuntimeOptions as v, type IEvaluator as w, type ILogger as x, type FlowcraftEvent as y, type IEventBus as z };

package/dist/types.d.ts

@@ -1 +1,3 @@
-export { C as ContextImplementation, E as EdgeDefinition, h as IAsyncContext, k as IEvaluator, m as IEventBus, l as ILogger, n as ISerializer, I as ISyncContext, M as Middleware, e as NodeClass, a as NodeConfig, c as NodeContext, N as NodeDefinition, d as NodeFunction, f as NodeImplementation, g as NodeRegistry, b as NodeResult, R as RuntimeDependencies, j as RuntimeOptions, W as WorkflowBlueprint, o as WorkflowError, p as WorkflowResult } from './types-CsTeXTiA.js';
+import './errors.js';
+export { r as ContextImplementation, j as EdgeDefinition, y as FlowcraftEvent, t as IAsyncContext, w as IEvaluator, z as IEventBus, x as ILogger, A as ISerializer, s as ISyncContext, M as Middleware, o as NodeClass, k as NodeConfig, m as NodeContext, h as NodeDefinition, n as NodeFunction, p as NodeImplementation, q as NodeRegistry, l as NodeResult, u as RuntimeDependencies, v as RuntimeOptions, U as UIGraph, g as WorkflowBlueprint, D as WorkflowError, J as WorkflowResult, H as WorkflowStatus } from './types-ezHUBdpL.js';
+import './container.js';