flowcraft 1.0.0-beta.1

package/src/executors/in-memory.test.ts

@@ -0,0 +1,93 @@
+import type { MiddlewareNext, NodeArgs } from '../workflow'
+import { describe, expect, it } from 'vitest'
+import { contextKey, Flow, Node, TypedContext } from '../workflow'
+import { InMemoryExecutor } from './in-memory'
+
+const VALUE = contextKey<number>('value')
+const PATH = contextKey<string[]>('path')
+const MIDDLEWARE_PATH = contextKey<string[]>('middleware_path')
+
+// Helper Nodes for testing
+class AddNode extends Node {
+	constructor(private num: number, public id: string) { super() }
+	async exec({ ctx }: any) {
+		const current = ctx.get(VALUE) ?? 0
+		ctx.set(VALUE, current + this.num)
+		const path = ctx.get(PATH) ?? []
+		ctx.set(PATH, [...path, this.id])
+	}
+}
+
+class BranchNode extends Node {
+	async post({ ctx }: any) {
+		const path = ctx.get(PATH) ?? []
+		ctx.set(PATH, [...path, 'branch'])
+		return ctx.get(VALUE) > 10 ? 'over' : 'under'
+	}
+}
+
+describe('testInMemoryExecutor', () => {
+	it('should execute a simple linear flow', async () => {
+		const ctx = new TypedContext([[VALUE, 1]])
+		const startNode = new AddNode(5, 'start')
+		startNode.next(new AddNode(3, 'next'))
+		const flow = new Flow(startNode)
+		const executor = new InMemoryExecutor()
+
+		await executor.run(flow, ctx)
+
+		expect(ctx.get(VALUE)).toBe(9)
+		expect(ctx.get(PATH)).toEqual(['start', 'next'])
+	})
+
+	it('should handle conditional branching', async () => {
+		const ctx = new TypedContext([[VALUE, 5]])
+		const start = new AddNode(6, 'start') // value becomes 11
+		const branch = new BranchNode()
+		const overNode = new AddNode(100, 'over_node')
+		const underNode = new AddNode(-1, 'under_node')
+		start.next(branch)
+		branch.next(overNode, 'over')
+		branch.next(underNode, 'under')
+
+		const flow = new Flow(start)
+		const executor = new InMemoryExecutor()
+
+		await executor.run(flow, ctx)
+
+		expect(ctx.get(VALUE)).toBe(111) // 5 + 6 + 100
+		expect(ctx.get(PATH)).toEqual(['start', 'branch', 'over_node'])
+	})
+
+	it('should correctly execute a composed flow (sub-flow)', async () => {
+		const ctx = new TypedContext([[VALUE, 1]])
+		const innerStart = new AddNode(5, 'inner_start') // 1 + 5 = 6
+		innerStart.next(new AddNode(10, 'inner_end')) // 6 + 10 = 16
+		const innerFlow = new Flow(innerStart)
+		const outerStart = new AddNode(100, 'outer_start') // 16 + 100 = 116
+		const outerFlow = new Flow(innerFlow)
+		innerFlow.next(outerStart)
+		const executor = new InMemoryExecutor()
+		await executor.run(outerFlow, ctx)
+		expect(ctx.get(VALUE)).toBe(116)
+		expect(ctx.get(PATH)).toEqual(['inner_start', 'inner_end', 'outer_start'])
+	})
+
+	it('should apply middleware from the orchestrating flow to its nodes', async () => {
+		const ctx = new TypedContext()
+		const flow = new Flow(new AddNode(10, 'node1'))
+		const testMiddleware = async (args: NodeArgs, next: MiddlewareNext) => {
+			const path = args.ctx.get(MIDDLEWARE_PATH) ?? []
+			args.ctx.set(MIDDLEWARE_PATH, [...path, `enter_${args.name}`])
+			const result = await next(args)
+			const finalPath = args.ctx.get(MIDDLEWARE_PATH) ?? []
+			args.ctx.set(MIDDLEWARE_PATH, [...finalPath, `exit_${args.name}`])
+			return result
+		}
+		flow.use(testMiddleware)
+		const executor = new InMemoryExecutor()
+		await executor.run(flow, ctx)
+		expect(ctx.get(VALUE)).toBe(10)
+		expect(ctx.get(MIDDLEWARE_PATH)).toEqual(['enter_AddNode', 'exit_AddNode'])
+	})
+})

package/src/executors/in-memory.ts

@@ -0,0 +1,140 @@
+import type { IExecutor, InternalRunOptions } from '../executor'
+import type { AbstractNode, Context, Flow, Logger, Middleware, MiddlewareNext, NodeArgs, RunOptions } from '../workflow'
+import { AbortError, NullLogger } from '../workflow'
+
+/**
+ * The default executor that runs a workflow within a single, in-memory process.
+ * This class contains the core logic for traversing a workflow graph, applying middleware,
+ * and handling node execution.
+ */
+export class InMemoryExecutor implements IExecutor {
+	/**
+	 * A stateless, reusable method that orchestrates the traversal of a graph.
+	 * It is called by `run()` for top-level flows and by `Flow.exec()` for sub-flows.
+	 * @param startNode The node where the graph traversal begins.
+	 * @param flowMiddleware The middleware array from the containing flow.
+	 * @param context The shared workflow context.
+	 * @param options The internal, normalized run options.
+	 * @returns The final action from the last executed node in the graph.
+	 * @internal
+	 */
+	public async _orch(
+		startNode: AbstractNode,
+		flowMiddleware: Middleware[],
+		context: Context,
+		options: InternalRunOptions,
+	): Promise<any> {
+		let currentNode: AbstractNode | undefined = startNode
+		let lastAction: any
+
+		const { logger, signal, params, executor } = options
+
+		while (currentNode) {
+			if (signal?.aborted)
+				throw new AbortError()
+
+			const chain = this.applyMiddleware(flowMiddleware, currentNode)
+
+			const nodeArgs: NodeArgs = {
+				ctx: context,
+				params,
+				signal,
+				logger,
+				prepRes: undefined,
+				execRes: undefined,
+				name: currentNode.constructor.name,
+				executor,
+			}
+
+			lastAction = await chain(nodeArgs)
+
+			const previousNode = currentNode
+			currentNode = this.getNextNode(previousNode, lastAction, logger)
+		}
+
+		return lastAction
+	}
+
+	/**
+	 * Executes a given flow with a specific context and options.
+	 * This is the main entry point for the in-memory execution engine.
+	 * @param flow The Flow instance to execute.
+	 * @param context The shared context for the workflow.
+	 * @param options Runtime options, including a logger, abort controller, or initial params.
+	 * @returns A promise that resolves with the final action of the workflow.
+	 */
+	public async run(flow: Flow, context: Context, options?: RunOptions): Promise<any> {
+		const logger = options?.logger ?? new NullLogger()
+		const controller = options?.controller
+		const combinedParams = { ...flow.params, ...options?.params }
+
+		const internalOptions: InternalRunOptions = {
+			logger,
+			signal: controller?.signal,
+			params: combinedParams,
+			executor: this,
+		}
+
+		// Handle "logic-bearing" flows (e.g., BatchFlow) that don't have a graph.
+		// Their logic is self-contained in their `exec` method.
+		if (!flow.startNode) {
+			logger.info(`Executor is running a logic-bearing flow: ${flow.constructor.name}`)
+			const chain = this.applyMiddleware(flow.middleware, flow)
+			return await chain({
+				...internalOptions,
+				ctx: context,
+				prepRes: undefined,
+				execRes: undefined,
+				name: flow.constructor.name,
+			})
+		}
+
+		logger.info(`Executor is running flow graph: ${flow.constructor.name}`)
+		// Delegate the graph traversal to our new stateless helper.
+		// Pass the flow's own middleware to be applied to its nodes.
+		return this._orch(flow.startNode, flow.middleware, context, internalOptions)
+	}
+
+	/**
+	 * Determines the next node to execute based on the action returned by the current node.
+	 * @internal
+	 */
+	public getNextNode(curr: AbstractNode, action: any, logger: Logger): AbstractNode | undefined {
+		const nextNode = curr.successors.get(action)
+		const actionDisplay = typeof action === 'symbol' ? action.toString() : action
+
+		if (nextNode) {
+			logger.debug(`Action '${actionDisplay}' from ${curr.constructor.name} leads to ${nextNode.constructor.name}`, { action })
+		}
+		else if (curr.successors.size > 0 && action !== undefined && action !== null) {
+			logger.info(`Flow ends: Action '${actionDisplay}' from ${curr.constructor.name} has no configured successor.`)
+		}
+		return nextNode
+	}
+
+	/**
+	 * Composes a chain of middleware functions around a node's execution.
+	 * @internal
+	 */
+	public applyMiddleware(middleware: Middleware[], nodeToRun: AbstractNode): MiddlewareNext {
+		// The final function in the chain is the actual execution of the node.
+		const runNode: MiddlewareNext = (args: NodeArgs) => {
+			return nodeToRun._run({
+				ctx: args.ctx,
+				params: { ...args.params, ...nodeToRun.params },
+				signal: args.signal,
+				logger: args.logger,
+				executor: args.executor,
+			})
+		}
+
+		if (!middleware || middleware.length === 0)
+			return runNode
+
+		// Build the chain backwards, so the first middleware in the array is the outermost.
+		return middleware.reduceRight<MiddlewareNext>(
+			(next, mw) => (args: NodeArgs) => mw(args, next),
+			runNode,
+		)
+	}
+}

package/src/functions.test.ts

@@ -0,0 +1,191 @@
+import type { Logger, RunOptions } from './workflow'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+	compose,
+	contextNode,
+	mapNode,
+	pipeline,
+	transformNode,
+} from './functions'
+import { contextKey, DEFAULT_ACTION, lens, TypedContext } from './workflow'
+
+// Mock logger for testing
+function createMockLogger(): Logger {
+	return {
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+	}
+}
+
+let mockLogger = createMockLogger()
+let runOptions: RunOptions = { logger: mockLogger }
+
+afterEach(() => {
+	mockLogger = createMockLogger()
+	runOptions = { logger: mockLogger }
+})
+
+// Context Keys for testing
+const NAME = contextKey<string>('name')
+const COUNTER = contextKey<number>('counter')
+const RESULT = contextKey<any>('result')
+const PREFIX = contextKey<string>('prefix')
+
+describe('mapNode', () => {
+	it('should create a node from a synchronous function', async () => {
+		const ctx = new TypedContext()
+		const doubleNode = mapNode<{ value: number }, number>(params => params.value * 2)
+			.toContext(RESULT)
+		await doubleNode.withParams({ value: 10 }).run(ctx, runOptions)
+		expect(ctx.get(RESULT)).toBe(20)
+	})
+
+	it('should create a node from an asynchronous function', async () => {
+		const ctx = new TypedContext()
+		const upperNode = mapNode<{ value: string }, string>(async params => params.value.toUpperCase())
+			.toContext(RESULT)
+		await upperNode.withParams({ value: 'hello' }).run(ctx, runOptions)
+		expect(ctx.get(RESULT)).toBe('HELLO')
+	})
+
+	it('should handle nodes that produce no output', async () => {
+		const ctx = new TypedContext()
+		const sideEffectFn = vi.fn()
+		const tapNode = mapNode<any, void>(params => sideEffectFn(params.value))
+		await tapNode.withParams({ value: 123 }).run(ctx, runOptions)
+		expect(sideEffectFn).toHaveBeenCalledWith(123)
+		const action = await tapNode.withParams({ value: 456 }).run(ctx, runOptions)
+		expect(Array.from(ctx.entries())).toHaveLength(0)
+		expect(action).toBe(DEFAULT_ACTION)
+	})
+})
+
+describe('contextNode', () => {
+	it('should access context and params in a synchronous function', async () => {
+		const ctx = new TypedContext([[PREFIX, 'Hello']])
+		const greeterNode = contextNode<{ name: string }, string>((ctx, params) => {
+			const prefix = ctx.get(PREFIX) ?? 'Default'
+			return `${prefix}, ${params.name}!`
+		}).toContext(RESULT)
+		await greeterNode.withParams({ name: 'World' }).run(ctx, runOptions)
+		expect(ctx.get(RESULT)).toBe('Hello, World!')
+	})
+
+	it('should access context and params in an asynchronous function', async () => {
+		const ctx = new TypedContext([[PREFIX, 'Hola']])
+		const greeterNode = contextNode<{ name: string }, string>(async (ctx, params) => {
+			const prefix = ctx.get(PREFIX)
+			await new Promise(resolve => setTimeout(resolve, 1))
+			return `${prefix}, ${params.name}!`
+		}).toContext(RESULT)
+		await greeterNode.withParams({ name: 'Mundo' }).run(ctx, runOptions)
+		expect(ctx.get(RESULT)).toBe('Hola, Mundo!')
+	})
+})
+
+describe('transformNode', () => {
+	it('should apply a single context transform', async () => {
+		const ctx = new TypedContext()
+		const nameLens = lens(NAME)
+		const setNode = transformNode(nameLens.set('Alice'))
+		await setNode.run(ctx, runOptions)
+		expect(ctx.get(NAME)).toBe('Alice')
+	})
+
+	it('should apply multiple context transforms in order', async () => {
+		const ctx = new TypedContext([[COUNTER, 10]])
+		const nameLens = lens(NAME)
+		const counterLens = lens(COUNTER)
+		const setupNode = transformNode(
+			nameLens.set('Bob'),
+			counterLens.update(c => (c ?? 0) + 5),
+		)
+		await setupNode.run(ctx, runOptions)
+		expect(ctx.get(NAME)).toBe('Bob')
+		expect(ctx.get(COUNTER)).toBe(15)
+	})
+
+	it('should be chainable within a pipeline', async () => {
+		const ctx = new TypedContext([[COUNTER, 0]])
+		const nameLens = lens(NAME)
+		const counterLens = lens(COUNTER)
+		// A node that reads from context
+		const readNode = contextNode((ctx) => {
+			return `${ctx.get(NAME)} has ${ctx.get(COUNTER)} points`
+		}).toContext(RESULT)
+		const flow = pipeline(
+			transformNode(
+				nameLens.set('Carol'),
+				counterLens.set(100),
+			),
+			readNode,
+		)
+		await flow.run(ctx, runOptions)
+		expect(ctx.get(RESULT)).toBe('Carol has 100 points')
+	})
+})
+
+describe('pipeline', () => {
+	it('should create and run a linear sequence of nodes', async () => {
+		const ctx = new TypedContext([[COUNTER, 5]])
+		const add10 = mapNode(() => 10).toContext(COUNTER)
+		const multiplyBy3 = contextNode(ctx => (ctx.get(COUNTER) ?? 0) * 3).toContext(COUNTER)
+		const flow = pipeline(add10, multiplyBy3)
+		await flow.run(ctx, runOptions)
+		expect(ctx.get(COUNTER)).toBe(30)
+	})
+
+	it('should run successfully with an empty sequence', async () => {
+		const ctx = new TypedContext()
+		const emptyFlow = pipeline()
+		const action = await emptyFlow.run(ctx, runOptions)
+		expect(Array.from(ctx.entries())).toHaveLength(0)
+		expect(action).toBe(DEFAULT_ACTION)
+	})
+})
+
+describe('compose', () => {
+	it('should compose two synchronous functions', async () => {
+		const add5 = (x: number) => x + 5
+		const multiply2 = (x: number) => x * 2
+		// multiply2(add5(x)) => (x + 5) * 2
+		const addThenMultiply = compose(multiply2, add5)
+		expect(await addThenMultiply(10)).toBe(30)
+	})
+
+	it('should compose two asynchronous functions', async () => {
+		const add5Async = async (x: number) => {
+			await new Promise(resolve => setTimeout(resolve, 1))
+			return x + 5
+		}
+		const multiply2Async = async (x: number) => {
+			await new Promise(resolve => setTimeout(resolve, 1))
+			return x * 2
+		}
+		const composed = compose(multiply2Async, add5Async)
+		expect(await composed(10)).toBe(30)
+	})
+
+	it('should compose mixed sync and async functions', async () => {
+		const add5 = (x: number) => x + 5
+		const multiply2Async = async (x: number) => x * 2
+		const composed1 = compose(multiply2Async, add5) // async(sync(x))
+		const composed2 = compose(add5, multiply2Async) // sync(async(x))
+		expect(await composed1(10)).toBe(30)
+		expect(await composed2(10)).toBe(25)
+	})
+
+	it('should be usable inside a mapNode', async () => {
+		const ctx = new TypedContext()
+		const add5 = (p: { val: number }) => ({ ...p, val: p.val + 5 })
+		const multiply2 = (p: { val: number }) => ({ ...p, val: p.val * 2 })
+		const composedFn = compose(multiply2, add5)
+		const processNode = mapNode(composedFn)
+			.map(res => res.val)
+			.toContext(RESULT)
+		await processNode.withParams({ val: 10 }).run(ctx, runOptions)
+		expect(ctx.get(RESULT)).toBe(30) // (10 + 5) * 2
+	})
+})

package/src/functions.ts

@@ -0,0 +1,117 @@
+import type { ContextTransform } from './context'
+import type { Context, Flow, Node, NodeArgs } from './workflow'
+import { SequenceFlow } from './builder/collection'
+import { composeContext } from './context'
+import { Node as BaseNode } from './workflow'
+
+/**
+ * A type for a pure function that can be executed within a `Node`,
+ * typically taking the node's `params` as input.
+ * @template TIn The input type, corresponding to `params`.
+ * @template TOut The output type, which becomes the node's `execRes`.
+ */
+export type NodeFunction<TIn = any, TOut = any> = (input: TIn) => TOut | Promise<TOut>
+
+/**
+ * A type for a function that operates on the shared `Context` in addition
+ * to the node's `params`.
+ * @template TIn The input type, corresponding to `params`.
+ * @template TOut The output type, which becomes the node's `execRes`.
+ */
+export type ContextFunction<TIn = any, TOut = any> = (ctx: Context, input: TIn) => TOut | Promise<TOut>
+
+/**
+ * Creates a `Node` from a simple, pure function that transforms an input to an output.
+ * The node's `params` object is passed as the input to the function.
+ *
+ * @example
+ * const add = (n: number) => mapNode<{ value: number }, number>(params => params.value + n)
+ * const add5Node = add(5) // A reusable node that adds 5 to its input parameter.
+ *
+ * @param fn A function that takes an input object and returns a result.
+ * @returns A new `Node` instance that wraps the function.
+ */
+export function mapNode<TIn, TOut>(fn: NodeFunction<TIn, TOut>): Node<TIn, TOut> {
+	return new class extends BaseNode<TIn, TOut> {
+		async exec({ params }: NodeArgs<TIn>): Promise<TOut> {
+			return fn(params as TIn)
+		}
+	}()
+}
+
+/**
+ * Creates a `Node` from a function that requires access to the shared `Context`.
+ * Both the `Context` and the node's `params` are passed as arguments to the function.
+ *
+ * @example
+ * const greeter = contextNode((ctx, params: { name: string }) => {
+ *   const language = ctx.get(LANGUAGE_KEY) || 'en'
+ *   return language === 'en' ? `Hello, ${params.name}` : `Hola, ${params.name}`
+ * })
+ *
+ * @param fn A function that takes the context and an input object, and returns a result.
+ * @returns A new `Node` instance that wraps the function.
+ */
+export function contextNode<TIn, TOut>(fn: ContextFunction<TIn, TOut>): Node<TIn, TOut> {
+	return new class extends BaseNode<TIn, TOut> {
+		async exec({ ctx, params }: NodeArgs<TIn>): Promise<TOut> {
+			return fn(ctx, params as TIn)
+		}
+	}()
+}
+
+/**
+ * Creates a `Node` that declaratively applies a series of transformations to the `Context`.
+ * This is a "side-effect" node used purely for state management; its logic runs in the `prep` phase,
+ * and it does not produce an `exec` output.
+ *
+ * @example
+ * const USER_ID = contextKey<string>('user_id')
+ * const userLens = lens(USER_ID)
+ * const setupUserContext = (userId: string) => transformNode(userLens.set(userId))
+ *
+ * @param transforms A sequence of `ContextTransform` functions (e.g., from a lens) to apply.
+ * @returns A new `Node` instance that will mutate the context when executed.
+ */
+export function transformNode(...transforms: ContextTransform[]): Node {
+	return new class extends BaseNode {
+		async prep({ ctx }: NodeArgs) {
+			// Apply the composed transformations directly to the mutable context.
+			composeContext(...transforms)(ctx)
+		}
+	}()
+}
+
+/**
+ * A functional-style alias for `SequenceFlow`. It constructs a linear workflow
+ * where each node executes in the order it is provided.
+ *
+ * @example
+ * const mathPipeline = pipeline(addNode(5), multiplyNode(2))
+ *
+ * @param nodes A sequence of `Node` instances to chain together.
+ * @returns A `Flow` instance representing the linear sequence.
+ */
+export function pipeline(...nodes: Node[]): Flow {
+	return new SequenceFlow(...nodes)
+}
+
+/**
+ * A classic functional composition utility. It takes two functions, `f` and `g`,
+ * and returns a new function that computes `f(g(x))`.
+ *
+ * This is a general-purpose helper, not a `Node` builder itself, but it can be
+ * used to create more complex `NodeFunction`s to pass to `mapNode`.
+ *
+ * @example
+ * const add5 = (x: number) => x + 5
+ * const multiply2 = (x: number) => x * 2
+ * const add5ThenMultiply2 = compose(multiply2, add5) // equivalent to: x => (x + 5) * 2
+ *
+ * @param f The outer function, which receives the result of `g`.
+ * @param g The inner function, which receives the initial input.
+ * @returns A new `NodeFunction` that combines both operations.
+ */
+export function compose<A, B, C>(f: NodeFunction<B, C>, g: NodeFunction<A, B>): NodeFunction<A, C> {
+	return async (input: A) => f(await g(input))
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './builder/index'
+export * from './executors/in-memory'
+export * from './functions'
+export * from './utils/index'
+export * from './workflow'

package/src/logger.ts

@@ -0,0 +1,41 @@
+/**
+ * Defines the interface for a logger that can be used by the workflow engine.
+ * This allows for plugging in any logging library (e.g., Pino, Winston).
+ */
+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
+}
+
+/**
+ * A logger implementation that performs no action (a "no-op" logger).
+ * This is the default logger used by the framework if none is provided,
+ * making Flowcraft silent out-of-the-box.
+ */
+export class NullLogger implements Logger {
+	debug() { /* no-op */ }
+	info() { /* no-op */ }
+	warn() { /* no-op */ }
+	error() { /* no-op */ }
+}
+
+/**
+ * A default logger implementation that writes messages to the `console`.
+ * Useful for development and debugging.
+ */
+export class ConsoleLogger implements Logger {
+	private log(level: 'debug' | 'info' | 'warn' | 'error', message: string, context?: object) {
+		const fullMessage = `[${level.toUpperCase()}] ${message}`
+		if (context && Object.keys(context).length > 0)
+			console[level](fullMessage, context)
+		else
+			console[level](fullMessage)
+	}
+
+	debug(message: string, context?: object) { this.log('debug', message, context) }
+	info(message: string, context?: object) { this.log('info', message, context) }
+	warn(message: string, context?: object) { this.log('warn', message, context) }
+	error(message: string, context?: object) { this.log('error', message, context) }
+}

package/src/types.ts

@@ -0,0 +1,75 @@
+import type { Context } from './context'
+import type { IExecutor } from './executor'
+import type { Logger } from './logger'
+
+/** A generic type for key-value parameters. */
+export type Params = Record<string, any>
+
+/** The default action returned by a node for linear progression. */
+export const DEFAULT_ACTION = Symbol('default')
+
+/** The action returned by a `.filter()` node when the predicate fails. */
+export const FILTER_FAILED = Symbol('filter_failed')
+
+/**
+ * The standard arguments object passed to a node's lifecycle methods.
+ * @template PrepRes The type of the `prepRes` property.
+ * @template ExecRes The type of the `execRes` property.
+ */
+export interface NodeArgs<PrepRes = any, ExecRes = any> {
+	/** The shared, mutable context for the workflow run. */
+	ctx: Context
+	/** The static parameters for the node, merged from the node and flow's `withParams`. */
+	params: Params
+	/** An `AbortSignal` for handling cancellation. */
+	signal?: AbortSignal
+	/** The logger instance for the workflow run. */
+	logger: Logger
+	/** The result of the `prep` phase. */
+	prepRes: PrepRes
+	/** The result of the `exec` phase. */
+	execRes: ExecRes
+	/** The final error object, available only in `execFallback`. */
+	error?: Error
+	/** The name of the Node's constructor, for logging. */
+	name?: string
+	/** A reference to the current `IExecutor` running the flow. */
+	executor?: IExecutor
+}
+
+/**
+ * The context object passed to a node's internal `_run` method.
+ * @internal
+ */
+export interface NodeRunContext {
+	ctx: Context
+	params: Params
+	signal?: AbortSignal
+	logger: Logger
+	executor?: IExecutor
+}
+
+/** Options for configuring a `Node` instance. */
+export interface NodeOptions {
+	/** The total number of times the `exec` phase will be attempted. Defaults to `1`. */
+	maxRetries?: number
+	/** The time in milliseconds to wait between failed `exec` attempts. Defaults to `0`. */
+	wait?: number
+}
+
+/** Options for running a top-level `Flow`. */
+export interface RunOptions {
+	/** An `AbortController` to gracefully cancel the workflow. */
+	controller?: AbortController
+	/** A `Logger` instance to receive logs from the execution engine. */
+	logger?: Logger
+	/** Top-level parameters to be merged into the context for the entire run. */
+	params?: Params
+	/** A custom `IExecutor` instance to run the workflow. Defaults to `InMemoryExecutor`. */
+	executor?: IExecutor
+}
+
+/** The function signature for the `next` function passed to middleware. */
+export type MiddlewareNext = (args: NodeArgs) => Promise<any>
+/** The function signature for a middleware function. */
+export type Middleware = (args: NodeArgs, next: MiddlewareNext) => Promise<any>