flowcraft 1.0.0-beta.1

package/docs/guide/builders.md

@@ -0,0 +1,157 @@
+# Builders
+
+Builders are helper classes provided by Flowcraft to abstract away the manual construction of common and complex workflow patterns. They handle the underlying `Node` and `Flow` wiring for you, so you can focus on your application's logic.
+
+This guide provides an overview of the available builders and helps you choose the right one for your use case.
+
+## Choosing the Right Builder
+
+- **For simple, linear sequences...**
+    ...where one step follows the next without branching, use **[`SequenceFlow`](#sequenceflow)**. It's the simplest way to create a basic pipeline. The functional `pipeline` helper offers an even more concise syntax for the same pattern.
+
+- **For parallel execution of different tasks...**
+    ...where your workflow has distinct branches that can run concurrently (a "fan-out, fan-in" pattern), use **[`ParallelFlow`](#parallelflow)**. This is ideal for structural parallelism, like fetching data from two different APIs at the same time.
+
+- **For processing a collection of data items...**
+    ...where you need to run the *same* operation on many different pieces of data, use a batch processor. Choose **[`ParallelBatchFlow`](#batch-processing-batchflow-and-parallelbatchflow)** for I/O-bound tasks (like making many API calls) or **[`BatchFlow`](#batch-processing-batchflow-and-parallelbatchflow)** for tasks that must run sequentially.
+
+- **For dynamic, data-driven graphs...**
+    ...where your workflow logic is defined in a declarative format like JSON, use the **[`GraphBuilder`](#graphbuilder)**. This is the most powerful and flexible option, perfect for building dynamic AI agent runtimes or systems where workflows are configuration, not code.
+
+---
+
+## `SequenceFlow`
+
+`SequenceFlow` creates a linear `Flow` from a list of nodes, automatically chaining them together in the order they are provided.
+
+### Example: Class-based Builder
+
+Instead of wiring nodes manually with `.next()`:
+
+```typescript
+const nodeA = new NodeA()
+const nodeB = new NodeB()
+const nodeC = new NodeC()
+
+nodeA.next(nodeB)
+nodeB.next(nodeC)
+
+const manualFlow = new Flow(nodeA)
+```
+
+You can use `SequenceFlow` for a more concise definition:
+
+```typescript
+import { SequenceFlow } from 'flowcraft'
+
+const sequence = new SequenceFlow(
+	new NodeA(),
+	new NodeB(),
+	new NodeC()
+)
+
+await sequence.run(context)
+```
+
+For an even more functional style, the `pipeline` helper provides the same functionality with a more direct syntax. See the [Functional API Reference](./functional-api.md#pipeline) for more details.
+
+```typescript
+import { pipeline } from 'flowcraft'
+
+const dataPipeline = pipeline(
+	new NodeA(),
+	new NodeB(),
+	new NodeC()
+)
+```
+
+---
+
+## `ParallelFlow`
+
+`ParallelFlow` executes a fixed set of different nodes concurrently. This is the "fan-out, fan-in" pattern, used for **structural parallelism**. After all parallel branches complete, the flow can proceed to a single, subsequent node.
+
+### When to Use
+
+Use `ParallelFlow` when your workflow logic itself has distinct branches that can run simultaneously. For example, building a user dashboard by fetching profile data and activity data from two different services at the same time.
+
+### Example
+
+```typescript
+import { ParallelFlow } from 'flowcraft'
+
+// Fetch data from two different sources in parallel.
+const parallelStep = new ParallelFlow([
+	new FetchUserProfileNode(), // Task A
+	new FetchUserActivityNode(), // Task B
+])
+
+// This node will only run after both fetch nodes have completed.
+const aggregateNode = new AggregateDashboardDataNode()
+parallelStep.next(aggregateNode)
+
+const dashboardFlow = new Flow(parallelStep)
+```
+
+---
+
+## `BatchFlow` (Sequential)
+
+`BatchFlow` processes items one by one, in order - executing the **same node** many times over a dynamic collection of data items. The next item is not processed until the previous one is completely finished.
+
+**Use Cases**: Processing items in a strict order, or interacting with a rate-limited API where you must avoid sending multiple requests at once.
+
+## `ParallelBatchFlow` (Concurrent)
+
+`ParallelBatchFlow` processes all items concurrently - executing the **same node** many times over a dynamic collection of data items. This provides a massive performance boost for I/O-bound tasks.
+
+**Use Cases**: Translating a document into 10 languages, fetching thumbnails for a list of 100 video URLs, or processing multiple user-uploaded files.
+
+### Example: The Document Translator
+
+This example uses `ParallelBatchFlow` to translate a document into several languages at once.
+
+```typescript
+import { AbstractNode, Node, ParallelBatchFlow, TypedContext } from 'flowcraft'
+
+// The single unit of work: translates text to one language.
+class TranslateNode extends Node {
+	async exec({ params }) { /* ... API call to translate params.text to params.language ... */ }
+}
+
+// The builder orchestrates the batch process.
+class TranslateFlow extends ParallelBatchFlow {
+	// 1. Implement the abstract property to define which node to run for each item.
+	protected nodeToRun: AbstractNode = new TranslateNode()
+
+	// 2. The `prep` method provides the list of items to process.
+	async prep({ ctx }) {
+		const languages = ctx.get(LANGUAGES) || []
+		const text = ctx.get(DOCUMENT_TEXT)
+
+		// Return an array of parameter objects.
+		// Each object will be merged into the TranslateNode's params for one parallel run.
+		return languages.map(language => ({ language, text }))
+	}
+}
+```
+
+---
+
+## GraphBuilder
+
+`GraphBuilder` is the most powerful and advanced builder. It allows you to construct a fully executable `Flow` from a declarative data structure (like a JSON object). This is the key to building dynamic, data-driven systems where the workflow logic is defined as configuration, not hard-coded.
+
+### When to Use
+
+- When you want to define workflow logic in a database or a set of JSON/YAML files.
+- When you need to support complex, non-linear workflows with multiple start points, fan-outs, and fan-ins.
+- For building modular AI Agent runtimes where different "tools" or "skills" are defined as graphs.
+
+### How It Works
+
+1. **Define a Graph**: You create a `WorkflowGraph` object containing a list of `nodes` and `edges`.
+2. **Create a Node Registry**: You map the string `type` from your graph nodes to the actual `Node` classes in your code.
+3. **Build the Flow**: You instantiate `GraphBuilder` with the registry and call `.build(graph)`.
+
+The `GraphBuilder` intelligently analyzes the graph's structure, automatically handling parallel start nodes, mid-flow fan-outs, and fan-ins. For a complete, in-depth example, see the **[Dynamic AI Agent example (`sandbox/4.dag/`)](https://github.com/gorango/flowcraft/tree/master/sandbox/4.dag/)**.

package/docs/guide/functional-api.md

@@ -0,0 +1,133 @@
+# Functional API
+
+While Flowcraft's core is built on composable classes like `Node` and `Flow`, it also provides a suite of functional helpers for developers who prefer a more functional programming style. These helpers allow you to define nodes and simple pipelines without explicitly creating new classes.
+
+All helpers are imported from the main `flowcraft` package.
+
+```typescript
+import {
+	composeContext,
+	contextNode,
+	lens,
+	mapNode,
+	pipeline,
+	transformNode
+} from 'flowcraft'
+```
+
+## Creating Nodes from Functions
+
+These helpers are the primary way to create `Node` instances from simple functions.
+
+### `mapNode`
+
+`mapNode` creates a `Node` from a pure function that transforms an input to an output. The node's input `params` object is passed as the single argument to your function.
+
+#### When to Use
+
+Use `mapNode` for simple, stateless transformations where the logic doesn't need access to the shared `Context`.
+
+#### Example
+
+```typescript
+import { Flow, mapNode } from 'flowcraft'
+
+// A simple function that adds two numbers from the params
+const add = (params: { a: number, b: number }) => params.a + params.b
+
+// Create a reusable Node from the function
+const addNode = mapNode(add)
+
+// Now use it in a flow
+const flow = new Flow(addNode.withParams({ a: 5, b: 10 }))
+```
+
+### `contextNode`
+
+`contextNode` is similar to `mapNode`, but the function you provide also receives the `Context` as its first argument.
+
+#### When to Use
+
+Use `contextNode` when your node's logic depends on state stored in the `Context`.
+
+#### Example
+
+```typescript
+import { contextKey, contextNode, Flow, TypedContext } from 'flowcraft'
+
+const LANGUAGE = contextKey<'en' | 'es'>('language')
+
+// A function that uses the context to determine the greeting
+function greeter(ctx, params: { name: string }) {
+	const lang = ctx.get(LANGUAGE) || 'en'
+	return lang === 'es' ? `Hola, ${params.name}` : `Hello, ${params.name}`
+}
+
+// Create a Node from the context-aware function
+const greetingNode = contextNode(greeter)
+
+const context = new TypedContext([[LANGUAGE, 'es']])
+const flow = new Flow(greetingNode.withParams({ name: 'Mundo' }))
+```
+
+## Creating Flows
+
+### `pipeline`
+
+`pipeline` is a functional alias for the `SequenceFlow` builder. It takes a sequence of `Node` instances and returns a `Flow` where they are all chained together in order.
+
+#### When to Use
+
+Use `pipeline` as a more readable, functional-style alternative to `new SequenceFlow(...)` for creating simple linear workflows.
+
+#### Example
+
+```typescript
+import { contextNode, mapNode, pipeline } from 'flowcraft'
+
+const fetchNode = mapNode(() => ({ user: 'Alice' }))
+const processNode = mapNode(data => `Processed ${data.user}`)
+const saveNode = contextNode((ctx, result) => { /* save result */ })
+
+const dataPipeline = pipeline(
+	fetchNode,
+	processNode,
+	saveNode
+)
+
+await dataPipeline.run(context)
+```
+
+## Declarative Context Management
+
+These helpers provide a functional way to manage state in the `Context`.
+
+### `lens` and `transformNode`
+
+A `lens` provides a way to "focus" on a single key in the `Context`, allowing you to create reusable functions that `get`, `set`, or `update` its value.
+
+`transformNode` is a special `Node` that takes these functions and applies them to the context. It's the ideal way to set up initial state for a workflow.
+
+#### When to Use
+
+Use this combination for declaratively setting up or mutating state in the `Context` as a distinct step in your workflow.
+
+#### Example
+
+```typescript
+import { contextKey, lens, transformNode } from 'flowcraft'
+
+const USER_ID = contextKey<string>('user_id')
+const ATTEMPTS = contextKey<number>('attempts')
+
+// Create lenses to focus on our specific context keys
+const userIdLens = lens(USER_ID)
+const attemptsLens = lens(ATTEMPTS)
+
+// A node that sets an initial user and resets the attempt counter.
+// The `set` and `update` methods from the lens return `ContextTransform` functions.
+const setupContextNode = transformNode(
+	userIdLens.set('user-123'),
+	attemptsLens.update(current => (current || 0) + 1) // Safely increments
+)
+```

package/docs/guide/index.md

@@ -0,0 +1,178 @@
+# Introduction to Flowcraft
+
+Welcome to Flowcraft! This guide will take you from the fundamental concepts to building your first workflow, giving you a comprehensive understanding of what Flowcraft is, why it's useful, and how it works.
+
+## What is Flowcraft?
+
+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 best way to see the power of this structure is to build something.
+
+## Quick Start: Your First Workflow
+
+This tutorial will walk you through creating a simple, three-step pipeline that takes a name as input, constructs a greeting, and assembles a final message.
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) installed on your system.
+- A package manager like `npm` or `pnpm`.
+- A way to run TypeScript files like `tsx` or `bun`.
+
+### Step 1: Project Setup
+
+In your project directory, install Flowcraft and the necessary TypeScript tools. We'll use `tsx` to run our TypeScript file directly.
+
+```bash
+npm install flowcraft
+```
+
+### Step 2: Define the Workflow Logic
+
+Create a new file named `main.ts`. This is where we'll define and run our workflow.
+
+```bash
+touch main.ts
+```
+
+Inside `main.ts`, we'll start by importing the core components we need from Flowcraft.
+
+```typescript
+// main.ts
+import { contextKey, Flow, Node, TypedContext } from 'flowcraft'
+
+// Define type-safe keys for our shared data
+const NAME = contextKey<string>('name')
+const GREETING = contextKey<string>('greeting')
+const FINAL_MESSAGE = contextKey<string>('final_message')
+
+// 1. nameNode: Takes a name from input `params` and stores it in the Context.
+const nameNode = new Node()
+	.exec(async ({ params }) => params.name)
+	.toContext(NAME)
+
+// 2. greetingNode: Reads the name from the Context, creates a greeting, and stores it back.
+const greetingNode = new Node()
+	.exec(async ({ ctx }) => `Hello, ${ctx.get(NAME)}!`)
+	.toContext(GREETING)
+
+// 3. finalNode: Reads the greeting from the Context and assembles the final message.
+const finalNode = new Node()
+	.exec(async ({ ctx }) => `${ctx.get(GREETING)} Welcome to Flowcraft!`)
+	.toContext(FINAL_MESSAGE)
+```
+
+### Step 3: Orchestrate and Run the `Flow`
+
+Now that we have our nodes, we need to wire them together into a sequence and run them.
+
+```typescript
+// main.ts (continued)
+
+// Chain the nodes to define the execution order.
+nameNode.next(greetingNode).next(finalNode)
+
+// Create a Flow, telling it which node to start with.
+const flow = new Flow(nameNode)
+
+// Execute the flow.
+async function main() {
+	const context = new TypedContext()
+
+	console.log('Starting workflow...')
+	await flow.withParams({ name: 'Developer' }).run(context)
+
+	const result = context.get(FINAL_MESSAGE)
+	console.log('Workflow complete!')
+	console.log(`Final Result: "${result}"`)
+}
+
+main()
+```
+
+### Step 4: Run It
+
+Your `main.ts` file should now contain the complete workflow. Run it from your terminal:
+
+```bash
+npx tsx main.ts
+```
+
+You should see the following output:
+
+```
+Starting workflow...
+Workflow complete!
+Final Result: "Hello, Developer! Welcome to Flowcraft!"
+```
+
+Congratulations! You've just built and run a Flowcraft workflow. Now, let's break down the concepts you just used.
+
+---
+
+## Core Concepts
+
+Flowcraft is built around a few simple, powerful concepts.
+
+### 1. Node
+
+The `Node` is the most fundamental building block, representing a single unit of work. In our Quick Start, `nameNode`, `greetingNode`, and `finalNode` were all created from the base `Node` class.
+
+Every `Node` has a well-defined, three-phase lifecycle:
+
+1. **`prep(args)`**: **Prepare Data**. Gathers data needed for execution, usually by reading from the `Context`.
+2. **`exec(args)`**: **Execute Core Logic**. Performs the main work. This phase is designed to be isolated from the `Context` to make it pure and testable.
+3. **`post(args)`**: **Process Results**. Updates the `Context` with the results and returns an **action** to determine the next step.
+
+For many common tasks, like in our example, you can use the fluent API (`.map`, `.toContext`, `.filter`) to create processing pipelines without writing a custom class.
+
+### 2. Flow
+
+A `Flow` is a special `Node` that acts as a **container for a graph of other nodes**. It holds the starting point of a workflow and orchestrates the execution.
+
+When you call `flow.run()`, an `Executor` starts with the flow's `startNode`, executes it, looks at the **action** it returns, and finds the next node connected via `.next()`. This repeats until the flow ends.
+
+### 3. Context
+
+The `Context` is the shared memory of a running workflow. It is passed to every node, allowing them to share state. In our example, we used it to pass the `name` from `nameNode` to `greetingNode`, and the `greeting` on to `finalNode`.
+
+- **Type-Safe by Default**: We used `contextKey<string>('name')` to create a type-safe key. This prevents you from accidentally writing a number where a string is expected.
+- **Mutable**: Nodes read from the context (usually in `prep` or `exec`) and write back to it (usually in `post` or via `.toContext`).
+
+### 4. Actions & Branching
+
+An **action** is a string returned by a node's `post()` method that the `Executor` uses to decide which path to take next.
+
+- **`DEFAULT_ACTION`**: Used for simple linear sequences. `nodeA.next(nodeB)` is shorthand for branching on the default action.
+- **Custom Actions**: Returning a custom string like `'success'` or `'error'` from `post()` enables conditional branching, allowing you to direct the workflow down different paths based on a node's outcome.
+
+---
+
+## When to Use Flowcraft
+
+Flowcraft is an excellent choice for:
+
+- **AI Agent Orchestration**: Modeling the "reasoning loop" of an AI agent is a natural fit for a graph. Conditional branching, tool use, and parallel thought processes are easily implemented. The **[Advanced RAG Agent](https://github.com/gorango/flowcraft/tree/master/sandbox/6.rag/)** is a complete, end-to-end example of this pattern.
+- **Data Processing & ETL Pipelines**: Fetching data, running transformations, and saving it to a destination. The [Parallel Batch Translation](https://github.com/gorango/flowcraft/tree/master/sandbox/3.parallel/) is a great example of this task.
+- **Complex Business Logic**: Any multi-step process with conditional paths, retries, and fallbacks (e.g., user onboarding, e-commerce order fulfillment). Look at some of the examples in the [DAG](https://github.com/gorango/flowcraft/tree/master/sandbox/4.dag/) sandbox.
+- **Multi-Step Background Jobs**: Running tasks in the background of a web application, like generating a report or processing a file. The [Distributed](https://github.com/gorango/flowcraft/tree/master/sandbox/5.distributed/) examples showcase running all of the same DAG workflows but in the background.
+
+## How Flowcraft Compares
+
+- **vs. Plain `async/await`**: Use `async/await` for simple, linear sequences. Use Flowcraft when your process starts to look like a state machine or a graph, with retries, fallbacks, or complex conditional logic.
+- **vs. LangChain / LlamaIndex**: Use those frameworks for rapid prototyping with their vast ecosystem of pre-built integrations. Use Flowcraft when you want an unopinionated **runtime** for your custom AI logic, giving you full control over your prompts and business logic.
+- **vs. Temporal / Airflow**: Use these heavy-duty platforms when you need **durability** (guaranteed execution that survives server crashes) out of the box. Use Flowcraft when you want to start with a lightweight, in-process library and have the *option* to build a distributed system later.
+
+## Next Steps
+
+Now that you have a solid foundation, you can explore more advanced topics:
+
+- **[Builders](./builders.md)**: Learn about creating sequential, parallel, and declarative graph-based flows.
+- **[Functional API](./functional-api.md)**: Discover a more functional style of defining nodes and pipelines.
+- **[Recipes](./recipes/)**: Find practical, copy-paste-friendly solutions for common workflow patterns.
+- **[Advanced Guides](./advanced-guides/composition.md)**: Dive into composition, middleware, custom executors, and more.

package/docs/guide/recipes/creating-a-loop.md

@@ -0,0 +1,113 @@
+# Recipes: Creating a Loop
+
+A common requirement in workflows is to perform an action repeatedly until a certain condition is met. While Flowcraft does not have a dedicated "loop" node, you can easily create loops by wiring a graph of nodes into a cycle.
+
+The key is to have a "decider" node that, based on some condition, either continues the loop or exits it.
+
+## The Pattern
+
+1. **Action Node**: A node that performs the main work of the loop's body.
+2. **Decider Node**: A node that checks a condition after the action is performed.
+3. **Cyclical Connection**: The decider node connects back to the action node to continue the loop.
+4. **Exit Connection**: The decider node connects to a different node to break the loop.
+
+```mermaid
+graph TD
+    A[Start] --> B(Loop Action)
+    B --> C{Check Condition}
+    C -- "Continue Loop" --> B
+    C -- "Exit Loop" --> D[End]
+```
+
+## Example: A Counter Loop
+
+Let's build a simple workflow that increments a counter from 0 to 3.
+
+### 1. Define Context and Nodes
+
+We need a key for our counter and three nodes:
+
+- `InitializeCounterNode`: Sets the counter to 0.
+- `IncrementCounterNode`: Adds 1 to the counter. This is our "Loop Action".
+- `CheckCounterNode`: Checks if the counter has reached the limit. This is our "Decider".
+- `EndNode`: A final node to execute after the loop is finished.
+
+```typescript
+import { contextKey, Flow, Node, TypedContext } from 'flowcraft'
+
+// The value we will be incrementing
+const COUNTER = contextKey<number>('counter')
+const MAX_LOOPS = 3
+
+const initializeNode = new Node().exec(async ({ ctx }) => ctx.set(COUNTER, 0))
+const endNode = new Node().exec(() => console.log('Loop finished.'))
+
+// The main work of the loop
+class IncrementCounterNode extends Node {
+	async exec({ ctx }) {
+		const current = ctx.get(COUNTER)!
+		console.log(`Loop body: Incrementing counter from ${current} to ${current + 1}`)
+		ctx.set(COUNTER, current + 1)
+	}
+}
+
+// The decider node
+class CheckCounterNode extends Node<void, void, 'continue' | 'exit'> {
+	async post({ ctx }) {
+		const current = ctx.get(COUNTER)!
+		if (current < MAX_LOOPS) {
+			console.log(`Condition check: ${current} < ${MAX_LOOPS}. Continuing loop.`)
+			return 'continue' // The action to continue the loop
+		}
+		else {
+			console.log(`Condition check: ${current} >= ${MAX_LOOPS}. Exiting loop.`)
+			return 'exit' // The action to break the loop
+		}
+	}
+}
+```
+
+### 2. Wire the Loop
+
+Now, we connect the nodes to form the cycle.
+
+```typescript
+// Create instances
+const init = initializeNode
+const increment = new IncrementCounterNode()
+const check = new CheckCounterNode()
+const end = endNode
+
+// Define the flow path
+init.next(increment)
+
+// The 'increment' node always goes to the 'check' node
+increment.next(check)
+
+// The 'check' node is the key to the loop
+check.next(increment, 'continue') // If action is 'continue', go back to increment
+check.next(end, 'exit') // If action is 'exit', go to the end
+
+// Create the flow starting with initialization
+const loopFlow = new Flow(init)
+```
+
+### 3. Run the Flow
+
+```typescript
+await loopFlow.run(new TypedContext())
+```
+
+The output will be:
+
+```
+Loop body: Incrementing counter from 0 to 1
+Condition check: 1 < 3. Continuing loop.
+Loop body: Incrementing counter from 1 to 2
+Condition check: 2 < 3. Continuing loop.
+Loop body: Incrementing counter from 2 to 3
+Condition check: 3 >= 3. Exiting loop.
+Loop finished.
+```
+
+This simple, powerful pattern is the foundation for building any kind of loop, from simple counters to complex agentic loops that decide whether to search for more information or answer a question based on the current context. The **[Research Agent (`sandbox/2.research/`)](https://github.com/gorango/flowcraft/tree/master/sandbox/2.research/)** example uses this exact pattern for its core logic.