flowcraft 2.1.1 → 2.3.0

package/dist/types-CQCe_nBM.d.ts

@@ -1,214 +0,0 @@
-/** 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;
-    /**
-     * @param params Static parameters for this node instance, passed from the blueprint.
-     */
-    constructor(params?: Record<string, any> | 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>;
-}
-
-/** 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;
-    /** 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>) => 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;
-    set: <K extends keyof TContext>(key: K, value: TContext[K]) => void;
-    has: <K extends keyof TContext>(key: K) => boolean;
-    delete: <K extends keyof TContext>(key: K) => 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>;
-    set: <K extends keyof TContext>(key: K, value: TContext[K]) => Promise<void>;
-    has: <K extends keyof TContext>(key: K) => Promise<boolean>;
-    delete: <K extends keyof TContext>(key: K) => 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;
-}
-/** Interface for a pluggable event bus. */
-interface IEventBus {
-    emit: (eventName: string, payload: Record<string, any>) => 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 {
-    nodeId: string;
-    message: string;
-    originalError?: any;
-    timestamp: string;
-    stack?: string;
-}
-/** The final result of a workflow execution. */
-interface WorkflowResult<TContext = Record<string, any>> {
-    context: TContext;
-    serializedContext: string;
-    status: 'completed' | 'failed' | 'stalled' | 'cancelled';
-    errors?: WorkflowError[];
-}
-
-export { BaseNode as B, type ContextImplementation as C, type EdgeDefinition as E, type ISyncContext as I, type Middleware as M, type NodeDefinition as N, type RuntimeDependencies as R, type WorkflowBlueprint as W, type NodeConfig as a, type NodeResult as b, type NodeContext as c, type NodeFunction as d, type NodeClass as e, type NodeImplementation as f, type NodeRegistry as g, type IAsyncContext as h, isNodeClass as i, type RuntimeOptions as j, type IEvaluator as k, type ILogger as l, type IEventBus as m, type ISerializer as n, type WorkflowError as o, type WorkflowResult as p };