flowcraft 1.0.0-beta.9 → 1.0.0

package/README.md

@@ -1,65 +1,72 @@
 # Flowcraft: A Workflow Framework
 
-Build complex, multi-step processes, from simple sequences to dynamic, graph-driven AI agents.
+[![npm version](https://img.shields.io/npm/v/flowcraft.svg)](https://www.npmjs.com/package/flowcraft)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Build complex, multi-step processes with a lightweight, composable, and type-safe TypeScript framework. Model everything from simple sequences to dynamic AI agents, running in-memory or across distributed systems.
+
+**[Read the Friendly Manual »](https://gorango.github.io/flowcraft/guide/)**
 
 ## Features
 
 - **Zero Dependencies**: Lightweight and dependency-free, ensuring a small footprint and easy integration.
+- **Composable & Reusable**: Define workflows by chaining nodes or declaratively embedding other flows as nodes.
+- **Type-Safe by Default**: Strong typing for workflow definitions, shared state, and node parameters.
+- **Async First**: Built on an asynchronous foundation to handle I/O-bound tasks gracefully.
+- **Resilient & Reliable**: Built-in support for retries with configurable delays and fallback logic.
+- **Dynamic Graph Engine**: Construct executable workflows from declarative JSON, ideal for AI agents.
+- **Extensible Execution**: A pluggable Executor pattern enables in-memory or distributed flows.
+- **Advanced Control Flow**: Full support for conditional branching, loops, and parallel execution.
+- **Modern Tooling**: A fluent functional API, static graph validation, and automatic visualizations.
 
-- **Composable & Reusable**: Define workflows by chaining nodes or embedding other flows as nodes.
-
-- **Extensible Execution Engine**: A pluggable `Executor` pattern enables in-memory or distributed flows.
+---
 
-- **Type-Safe**: Written in TypeScript to provide strong typing for your workflow definitions, context, and node parameters.
+Flowcraft is a lightweight, zero-dependency TypeScript framework for building complex, multi-step processes. It empowers you to model everything from simple sequential tasks to dynamic, graph-driven AI agents with a clear and composable API.
 
-- **Async by Default**: Built on an asynchronous foundation to handle I/O-bound and CPU-bound tasks.
+At its core, Flowcraft is guided by a few key principles:
 
-- **Middleware**: Intercept execution of nodes to handle cross-cutting concerns like logging or auth.
+1.  **Structure for Complexity**: It provides a clear way to model asynchronous processes. By breaking logic into discrete `Node`s with a defined lifecycle, you can turn tangled promise chains and `async/await` blocks into maintainable, testable graphs.
+2.  **Start Simple, Scale Gracefully**: You can start with an in-memory workflow in a single file. As your needs grow, the architecture allows you to scale up to a robust, distributed system using message queues—**without changing your core business logic**.
+3.  **Composability is Key**: A `Flow` is just a specialized `Node`. This simple but powerful concept means entire workflows can be treated as building blocks, allowing you to create highly modular and reusable systems.
 
-- **Conditional Branching**: Direct the flow's execution path based on the results of any node.
+## The Two Paths of Flowcraft
 
-- **Retry Logic & Fallbacks**: Retry failed operations with configurable delays and fallback logic.
+Flowcraft is designed to cater to two primary use cases, and the documentation is structured to guide you down the path that best fits your needs:
 
-- **Cancellation Support**: Gracefully abort running workflows using standard `AbortController`s.
+### 1. Programmatic Workflows
 
-- **Pluggable Logging**: Use the built-in `ConsoleLogger` or bring your own (e.g., Pino, Winston).
+This is the path for developers who want to build and manage workflows directly within their application's code. Using a fluent, chainable API and functional helpers, you can quickly define, test, and run complex processes in-memory.
 
-- **Dynamic Graph Engine**: Define complex, graph-based workflows as simple JSON files.
+**Choose this path if you are:**
 
-- **Fluent & Functional API**: A chainable API on the `Node` class and a collection of functional helpers.
+- Building background jobs for a web application.
+- Creating complex, multi-step data processing pipelines.
+- Looking for a structured way to manage complex `async/await` logic.
 
-## Installation
+**[Learn how to build Programmatic Workflows »](https://gorango.github.io/flowcraft/guide/programmatic/basics.html)**
 
-```bash
-npm install flowcraft
-```
+### 2. Declarative Workflows (for Scale)
 
-## Quick Start
+This is the path for architects and developers building dynamic, data-driven, or distributed systems. You define your workflow's structure as a declarative data format (like JSON), and the `GraphBuilder` "compiles" it into an executable, serializable `Blueprint`.
 
-Create and run a simple workflow in a few lines of code.
+**Choose this path if you are:**
 
-```typescript
-import { Flow, Node } from 'flowcraft'
+- Building a system where workflows are defined by users or stored in a database.
+- Creating a runtime for dynamic AI agents.
+- Architecting a distributed system where tasks are executed by a pool of workers.
 
-const greetNode = new Node()
-// The exec method contains the core logic of the node.
-	.exec(() => 'Hello, World!')
-// Functional helpers make common tasks easy.
-	.tap(console.log)
+**[Learn how to build Declarative Workflows »](https://gorango.github.io/flowcraft/guide/declarative/basics.html)**
 
-const flow = new Flow(greetNode)
-// Run using the default InMemoryExecutor.
-await flow.run()
-```
+---
 
 ## Learn by Example
 
 > [!TIP]
-> The best way to understand the framework is by exploring the included sandbox examples. They are ordered by increasing complexity, each introducing new features and demonstrating the flexibility of the core engine.
+> The best way to learn is by exploring the included sandbox examples. They are ordered by complexity, each demonstrating a new feature of the core engine.
 
 ### 1. Basic Sequential Flow: Article Writer
 
-A simple, linear workflow that demonstrates the core concepts of creating a sequence of nodes to perform a multi-step task like generating an article.
+A simple, linear workflow that demonstrates the core concepts of creating a sequence of nodes to perform a multi-step task.
 
 ```mermaid
 graph LR
@@ -67,8 +74,8 @@ graph LR
     B --> C[Apply Style]
 ```
 
-- **Demonstrates**: `Node` chaining, passing data via `Context`, and a simple `BatchFlow`.
-- **[Explore the Basic example »](./sandbox/1.basic/)**
+- **Demonstrates**: `Node` chaining, passing data via `Context`.
+- **[Explore the Basic example »](https://github.com/gorango/flowcraft/tree/main/sandbox/1.basic/)**
 
 ### 2. Conditional Branching: Research Agent
 
@@ -81,12 +88,12 @@ graph TD
     B --> A
 ```
 
-- **Demonstrates**: Conditional branching with custom actions, creating loops, and building simple state machines.
-- **[Explore the Research Agent example »](./sandbox/2.research/)**
+- **Demonstrates**: Conditional branching, creating loops, and building simple state machines.
+- **[Explore the Research Agent example »](https://github.com/gorango/flowcraft/tree/main/sandbox/2.research/)**
 
 ### 3. Parallel Batch Processing: Document Translator
 
-A practical example that translates a document into multiple languages concurrently. It uses the `ParallelBatchFlow` builder to showcase significant performance boosts for I/O-bound tasks.
+A practical example that translates a document into multiple languages concurrently using `ParallelBatchFlow` for a massive performance boost on I/O-bound tasks.
 
 ```mermaid
 graph TD
@@ -94,192 +101,53 @@ graph TD
     B -- "Chinese" --> T1[TranslateNode]
     B -- "Spanish" --> T2[TranslateNode]
     B -- "Japanese" --> T3[TranslateNode]
-    B -- "German" --> T4[TranslateNode]
-    T1 --> S1[Save Chinese.md]
-    T2 --> S2[Save Spanish.md]
-    T3 --> S3[Save Japanese.md]
-    T4 --> S4[Save German.md]
+    T1 & T2 & T3 --> S[Save Files]
 ```
 
-- **Demonstrates**: `ParallelBatchFlow` for high-throughput concurrent processing of I/O-bound tasks.
-- **[Explore the Parallel Translation example »](./sandbox/3.parallel/)**
+- **Demonstrates**: High-throughput concurrent processing for data-parallel tasks.
+- **[Explore the Parallel Translation example »](https://github.com/gorango/flowcraft/tree/main/sandbox/3.parallel/)**
 
 ### 4. Dynamic Graph Engine: AI Agent Runtime
 
-The most advanced example: a powerful runtime that executes complex, graph-based AI workflows defined in simple JSON-like objects. This shows how to build highly dynamic and modular AI agent systems.
-
-> [!IMPORTANT]
-> The `GraphBuilder` is fully **type-safe**. By defining a simple map of your node types to their data payloads, TypeScript can validate your entire graph at compile time, ensuring that the data provided to each node matches what its class expects. This eliminates a whole category of runtime configuration errors.
+A powerful runtime that executes complex, graph-based AI workflows defined in simple JSON-like objects. This shows how to build highly dynamic and modular AI agent systems.
 
 ```mermaid
 graph TD
-    A(User Post) --> B[check_for_pii]
-    A --> C[check_for_hate_speech]
-    A --> D[check_for_spam]
-    B --> E{triage_post}
-    C --> E
-    D --> E
+    A(User Post) --> B[check_pii] & C[check_hate_speech] & D[check_spam]
+    B & C & D --> E{triage_post}
     E -- action_ban --> F["Sub-Workflow: Ban User"]
-    E -- action_redact --> G["Sub-Workflow: Redact Post"]
-    E -- action_delete_spam --> H["Sub-Workflow: Delete"]
-    E -- action_approve --> I[approve_post_branch]
-    F --> Z[final_log]
-    G --> Z
-    H --> Z
-    I --> Z
+    E -- action_approve --> G[approve_post_branch]
 ```
 
 - **Demonstrates**:
-  - **Type-safe graph construction** from declarative definitions using `GraphBuilder`.
-  - Parallel fan-in and fan-out (mid-flow branching).
-  - Reusable, data-driven nodes (e.g., an LLM-powered router).
-  - Complex sub-workflow composition.
-- **[Explore the Dynamic AI Agent example »](./sandbox/4.dag/)**
+    - Type-safe graph construction from declarative definitions using `GraphBuilder`.
+    - Parallel fan-in and fan-out.
+    - Reusable, data-driven nodes and complex sub-workflow composition.
+- **[Explore the Dynamic AI Agent example »](https://github.com/gorango/flowcraft/tree/main/sandbox/4.dag/)**
 
 ### 5. Distributed Execution: AI Agent with BullMQ
 
-This example takes the same type-safe graph definition from the previous example and runs it in a distributed environment using a custom `BullMQExecutor`. It demonstrates a client-worker architecture for building scalable and resilient background job processors.
+This example takes the same type-safe graph definition from the previous example and runs it in a distributed environment using a custom `BullMQExecutor`, demonstrating a client-worker architecture for scalable background jobs.
 
 - **Demonstrates**:
-  - A pluggable `IExecutor` for distributed workflows.
-  - Client-worker architecture with state serialization.
-  - Mid-flight, distributed cancellation of long-running jobs.
-  - How business logic (the graph) remains unchanged when the execution environment changes.
-- **[Explore the Distributed AI Agent example »](./sandbox/5.distributed/)**
+    - A pluggable `IExecutor` for distributed workflows.
+    - How business logic (the graph) remains unchanged when the execution environment changes.
+- **[Explore the Distributed AI Agent example »](https://github.com/gorango/flowcraft/tree/main/sandbox/5.distributed/)**
 
 ### 6. Advanced RAG Agent: Complex Data & Serialization
 
-A complete, end-to-end Retrieval-Augmented Generation (RAG) agent that ingests a document, creates embeddings in parallel, performs a vector search, and synthesizes an answer. This example showcases how to build a sophisticated, data-driven AI workflow.
-
-```mermaid
-graph TD
-    A[Load & Chunk Document] --> B[Generate Embeddings]
-    B --> C[Store in Vector DB]
-    C --> D[Vector Search for Question]
-    D --> E[Generate Final Answer]
-```
+A complete Retrieval-Augmented Generation (RAG) agent that ingests a document, creates embeddings, performs a vector search, and synthesizes an answer, showcasing a sophisticated, data-driven AI workflow.
 
 - **Demonstrates**:
-  - A full, practical RAG pipeline.
-  - A mix of custom, single-responsibility nodes.
-  - Handling complex data types (`Map`, `Date`, custom classes) in the `Context`.
-  - The necessity of robust serialization (using `superjson`) for state management.
-- **[Explore the RAG Agent example »](./sandbox/6.rag/)**
-
-## Core Concepts
-
-### Node
-
-The `Node` is the fundamental building block of a workflow. It represents a single unit of work and is fully generic, allowing you to define types for its lifecycle results and its static parameters.
-
-The class signature is: `Node<PrepRes, ExecRes, PostRes, TParams>`
-
-- `PrepRes`: The type of data returned by the `prep` phase.
-- `ExecRes`: The type of data returned by the `exec` phase.
-- `PostRes`: The type of the "action" returned by the `post` phase.
-- `TParams`: The type of the static parameters object for the node, accessible via `.withParams()`.
-
-**Example: A Type-Safe GreetNode**
-
-For nodes that do require static configuration, you can provide a type for the parameters to get full autocompletion and compile-time safety.
-
-```typescript
-// 1. Define the shape of the node's parameters.
-interface GreetParams {
-	greeting: string
-	loudly: boolean
-}
-
-// 2. Define the node with the TParams generic.
-class GreetNode extends Node<void, string, any, GreetParams> {
-	// 3. The 'exec' method can safely access typed parameters.
-	async exec({ params }: NodeArgs<GreetParams>): Promise<string> {
-		let message = `${params.greeting}, World!`
-		if (params.loudly) {
-			message = message.toUpperCase()
-		}
-		return message
-	}
-}
-
-// 4. Instantiate and configure with type-safe .withParams()
-const greetNode = new GreetNode()
-	.withParams({ greeting: 'Hello', loudly: true }) // Autocompletes and type-checks!
-	.tap(console.log) // "HELLO, WORLD!"
-
-// TypeScript would throw an error on this line:
-// greetNode.withParams({ greting: 'Hi', loudly: false }); // Property 'greting' does not exist.
-```
-
-A chainable API on the `Node` class has a set of functional helpers:
-
-- `.withParams(params)`: Sets type-safe static parameters for the node.
-- `.map(fn)`: Transform the output of a node.
-- `.filter(predicate)`: Conditionally proceed based on a node's output.
-- `.tap(fn)`: Perform a side-effect without changing the output.
-- `.toContext(key)`: Store a node's result in the context.
-
-### Flow
-
-A `Flow` is a special type of `Node` that orchestrates a sequence of other nodes. It is also generic (`Flow<PrepRes, ExecRes, TParams>`) and can be configured with its own parameters and middleware. It contains the logic for traversing its own graph of operations, making it a powerful, self-contained unit of work.
-
-### Executor
-
-An `Executor` is responsible for **running** a `Flow`. It provides the top-level execution environment, handling setup and teardown. The framework is decoupled from the execution strategy, allowing you to use the default `InMemoryExecutor` or plug in custom executors for different environments (e.g., distributed queues).
-
-### Middleware
+    - A full, practical RAG pipeline with custom nodes.
+    - Handling complex data types (`Map`, `Date`, etc.) in the `Context`.
+    - Robust serialization (using `superjson`) for reliable state management.
+- **[Explore the RAG Agent example &raquo;](https://github.com/gorango/flowcraft/tree/main/sandbox/6.rag/)**
 
-A `Flow` can be configured with middleware functions that wrap the execution of every node within it. This is the ideal pattern for handling **cross-cutting concerns** like performance monitoring, centralized logging, or transaction management without cluttering your business logic.
+## Documentation
 
-### Context
-
-The `Context` is a shared, type-safe `Map`-like object passed through every node in a flow. It acts as a shared memory space, allowing nodes to pass data and share state.
-
-### Actions & Branching
-
-A node's `post()` method returns a string called an **action**. The flow uses this action to look up the next node to execute. The default action is a `symbol`, but returning custom strings allows for conditional branching. The fluent `.filter()` method provides another powerful way to branch based on a `FILTER_FAILED` action.
-
-### Builders
-
-To simplify the creation of common and complex patterns, the framework provides a `builder` module. These helpers abstract the construction of executable `Flow`s.
-
-- **`SequenceFlow`**: Creates a linear flow from a sequence of nodes.
-- **`BatchFlow` / `ParallelBatchFlow`**: Process a collection of items sequentially or concurrently.
-- **`GraphBuilder`**: Translates a declarative graph definition into a fully executable `Flow`.
-
-## Unit Tests
-
-> [!TIP]
-> For clear, focused examples of specific, individual features (like retries, middleware, cancellation, and composition), the unit tests are an excellent resource.
-
-- Core workflow tests: [`src/workflow.test.ts`](src/workflow.test.ts)
-- Collections tests: [`src/builder/collection.test.ts`](src/builder/collection.test.ts)
-- Graph builder tests: [`src/builder/graph.test.ts`](src/builder/graph.test.ts)
-
-## API Reference
-
-### Core Classes
-
-- `Node`: The base class for a unit of work: `Node<PrepRes, ExecRes, PostRes, TParams>`. It has built-in retry logic and a fluent API (`.map`, `.filter`, etc.).
-- `Flow`: Orchestrates a sequence of nodes: `Flow<PrepRes, ExecRes, TParams>`. Supports middleware via `.use()`.
-- `InMemoryExecutor`: The default `IExecutor` implementation for running flows in-memory.
-- `TypedContext`: The standard `Map`-based implementation for the `Context` interface.
-- `ConsoleLogger`, `NullLogger`: Pre-built logger implementations.
-
-### Functional Helpers
-
-A collection of functions for creating nodes and pipelines in a more functional style.
-
-- `mapNode`: Creates a `Node` from a simple, pure function: `mapNode<TIn extends Params, TOut>(fn)`. The function receives the node's `params` as its input.
-- `contextNode`: Creates a `Node` from a function that requires access to the `Context`: `contextNode<TIn extends Params, TOut>(fn)`. The function receives the context and the node's `params`.
-- `pipeline`: A functional alias for creating a linear sequence of nodes.
-
-### Builder Classes
-
-- `SequenceFlow`: A `Flow` that creates a linear flow from a sequence of nodes.
-- `BatchFlow`: A `Flow` that processes a collection of items sequentially.
-- `ParallelBatchFlow`: A `Flow` that processes a collection of items in parallel.
-- `GraphBuilder`: Constructs a `Flow` from a declarative graph definition.
+For a deep dive into all features, patterns, and APIs, please see the **[complete Flowcraft documentation](https://gorango.github.io/flowcraft/guide/)**.
 
 ---
-Licensed under the [MIT License](./LICENSE).
+
+Licensed under the [MIT License](https://github.com/gorango/flowcraft/tree/main/LICENSE).

package/dist/builder/graph/graph.d.ts

@@ -0,0 +1,57 @@
+import { Logger } from '../../logger.js';
+import { f as NodeTypeMap, i as TypedNodeRegistry, n as NodeRegistry, o as GraphBuilderOptions, h as TypedWorkflowGraph, k as BuildResult, m as WorkflowGraph, B as BlueprintBuildResult } from '../../types-U76Ukj96.js';
+import '../../context.js';
+
+/**
+ * A smart factory that takes an object of custom node classes and returns a fully
+ * prepared `NodeRegistry` map with all internal nodes required by the GraphBuilder.
+ *
+ * @param registry An object where keys are node type strings and values are the corresponding Node constructors.
+ * @returns A `Map` instance ready to be used by the `GraphBuilder` or a custom executor.
+ */
+declare function createNodeRegistry<TNodeMap extends NodeTypeMap, TContext = object>(registry: TypedNodeRegistry<TNodeMap, TContext>): NodeRegistry;
+/**
+ * Constructs a serializable `WorkflowBlueprint` from a declarative `WorkflowGraph` definition.
+ * The blueprint is a static, storable artifact that can be executed by a `BlueprintExecutor`.
+ * @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 object = object> {
+    private nodeOptionsContext;
+    private registry;
+    private subWorkflowNodeTypes;
+    private conditionalNodeTypes;
+    private subWorkflowResolver?;
+    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 for immediate in-memory execution.
+     * @param graph The `WorkflowGraph` object describing the flow.
+     * @param log Whether to log the graph after flattening. Defaults to `false`.
+     * @returns A `BuildResult` object containing the executable `flow` and a `nodeMap`.
+     */
+    build(graph: TypedWorkflowGraph<TNodeMap>, log?: boolean): BuildResult;
+    build(graph: WorkflowGraph, log?: boolean): BuildResult;
+    /**
+     * Builds a serializable `WorkflowBlueprint` from a graph definition.
+     * This is the recommended method for preparing a workflow for a distributed environment.
+     * @param graph The `WorkflowGraph` object describing the flow.
+     * @returns A `BlueprintBuildResult` object containing the serializable `blueprint`.
+     */
+    buildBlueprint(graph: TypedWorkflowGraph<TNodeMap>): BlueprintBuildResult;
+    buildBlueprint(graph: WorkflowGraph): BlueprintBuildResult;
+    private _createPredecessorIdMaps;
+    private _findBranchTerminals;
+    private _findConditionalConvergence;
+}
+
+export { GraphBuilder, createNodeRegistry };

package/dist/builder/graph/graph.js

@@ -0,0 +1,21 @@
+export { GraphBuilder, createNodeRegistry } from '../../chunk-3YMBNZ77.js';
+import '../../chunk-WGVHM7DU.js';
+import '../../chunk-L5PK5VL2.js';
+import '../../chunk-F6C6J7HK.js';
+import '../../chunk-UY4PNPBX.js';
+import '../../chunk-ELEHMJPM.js';
+import '../../chunk-HEO3XL4Z.js';
+import '../../chunk-7XUN3OQT.js';
+import '../../chunk-WR5PDOPP.js';
+import '../../chunk-VMH2LRM6.js';
+import '../../chunk-YR433ZDA.js';
+import '../../chunk-6QCXIRLA.js';
+import '../../chunk-BRFMFLR6.js';
+import '../../chunk-PNWOW52F.js';
+import '../../chunk-VZDHIOCH.js';
+import '../../chunk-S4WFNGQG.js';
+import '../../chunk-64DNBF5W.js';
+import '../../chunk-IIKTTIW5.js';
+import '../../chunk-AOHBHYF6.js';
+//# sourceMappingURL=graph.js.map
+//# sourceMappingURL=graph.js.map

package/dist/builder/graph/graph.js.map

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

package/dist/builder/graph/index.d.ts

@@ -0,0 +1,8 @@
+export { GraphBuilder, createNodeRegistry } from './graph.js';
+export { ConditionalJoinNode, InputMappingNode, OutputMappingNode, ParallelBranchContainer, SubWorkflowContainerNode } from './internal-nodes.js';
+export { BlueprintExecutor } from './runner.js';
+export { B as BlueprintBuildResult, k as BuildResult, o as GraphBuilderOptions, G as GraphEdge, l as GraphNode, g as NodeConstructorOptions, n as NodeRegistry, f as NodeTypeMap, O as OriginalPredecessorIdMap, j as PredecessorIdMap, S as SubWorkflowResolver, T as TypedGraphNode, i as TypedNodeRegistry, h as TypedWorkflowGraph, W as WorkflowBlueprint, m as WorkflowGraph } from '../../types-U76Ukj96.js';
+import '../patterns.js';
+import '../../logger.js';
+import '../../context.js';
+import '../../functions.js';

package/dist/builder/graph/index.js

@@ -0,0 +1,23 @@
+import '../../chunk-GMKJ34T2.js';
+import '../../chunk-KOBEU2EM.js';
+export { BlueprintExecutor, GraphBuilder, createNodeRegistry } from '../../chunk-3YMBNZ77.js';
+export { ConditionalJoinNode, InputMappingNode, OutputMappingNode, ParallelBranchContainer, SubWorkflowContainerNode } from '../../chunk-WGVHM7DU.js';
+import '../../chunk-L5PK5VL2.js';
+import '../../chunk-F6C6J7HK.js';
+import '../../chunk-UY4PNPBX.js';
+import '../../chunk-ELEHMJPM.js';
+import '../../chunk-HEO3XL4Z.js';
+import '../../chunk-7XUN3OQT.js';
+import '../../chunk-WR5PDOPP.js';
+import '../../chunk-VMH2LRM6.js';
+import '../../chunk-YR433ZDA.js';
+import '../../chunk-6QCXIRLA.js';
+import '../../chunk-BRFMFLR6.js';
+import '../../chunk-PNWOW52F.js';
+import '../../chunk-VZDHIOCH.js';
+import '../../chunk-S4WFNGQG.js';
+import '../../chunk-64DNBF5W.js';
+import '../../chunk-IIKTTIW5.js';
+import '../../chunk-AOHBHYF6.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/builder/graph/index.js.map

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

package/dist/builder/graph/internal-nodes.d.ts

@@ -0,0 +1,59 @@
+import { Context } from '../../context.js';
+import { N as Node, b as NodeArgs, A as AbstractNode } from '../../types-U76Ukj96.js';
+import { ParallelFlow } from '../patterns.js';
+import '../../logger.js';
+import '../../functions.js';
+
+/**
+ * An internal node used by the GraphBuilder to handle the `inputs` mapping
+ * of an inlined sub-workflow. It copies data from the parent context scope
+ * to the sub-workflow's context scope.
+ * @internal
+ */
+declare class InputMappingNode<TContext extends Context = Context> extends Node<void, void, any, any, TContext> {
+    private mappings;
+    constructor(options: {
+        data: Record<string, string>;
+    });
+    prep({ ctx, logger }: NodeArgs<void, void, any, TContext>): Promise<void>;
+}
+/**
+ * An internal node used by the GraphBuilder to handle the `outputs` mapping
+ * of an inlined sub-workflow. It copies data from the sub-workflow's
+ * context scope back to the parent's context scope.
+ * @internal
+ */
+declare class OutputMappingNode<TContext extends Context = Context> extends Node<void, void, any, any, TContext> {
+    private mappings;
+    constructor(options: {
+        data: Record<string, string>;
+    });
+    prep({ ctx, logger }: NodeArgs<void, void, any, TContext>): Promise<void>;
+}
+/**
+ * A private class used by the builder to represent the sub-workflow container itself.
+ * It's a structural node that preserves the original node ID in the flattened graph.
+ * @internal
+ */
+declare class SubWorkflowContainerNode<TContext extends Context = Context> extends Node<void, void, any, any, TContext> {
+    constructor();
+    exec(): Promise<void>;
+}
+/** A private class used by the builder to represent parallel execution blocks. */
+declare class ParallelBranchContainer<TContext extends Context = Context> extends ParallelFlow<TContext> {
+    /** A tag to reliably identify this node type in the visualizer. */
+    readonly isParallelContainer = true;
+    nodesToRun: AbstractNode[];
+    constructor();
+}
+/**
+ * A private class used by the builder to unify conditional branches
+ * before they connect to a common successor. This ensures the successor
+ * only has one predecessor, preventing false fan-in detection.
+ * @internal
+ */
+declare class ConditionalJoinNode<TContext extends Context = Context> extends Node<void, void, any, any, TContext> {
+    constructor();
+}
+
+export { ConditionalJoinNode, InputMappingNode, OutputMappingNode, ParallelBranchContainer, SubWorkflowContainerNode };

package/dist/builder/graph/internal-nodes.js

@@ -0,0 +1,20 @@
+export { ConditionalJoinNode, InputMappingNode, OutputMappingNode, ParallelBranchContainer, SubWorkflowContainerNode } from '../../chunk-WGVHM7DU.js';
+import '../../chunk-L5PK5VL2.js';
+import '../../chunk-F6C6J7HK.js';
+import '../../chunk-UY4PNPBX.js';
+import '../../chunk-ELEHMJPM.js';
+import '../../chunk-HEO3XL4Z.js';
+import '../../chunk-7XUN3OQT.js';
+import '../../chunk-WR5PDOPP.js';
+import '../../chunk-VMH2LRM6.js';
+import '../../chunk-YR433ZDA.js';
+import '../../chunk-6QCXIRLA.js';
+import '../../chunk-BRFMFLR6.js';
+import '../../chunk-PNWOW52F.js';
+import '../../chunk-VZDHIOCH.js';
+import '../../chunk-S4WFNGQG.js';
+import '../../chunk-64DNBF5W.js';
+import '../../chunk-IIKTTIW5.js';
+import '../../chunk-AOHBHYF6.js';
+//# sourceMappingURL=internal-nodes.js.map
+//# sourceMappingURL=internal-nodes.js.map

package/dist/builder/graph/internal-nodes.js.map

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

package/dist/builder/graph/runner.d.ts

@@ -0,0 +1,51 @@
+import { Context } from '../../context.js';
+import { I as IExecutor, F as Flow, A as AbstractNode, W as WorkflowBlueprint, n as NodeRegistry, i as TypedNodeRegistry, R as RunOptions } from '../../types-U76Ukj96.js';
+import '../../logger.js';
+
+/**
+ * An execution engine that hydrates a runnable `Flow` from a serializable
+ * `WorkflowBlueprint` and runs it. This is the recommended executor for
+ *  distributed systems where the workflow is built once and executed many times by workers.
+ */
+declare class BlueprintExecutor implements IExecutor {
+    private blueprint;
+    private nodeOptionsContext;
+    readonly flow: Flow;
+    readonly nodeMap: Map<string, AbstractNode>;
+    private readonly registry;
+    constructor(blueprint: WorkflowBlueprint, registry: NodeRegistry | TypedNodeRegistry<any, any>, nodeOptionsContext?: Record<string, any>);
+    private _populateContainers;
+    /**
+     * Retrieves a hydrated node instance from the blueprint by its ID.
+     * This is useful for workers that need to execute a specific node from the graph.
+     * @param nodeId The ID of the node to retrieve.
+     * @returns The `AbstractNode` instance if found, otherwise `undefined`.
+     */
+    getNode(nodeId: string): AbstractNode | undefined;
+    /**
+     * Instantiates all node objects from the blueprint's definition.
+     * @private
+     */
+    private _createNodeMap;
+    /**
+     * Wires the hydrated node instances together based on the blueprint's edges.
+     * @private
+     */
+    private _wireGraph;
+    /**
+     * Executes the flow defined by the blueprint.
+     * @param flow The flow 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>;
+    /**
+     * Determines the next node to execute based on the action returned by the current node.
+     * For distributed systems, this logic would live on the orchestrator.
+     * @internal
+     */
+    getNextNode(curr: AbstractNode, action: any): AbstractNode | undefined;
+}
+
+export { BlueprintExecutor };

package/dist/builder/graph/runner.js

@@ -0,0 +1,21 @@
+export { BlueprintExecutor } from '../../chunk-3YMBNZ77.js';
+import '../../chunk-WGVHM7DU.js';
+import '../../chunk-L5PK5VL2.js';
+import '../../chunk-F6C6J7HK.js';
+import '../../chunk-UY4PNPBX.js';
+import '../../chunk-ELEHMJPM.js';
+import '../../chunk-HEO3XL4Z.js';
+import '../../chunk-7XUN3OQT.js';
+import '../../chunk-WR5PDOPP.js';
+import '../../chunk-VMH2LRM6.js';
+import '../../chunk-YR433ZDA.js';
+import '../../chunk-6QCXIRLA.js';
+import '../../chunk-BRFMFLR6.js';
+import '../../chunk-PNWOW52F.js';
+import '../../chunk-VZDHIOCH.js';
+import '../../chunk-S4WFNGQG.js';
+import '../../chunk-64DNBF5W.js';
+import '../../chunk-IIKTTIW5.js';
+import '../../chunk-AOHBHYF6.js';
+//# sourceMappingURL=runner.js.map
+//# sourceMappingURL=runner.js.map

package/dist/builder/graph/runner.js.map

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

package/dist/builder/graph/types.d.ts

@@ -0,0 +1,3 @@
+export { B as BlueprintBuildResult, k as BuildResult, o as GraphBuilderOptions, G as GraphEdge, l as GraphNode, g as NodeConstructorOptions, n as NodeRegistry, f as NodeTypeMap, O as OriginalPredecessorIdMap, j as PredecessorIdMap, S as SubWorkflowResolver, T as TypedGraphNode, i as TypedNodeRegistry, h as TypedWorkflowGraph, W as WorkflowBlueprint, m as WorkflowGraph } from '../../types-U76Ukj96.js';
+import '../../context.js';
+import '../../logger.js';