flowcraft 1.0.0-beta.1

package/docs/guide/advanced-guides/error-handling.md

@@ -0,0 +1,135 @@
+# Error Handling
+
+Real-world processes can fail. Network connections drop, APIs return errors, and unexpected conditions occur. Flowcraft provides built-in mechanisms for making your workflows resilient through automatic retries and fallback logic.
+
+## How Errors are Handled
+
+When an error is thrown inside a `Node`, Flowcraft wraps it in a `WorkflowError` object. This custom error provides additional context, including:
+
+- `nodeName`: The name of the `Node` class where the error occurred.
+- `phase`: The lifecycle phase (`'prep'`, `'exec'`, or `'post'`) where the error was thrown.
+- `originalError`: The underlying error that was caught.
+
+This ensures that you always know the precise location of a failure in your workflow.
+
+If an unhandled error occurs (meaning there is no fallback logic), it will propagate up and halt the entire `Flow`.
+
+## Automatic Retries
+
+The most common way to handle transient failures (like a temporary network issue) is to simply retry the operation. You can configure this directly on any `Node` instance through its constructor options.
+
+### `maxRetries` and `wait`
+
+- `maxRetries`: The total number of times the `exec` phase will be attempted. A value of `1` (the default) means no retries. A value of `3` means one initial attempt and up to two retries.
+- `wait`: The time in milliseconds to wait between retry attempts. Defaults to `0`.
+
+> [!IMPORTANT]
+> **Only the `exec` phase is retried.** Errors in `prep` or `post` are considered fatal for that node and will immediately cause a failure. This is by design, as these phases often involve state changes in the `Context` that might not be safe to repeat.
+
+### Example: Retrying an API Call
+
+Let's create a node that simulates a flaky API call and configure it to retry.
+
+```typescript
+import { ConsoleLogger, Flow, Node, TypedContext } from 'flowcraft'
+
+class FlakyApiNode extends Node {
+	private attempts = 0
+
+	constructor() {
+		// Configure to try a total of 3 times, waiting 100ms between failures.
+		super({ maxRetries: 3, wait: 100 })
+	}
+
+	async exec() {
+		this.attempts++
+		console.log(`Calling API, attempt #${this.attempts}...`)
+
+		if (this.attempts < 3) {
+			throw new Error('API is temporarily unavailable!')
+		}
+
+		console.log('API call successful!')
+		return { data: 'some important data' }
+	}
+}
+
+const flow = new Flow(new FlakyApiNode())
+// We'll use a ConsoleLogger to see the retry warnings.
+await flow.run(new TypedContext(), { logger: new ConsoleLogger() })
+```
+
+The output will look like this, demonstrating the retry logic:
+
+```
+[INFO] Running node: FlakyApiNode
+Calling API, attempt #1...
+[WARN] Attempt 1/3 failed for FlakyApiNode. Retrying...
+Calling API, attempt #2...
+[WARN] Attempt 2/3 failed for FlakyApiNode. Retrying...
+Calling API, attempt #3...
+API call successful!
+```
+
+## Fallback Logic
+
+What happens if all retries are exhausted and the `exec` phase still fails? By default, the node throws an error. However, you can provide a safety net by implementing the `execFallback` method.
+
+`execFallback` is a special lifecycle method on the `Node` class. It is only called if all `exec` attempts (initial + retries) have failed. It receives the same `args` as `exec`, with the final `error` object included.
+
+The return value of `execFallback` will be passed to the `post` phase, just as a successful `exec` result would be. This allows your workflow to gracefully recover and continue, perhaps with default or cached data.
+
+### Example: Using a Fallback
+
+Let's modify the previous example to handle a permanent failure.
+
+```typescript
+import { ConsoleLogger, contextKey, Flow, Node, TypedContext } from 'flowcraft'
+
+class ResilientApiNode extends Node<void, { data: string }> {
+	constructor() {
+		super({ maxRetries: 2 }) // Try twice
+	}
+
+	async exec() {
+		console.log('Attempting to call the API...')
+		throw new Error('API is down!')
+	}
+
+	// This method runs after all exec retries fail.
+	async execFallback({ error }) {
+		console.error(`All API attempts failed. Reason: ${error.message}`)
+		console.log('Returning cached/default data as a fallback.')
+		return { data: 'default fallback data' }
+	}
+
+	async post({ ctx, execRes }) {
+		// The post phase doesn't care if exec or execFallback ran.
+		// It just receives the result.
+		ctx.set(DATA_KEY, execRes.data)
+	}
+}
+
+const DATA_KEY = contextKey<string>('data')
+const context = new TypedContext()
+const flow = new Flow(new ResilientApiNode())
+
+await flow.run(context, { logger: new ConsoleLogger() })
+
+console.log(`Final data in context: ${context.get(DATA_KEY)}`)
+```
+
+The output will be:
+
+```
+[INFO] Running node: ResilientApiNode
+Attempting to call the API...
+[WARN] Attempt 1/2 failed for ResilientApiNode. Retrying...
+Attempting to call the API...
+[ERROR] All retries failed for ResilientApiNode. Executing fallback.
+All API attempts failed. Reason: API is down!
+Returning cached/default data as a fallback.
+Final data in context: default fallback data
+```
+
+The workflow completed successfully because the fallback provided a valid result, allowing the `post` phase and the rest of the flow to proceed.

package/docs/guide/advanced-guides/logging.md

@@ -0,0 +1,106 @@
+# Pluggable Logging
+
+Effective logging is essential for debugging and monitoring any application. Flowcraft is designed to be completely unopinionated about your logging strategy. It provides a simple `Logger` interface and includes a few basic implementations, but makes it easy to plug in any logging library you prefer, such as **Pino**, **Winston**, or your company's standard logger.
+
+## The `Logger` Interface
+
+The framework uses a simple interface to decouple itself from any specific logging implementation. Any logger you provide must conform to this shape:
+
+```typescript
+export interface Logger {
+	debug: (message: string, context?: object) => void
+	info: (message: string, context?: object) => void
+	warn: (message: string, context?: object) => void
+	error: (message: string, context?: object) => void
+}
+```
+
+The `context` object is used to pass structured data, which is a best practice for modern logging. The Flowcraft engine will automatically pass contextual information here, such as retry attempts or error details.
+
+## Using the Built-in Loggers
+
+Flowcraft comes with two pre-built loggers:
+
+- **`ConsoleLogger`**: A straightforward logger that prints messages to the `console` (e.g., `console.info`, `console.warn`). This is great for development and debugging.
+- **`NullLogger`**: A logger that does nothing.
+
+> [!NOTE]
+> **Flowcraft is silent by default.** The `NullLogger` is the framework's default if no logger is provided. This ensures that Flowcraft doesn't clutter your application's output unless you explicitly enable logging by passing a `logger` in the `RunOptions`.
+
+To use the `ConsoleLogger`, simply pass it in the `RunOptions` when you execute a flow:
+
+```typescript
+import { ConsoleLogger, Flow, Node, TypedContext } from 'flowcraft'
+
+const myFlow = new Flow(new Node().exec(() => 'done'))
+const context = new TypedContext()
+
+// Run the flow with the console logger enabled
+await myFlow.run(context, { logger: new ConsoleLogger() })
+```
+
+This will produce detailed output about the flow's execution, including which nodes are running, what actions they return, and any warnings or errors.
+
+## Integrating a Custom Logger (e.g., Pino)
+
+Plugging in a production-grade logger like [Pino](https://github.com/pinojs/pino) is easy. All you need is a simple adapter class that maps Pino's logging methods to Flowcraft's `Logger` interface.
+
+### Example: Pino Logger Adapter
+
+First, install pino:
+
+```bash
+npm install pino
+```
+
+Then, create an adapter class:
+
+```typescript
+// src/loggers/pino-logger.ts
+import { Logger as FlowcraftLogger } from 'flowcraft'
+import pino, { Logger as PinoLogger } from 'pino'
+
+export class PinoFlowcraftLogger implements FlowcraftLogger {
+	private pino: PinoLogger
+
+	constructor(options?: pino.LoggerOptions) {
+		// Initialize pino with your desired configuration
+		this.pino = pino(options || {
+			level: 'info',
+			transport: {
+				target: 'pino-pretty', // for development
+			},
+		})
+	}
+
+	// Map the interface methods to pino's methods
+	public debug(message: string, context?: object): void {
+		this.pino.debug(context || {}, message)
+	}
+
+	public info(message: string, context?: object): void {
+		this.pino.info(context || {}, message)
+	}
+
+	public warn(message: string, context?: object): void {
+		this.pino.warn(context || {}, message)
+	}
+
+	public error(message: string, context?: object): void {
+		this.pino.error(context || {}, message)
+	}
+}
+```
+
+Now you can use your custom logger just like a built-in one:
+
+```typescript
+// main.ts
+import { PinoFlowcraftLogger } from './loggers/pino-logger'
+
+const pinoLogger = new PinoFlowcraftLogger()
+
+await myFlow.run(context, { logger: pinoLogger })
+```
+
+Your workflow's execution logs will now be formatted as structured JSON (or pretty-printed, depending on your Pino configuration), ready to be shipped to a log aggregation service like Datadog, Logstash, or Splunk.

package/docs/guide/advanced-guides/middleware.md

@@ -0,0 +1,106 @@
+# Middleware
+
+Middleware provides a powerful mechanism to hook into the execution of nodes within a `Flow`. It allows you to wrap the logic of every node, making it the ideal pattern for handling **cross-cutting concerns** without cluttering your business logic.
+
+## What is Middleware?
+
+A middleware is a function that sits between the `Executor` and the `Node` it is about to execute. It receives the node's arguments and a `next` function. The middleware can perform actions before calling `next()` to proceed with the node's execution, and after `next()` returns to process the result.
+
+This is conceptually similar to middleware in web frameworks like Express or Koa.
+
+## Common Use Cases
+
+- **Performance Monitoring**: Start a timer before `next()` and record the duration after it completes to measure how long each node takes.
+- **Authentication/Authorization**: Check if the current context has valid credentials before allowing a node to run.
+- **Transaction Management**: Start a database transaction before the first node in a flow and commit or roll it back after the flow completes.
+- **Input/Output Validation**: Validate a node's parameters before execution or its results after execution.
+- **Centralized Logging**: Implement structured logging for every node's entry and exit. See the [Logging Guide](./logging.md) for more on this topic.
+
+## How to Use Middleware
+
+You can add middleware to any `Flow` instance using the `.use()` method. You can add multiple middleware functions; they will be executed in the order they are added.
+
+### The Middleware Function Signature
+
+A middleware function has the following signature:
+
+```typescript
+type Middleware = (args: NodeArgs, next: MiddlewareNext) => Promise<any>
+type MiddlewareNext = (args: NodeArgs) => Promise<any>
+```
+
+- `args`: The `NodeArgs` object, containing the `ctx`, `params`, `logger`, etc., for the node about to be executed.
+- `next`: A function that you must call to pass control to the next middleware in the chain, or to the node itself if it's the last one.
+
+### Example: Database Transaction Middleware
+
+A classic use case for middleware is managing a database transaction. We want to start a transaction before the flow runs and either `COMMIT` it on success or `ROLLBACK` on failure.
+
+Let's assume we have a `dbClient` with `beginTransaction`, `commit`, and `rollback` methods.
+
+```typescript
+// A mock database client
+const dbClient = {
+	beginTransaction: async () => console.log('[DB] ==> BEGIN TRANSACTION'),
+	commit: async () => console.log('[DB] <== COMMIT'),
+	rollback: async () => console.log('[DB] <== ROLLBACK'),
+	query: async (sql: string) => console.log(`[DB] Executing: ${sql}`),
+}
+
+// Our transaction middleware
+async function transactionMiddleware(args, next) {
+	// This middleware only acts on the top-level Flow, not individual nodes.
+	// We check the node's name to apply the logic selectively.
+	if (args.name !== 'TransactionFlow') {
+		return next(args)
+	}
+
+	await dbClient.beginTransaction()
+	try {
+		// Call next() to execute the entire wrapped flow
+		const result = await next(args)
+		await dbClient.commit()
+		return result
+	}
+	catch (error) {
+		console.error('[DB] Error occurred, rolling back transaction.')
+		await dbClient.rollback()
+		// Re-throw the error so the top-level caller knows the flow failed
+		throw error
+	}
+}
+
+// Nodes that simulate database operations
+class CreateUserNode extends Node {
+	async exec() { await dbClient.query('INSERT INTO users...') }
+}
+class UpdateProfileNode extends Node {
+	async exec() { await dbClient.query('UPDATE profiles...') }
+}
+
+// A specific Flow class to attach the middleware to
+class TransactionFlow extends Flow {}
+
+// Create a flow with a couple of nodes
+const flow = new TransactionFlow(new CreateUserNode())
+flow.startNode.next(new UpdateProfileNode())
+
+// Apply the middleware
+flow.use(transactionMiddleware)
+
+// Run it
+console.log('--- Running successful transaction ---')
+await flow.run(new TypedContext())
+```
+
+When this runs, the transaction is correctly committed:
+
+```
+--- Running successful transaction ---
+[DB] ==> BEGIN TRANSACTION
+[DB] Executing: INSERT INTO users...
+[DB] Executing: UPDATE profiles...
+[DB] <== COMMIT
+```
+
+If a node were to fail, the `try...catch` block in the middleware would catch the error and issue a `ROLLBACK`, ensuring data integrity. This powerful pattern keeps your business logic nodes (`CreateUserNode`) clean and unaware of transaction management.

package/docs/guide/advanced-guides/observability.md

@@ -0,0 +1,175 @@
+# Observability (Tracing & Metrics)
+
+For production-grade applications, understanding how your workflows are performing is critical. Observability—through structured logging, distributed tracing, and metrics—allows you to debug issues, identify bottlenecks, and monitor the health of your system.
+
+Flowcraft's `Middleware` pattern is the perfect place to integrate observability tooling like **OpenTelemetry** without cluttering your business logic. This guide will show you how to create a middleware that adds tracing and metrics to every node in your flow.
+
+## The Goal
+
+We want to create a middleware that, for every node execution:
+
+1. **Starts a new OpenTelemetry Span**: This creates a "trace" that visualizes the node as a distinct unit of work, showing its duration and relationship to other nodes.
+2. **Adds Attributes**: Enriches the span with useful information like the node's name, the action it returned, and whether it succeeded or failed.
+3. **Records Metrics**: Captures the duration of the node's execution as a histogram metric, allowing you to create dashboards and alerts for performance.
+4. **Propagates Context**: Ensures that any operations performed *inside* the node (like an API call) are part of the same trace.
+
+## Prerequisites
+
+This guide assumes you have a basic OpenTelemetry setup for Node.js. If you don't, please refer to the official [OpenTelemetry for Node.js Getting Started guide](https://opentelemetry.io/docs/instrumentation/js/getting-started/nodejs/).
+
+At a minimum, you'll need the following packages:
+
+```bash
+npm install @opentelemetry/api \
+  @opentelemetry/sdk-node \
+  @opentelemetry/auto-instrumentations-node
+```
+
+And a simple file (`tracing.ts`) to configure the SDK:
+
+```typescript
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http' // or your preferred exporter
+// src/tracing.ts
+import { NodeSDK } from '@opentelemetry/sdk-node'
+
+const sdk = new NodeSDK({
+	traceExporter: new OTLPTraceExporter(),
+	instrumentations: [getNodeAutoInstrumentations()],
+})
+
+sdk.start()
+```
+
+## The Observability Middleware
+
+Here is a complete, reusable middleware for OpenTelemetry. You can place this in a file like `src/middleware/tracing.ts`.
+
+```typescript
+import {
+	context,
+	Meter,
+	metrics,
+	Span,
+	SpanStatusCode,
+	trace,
+	Tracer,
+} from '@opentelemetry/api'
+// src/middleware/tracing.ts
+import { Middleware, NodeArgs } from 'flowcraft'
+
+export class ObservabilityMiddleware {
+	private tracer: Tracer
+	private meter: Meter
+	private nodeDurationHistogram: any // In real OTel, this is an Instrument
+
+	constructor() {
+		// Get the global tracer and meter from your OTel setup
+		this.tracer = trace.getTracer('flowcraft-workflow-tracer')
+		this.meter = metrics.getMeter('flowcraft-workflow-meter')
+
+		// Create a metric to record node execution time
+		this.nodeDurationHistogram = this.meter.createHistogram('flowcraft.node.duration', {
+			description: 'Duration of Flowcraft node execution',
+			unit: 'ms',
+		})
+	}
+
+	// The middleware function itself
+	public readonly middleware: Middleware = async (args: NodeArgs, next) => {
+		const { name: nodeName } = args
+
+		// Start a new span for this node execution
+		return this.tracer.startActiveSpan(`run ${nodeName}`, async (span: Span) => {
+			const startTime = Date.now()
+
+			span.setAttribute('flowcraft.node.name', nodeName)
+
+			try {
+				// Run the actual node logic
+				const action = await next(args)
+
+				const duration = Date.now() - startTime
+
+				// Record the duration as a metric
+				this.nodeDurationHistogram.record(duration, { 'flowcraft.node.name': nodeName, 'flowcraft.node.status': 'success' })
+
+				// Add the action to the span and set status to OK
+				span.setAttribute('flowcraft.node.action', String(action))
+				span.setStatus({ code: SpanStatusCode.OK })
+
+				return action
+			}
+			catch (error: any) {
+				const duration = Date.now() - startTime
+
+				// Record the failed duration
+				this.nodeDurationHistogram.record(duration, { 'flowcraft.node.name': nodeName, 'flowcraft.node.status': 'error' })
+
+				// Mark the span as failed and record the error details
+				span.setStatus({
+					code: SpanStatusCode.ERROR,
+					message: error.message,
+				})
+				span.recordException(error)
+
+				// Re-throw the error to ensure the workflow's error handling takes over
+				throw error
+			}
+			finally {
+				// End the span, ensuring it's always closed
+				span.end()
+			}
+		})
+	}
+}
+```
+
+## How to Use It
+
+Using the middleware is straightforward. Instantiate it and apply it to your `Flow` with `.use()`.
+
+```typescript
+import { Flow, Node, TypedContext } from 'flowcraft'
+
+import { ObservabilityMiddleware } from './middleware/tracing'
+// main.ts
+import './tracing' // Important: Initialize OpenTelemetry SDK first!
+
+class GreetNode extends Node {
+	async exec() {
+		console.log('Hello from GreetNode!')
+		// In a real app, an instrumented library like `fetch` would create a child span automatically here.
+	}
+}
+
+class FarewellNode extends Node {
+	async exec() {
+		console.log('Goodbye from FarewellNode!')
+	}
+}
+
+// 1. Create an instance of our middleware
+const obsMiddleware = new ObservabilityMiddleware()
+
+// 2. Create the flow
+const greetNode = new GreetNode()
+greetNode.next(new FarewellNode())
+const flow = new Flow(greetNode)
+
+// 3. Apply the middleware to the flow
+flow.use(obsMiddleware.middleware)
+
+// 4. Run it
+await flow.run(new TypedContext())
+```
+
+## What Happens Now?
+
+When you run this code with a configured OpenTelemetry exporter (e.g., sending to Jaeger, Zipkin, or a service like Honeycomb or Datadog), you will get:
+
+- **A Trace Waterfall**: You'll see a visual breakdown of your workflow. The `run GreetNode` span will be followed by the `run FarewellNode` span. You can immediately see how long each took and in what order they executed.
+- **Rich Context**: Clicking on a span will show all the attributes we added: the node's name, the action it returned, and any errors that occurred.
+- **Performance Metrics**: You can now build dashboards and alerts based on the `flowcraft.node.duration` metric. For example, you can graph the P95 duration for a specific node or alert if its failure rate (`flowcraft.node.status: 'error'`) spikes.
+
+This simple but powerful pattern makes your Flowcraft workflows fully observable, turning them from black boxes into transparent, debuggable, and production-ready systems.