flowcraft 1.0.0 → 2.0.0

package/README.md

@@ -1,153 +1,56 @@
-# Flowcraft: A Workflow Framework
+# Flowcraft
 
-[![npm version](https://img.shields.io/npm/v/flowcraft.svg)](https://www.npmjs.com/package/flowcraft)
+[![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)
+[![Codecov](https://img.shields.io/codecov/c/github/gorango/flowcraft/master)](https://codecov.io/github/gorango/flowcraft)
 
-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.
+Build complex, multi-step processes with a lightweight, composable, and type-safe approach. Model complex business processes, data pipelines, ETL workflows, or AI agents and scale from in-memory scripts to distributed systems without changing the core business logic.
 
-**[Read the Friendly Manual »](https://gorango.github.io/flowcraft/guide/)**
-
-## Features
+## Key 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.
-
----
-
-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.
-
-At its core, Flowcraft is guided by a few key principles:
-
-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.
-
-## The Two Paths of Flowcraft
-
-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:
-
-### 1. Programmatic Workflows
-
-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.
-
-**Choose this path if you are:**
-
-- 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.
-
-**[Learn how to build Programmatic Workflows »](https://gorango.github.io/flowcraft/guide/programmatic/basics.html)**
-
-### 2. Declarative Workflows (for Scale)
-
-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`.
-
-**Choose this path if you are:**
-
-- 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.
-
-**[Learn how to build Declarative Workflows »](https://gorango.github.io/flowcraft/guide/declarative/basics.html)**
-
----
-
-## Learn by Example
-
-> [!TIP]
-> 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.
-
-```mermaid
-graph LR
-    A[Generate Outline] --> B[Write Content]
-    B --> C[Apply Style]
+- **Declarative Workflows**: Define workflows as serializable objects with nodes and edges.
+- **Unopinionated Logic**: Nodes can be simple functions or structured classes, supporting any logic.
+- **Progressive Scalability**: Run in-memory or scale to distributed systems using the same blueprint.
+- **Resilient Execution**: Built-in support for retries, fallbacks, timeouts, and graceful cancellation.
+- **Advanced Patterns**: Includes batch processing and loop constructs for complex workflows.
+- **Extensibility**: Pluggable loggers, evaluators, serializers, and middleware for custom behavior.
+- **Static Analysis**: Tools to detect cycles, validate blueprints, and generate visual diagrams.
+- **Type-Safe API**: Fully typed with TypeScript for a robust developer experience.
+
+## Installation
+
+```bash
+npm install flowcraft
 ```
 
-- **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
+## Usage
 
-A simple agent that uses a loop and conditional branching to decide whether to search the web for information or answer a question based on the current context.
+```typescript
+import { createFlow, FlowRuntime } from './index'
 
-```mermaid
-graph TD
-    A{Decide Action} -->|"search"| B[Search Web]
-    A -->|"answer"| C[Answer Question]
-    B --> A
-```
-
-- **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/)**
+const flow = createFlow('simple-workflow')
+	.node('start', async () => ({ output: 42 }))
+	.node('double', async ({ input }) => ({ output: input * 2 }), { inputs: 'start' })
+	.edge('start', 'double')
+	.toBlueprint()
 
-### 3. Parallel Batch Processing: Document Translator
+const runtime = new FlowRuntime({
+	registry: flow.getFunctionRegistry(),
+})
 
-A practical example that translates a document into multiple languages concurrently using `ParallelBatchFlow` for a massive performance boost on I/O-bound tasks.
+async function run() {
+	const result = await runtime.run(flow, {})
+	console.log(result) // { context: { start: 42, double: 84 }, status: 'completed' }
+}
 
-```mermaid
-graph TD
-    A[Load README.md] --> B["ParallelBatchFlow"]
-    B -- "Chinese" --> T1[TranslateNode]
-    B -- "Spanish" --> T2[TranslateNode]
-    B -- "Japanese" --> T3[TranslateNode]
-    T1 & T2 & T3 --> S[Save Files]
+run()
 ```
 
-- **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
-
-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_pii] & C[check_hate_speech] & D[check_spam]
-    B & C & D --> E{triage_post}
-    E -- action_ban --> F["Sub-Workflow: Ban User"]
-    E -- action_approve --> G[approve_post_branch]
-```
-
-- **Demonstrates**:
-    - 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`, demonstrating a client-worker architecture for scalable background jobs.
-
-- **Demonstrates**:
-    - 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 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 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 »](https://github.com/gorango/flowcraft/tree/main/sandbox/6.rag/)**
-
 ## Documentation
 
-For a deep dive into all features, patterns, and APIs, please see the **[complete Flowcraft documentation](https://gorango.github.io/flowcraft/guide/)**.
+For a complete overview all features, patterns, examples, and APIs, please see the **[Flowcraft documentation](https://flowcraft.js.org/)**.
 
----
+## License
 
-Licensed under the [MIT License](https://github.com/gorango/flowcraft/tree/main/LICENSE).
+Flowcraft is licensed under the [MIT License](LICENSE).

package/dist/analysis.d.ts

@@ -0,0 +1,43 @@
+import { W as WorkflowBlueprint } from './types-CZN_FcB6.js';
+
+/**
+ * A list of cycles found in the graph. Each cycle is an array of node IDs.
+ */
+type Cycles = string[][];
+/**
+ * Analysis result for a workflow blueprint
+ */
+interface BlueprintAnalysis {
+    /** Cycles found in the graph */
+    cycles: Cycles;
+    /** Node IDs that have no incoming edges (start nodes) */
+    startNodeIds: string[];
+    /** Node IDs that have no outgoing edges (terminal nodes) */
+    terminalNodeIds: string[];
+    /** Total number of nodes */
+    nodeCount: number;
+    /** Total number of edges */
+    edgeCount: number;
+    /** Whether the graph is a valid DAG (no cycles) */
+    isDag: boolean;
+}
+/**
+ * Analyzes a workflow blueprint to detect cycles.
+ * @param blueprint The WorkflowBlueprint object containing nodes and edges.
+ * @returns An array of cycles found. Each cycle is represented as an array of node IDs.
+ */
+declare function checkForCycles(blueprint: WorkflowBlueprint): Cycles;
+/**
+ * Generates Mermaid diagram syntax from a WorkflowBlueprint
+ * @param blueprint The WorkflowBlueprint object containing nodes and edges
+ * @returns Mermaid syntax string for the flowchart
+ */
+declare function generateMermaid(blueprint: WorkflowBlueprint): string;
+/**
+ * Analyzes a workflow blueprint and returns comprehensive analysis
+ * @param blueprint The WorkflowBlueprint object containing nodes and edges
+ * @returns Analysis result with cycles, start nodes, terminal nodes, and other metrics
+ */
+declare function analyzeBlueprint(blueprint: WorkflowBlueprint): BlueprintAnalysis;
+
+export { type BlueprintAnalysis, type Cycles, analyzeBlueprint, checkForCycles, generateMermaid };

package/dist/analysis.js

@@ -0,0 +1,3 @@
+export { analyzeBlueprint, checkForCycles, generateMermaid } from './chunk-M23P46ZL.js';
+//# sourceMappingURL=analysis.js.map
+//# sourceMappingURL=analysis.js.map

package/dist/chunk-55J6XMHW.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=chunk-55J6XMHW.js.map
+//# sourceMappingURL=chunk-55J6XMHW.js.map

package/dist/{chunk-7XUN3OQT.js.map → chunk-55J6XMHW.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-7XUN3OQT.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-55J6XMHW.js"}

package/dist/chunk-6DNEDIIT.js

@@ -0,0 +1,123 @@
+import { isNodeClass } from './chunk-DSZSR7UE.js';
+
+// src/flow.ts
+var Flow = class {
+  blueprint;
+  functionRegistry;
+  loopControllerIds;
+  constructor(id) {
+    this.blueprint = { id, nodes: [], edges: [] };
+    this.functionRegistry = /* @__PURE__ */ new Map();
+    this.loopControllerIds = /* @__PURE__ */ new Map();
+  }
+  node(id, implementation, options) {
+    let usesKey;
+    if (isNodeClass(implementation)) {
+      usesKey = implementation.name && implementation.name !== "BaseNode" ? implementation.name : `class_${globalThis.crypto.randomUUID()}`;
+      this.functionRegistry.set(usesKey, implementation);
+    } else {
+      usesKey = `fn_${globalThis.crypto.randomUUID()}`;
+      this.functionRegistry.set(usesKey, implementation);
+    }
+    const nodeDef = { id, uses: usesKey, ...options };
+    this.blueprint.nodes.push(nodeDef);
+    return this;
+  }
+  edge(source, target, options) {
+    const edgeDef = { source, target, ...options };
+    this.blueprint.edges.push(edgeDef);
+    return this;
+  }
+  /**
+   * Creates a batch processing pattern.
+   * It takes an input array, runs a worker node on each item in parallel, and gathers the results.
+   * @param id The base ID for this batch operation.
+   * @param worker The node implementation to run on each item.
+   * @param options Configuration for the batch operation.
+   * @param options.inputKey The key in the context that holds the input array for the batch.
+   * @param options.outputKey The key in the context where the array of results will be stored.
+   * @returns The Flow instance for chaining.
+   */
+  batch(id, worker, options) {
+    const { inputKey, outputKey } = options;
+    const scatterId = `${id}_scatter`;
+    const gatherId = `${id}_gather`;
+    let workerUsesKey;
+    if (isNodeClass(worker)) {
+      workerUsesKey = worker.name && worker.name !== "BaseNode" ? worker.name : `class_batch_worker_${globalThis.crypto.randomUUID()}`;
+      this.functionRegistry.set(workerUsesKey, worker);
+    } else {
+      workerUsesKey = `fn_batch_worker_${globalThis.crypto.randomUUID()}`;
+      this.functionRegistry.set(workerUsesKey, worker);
+    }
+    this.blueprint.nodes.push({
+      id: scatterId,
+      uses: "batch-scatter",
+      // This is a special, built-in node type
+      inputs: inputKey,
+      params: { workerUsesKey, outputKey, gatherNodeId: gatherId }
+    });
+    this.blueprint.nodes.push({
+      id: gatherId,
+      uses: "batch-gather",
+      // built-in node type
+      params: { outputKey },
+      config: { joinStrategy: "all" }
+      // Important: Must wait for all scattered jobs
+    });
+    this.edge(scatterId, gatherId);
+    return this;
+  }
+  /**
+   * Creates a loop pattern in the workflow graph.
+   * @param id A unique identifier for the loop construct.
+   * @param options Defines the start, end, and continuation condition of the loop.
+   * @param options.startNodeId The ID of the first node inside the loop body.
+   * @param options.endNodeId The ID of the last node inside the loop body.
+   * @param options.condition An expression that, if true, causes the loop to run again.
+   */
+  loop(id, options) {
+    const { startNodeId, endNodeId, condition } = options;
+    const controllerId = `${id}-loop`;
+    this.loopControllerIds.set(id, controllerId);
+    this.blueprint.nodes.push({
+      id: controllerId,
+      uses: "loop-controller",
+      // Special built-in node type
+      params: { condition },
+      config: { joinStrategy: "any" }
+    });
+    this.edge(endNodeId, controllerId);
+    this.edge(controllerId, startNodeId, { action: "continue", transform: `context.${endNodeId}` });
+    const startNode = this.blueprint.nodes.find((n) => n.id === startNodeId);
+    if (startNode)
+      startNode.config = { ...startNode.config, joinStrategy: "any" };
+    const endNode = this.blueprint.nodes.find((n) => n.id === endNodeId);
+    if (endNode)
+      endNode.config = { ...endNode.config, joinStrategy: "any" };
+    return this;
+  }
+  getLoopControllerId(id) {
+    const controllerId = this.loopControllerIds.get(id);
+    if (!controllerId) {
+      throw new Error(`Loop with id '${id}' not found. Ensure you have defined it using the .loop() method.`);
+    }
+    return controllerId;
+  }
+  toBlueprint() {
+    if (!this.blueprint.nodes || this.blueprint.nodes.length === 0) {
+      throw new Error("Cannot build a blueprint with no nodes.");
+    }
+    return this.blueprint;
+  }
+  getFunctionRegistry() {
+    return this.functionRegistry;
+  }
+};
+function createFlow(id) {
+  return new Flow(id);
+}
+
+export { Flow, createFlow };
+//# sourceMappingURL=chunk-6DNEDIIT.js.map
+//# sourceMappingURL=chunk-6DNEDIIT.js.map

package/dist/chunk-6DNEDIIT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/flow.ts"],"names":[],"mappings":"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","file":"chunk-6DNEDIIT.js","sourcesContent":["import type { EdgeDefinition, NodeClass, NodeDefinition, NodeFunction, WorkflowBlueprint } from './types'\nimport { isNodeClass } from './node'\n\n/**\n * A fluent API for programmatically constructing a WorkflowBlueprint.\n */\nexport class Flow<\n\tTContext extends Record<string, any> = Record<string, any>,\n\tTDependencies extends Record<string, any> = Record<string, any>,\n> {\n\tprivate blueprint: Partial<WorkflowBlueprint>\n\tprivate functionRegistry: Map<string, NodeFunction | NodeClass>\n\tprivate loopControllerIds: Map<string, string>\n\n\tconstructor(id: string) {\n\t\tthis.blueprint = { id, nodes: [], edges: [] }\n\t\tthis.functionRegistry = new Map()\n\t\tthis.loopControllerIds = new Map()\n\t}\n\n\tnode(\n\t\tid: string,\n\t\timplementation: NodeFunction<TContext, TDependencies> | NodeClass,\n\t\toptions?: Omit<NodeDefinition, 'id' | 'uses'>,\n\t): this {\n\t\tlet usesKey: string\n\n\t\tif (isNodeClass(implementation)) {\n\t\t\tusesKey = (implementation.name && implementation.name !== 'BaseNode')\n\t\t\t\t? implementation.name\n\t\t\t\t: `class_${globalThis.crypto.randomUUID()}`\n\t\t\tthis.functionRegistry.set(usesKey, implementation)\n\t\t}\n\t\telse {\n\t\t\tusesKey = `fn_${globalThis.crypto.randomUUID()}`\n\t\t\tthis.functionRegistry.set(usesKey, implementation as NodeFunction)\n\t\t}\n\n\t\tconst nodeDef: NodeDefinition = { id, uses: usesKey, ...options }\n\t\tthis.blueprint.nodes!.push(nodeDef)\n\t\treturn this\n\t}\n\n\tedge(source: string, target: string, options?: Omit<EdgeDefinition, 'source' | 'target'>): this {\n\t\tconst edgeDef: EdgeDefinition = { source, target, ...options }\n\t\tthis.blueprint.edges!.push(edgeDef)\n\t\treturn this\n\t}\n\n\t/**\n\t * Creates a batch processing pattern.\n\t * It takes an input array, runs a worker node on each item in parallel, and gathers the results.\n\t * @param id The base ID for this batch operation.\n\t * @param worker The node implementation to run on each item.\n\t * @param options Configuration for the batch operation.\n\t * @param options.inputKey The key in the context that holds the input array for the batch.\n\t * @param options.outputKey The key in the context where the array of results will be stored.\n\t * @returns The Flow instance for chaining.\n\t */\n\tbatch(id: string, worker: NodeFunction<TContext, TDependencies> | NodeClass, options: {\n\t\t/** The key in the context that holds the input array for the batch. */\n\t\tinputKey: string\n\t\t/** The key in the context where the array of results will be stored. */\n\t\toutputKey: string\n\t}): this {\n\t\tconst { inputKey, outputKey } = options\n\t\tconst scatterId = `${id}_scatter`\n\t\tconst gatherId = `${id}_gather`\n\n\t\t// Register the user's worker implementation under a unique key.\n\t\tlet workerUsesKey: string\n\t\tif (isNodeClass(worker)) {\n\t\t\tworkerUsesKey = (worker.name && worker.name !== 'BaseNode') ? worker.name : `class_batch_worker_${globalThis.crypto.randomUUID()}`\n\t\t\tthis.functionRegistry.set(workerUsesKey, worker)\n\t\t}\n\t\telse {\n\t\t\tworkerUsesKey = `fn_batch_worker_${globalThis.crypto.randomUUID()}`\n\t\t\tthis.functionRegistry.set(workerUsesKey, worker as NodeFunction)\n\t\t}\n\n\t\t// Scatter Node: A built-in node that takes an array and dynamically schedules worker nodes.\n\t\tthis.blueprint.nodes!.push({\n\t\t\tid: scatterId,\n\t\t\tuses: 'batch-scatter', // This is a special, built-in node type\n\t\t\tinputs: inputKey,\n\t\t\tparams: { workerUsesKey, outputKey, gatherNodeId: gatherId },\n\t\t})\n\n\t\t// Gather Node: A built-in node that waits for all workers to finish and collects the results.\n\t\tthis.blueprint.nodes!.push({\n\t\t\tid: gatherId,\n\t\t\tuses: 'batch-gather', // built-in node type\n\t\t\tparams: { outputKey },\n\t\t\tconfig: { joinStrategy: 'all' }, // Important: Must wait for all scattered jobs\n\t\t})\n\n\t\t// Edge to connect the scatter and gather nodes. The orchestrator will manage the dynamic workers.\n\t\tthis.edge(scatterId, gatherId)\n\n\t\treturn this\n\t}\n\n\t/**\n\t * Creates a loop pattern in the workflow graph.\n\t * @param id A unique identifier for the loop construct.\n\t * @param options Defines the start, end, and continuation condition of the loop.\n\t * @param options.startNodeId The ID of the first node inside the loop body.\n\t * @param options.endNodeId The ID of the last node inside the loop body.\n\t * @param options.condition An expression that, if true, causes the loop to run again.\n\t */\n\tloop(id: string, options: {\n\t\t/** The ID of the first node inside the loop body. */\n\t\tstartNodeId: string\n\t\t/** The ID of the last node inside the loop body. */\n\t\tendNodeId: string\n\t\t/** An expression that, if true, causes the loop to run again. */\n\t\tcondition: string\n\t}): this {\n\t\tconst { startNodeId, endNodeId, condition } = options\n\t\tconst controllerId = `${id}-loop`\n\n\t\t// Store the generated ID against the user-provided loop ID\n\t\tthis.loopControllerIds.set(id, controllerId)\n\n\t\t// Add the controller node, which evaluates the loop condition.\n\t\t// Set joinStrategy='any' to allow re-execution on each loop iteration\n\t\tthis.blueprint.nodes!.push({\n\t\t\tid: controllerId,\n\t\t\tuses: 'loop-controller', // Special built-in node type\n\t\t\tparams: { condition },\n\t\t\tconfig: { joinStrategy: 'any' },\n\t\t})\n\n\t\t// Connect the end of the loop body to the controller.\n\t\tthis.edge(endNodeId, controllerId)\n\n\t\t// Connect the controller back to the start of the loop if the condition is met.\n\t\t// Use a transform to pass the end node's value to the start node for the next iteration.\n\t\tthis.edge(controllerId, startNodeId, { action: 'continue', transform: `context.${endNodeId}` })\n\n\t\t// Set the start and end nodes to use 'any' join strategy so they can re-execute\n\t\t// Start node: executes when either its initial predecessor OR the loop controller completes\n\t\t// End node: needs to re-execute on each loop iteration\n\t\tconst startNode = this.blueprint.nodes!.find(n => n.id === startNodeId)\n\t\tif (startNode)\n\t\t\tstartNode.config = { ...startNode.config, joinStrategy: 'any' }\n\n\t\tconst endNode = this.blueprint.nodes!.find(n => n.id === endNodeId)\n\t\tif (endNode)\n\t\t\tendNode.config = { ...endNode.config, joinStrategy: 'any' }\n\n\t\treturn this\n\t}\n\n\tgetLoopControllerId(id: string): string {\n\t\tconst controllerId = this.loopControllerIds.get(id)\n\t\tif (!controllerId) {\n\t\t\tthrow new Error(`Loop with id '${id}' not found. Ensure you have defined it using the .loop() method.`)\n\t\t}\n\t\treturn controllerId\n\t}\n\n\ttoBlueprint(): WorkflowBlueprint {\n\t\tif (!this.blueprint.nodes || this.blueprint.nodes.length === 0) {\n\t\t\tthrow new Error('Cannot build a blueprint with no nodes.')\n\t\t}\n\t\treturn this.blueprint as WorkflowBlueprint\n\t}\n\n\tgetFunctionRegistry() {\n\t\treturn this.functionRegistry\n\t}\n}\n\n/**\n * Helper function to create a new Flow builder instance.\n */\nexport function createFlow<\n\tTContext extends Record<string, any> = Record<string, any>,\n\tTDependencies extends Record<string, any> = Record<string, any>,\n>(id: string): Flow<TContext, TDependencies> {\n\treturn new Flow(id)\n}\n"]}

package/dist/chunk-734J4PTM.js

@@ -0,0 +1,100 @@
+import { CancelledWorkflowError, FatalNodeExecutionError } from './chunk-WXT3YEWU.js';
+
+// src/runtime/executors.ts
+var FunctionNodeExecutor = class {
+  constructor(implementation, maxRetries, eventBus) {
+    this.implementation = implementation;
+    this.maxRetries = maxRetries;
+    this.eventBus = eventBus;
+  }
+  async execute(nodeDef, context, executionId, signal) {
+    let lastError;
+    for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+      try {
+        signal?.throwIfAborted();
+        const result = await this.implementation(context);
+        if (attempt > 1) {
+          context.dependencies.logger.info(`Node execution succeeded after retry`, { nodeId: nodeDef.id, attempt, executionId });
+        }
+        return result;
+      } catch (error) {
+        lastError = error;
+        if (error instanceof DOMException && error.name === "AbortError") {
+          throw new CancelledWorkflowError("Workflow cancelled");
+        }
+        if (error instanceof FatalNodeExecutionError)
+          break;
+        if (attempt < this.maxRetries) {
+          context.dependencies.logger.warn(`Node execution failed, retrying`, { nodeId: nodeDef.id, attempt, maxRetries: this.maxRetries, error: error instanceof Error ? error.message : String(error), executionId });
+          await this.eventBus.emit("node:retry", { blueprintId: context.dependencies.blueprint?.id || "", nodeId: nodeDef.id, attempt, executionId });
+        } else {
+          context.dependencies.logger.error(`Node execution failed after all retries`, { nodeId: nodeDef.id, attempts: this.maxRetries, error: error instanceof Error ? error.message : String(error), executionId });
+        }
+      }
+    }
+    throw lastError;
+  }
+};
+var ClassNodeExecutor = class {
+  constructor(implementation, maxRetries, eventBus) {
+    this.implementation = implementation;
+    this.maxRetries = maxRetries;
+    this.eventBus = eventBus;
+  }
+  async execute(nodeDef, context, executionId, signal) {
+    const instance = new this.implementation(nodeDef.params || {});
+    try {
+      signal?.throwIfAborted();
+      const prepResult = await instance.prep(context);
+      let execResult;
+      let lastError;
+      for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+        try {
+          signal?.throwIfAborted();
+          execResult = await instance.exec(prepResult, context);
+          lastError = void 0;
+          if (attempt > 1) {
+            context.dependencies.logger.info(`Node execution succeeded after retry`, { nodeId: nodeDef.id, attempt, executionId });
+          }
+          break;
+        } catch (error) {
+          lastError = error;
+          if (error instanceof DOMException && error.name === "AbortError") {
+            throw new CancelledWorkflowError("Workflow cancelled");
+          }
+          if (error instanceof FatalNodeExecutionError)
+            break;
+          if (attempt < this.maxRetries) {
+            context.dependencies.logger.warn(`Node execution failed, retrying`, { nodeId: nodeDef.id, attempt, maxRetries: this.maxRetries, error: error instanceof Error ? error.message : String(error), executionId });
+            await this.eventBus.emit("node:retry", { blueprintId: context.dependencies.blueprint?.id || "", nodeId: nodeDef.id, attempt, executionId });
+          } else {
+            context.dependencies.logger.error(`Node execution failed after all retries`, { nodeId: nodeDef.id, attempts: this.maxRetries, error: error instanceof Error ? error.message : String(error), executionId });
+          }
+        }
+      }
+      if (lastError) {
+        signal?.throwIfAborted();
+        execResult = await instance.fallback(lastError, context);
+      }
+      signal?.throwIfAborted();
+      return await instance.post(execResult, context);
+    } catch (error) {
+      if (error instanceof DOMException && error.name === "AbortError") {
+        throw new CancelledWorkflowError("Workflow cancelled");
+      }
+      throw error;
+    }
+  }
+};
+var BuiltInNodeExecutor = class {
+  constructor(executeBuiltIn) {
+    this.executeBuiltIn = executeBuiltIn;
+  }
+  async execute(nodeDef, context) {
+    return this.executeBuiltIn(nodeDef, context.context);
+  }
+};
+
+export { BuiltInNodeExecutor, ClassNodeExecutor, FunctionNodeExecutor };
+//# sourceMappingURL=chunk-734J4PTM.js.map
+//# sourceMappingURL=chunk-734J4PTM.js.map

package/dist/chunk-734J4PTM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/runtime/executors.ts"],"names":[],"mappings":"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","file":"chunk-734J4PTM.js","sourcesContent":["import type { BaseNode } from '../node'\nimport type { ContextImplementation, IEventBus, NodeContext, NodeDefinition, NodeFunction, NodeResult } from '../types'\nimport { CancelledWorkflowError, FatalNodeExecutionError } from '../errors'\n\nexport interface ExecutionStrategy {\n\texecute: (\n\t\tnodeDef: NodeDefinition,\n\t\tcontext: NodeContext<any, any>,\n\t\texecutionId?: string,\n\t\tsignal?: AbortSignal,\n\t) => Promise<NodeResult>\n}\n\nexport class FunctionNodeExecutor implements ExecutionStrategy {\n\tconstructor(\n\t\tprivate implementation: NodeFunction,\n\t\tprivate maxRetries: number,\n\t\tprivate eventBus: IEventBus,\n\t) { }\n\n\tasync execute(\n\t\tnodeDef: NodeDefinition,\n\t\tcontext: NodeContext<any, any>,\n\t\texecutionId?: string,\n\t\tsignal?: AbortSignal,\n\t): Promise<NodeResult> {\n\t\tlet lastError: any\n\t\tfor (let attempt = 1; attempt <= this.maxRetries; attempt++) {\n\t\t\ttry {\n\t\t\t\tsignal?.throwIfAborted()\n\t\t\t\tconst result = await this.implementation(context)\n\t\t\t\tif (attempt > 1) {\n\t\t\t\t\tcontext.dependencies.logger.info(`Node execution succeeded after retry`, { nodeId: nodeDef.id, attempt, executionId })\n\t\t\t\t}\n\t\t\t\treturn result\n\t\t\t}\n\t\t\tcatch (error) {\n\t\t\t\tlastError = error\n\t\t\t\tif (error instanceof DOMException && error.name === 'AbortError') {\n\t\t\t\t\tthrow new CancelledWorkflowError('Workflow cancelled')\n\t\t\t\t}\n\t\t\t\tif (error instanceof FatalNodeExecutionError)\n\t\t\t\t\tbreak\n\t\t\t\tif (attempt < this.maxRetries) {\n\t\t\t\t\tcontext.dependencies.logger.warn(`Node execution failed, retrying`, { nodeId: nodeDef.id, attempt, maxRetries: this.maxRetries, error: error instanceof Error ? error.message : String(error), executionId })\n\t\t\t\t\tawait this.eventBus.emit('node:retry', { blueprintId: context.dependencies.blueprint?.id || '', nodeId: nodeDef.id, attempt, executionId })\n\t\t\t\t}\n\t\t\t\telse {\n\t\t\t\t\tcontext.dependencies.logger.error(`Node execution failed after all retries`, { nodeId: nodeDef.id, attempts: this.maxRetries, error: error instanceof Error ? error.message : String(error), executionId })\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tthrow lastError\n\t}\n}\n\nexport class ClassNodeExecutor implements ExecutionStrategy {\n\tconstructor(\n\t\tprivate implementation: typeof BaseNode,\n\t\tprivate maxRetries: number,\n\t\tprivate eventBus: IEventBus,\n\t) { }\n\n\tasync execute(\n\t\tnodeDef: NodeDefinition,\n\t\tcontext: NodeContext<any, any>,\n\t\texecutionId?: string,\n\t\tsignal?: AbortSignal,\n\t): Promise<NodeResult> {\n\t\tconst instance = new (this.implementation as new (params: Record<string, any>) => BaseNode)(nodeDef.params || {})\n\t\ttry {\n\t\t\tsignal?.throwIfAborted()\n\t\t\tconst prepResult = await instance.prep(context)\n\t\t\tlet execResult: Omit<NodeResult, 'error'>\n\t\t\tlet lastError: any\n\t\t\tfor (let attempt = 1; attempt <= this.maxRetries; attempt++) {\n\t\t\t\ttry {\n\t\t\t\t\tsignal?.throwIfAborted()\n\t\t\t\t\texecResult = await instance.exec(prepResult, context)\n\t\t\t\t\tlastError = undefined\n\t\t\t\t\tif (attempt > 1) {\n\t\t\t\t\t\tcontext.dependencies.logger.info(`Node execution succeeded after retry`, { nodeId: nodeDef.id, attempt, executionId })\n\t\t\t\t\t}\n\t\t\t\t\tbreak\n\t\t\t\t}\n\t\t\t\tcatch (error) {\n\t\t\t\t\tlastError = error\n\t\t\t\t\tif (error instanceof DOMException && error.name === 'AbortError') {\n\t\t\t\t\t\tthrow new CancelledWorkflowError('Workflow cancelled')\n\t\t\t\t\t}\n\t\t\t\t\tif (error instanceof FatalNodeExecutionError)\n\t\t\t\t\t\tbreak\n\t\t\t\t\tif (attempt < this.maxRetries) {\n\t\t\t\t\t\tcontext.dependencies.logger.warn(`Node execution failed, retrying`, { nodeId: nodeDef.id, attempt, maxRetries: this.maxRetries, error: error instanceof Error ? error.message : String(error), executionId })\n\t\t\t\t\t\tawait this.eventBus.emit('node:retry', { blueprintId: context.dependencies.blueprint?.id || '', nodeId: nodeDef.id, attempt, executionId })\n\t\t\t\t\t}\n\t\t\t\t\telse {\n\t\t\t\t\t\tcontext.dependencies.logger.error(`Node execution failed after all retries`, { nodeId: nodeDef.id, attempts: this.maxRetries, error: error instanceof Error ? error.message : String(error), executionId })\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (lastError) {\n\t\t\t\tsignal?.throwIfAborted()\n\t\t\t\texecResult = await instance.fallback(lastError, context)\n\t\t\t}\n\t\t\tsignal?.throwIfAborted()\n\t\t\treturn await instance.post(execResult!, context)\n\t\t}\n\t\tcatch (error) {\n\t\t\tif (error instanceof DOMException && error.name === 'AbortError') {\n\t\t\t\tthrow new CancelledWorkflowError('Workflow cancelled')\n\t\t\t}\n\t\t\tthrow error\n\t\t}\n\t}\n}\n\nexport class BuiltInNodeExecutor implements ExecutionStrategy {\n\tconstructor(\n\t\tprivate executeBuiltIn: (nodeDef: NodeDefinition, context: ContextImplementation<any>) => Promise<NodeResult>,\n\t) { }\n\n\tasync execute(\n\t\tnodeDef: NodeDefinition,\n\t\tcontext: NodeContext<any, any>,\n\t): Promise<NodeResult> {\n\t\treturn this.executeBuiltIn(nodeDef, context.context as ContextImplementation<any>)\n\t}\n}\n"]}

package/dist/chunk-DSZSR7UE.js

@@ -0,0 +1,40 @@
+// src/node.ts
+function isNodeClass(impl) {
+  return typeof impl === "function" && !!impl.prototype?.exec;
+}
+var BaseNode = class {
+  /**
+   * @param params Static parameters for this node instance, passed from the blueprint.
+   */
+  constructor(params) {
+    this.params = params;
+  }
+  /**
+   * 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.
+   */
+  async prep(context) {
+    return context.input;
+  }
+  /**
+   * 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.
+   */
+  async post(execResult, _context) {
+    return execResult;
+  }
+  /**
+   * 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.
+   */
+  async fallback(error, _context) {
+    throw error;
+  }
+};
+
+export { BaseNode, isNodeClass };
+//# sourceMappingURL=chunk-DSZSR7UE.js.map
+//# sourceMappingURL=chunk-DSZSR7UE.js.map

package/dist/chunk-DSZSR7UE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/node.ts"],"names":[],"mappings":";AAKO,SAAS,YAAY,IAAA,EAA8B;AACzD,EAAA,OAAO,OAAO,IAAA,KAAS,UAAA,IAAc,CAAC,CAAC,KAAK,SAAA,EAAW,IAAA;AACxD;AAOO,IAAe,WAAf,MAGL;AAAA;AAAA;AAAA;AAAA,EAID,YAAsB,MAAA,EAA6B;AAA7B,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAAA,EAA+B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOrD,MAAM,KAAK,OAAA,EAA6D;AACvE,IAAA,OAAO,OAAA,CAAQ,KAAA;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcA,MAAM,IAAA,CAAK,UAAA,EAAuC,QAAA,EAAqE;AACtH,IAAA,OAAO,UAAA;AAAA,EACR;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,QAAA,CAAS,KAAA,EAAc,QAAA,EAAoF;AAEhH,IAAA,MAAM,KAAA;AAAA,EACP;AACD","file":"chunk-DSZSR7UE.js","sourcesContent":["/** eslint-disable unused-imports/no-unused-vars */\n\nimport type { NodeClass, NodeContext, NodeResult, RuntimeDependencies } from './types'\n\n/** A type guard to reliably distinguish a NodeClass from a NodeFunction. */\nexport function isNodeClass(impl: any): impl is NodeClass {\n\treturn typeof impl === 'function' && !!impl.prototype?.exec\n}\n\n/**\n * A structured, class-based node for complex logic with a safe, granular lifecycle.\n * This class is generic, allowing implementations to specify the exact context\n * and dependency types they expect.\n */\nexport abstract class BaseNode<\n\tTContext extends Record<string, any> = Record<string, any>,\n\tTDependencies extends RuntimeDependencies = RuntimeDependencies,\n> {\n\t/**\n\t * @param params Static parameters for this node instance, passed from the blueprint.\n\t */\n\tconstructor(protected params: Record<string, any>) { }\n\n\t/**\n\t * Phase 1: Gathers and prepares data for execution. This phase is NOT retried on failure.\n\t * @param context The node's execution context.\n\t * @returns The data needed for the `exec` phase.\n\t */\n\tasync prep(context: NodeContext<TContext, TDependencies>): Promise<any> {\n\t\treturn context.input\n\t}\n\n\t/**\n\t * Phase 2: Performs the core, isolated logic. This is the ONLY phase that is retried.\n\t * @param prepResult The data returned from the `prep` phase.\n\t * @param context The node's execution context.\n\t */\n\tabstract exec(prepResult: any, context: NodeContext<TContext, TDependencies>): Promise<Omit<NodeResult, 'error'>>\n\n\t/**\n\t * Phase 3: Processes the result and saves state. This phase is NOT retried.\n\t * @param execResult The successful result from the `exec` or `fallback` phase.\n\t * @param _context The node's execution context.\n\t */\n\tasync post(execResult: Omit<NodeResult, 'error'>, _context: NodeContext<TContext, TDependencies>): Promise<NodeResult> {\n\t\treturn execResult\n\t}\n\n\t/**\n\t * An optional safety net that runs if all `exec` retries fail.\n\t * @param error The final error from the last `exec` attempt.\n\t * @param _context The node's execution context.\n\t */\n\tasync fallback(error: Error, _context: NodeContext<TContext, TDependencies>): Promise<Omit<NodeResult, 'error'>> {\n\t\t// By default, re-throw the error, failing the node.\n\t\tthrow error\n\t}\n}\n"]}

package/dist/chunk-GTZC6PQI.js

@@ -0,0 +1,22 @@
+// src/evaluator.ts
+var SimpleEvaluator = class {
+  evaluate(expression, context) {
+    try {
+      const validIdentifierRegex = /^[a-z_$][\w$]*$/i;
+      const validKeys = Object.keys(context).filter((key) => validIdentifierRegex.test(key));
+      const validContext = {};
+      for (const key of validKeys) {
+        validContext[key] = context[key];
+      }
+      const sandbox = new Function(...validKeys, `return ${expression}`);
+      return sandbox(...validKeys.map((k) => validContext[k]));
+    } catch (error) {
+      console.error(`Error evaluating expression "${expression}":`, error);
+      return void 0;
+    }
+  }
+};
+
+export { SimpleEvaluator };
+//# sourceMappingURL=chunk-GTZC6PQI.js.map
+//# sourceMappingURL=chunk-GTZC6PQI.js.map

package/dist/chunk-GTZC6PQI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/evaluator.ts"],"names":[],"mappings":";AAiBO,IAAM,kBAAN,MAA4C;AAAA,EAClD,QAAA,CAAS,YAAoB,OAAA,EAAmC;AAC/D,IAAA,IAAI;AAEH,MAAA,MAAM,oBAAA,GAAuB,kBAAA;AAC7B,MAAA,MAAM,SAAA,GAAY,MAAA,CAAO,IAAA,CAAK,OAAO,CAAA,CAAE,OAAO,CAAA,GAAA,KAAO,oBAAA,CAAqB,IAAA,CAAK,GAAG,CAAC,CAAA;AACnF,MAAA,MAAM,eAAoC,EAAC;AAC3C,MAAA,KAAA,MAAW,OAAO,SAAA,EAAW;AAC5B,QAAA,YAAA,CAAa,GAAG,CAAA,GAAI,OAAA,CAAQ,GAAG,CAAA;AAAA,MAChC;AAIA,MAAA,MAAM,UAAU,IAAI,QAAA,CAAS,GAAG,SAAA,EAAW,CAAA,OAAA,EAAU,UAAU,CAAA,CAAE,CAAA;AACjE,MAAA,OAAO,OAAA,CAAQ,GAAG,SAAA,CAAU,GAAA,CAAI,OAAK,YAAA,CAAa,CAAC,CAAC,CAAC,CAAA;AAAA,IACtD,SACO,KAAA,EAAO;AACb,MAAA,OAAA,CAAQ,KAAA,CAAM,CAAA,6BAAA,EAAgC,UAAU,CAAA,EAAA,CAAA,EAAM,KAAK,CAAA;AAEnE,MAAA,OAAO,MAAA;AAAA,IACR;AAAA,EACD;AACD","file":"chunk-GTZC6PQI.js","sourcesContent":["import type { IEvaluator } from './types'\n\n/**\n * A simple, safe, placeholder expression evaluator.\n * It provides a sandboxed environment for evaluating edge conditions and transforms.\n *\n * @warning This implementation uses `new Function()` which, while sandboxed from the global\n * scope, can be a security risk if expressions are provided by end-users. It is NOT\n * recommended for production systems. Please replace this with a more robust and secure\n * library like `jsep` by providing your own implementation in the runtime options.\n *\n * This implementation can only access properties on a single context object.\n * Example expressions:\n * - \"result.output.status === 'SUCCESS'\"\n * - \"context.user.isAdmin\"\n * - \"input.value * 100\"\n */\nexport class SimpleEvaluator implements IEvaluator {\n\tevaluate(expression: string, context: Record<string, any>): any {\n\t\ttry {\n\t\t\t// Filter out keys that aren't valid JavaScript identifiers\n\t\t\tconst validIdentifierRegex = /^[a-z_$][\\w$]*$/i\n\t\t\tconst validKeys = Object.keys(context).filter(key => validIdentifierRegex.test(key))\n\t\t\tconst validContext: Record<string, any> = {}\n\t\t\tfor (const key of validKeys) {\n\t\t\t\tvalidContext[key] = context[key]\n\t\t\t}\n\n\t\t\t// Creates a function that is sandboxed to only the keys of the `context` object.\n\t\t\t// It prevents access to global scope (e.g., `window`, `process`).\n\t\t\tconst sandbox = new Function(...validKeys, `return ${expression}`) // eslint-disable-line no-new-func\n\t\t\treturn sandbox(...validKeys.map(k => validContext[k]))\n\t\t}\n\t\tcatch (error) {\n\t\t\tconsole.error(`Error evaluating expression \"${expression}\":`, error)\n\t\t\t// In case of a syntax error or other issue, default to a \"falsy\" value.\n\t\t\treturn undefined\n\t\t}\n\t}\n}\n"]}

package/dist/chunk-HMR2GEGE.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=chunk-HMR2GEGE.js.map
+//# sourceMappingURL=chunk-HMR2GEGE.js.map

package/dist/{chunk-F2RSES6P.js.map → chunk-HMR2GEGE.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-F2RSES6P.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-HMR2GEGE.js"}

package/dist/chunk-J3RNCPED.js

@@ -0,0 +1,27 @@
+// src/sanitizer.ts
+function sanitizeBlueprint(raw) {
+  const nodes = raw.nodes?.map((node) => ({
+    id: node.id,
+    uses: node.uses,
+    params: node.params,
+    inputs: node.inputs,
+    config: node.config
+  })) || [];
+  const edges = raw.edges?.map((edge) => ({
+    source: edge.source,
+    target: edge.target,
+    action: edge.action,
+    condition: edge.condition,
+    transform: edge.transform
+  })) || [];
+  return {
+    id: raw.id,
+    nodes,
+    edges,
+    metadata: raw.metadata
+  };
+}
+
+export { sanitizeBlueprint };
+//# sourceMappingURL=chunk-J3RNCPED.js.map
+//# sourceMappingURL=chunk-J3RNCPED.js.map