flowcraft 1.0.0 → 2.1.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 of all features, patterns, examples, and APIs, 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-lG3xCzp_.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-HN72TZY5.js';
+//# sourceMappingURL=analysis.js.map
+//# sourceMappingURL=analysis.js.map

package/dist/chunk-4PELJWF7.js

@@ -0,0 +1,29 @@
+// src/logger.ts
+var ConsoleLogger = class {
+  debug(message, meta) {
+    console.debug(`[DEBUG] ${message}`, meta || "");
+  }
+  info(message, meta) {
+    console.info(`[INFO] ${message}`, meta || "");
+  }
+  warn(message, meta) {
+    console.warn(`[WARN] ${message}`, meta || "");
+  }
+  error(message, meta) {
+    console.error(`[ERROR] ${message}`, meta || "");
+  }
+};
+var NullLogger = class {
+  debug(_message, _meta) {
+  }
+  info(_message, _meta) {
+  }
+  warn(_message, _meta) {
+  }
+  error(_message, _meta) {
+  }
+};
+
+export { ConsoleLogger, NullLogger };
+//# sourceMappingURL=chunk-4PELJWF7.js.map
+//# sourceMappingURL=chunk-4PELJWF7.js.map

package/dist/chunk-4PELJWF7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/logger.ts"],"names":[],"mappings":";AAGO,IAAM,gBAAN,MAAuC;AAAA,EAC7C,KAAA,CAAM,SAAiB,IAAA,EAAkC;AACxD,IAAA,OAAA,CAAQ,KAAA,CAAM,CAAA,QAAA,EAAW,OAAO,CAAA,CAAA,EAAI,QAAQ,EAAE,CAAA;AAAA,EAC/C;AAAA,EAEA,IAAA,CAAK,SAAiB,IAAA,EAAkC;AACvD,IAAA,OAAA,CAAQ,IAAA,CAAK,CAAA,OAAA,EAAU,OAAO,CAAA,CAAA,EAAI,QAAQ,EAAE,CAAA;AAAA,EAC7C;AAAA,EAEA,IAAA,CAAK,SAAiB,IAAA,EAAkC;AACvD,IAAA,OAAA,CAAQ,IAAA,CAAK,CAAA,OAAA,EAAU,OAAO,CAAA,CAAA,EAAI,QAAQ,EAAE,CAAA;AAAA,EAC7C;AAAA,EAEA,KAAA,CAAM,SAAiB,IAAA,EAAkC;AACxD,IAAA,OAAA,CAAQ,KAAA,CAAM,CAAA,QAAA,EAAW,OAAO,CAAA,CAAA,EAAI,QAAQ,EAAE,CAAA;AAAA,EAC/C;AACD;AAGO,IAAM,aAAN,MAAoC;AAAA,EAC1C,KAAA,CAAM,UAAkB,KAAA,EAAmC;AAAA,EAAC;AAAA,EAC5D,IAAA,CAAK,UAAkB,KAAA,EAAmC;AAAA,EAAC;AAAA,EAC3D,IAAA,CAAK,UAAkB,KAAA,EAAmC;AAAA,EAAC;AAAA,EAC3D,KAAA,CAAM,UAAkB,KAAA,EAAmC;AAAA,EAAC;AAC7D","file":"chunk-4PELJWF7.js","sourcesContent":["import type { ILogger } from './types'\n\n/** A logger implementation that outputs to the console. */\nexport class ConsoleLogger implements ILogger {\n\tdebug(message: string, meta?: Record<string, any>): void {\n\t\tconsole.debug(`[DEBUG] ${message}`, meta || '')\n\t}\n\n\tinfo(message: string, meta?: Record<string, any>): void {\n\t\tconsole.info(`[INFO] ${message}`, meta || '')\n\t}\n\n\twarn(message: string, meta?: Record<string, any>): void {\n\t\tconsole.warn(`[WARN] ${message}`, meta || '')\n\t}\n\n\terror(message: string, meta?: Record<string, any>): void {\n\t\tconsole.error(`[ERROR] ${message}`, meta || '')\n\t}\n}\n\n/** A logger implementation that does nothing (no-op). */\nexport class NullLogger implements ILogger {\n\tdebug(_message: string, _meta?: Record<string, any>): void {}\n\tinfo(_message: string, _meta?: Record<string, any>): void {}\n\twarn(_message: string, _meta?: Record<string, any>): void {}\n\terror(_message: string, _meta?: Record<string, any>): void {}\n}\n"]}

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-5EHIPX23.js

@@ -0,0 +1,202 @@
+import { FlowRuntime } from './chunk-CO5BTPKI.js';
+import { JsonSerializer } from './chunk-CYHZ2YVH.js';
+
+// src/runtime/adapter.ts
+var BaseDistributedAdapter = class {
+  runtime;
+  store;
+  serializer;
+  constructor(options) {
+    this.runtime = new FlowRuntime(options.runtimeOptions);
+    this.store = options.coordinationStore;
+    this.serializer = options.runtimeOptions.serializer || new JsonSerializer();
+    console.log("[Adapter] BaseDistributedAdapter initialized.");
+  }
+  /**
+   * Starts the worker, which begins listening for and processing jobs from the queue.
+   */
+  start() {
+    console.log("[Adapter] Starting worker...");
+    this.processJobs(this.handleJob.bind(this));
+  }
+  /**
+   * Hook called at the start of job processing. Subclasses can override this
+   * to perform additional setup (e.g., timestamp tracking for reconciliation).
+   */
+  async onJobStart(_runId, _blueprintId, _nodeId) {
+  }
+  /**
+   * The main handler for processing a single job from the queue.
+   */
+  async handleJob(job) {
+    const { runId, blueprintId, nodeId } = job;
+    await this.onJobStart(runId, blueprintId, nodeId);
+    const blueprint = this.runtime.options.blueprints?.[blueprintId];
+    if (!blueprint) {
+      const reason = `Blueprint with ID '${blueprintId}' not found in the worker's runtime registry.`;
+      console.error(`[Adapter] FATAL: ${reason}`);
+      await this.publishFinalResult(runId, { status: "failed", reason });
+      return;
+    }
+    const context = this.createContext(runId);
+    const hasBlueprintId = await context.has("blueprintId");
+    if (!hasBlueprintId) {
+      await context.set("blueprintId", blueprintId);
+    }
+    const workerState = {
+      getContext: () => context,
+      markFallbackExecuted: () => {
+      },
+      addError: (nodeId2, error) => {
+        console.error(`[Adapter] Error in node ${nodeId2}:`, error);
+      }
+    };
+    try {
+      const result = await this.runtime.executeNode(blueprint, nodeId, workerState);
+      await context.set(nodeId, result.output);
+      const nodeDef = blueprint.nodes.find((n) => n.id === nodeId);
+      if (nodeDef?.uses === "output") {
+        console.log(`[Adapter] \u2705 Output node '${nodeId}' finished. Declaring workflow complete for Run ID: ${runId}`);
+        const finalContext = await context.toJSON();
+        const finalResult = {
+          context: finalContext,
+          serializedContext: this.serializer.serialize(finalContext),
+          status: "completed"
+        };
+        await this.publishFinalResult(runId, {
+          status: "completed",
+          payload: finalResult
+        });
+        return;
+      }
+      const nextNodes = await this.runtime.determineNextNodes(blueprint, nodeId, result, context);
+      if (nextNodes.length === 0) {
+        console.log(
+          `[Adapter] Terminal node '${nodeId}' reached for Run ID '${runId}', but it was not an 'output' node. This branch will now terminate.`
+        );
+        return;
+      }
+      for (const { node: nextNodeDef, edge } of nextNodes) {
+        await this.runtime.applyEdgeTransform(edge, result, nextNodeDef, context);
+        const isReady = await this.isReadyForFanIn(runId, blueprint, nextNodeDef.id);
+        if (isReady) {
+          console.log(`[Adapter] Node '${nextNodeDef.id}' is ready. Enqueuing job.`);
+          await this.enqueueJob({ runId, blueprintId, nodeId: nextNodeDef.id });
+        } else {
+          console.log(`[Adapter] Node '${nextNodeDef.id}' is waiting for other predecessors to complete.`);
+        }
+      }
+    } catch (error) {
+      const reason = error.message || "Unknown execution error";
+      console.error(`[Adapter] FATAL: Job for node '${nodeId}' failed for Run ID '${runId}': ${reason}`);
+      await this.publishFinalResult(runId, { status: "failed", reason });
+    }
+  }
+  /**
+   * Encapsulates the fan-in join logic using the coordination store.
+   */
+  async isReadyForFanIn(runId, blueprint, targetNodeId) {
+    const targetNode = blueprint.nodes.find((n) => n.id === targetNodeId);
+    if (!targetNode) {
+      throw new Error(`Node '${targetNodeId}' not found in blueprint`);
+    }
+    const joinStrategy = targetNode.config?.joinStrategy || "all";
+    const predecessors = blueprint.edges.filter((e) => e.target === targetNodeId);
+    if (predecessors.length <= 1) {
+      return true;
+    }
+    if (joinStrategy === "any") {
+      const lockKey = `flowcraft:joinlock:${runId}:${targetNodeId}`;
+      return await this.store.setIfNotExist(lockKey, "locked", 3600);
+    } else {
+      const fanInKey = `flowcraft:fanin:${runId}:${targetNodeId}`;
+      const readyCount = await this.store.increment(fanInKey, 3600);
+      if (readyCount >= predecessors.length) {
+        await this.store.delete(fanInKey);
+        return true;
+      }
+      return false;
+    }
+  }
+  /**
+   * Reconciles the state of a workflow run. It inspects the persisted
+   * context to find completed nodes, determines the next set of executable
+   * nodes (the frontier), and enqueues jobs for them if they aren't
+   * already running. This is the core of the resume functionality.
+   *
+   * @param runId The unique ID of the workflow execution to reconcile.
+   * @returns The set of node IDs that were enqueued for execution.
+   */
+  async reconcile(runId) {
+    const context = this.createContext(runId);
+    const blueprintId = await context.get("blueprintId");
+    if (!blueprintId) {
+      throw new Error(`Cannot reconcile runId '${runId}': blueprintId not found in context.`);
+    }
+    const blueprint = this.runtime.options.blueprints?.[blueprintId];
+    if (!blueprint) {
+      throw new Error(`Cannot reconcile runId '${runId}': Blueprint with ID '${blueprintId}' not found.`);
+    }
+    const state = await context.toJSON();
+    const completedNodes = new Set(Object.keys(state).filter((k) => blueprint.nodes.some((n) => n.id === k)));
+    const frontier = this.calculateResumedFrontier(blueprint, completedNodes);
+    const enqueuedNodes = /* @__PURE__ */ new Set();
+    for (const nodeId of frontier) {
+      const nodeDef = blueprint.nodes.find((n) => n.id === nodeId);
+      const joinStrategy = nodeDef?.config?.joinStrategy || "all";
+      let shouldEnqueue = false;
+      if (joinStrategy === "any") {
+        const lockKey = `flowcraft:joinlock:${runId}:${nodeId}`;
+        if (await this.store.setIfNotExist(lockKey, "locked-by-reconcile", 3600)) {
+          shouldEnqueue = true;
+        } else {
+          console.log(`[Adapter] Reconciling: Node '${nodeId}' is an 'any' join and is already locked.`, { runId });
+        }
+      } else {
+        const lockKey = `flowcraft:nodelock:${runId}:${nodeId}`;
+        if (await this.store.setIfNotExist(lockKey, "locked", 120)) {
+          shouldEnqueue = true;
+        } else {
+          console.log(`[Adapter] Reconciling: Node '${nodeId}' is already locked.`, { runId });
+        }
+      }
+      if (shouldEnqueue) {
+        console.log(`[Adapter] Reconciling: Enqueuing ready job for node '${nodeId}'`, { runId });
+        await this.enqueueJob({ runId, blueprintId: blueprint.id, nodeId });
+        enqueuedNodes.add(nodeId);
+      }
+    }
+    return enqueuedNodes;
+  }
+  calculateResumedFrontier(blueprint, completedNodes) {
+    const newFrontier = /* @__PURE__ */ new Set();
+    const allPredecessors = /* @__PURE__ */ new Map();
+    for (const node of blueprint.nodes) {
+      allPredecessors.set(node.id, /* @__PURE__ */ new Set());
+    }
+    for (const edge of blueprint.edges) {
+      allPredecessors.get(edge.target)?.add(edge.source);
+    }
+    for (const node of blueprint.nodes) {
+      if (completedNodes.has(node.id)) {
+        continue;
+      }
+      const predecessors = allPredecessors.get(node.id) ?? /* @__PURE__ */ new Set();
+      if (predecessors.size === 0 && !completedNodes.has(node.id)) {
+        newFrontier.add(node.id);
+        continue;
+      }
+      const joinStrategy = node.config?.joinStrategy || "all";
+      const completedPredecessors = [...predecessors].filter((p) => completedNodes.has(p));
+      const isReady = joinStrategy === "any" ? completedPredecessors.length > 0 : completedPredecessors.length === predecessors.size;
+      if (isReady) {
+        newFrontier.add(node.id);
+      }
+    }
+    return newFrontier;
+  }
+};
+
+export { BaseDistributedAdapter };
+//# sourceMappingURL=chunk-5EHIPX23.js.map
+//# sourceMappingURL=chunk-5EHIPX23.js.map

package/dist/chunk-5EHIPX23.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/runtime/adapter.ts"],"names":["nodeId"],"mappings":"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","file":"chunk-5EHIPX23.js","sourcesContent":["import { JsonSerializer } from '../serializer'\nimport type {\n\tIAsyncContext,\n\tISerializer,\n\tNodeResult,\n\tRuntimeOptions,\n\tWorkflowBlueprint,\n\tWorkflowResult,\n} from '../types'\nimport { FlowRuntime } from './runtime'\n\n/**\n * Defines the contract for an atomic, distributed key-value store required by\n * the adapter for coordination tasks like fan-in joins and locking.\n */\nexport interface ICoordinationStore {\n\t/** Atomically increments a key and returns the new value. Ideal for 'all' joins. */\n\tincrement: (key: string, ttlSeconds: number) => Promise<number>\n\t/** Sets a key only if it does not already exist. Ideal for 'any' joins (locking). */\n\tsetIfNotExist: (key: string, value: string, ttlSeconds: number) => Promise<boolean>\n\t/** Deletes a key. Used for cleanup. */\n\tdelete: (key: string) => Promise<void>\n}\n\n/** Configuration options for constructing a BaseDistributedAdapter. */\nexport interface AdapterOptions {\n\truntimeOptions: RuntimeOptions<any>\n\tcoordinationStore: ICoordinationStore\n}\n\n/** The data payload expected for a job in the queue. */\nexport interface JobPayload {\n\trunId: string\n\tblueprintId: string\n\tnodeId: string\n}\n\n/**\n * The base class for all distributed adapters. It handles the technology-agnostic\n * orchestration logic and leaves queue-specific implementation to subclasses.\n */\nexport abstract class BaseDistributedAdapter {\n\tprotected readonly runtime: FlowRuntime<any, any>\n\tprotected readonly store: ICoordinationStore\n\tprotected readonly serializer: ISerializer\n\n\tconstructor(options: AdapterOptions) {\n\t\tthis.runtime = new FlowRuntime(options.runtimeOptions)\n\t\tthis.store = options.coordinationStore\n\t\tthis.serializer = options.runtimeOptions.serializer || new JsonSerializer()\n\t\tconsole.log('[Adapter] BaseDistributedAdapter initialized.')\n\t}\n\n\t/**\n\t * Starts the worker, which begins listening for and processing jobs from the queue.\n\t */\n\tpublic start(): void {\n\t\tconsole.log('[Adapter] Starting worker...')\n\t\tthis.processJobs(this.handleJob.bind(this))\n\t}\n\n\t/**\n\t * Creates a technology-specific distributed context for a given workflow run.\n\t * @param runId The unique ID for the workflow execution.\n\t */\n\tprotected abstract createContext(runId: string): IAsyncContext<Record<string, any>>\n\t/**\n\t * Sets up the listener for the message queue. The implementation should call the\n\t * provided `handler` function for each new job received.\n\t * @param handler The core logic to execute for each job.\n\t */\n\tprotected abstract processJobs(handler: (job: JobPayload) => Promise<void>): void\n\n\t/**\n\t * Enqueues a new job onto the message queue.\n\t * @param job The payload for the job to be enqueued.\n\t */\n\tprotected abstract enqueueJob(job: JobPayload): Promise<void>\n\n\t/**\n\t * Publishes the final result of a completed or failed workflow run.\n\t * @param runId The unique ID of the workflow run.\n\t * @param result The final status and payload of the workflow.\n\t */\n\tprotected abstract publishFinalResult(\n\t\trunId: string,\n\t\tresult: {\n\t\t\tstatus: 'completed' | 'failed'\n\t\t\tpayload?: WorkflowResult\n\t\t\treason?: string\n\t\t},\n\t): Promise<void>\n\n\t/**\n\t * Hook called at the start of job processing. Subclasses can override this\n\t * to perform additional setup (e.g., timestamp tracking for reconciliation).\n\t */\n\tprotected async onJobStart(_runId: string, _blueprintId: string, _nodeId: string): Promise<void> {\n\t\t// default implementation does nothing\n\t}\n\n\t/**\n\t * The main handler for processing a single job from the queue.\n\t */\n\tprotected async handleJob(job: JobPayload): Promise<void> {\n\t\tconst { runId, blueprintId, nodeId } = job\n\n\t\tawait this.onJobStart(runId, blueprintId, nodeId)\n\n\t\tconst blueprint = this.runtime.options.blueprints?.[blueprintId]\n\t\tif (!blueprint) {\n\t\t\tconst reason = `Blueprint with ID '${blueprintId}' not found in the worker's runtime registry.`\n\t\t\tconsole.error(`[Adapter] FATAL: ${reason}`)\n\t\t\tawait this.publishFinalResult(runId, { status: 'failed', reason })\n\t\t\treturn\n\t\t}\n\n\t\tconst context = this.createContext(runId)\n\n\t\t// persist the blueprintId for the reconcile method to find later\n\t\tconst hasBlueprintId = await context.has('blueprintId' as any)\n\t\tif (!hasBlueprintId) {\n\t\t\tawait context.set('blueprintId' as any, blueprintId)\n\t\t}\n\t\tconst workerState = {\n\t\t\tgetContext: () => context,\n\t\t\tmarkFallbackExecuted: () => {},\n\t\t\taddError: (nodeId: string, error: Error) => {\n\t\t\t\tconsole.error(`[Adapter] Error in node ${nodeId}:`, error)\n\t\t\t},\n\t\t} as any\n\n\t\ttry {\n\t\t\tconst result: NodeResult<any, any> = await this.runtime.executeNode(blueprint, nodeId, workerState)\n\t\t\tawait context.set(nodeId as any, result.output)\n\n\t\t\tconst nodeDef = blueprint.nodes.find((n) => n.id === nodeId)\n\t\t\t// workflow is considered complete when the first 'output' node finishes.\n\t\t\tif (nodeDef?.uses === 'output') {\n\t\t\t\tconsole.log(`[Adapter] ✅ Output node '${nodeId}' finished. Declaring workflow complete for Run ID: ${runId}`)\n\t\t\t\tconst finalContext = await context.toJSON()\n\t\t\t\tconst finalResult: WorkflowResult = {\n\t\t\t\t\tcontext: finalContext,\n\t\t\t\t\tserializedContext: this.serializer.serialize(finalContext),\n\t\t\t\t\tstatus: 'completed',\n\t\t\t\t}\n\t\t\t\tawait this.publishFinalResult(runId, {\n\t\t\t\t\tstatus: 'completed',\n\t\t\t\t\tpayload: finalResult,\n\t\t\t\t})\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tconst nextNodes = await this.runtime.determineNextNodes(blueprint, nodeId, result, context)\n\n\t\t\t// stop if a branch terminates but it wasn't an 'output' node\n\t\t\tif (nextNodes.length === 0) {\n\t\t\t\tconsole.log(\n\t\t\t\t\t`[Adapter] Terminal node '${nodeId}' reached for Run ID '${runId}', but it was not an 'output' node. This branch will now terminate.`,\n\t\t\t\t)\n\t\t\t\treturn\n\t\t\t}\n\n\t\t\tfor (const { node: nextNodeDef, edge } of nextNodes) {\n\t\t\t\tawait this.runtime.applyEdgeTransform(edge, result, nextNodeDef, context)\n\t\t\t\tconst isReady = await this.isReadyForFanIn(runId, blueprint, nextNodeDef.id)\n\t\t\t\tif (isReady) {\n\t\t\t\t\tconsole.log(`[Adapter] Node '${nextNodeDef.id}' is ready. Enqueuing job.`)\n\t\t\t\t\tawait this.enqueueJob({ runId, blueprintId, nodeId: nextNodeDef.id })\n\t\t\t\t} else {\n\t\t\t\t\tconsole.log(`[Adapter] Node '${nextNodeDef.id}' is waiting for other predecessors to complete.`)\n\t\t\t\t}\n\t\t\t}\n\t\t} catch (error: any) {\n\t\t\tconst reason = error.message || 'Unknown execution error'\n\t\t\tconsole.error(`[Adapter] FATAL: Job for node '${nodeId}' failed for Run ID '${runId}': ${reason}`)\n\t\t\tawait this.publishFinalResult(runId, { status: 'failed', reason })\n\t\t}\n\t}\n\n\t/**\n\t * Encapsulates the fan-in join logic using the coordination store.\n\t */\n\tprotected async isReadyForFanIn(runId: string, blueprint: WorkflowBlueprint, targetNodeId: string): Promise<boolean> {\n\t\tconst targetNode = blueprint.nodes.find((n) => n.id === targetNodeId)\n\t\tif (!targetNode) {\n\t\t\tthrow new Error(`Node '${targetNodeId}' not found in blueprint`)\n\t\t}\n\t\tconst joinStrategy = targetNode.config?.joinStrategy || 'all'\n\t\tconst predecessors = blueprint.edges.filter((e) => e.target === targetNodeId)\n\n\t\tif (predecessors.length <= 1) {\n\t\t\treturn true\n\t\t}\n\n\t\tif (joinStrategy === 'any') {\n\t\t\tconst lockKey = `flowcraft:joinlock:${runId}:${targetNodeId}`\n\t\t\treturn await this.store.setIfNotExist(lockKey, 'locked', 3600)\n\t\t} else {\n\t\t\tconst fanInKey = `flowcraft:fanin:${runId}:${targetNodeId}`\n\t\t\tconst readyCount = await this.store.increment(fanInKey, 3600)\n\t\t\tif (readyCount >= predecessors.length) {\n\t\t\t\tawait this.store.delete(fanInKey)\n\t\t\t\treturn true\n\t\t\t}\n\t\t\treturn false\n\t\t}\n\t}\n\n\t/**\n\t * Reconciles the state of a workflow run. It inspects the persisted\n\t * context to find completed nodes, determines the next set of executable\n\t * nodes (the frontier), and enqueues jobs for them if they aren't\n\t * already running. This is the core of the resume functionality.\n\t *\n\t * @param runId The unique ID of the workflow execution to reconcile.\n\t * @returns The set of node IDs that were enqueued for execution.\n\t */\n\tpublic async reconcile(runId: string): Promise<Set<string>> {\n\t\tconst context = this.createContext(runId)\n\t\tconst blueprintId = (await context.get('blueprintId' as any)) as string | undefined\n\n\t\tif (!blueprintId) {\n\t\t\tthrow new Error(`Cannot reconcile runId '${runId}': blueprintId not found in context.`)\n\t\t}\n\t\tconst blueprint = this.runtime.options.blueprints?.[blueprintId]\n\t\tif (!blueprint) {\n\t\t\tthrow new Error(`Cannot reconcile runId '${runId}': Blueprint with ID '${blueprintId}' not found.`)\n\t\t}\n\n\t\tconst state = await context.toJSON()\n\t\t// filter out internal keys\n\t\tconst completedNodes = new Set(Object.keys(state).filter((k) => blueprint.nodes.some((n) => n.id === k)))\n\n\t\tconst frontier = this.calculateResumedFrontier(blueprint, completedNodes)\n\n\t\tconst enqueuedNodes = new Set<string>()\n\t\tfor (const nodeId of frontier) {\n\t\t\tconst nodeDef = blueprint.nodes.find((n) => n.id === nodeId)\n\t\t\tconst joinStrategy = nodeDef?.config?.joinStrategy || 'all'\n\n\t\t\tlet shouldEnqueue = false\n\n\t\t\tif (joinStrategy === 'any') {\n\t\t\t\t// acquire the permanent join lock\n\t\t\t\tconst lockKey = `flowcraft:joinlock:${runId}:${nodeId}`\n\t\t\t\tif (await this.store.setIfNotExist(lockKey, 'locked-by-reconcile', 3600)) {\n\t\t\t\t\tshouldEnqueue = true\n\t\t\t\t} else {\n\t\t\t\t\tconsole.log(`[Adapter] Reconciling: Node '${nodeId}' is an 'any' join and is already locked.`, { runId })\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\t// 'all' joins and single-predecessor nodes use a temporary lock\n\t\t\t\tconst lockKey = `flowcraft:nodelock:${runId}:${nodeId}`\n\t\t\t\tif (await this.store.setIfNotExist(lockKey, 'locked', 120)) {\n\t\t\t\t\tshouldEnqueue = true\n\t\t\t\t} else {\n\t\t\t\t\tconsole.log(`[Adapter] Reconciling: Node '${nodeId}' is already locked.`, { runId })\n\t\t\t\t}\n\t\t\t}\n\n\t\t\tif (shouldEnqueue) {\n\t\t\t\tconsole.log(`[Adapter] Reconciling: Enqueuing ready job for node '${nodeId}'`, { runId })\n\t\t\t\tawait this.enqueueJob({ runId, blueprintId: blueprint.id, nodeId })\n\t\t\t\tenqueuedNodes.add(nodeId)\n\t\t\t}\n\t\t}\n\n\t\treturn enqueuedNodes\n\t}\n\n\tprivate calculateResumedFrontier(blueprint: WorkflowBlueprint, completedNodes: Set<string>): Set<string> {\n\t\tconst newFrontier = new Set<string>()\n\t\tconst allPredecessors = new Map<string, Set<string>>()\n\t\t// (logic extracted from the GraphTraverser)\n\t\tfor (const node of blueprint.nodes) {\n\t\t\tallPredecessors.set(node.id, new Set())\n\t\t}\n\t\tfor (const edge of blueprint.edges) {\n\t\t\tallPredecessors.get(edge.target)?.add(edge.source)\n\t\t}\n\n\t\tfor (const node of blueprint.nodes) {\n\t\t\tif (completedNodes.has(node.id)) {\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\tconst predecessors = allPredecessors.get(node.id) ?? new Set()\n\t\t\tif (predecessors.size === 0 && !completedNodes.has(node.id)) {\n\t\t\t\tnewFrontier.add(node.id)\n\t\t\t\tcontinue\n\t\t\t}\n\n\t\t\tconst joinStrategy = node.config?.joinStrategy || 'all'\n\t\t\tconst completedPredecessors = [...predecessors].filter((p) => completedNodes.has(p))\n\n\t\t\tconst isReady =\n\t\t\t\tjoinStrategy === 'any' ? completedPredecessors.length > 0 : completedPredecessors.length === predecessors.size\n\n\t\t\tif (isReady) {\n\t\t\t\tnewFrontier.add(node.id)\n\t\t\t}\n\t\t}\n\t\treturn newFrontier\n\t}\n}\n"]}

package/dist/chunk-5QMPFUKA.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-5QMPFUKA.js.map
+//# sourceMappingURL=chunk-5QMPFUKA.js.map

package/dist/chunk-5QMPFUKA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/node.ts"],"names":[],"mappings":";AAGO,SAAS,YAAY,IAAA,EAA8B;AACzD,EAAA,OAAO,OAAO,IAAA,KAAS,UAAA,IAAc,CAAC,CAAC,KAAK,SAAA,EAAW,IAAA;AACxD;AAOO,IAAe,WAAf,MAML;AAAA;AAAA;AAAA;AAAA,EAID,YAAsB,MAAA,EAA8B;AAA9B,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAAA,EAA+B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOrD,MAAM,KAAK,OAAA,EAAqE;AAC/E,IAAA,OAAO,OAAA,CAAQ,KAAA;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAiBA,MAAM,IAAA,CACL,UAAA,EACA,QAAA,EACwC;AACxC,IAAA,OAAO,UAAA;AAAA,EACR;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,QAAA,CACL,KAAA,EACA,QAAA,EACuD;AAEvD,IAAA,MAAM,KAAA;AAAA,EACP;AACD","file":"chunk-5QMPFUKA.js","sourcesContent":["import 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\tTInput = any,\n\tTOutput = any,\n\tTAction extends string = string,\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, TInput>): 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(\n\t\tprepResult: any,\n\t\tcontext: NodeContext<TContext, TDependencies, TInput>,\n\t): Promise<Omit<NodeResult<TOutput, TAction>, '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(\n\t\texecResult: Omit<NodeResult<TOutput, TAction>, 'error'>,\n\t\t_context: NodeContext<TContext, TDependencies, TInput>,\n\t): Promise<NodeResult<TOutput, TAction>> {\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(\n\t\terror: Error,\n\t\t_context: NodeContext<TContext, TDependencies, TInput>,\n\t): Promise<Omit<NodeResult<TOutput, TAction>, 'error'>> {\n\t\t// By default, re-throw the error, failing the node.\n\t\tthrow error\n\t}\n}\n"]}