flowcraft 1.0.0-beta.2 → 1.0.0-beta.20

package/README.md

@@ -10,7 +10,7 @@ Build complex, multi-step processes, from simple sequences to dynamic, graph-dri
 
 - **Extensible Execution Engine**: A pluggable `Executor` pattern enables in-memory or distributed flows.
 
-- **Type-Safe**: Written in TypeScript to provide strong typing for your workflow definitions and context.
+- **Type-Safe**: Written in TypeScript to provide strong typing for your workflow definitions, context, and node parameters.
 
 - **Async by Default**: Built on an asynchronous foundation to handle I/O-bound and CPU-bound tasks.
 
@@ -39,12 +39,11 @@ npm install flowcraft
 Create and run a simple workflow in a few lines of code.
 
 ```typescript
-import { Flow, Node } from 'flowcraft'
+import { Flow, mapNode } from 'flowcraft' // Use mapNode for simple functions
 
-const greetNode = new Node()
-// The exec method contains the core logic of the node.
-	.exec(() => 'Hello, World!')
-// Functional helpers make common tasks easy.
+// Create a node from a simple function that takes params and returns a value.
+const greetNode = mapNode(() => 'Hello, World!')
+	// Functional helpers make common tasks easy.
 	.tap(console.log)
 
 const flow = new Flow(greetNode)
@@ -68,7 +67,7 @@ graph LR
 ```
 
 - **Demonstrates**: `Node` chaining, passing data via `Context`, and a simple `BatchFlow`.
-- **[Explore the Basic example »](./sandbox/1.basic/)**
+- **[Explore the Basic example »](https://github.com/gorango/flowcraft/tree/main/sandbox/1.basic/)**
 
 ### 2. Conditional Branching: Research Agent
 
@@ -82,7 +81,7 @@ graph TD
 ```
 
 - **Demonstrates**: Conditional branching with custom actions, creating loops, and building simple state machines.
-- **[Explore the Research Agent example »](./sandbox/2.research/)**
+- **[Explore the Research Agent example »](https://github.com/gorango/flowcraft/tree/main/sandbox/2.research/)**
 
 ### 3. Parallel Batch Processing: Document Translator
 
@@ -102,7 +101,7 @@ graph TD
 ```
 
 - **Demonstrates**: `ParallelBatchFlow` for high-throughput concurrent processing of I/O-bound tasks.
-- **[Explore the Parallel Translation example »](./sandbox/3.parallel/)**
+- **[Explore the Parallel Translation example »](https://github.com/gorango/flowcraft/tree/main/sandbox/3.parallel/)**
 
 ### 4. Dynamic Graph Engine: AI Agent Runtime
 
@@ -134,7 +133,7 @@ graph TD
   - Parallel fan-in and fan-out (mid-flow branching).
   - Reusable, data-driven nodes (e.g., an LLM-powered router).
   - Complex sub-workflow composition.
-- **[Explore the Dynamic AI Agent example »](./sandbox/4.dag/)**
+- **[Explore the Dynamic AI Agent example »](https://github.com/gorango/flowcraft/tree/main/sandbox/4.dag/)**
 
 ### 5. Distributed Execution: AI Agent with BullMQ
 
@@ -145,7 +144,7 @@ This example takes the same type-safe graph definition from the previous example
   - Client-worker architecture with state serialization.
   - Mid-flight, distributed cancellation of long-running jobs.
   - How business logic (the graph) remains unchanged when the execution environment changes.
-- **[Explore the Distributed AI Agent example »](./sandbox/5.distributed/)**
+- **[Explore the Distributed AI Agent example »](https://github.com/gorango/flowcraft/tree/main/sandbox/5.distributed/)**
 
 ### 6. Advanced RAG Agent: Complex Data & Serialization
 
@@ -164,28 +163,127 @@ graph TD
   - A mix of custom, single-responsibility nodes.
   - Handling complex data types (`Map`, `Date`, custom classes) in the `Context`.
   - The necessity of robust serialization (using `superjson`) for state management.
-- **[Explore the RAG Agent example »](./sandbox/6.rag/)**
+- **[Explore the RAG Agent example »](https://github.com/gorango/flowcraft/tree/main/sandbox/6.rag/)**
 
 ## Core Concepts
 
 ### Node
 
-The `Node` is the fundamental building block of a workflow. It represents a single, potentially asynchronous unit of work with a three-phase lifecycle:
+The `Node` is the fundamental building block of a workflow. It represents a single unit of work and is fully generic, allowing you to define types for its lifecycle results and its static parameters.
 
-1. `prep(args)`: Prepare data for execution (e.g., fetch from `Context`).
-2. `exec(args)`: Perform the core logic, isolated from the context.
-3. `post(args)`: Process results, update the `Context`, and return an "action" string to determine the next step.
+The class signature is: `Node<PrepRes, ExecRes, PostRes, TParams>`
+
+- `PrepRes`: The type of data returned by the `prep` phase.
+- `ExecRes`: The type of data returned by the `exec` phase.
+- `PostRes`: The type of the "action" returned by the `post` phase.
+- `TParams`: The type of the static parameters object for the node, accessible via `.withParams()`.
+
+**Example: A Type-Safe GreetNode**
+
+For nodes that do require static configuration, you can provide a type for the parameters to get full autocompletion and compile-time safety.
+
+```typescript
+// 1. Define the shape of the node's parameters.
+interface GreetParams {
+	greeting: string
+	loudly: boolean
+}
+
+// 2. Define the node with the TParams generic.
+class GreetNode extends Node<void, string, any, GreetParams> {
+	// 3. The 'exec' method can safely access typed parameters.
+	async exec({ params }: NodeArgs<GreetParams>): Promise<string> {
+		let message = `${params.greeting}, World!`
+		if (params.loudly) {
+			message = message.toUpperCase()
+		}
+		return message
+	}
+}
+
+// 4. Instantiate and configure with type-safe .withParams()
+const greetNode = new GreetNode()
+	.withParams({ greeting: 'Hello', loudly: true }) // Autocompletes and type-checks!
+	.tap(console.log) // "HELLO, WORLD!"
+
+// TypeScript would throw an error on this line:
+// greetNode.withParams({ greting: 'Hi', loudly: false }); // Property 'greting' does not exist.
+```
 
 A chainable API on the `Node` class has a set of functional helpers:
 
+- `.withParams(params)`: Sets type-safe static parameters for the node.
 - `.map(fn)`: Transform the output of a node.
 - `.filter(predicate)`: Conditionally proceed based on a node's output.
 - `.tap(fn)`: Perform a side-effect without changing the output.
 - `.toContext(key)`: Store a node's result in the context.
+- `.withLens(lens, value)`: Applies a context mutation before the node executes
+
+### Simplified Node Base Classes
+
+To reduce boilerplate for common patterns, Flowcraft provides specialized abstract base classes.
+
+#### `ExecNode`
+
+For nodes that only need to perform a core action and return a value. This is the most common pattern.
+
+```typescript
+// 1. Define params and the node, extending ExecNode<ExecRes, TParams>
+interface GreetParams { name: string }
+
+class GreetNode extends ExecNode<string, GreetParams> {
+	// 2. You only need to implement the 'exec' method.
+	async exec({ params }: NodeArgs<void, void, GreetParams>): Promise<string> {
+		return `Hello, ${params.name}!`
+	}
+}
+
+// Usage:
+const greetNode = new GreetNode().withParams({ name: 'World' })
+```
+
+#### `PreNode`
+
+For nodes that only modify state (e.g., in the `Context`) and don't produce an output. Their logic can be placed in the `prep` phase.
+
+```typescript
+const COUNTER = contextKey<number>('counter')
+
+class IncrementCounterNode extends PreNode {
+	// You only need to implement the 'prep' method for context mutations.
+	async prep({ ctx }: NodeArgs): Promise<void> {
+		const current = ctx.get(COUNTER) ?? 0
+		ctx.set(COUNTER, current + 1)
+	}
+}
+```
+
+#### `PostNode`
+
+For nodes that route the workflow by returning a custom action string from their `post` method.
+
+```typescript
+const USER_ROLE = contextKey<'admin' | 'guest'>('user_role')
+
+type UserAction = 'grant_access' | 'deny_access'
+
+class CheckAdminNode extends PostNode<UserAction> {
+	// You only need to implement the 'post' method for branching logic.
+	async post({ ctx }: NodeArgs): Promise<UserAction> {
+		const role = ctx.get(USER_ROLE)
+		return role === 'admin' ? 'grant_access' : 'deny_access'
+	}
+}
+
+// Usage in a flow:
+const checkAdmin = new CheckAdminNode()
+checkAdmin.next(new AdminPanelNode(), 'grant_access')
+checkAdmin.next(new GuestPageNode(), 'deny_access')
+```
 
 ### Flow
 
-A `Flow` is a special type of `Node` that orchestrates a sequence of other nodes. It contains the logic for traversing its own graph of operations, making it a powerful, self-contained unit of work.
+A `Flow` is a special type of `Node` that orchestrates a sequence of other nodes. It is also generic (`Flow<PrepRes, ExecRes, TParams>`) and can be configured with its own parameters and middleware. It contains the logic for traversing its own graph of operations, making it a powerful, self-contained unit of work.
 
 ### Executor
 
@@ -216,16 +314,16 @@ To simplify the creation of common and complex patterns, the framework provides
 > [!TIP]
 > For clear, focused examples of specific, individual features (like retries, middleware, cancellation, and composition), the unit tests are an excellent resource.
 
-- Core workflow tests: [`src/workflow.test.ts`](src/workflow.test.ts)
-- Collections tests: [`src/builder/collection.test.ts`](src/builder/collection.test.ts)
-- Graph builder tests: [`src/builder/graph.test.ts`](src/builder/graph.test.ts)
+- Core workflow tests: [`src/workflow.test.ts`](https://github.com/gorango/flowcraft/tree/main/workflow.test.ts)
+- Patterns tests: [`src/builder/patterns.test.ts`](https://github.com/gorango/flowcraft/tree/main/builder/patterns.test.ts)
+- Graph builder tests: [`src/builder/graph.test.ts`](https://github.com/gorango/flowcraft/tree/main/builder/graph.test.ts)
 
 ## API Reference
 
 ### Core Classes
 
-- `Node`: The base class for a unit of work with built-in retry logic and a fluent API (`.map`, `.filter`, etc.).
-- `Flow`: Orchestrates a sequence of nodes and supports middleware via `.use()`.
+- `Node`: The base class for a unit of work: `Node<PrepRes, ExecRes, PostRes, TParams>`. It has built-in retry logic and a fluent API (`.map`, `.filter`, etc.).
+- `Flow`: Orchestrates a sequence of nodes: `Flow<PrepRes, ExecRes, TParams>`. Supports middleware via `.use()`.
 - `InMemoryExecutor`: The default `IExecutor` implementation for running flows in-memory.
 - `TypedContext`: The standard `Map`-based implementation for the `Context` interface.
 - `ConsoleLogger`, `NullLogger`: Pre-built logger implementations.
@@ -234,16 +332,28 @@ To simplify the creation of common and complex patterns, the framework provides
 
 A collection of functions for creating nodes and pipelines in a more functional style.
 
-- `mapNode`: Creates a `Node` from a simple, pure function.
-- `contextNode`: Creates a `Node` from a function that requires access to the `Context`.
+- `mapNode`: Creates a `Node` from a simple, pure function: `mapNode<TIn extends Params, TOut>(fn)`. The function receives the node's `params` as its input.
+- `contextNode`: Creates a `Node` from a function that requires access to the `Context`: `contextNode<TIn extends Params, TOut>(fn)`. The function receives the context and the node's `params`.
+- `transformNode`: Creates a `Node` that applies one or more `ContextTransform` functions (often created with a `lens`). This is ideal for declarative state management.
 - `pipeline`: A functional alias for creating a linear sequence of nodes.
+- `mapCollection`: Creates a `Flow` that applies a function to each item in a collection in parallel, returning an array of the results.
+- `filterCollection`: Creates a `Flow` that filters a collection in parallel based on a predicate function.
+- `reduceCollection`: Creates a `Flow` that reduces a collection to a single value by applying a reducer function sequentially.
 
 ### Builder Classes
 
 - `SequenceFlow`: A `Flow` that creates a linear flow from a sequence of nodes.
 - `BatchFlow`: A `Flow` that processes a collection of items sequentially.
 - `ParallelBatchFlow`: A `Flow` that processes a collection of items in parallel.
-- `GraphBuilder`: Constructs a `Flow` from a declarative graph definition.
+- `GraphBuilder`: Constructs a `Flow` from a declarative graph definition. Its `.build()` method returns a `BuildResult` object containing:
+  - `flow`: The executable `Flow` instance.
+  - `nodeMap`: A `Map` of all instantiated nodes, keyed by their ID.
+  - `predecessorCountMap`: A `Map` of node IDs to their total number of incoming connections.
+  - `predecessorIdMap`: A `Map` of node IDs to an array of their direct predecessor IDs, useful for advanced executors.
+
+## Documentation
+
+The complete [Flowcraft documentation](https://flowcraft-docs.netlify.app) is available on the website.
 
 ---
-Licensed under the [MIT License](./LICENSE).
+Licensed under the [MIT License](https://github.com/gorango/flowcraft/tree/main/LICENSE).