flowneer 0.7.0 → 0.8.0

package/README.md

@@ -22,6 +22,10 @@ A tiny, zero-dependency fluent flow builder for TypeScript. Chain steps, branch
 bun add flowneer
 ```
 
+## For LLM Agents
+[llms.txt](https://fanna1119.github.io/flowneer/llms.txt)
+[llms-full.txt](https://fanna1119.github.io/flowneer/llms-full.txt)
+
 ## Quick start
 
 ```typescript

package/dist/FlowBuilder-B0SMJ4um.d.ts

@@ -0,0 +1,390 @@
+/**
+ * Generic validator interface — structurally compatible with Zod, ArkType,
+ * Valibot, or any custom implementation that exposes `.parse(input)`.
+ * Used by `withStructuredOutput` and output parsers.
+ */
+interface Validator<T = unknown> {
+    parse(input: unknown): T;
+}
+/**
+ * Events yielded by `FlowBuilder.stream()`.
+ */
+type StreamEvent<S = any> = {
+    type: "step:before";
+    meta: StepMeta;
+} | {
+    type: "step:after";
+    meta: StepMeta;
+    shared: S;
+} | {
+    type: "chunk";
+    data: unknown;
+} | {
+    type: "error";
+    error: unknown;
+} | {
+    type: "done";
+};
+/**
+ * Function signature for all step logic.
+ * Return an action string to route, or undefined/void to continue.
+ *
+ * Steps may also be declared as `async function*` generators — each `yield`
+ * forwards its value to the active stream consumer as a `chunk` event.
+ * The generator's final `return` value is still routed normally, so
+ * `return "#anchorName"` works exactly as it does in plain steps.
+ *
+ * @example
+ * .then(async function* (s) {
+ *   for await (const token of llmStream(s.prompt)) {
+ *     s.response += token;
+ *     yield token;           // → chunk event on flow.stream()
+ *   }
+ * })
+ */
+type NodeFn<S = any, P extends Record<string, unknown> = Record<string, unknown>> = (shared: S, params: P) => Promise<string | undefined | void> | string | undefined | void | AsyncGenerator<unknown, string | undefined | void, unknown>;
+/**
+ * A numeric value or a function that computes it from the current shared state
+ * and params. Use functions for dynamic per-item behaviour, e.g.
+ * `retries: (s) => (s.__batchItem % 3 === 0 ? 3 : 1)`.
+ */
+type NumberOrFn<S = any, P extends Record<string, unknown> = Record<string, unknown>> = number | ((shared: S, params: P) => number);
+interface NodeOptions<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
+    retries?: NumberOrFn<S, P>;
+    delaySec?: NumberOrFn<S, P>;
+    timeoutMs?: NumberOrFn<S, P>;
+    /** Human-readable label for this step, shown in error messages and hook metadata. */
+    label?: string;
+}
+interface RunOptions {
+    signal?: AbortSignal;
+}
+/** Metadata exposed to hooks — intentionally minimal to avoid coupling. */
+interface StepMeta {
+    index: number;
+    type: "fn" | "branch" | "loop" | "batch" | "parallel" | "anchor";
+    label?: string;
+}
+/**
+ * Narrows which steps a hook fires for.
+ *
+ * - **String array** — only steps whose `label` matches are affected.
+ *   Entries are exact matches unless they contain `*`, which acts as a
+ *   wildcard matching any substring (glob-style).
+ *   e.g. `["llm:*"]` matches `"llm:summarise"`, `"llm:embed"`, etc.
+ * - **Predicate** — full control; return `true` to match.
+ *
+ * Unmatched `wrapStep`/`wrapParallelFn` hooks still call `next()` automatically
+ * so the middleware chain is never broken.
+ *
+ * @example
+ * // Exact labels
+ * flow.withRateLimit({ intervalMs: 1000 }, ["callLlm", "callEmbeddings"]);
+ *
+ * // Wildcard — any step whose label starts with "llm:"
+ * flow.withRateLimit({ intervalMs: 1000 }, ["llm:*"]);
+ *
+ * // Custom predicate
+ * flow.addHooks({ beforeStep: log }, (meta) => meta.type === "fn");
+ */
+type StepFilter = string[] | ((meta: StepMeta) => boolean);
+/** Lifecycle hooks that plugins can register. */
+interface FlowHooks<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
+    /** Fires once before the first step runs. */
+    beforeFlow?: (shared: S, params: P) => void | Promise<void>;
+    beforeStep?: (meta: StepMeta, shared: S, params: P) => void | Promise<void>;
+    /**
+     * Wraps step execution — call `next()` to invoke the step body.
+     * Omitting `next()` skips execution (dry-run, mock, etc.).
+     * Multiple `wrapStep` registrations are composed innermost-first.
+     */
+    wrapStep?: (meta: StepMeta, next: () => Promise<void>, shared: S, params: P) => Promise<void>;
+    afterStep?: (meta: StepMeta, shared: S, params: P) => void | Promise<void>;
+    /**
+     * Wraps individual functions within a `.parallel()` step.
+     * `fnIndex` is the position within the fns array.
+     */
+    wrapParallelFn?: (meta: StepMeta, fnIndex: number, next: () => Promise<void>, shared: S, params: P) => Promise<void>;
+    onError?: (meta: StepMeta, error: unknown, shared: S, params: P) => void;
+    afterFlow?: (shared: S, params: P) => void | Promise<void>;
+}
+/**
+ * A plugin is an object whose keys become methods on `FlowBuilder.prototype`.
+ * Each method receives the builder as `this` and should return `this` for chaining.
+ *
+ * Use declaration merging to get type-safe access:
+ * ```ts
+ * declare module "flowneer" {
+ *   interface FlowBuilder<S, P> { withTracing(fn: TraceCallback): this; }
+ * }
+ * ```
+ */
+type FlowneerPlugin = Record<string, (this: FlowBuilder<any, any>, ...args: any[]) => any>;
+/**
+ * An instance-scoped plugin. Called immediately when passed to `flow.use()`;
+ * registers hooks and/or performs setup on the specific `FlowBuilder` instance.
+ *
+ * Write plugins as factories so settings are captured in a closure:
+ * ```ts
+ * function withTiming(): InstancePlugin<any> {
+ *   return (flow) => {
+ *     const starts = new Map<number, number>();
+ *     flow.addHooks({
+ *       beforeStep: (meta) => { starts.set(meta.index, Date.now()); },
+ *       afterStep:  (meta, shared) => { shared.__timings ??= {}; shared.__timings[meta.index] = Date.now() - starts.get(meta.index)!; },
+ *     });
+ *   };
+ * }
+ *
+ * const flow = new FlowBuilder<MyState>()
+ *   .with([withTiming(), withRateLimit({ rps: 10 })])
+ *   .then(myStep);
+ * ```
+ *
+ * Order matters: plugins are applied left-to-right, so earlier plugins wrap
+ * later ones (the first plugin's `wrapStep` runs outermost).
+ */
+type InstancePlugin<S = any, P extends Record<string, unknown> = Record<string, unknown>> = (flow: FlowBuilder<S, P>) => void;
+
+interface FnStep<S, P extends Record<string, unknown>> {
+    type: "fn";
+    fn: NodeFn<S, P>;
+    retries: NumberOrFn<S, P>;
+    delaySec: NumberOrFn<S, P>;
+    timeoutMs: NumberOrFn<S, P>;
+    label?: string;
+}
+interface BranchStep<S, P extends Record<string, unknown>> {
+    type: "branch";
+    router: NodeFn<S, P>;
+    branches: Record<string, NodeFn<S, P>>;
+    retries: NumberOrFn<S, P>;
+    delaySec: NumberOrFn<S, P>;
+    timeoutMs: NumberOrFn<S, P>;
+    label?: string;
+}
+interface LoopStep<S, P extends Record<string, unknown>> {
+    type: "loop";
+    condition: (shared: S, params: P) => Promise<boolean> | boolean;
+    body: CoreFlowBuilder<S, P>;
+    label?: string;
+}
+interface BatchStep<S, P extends Record<string, unknown>> {
+    type: "batch";
+    itemsExtractor: (shared: S, params: P) => Promise<any[]> | any[];
+    processor: CoreFlowBuilder<S, P>;
+    key: string;
+    label?: string;
+}
+interface ParallelStep<S, P extends Record<string, unknown>> {
+    type: "parallel";
+    fns: NodeFn<S, P>[];
+    retries: NumberOrFn<S, P>;
+    delaySec: NumberOrFn<S, P>;
+    timeoutMs: NumberOrFn<S, P>;
+    reducer?: (shared: S, drafts: S[]) => void;
+    label?: string;
+}
+interface AnchorStep {
+    type: "anchor";
+    name: string;
+    /** Maximum number of times a goto may jump to this anchor per run. */
+    maxVisits?: number;
+}
+type Step<S, P extends Record<string, unknown>> = FnStep<S, P> | BranchStep<S, P> | LoopStep<S, P> | BatchStep<S, P> | ParallelStep<S, P> | AnchorStep;
+
+type ResolvedHooks<S, P extends Record<string, unknown>> = {
+    beforeFlow: NonNullable<FlowHooks<S, P>["beforeFlow"]>[];
+    beforeStep: NonNullable<FlowHooks<S, P>["beforeStep"]>[];
+    wrapStep: NonNullable<FlowHooks<S, P>["wrapStep"]>[];
+    afterStep: NonNullable<FlowHooks<S, P>["afterStep"]>[];
+    wrapParallelFn: NonNullable<FlowHooks<S, P>["wrapParallelFn"]>[];
+    onError: NonNullable<FlowHooks<S, P>["onError"]>[];
+    afterFlow: NonNullable<FlowHooks<S, P>["afterFlow"]>[];
+};
+/**
+ * Runtime context passed to every registered step handler.
+ * Full access to the builder so handlers can run sub-flows etc.
+ */
+interface StepContext<S, P extends Record<string, unknown> = Record<string, unknown>> {
+    shared: S;
+    params: P;
+    signal?: AbortSignal;
+    hooks: ResolvedHooks<S, P>;
+    meta: StepMeta;
+    builder: CoreFlowBuilder<S, P>;
+}
+/**
+ * Signature for step type execution handlers registered via
+ * `CoreFlowBuilder.registerStepType()`.
+ *
+ * Return a goto anchor name (without `#`) to jump, or `undefined` to continue.
+ */
+type StepHandler = (step: any, ctx: StepContext<any, any>) => Promise<string | undefined>;
+/**
+ * Minimal orchestration engine. Knows nothing about specific step types —
+ * those are registered as plugins via `CoreFlowBuilder.registerStepType()`.
+ *
+ * Use this as a base when you want a completely fresh, zero-assumption builder.
+ * The exported `FlowBuilder` extends this with all primitive step types
+ * (fn, branch, loop, batch, parallel, anchor) pre-registered.
+ */
+declare class CoreFlowBuilder<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
+    /** @internal Ordered list of step descriptors. */
+    steps: Step<S, P>[];
+    /** @internal Cached anchor-name → index map; null when stale. */
+    protected _anchorMap: Map<string, number> | null;
+    private _hooksList;
+    private _hooksCache;
+    private static _stepHandlers;
+    /**
+     * Register a handler for a custom step type.
+     * Called once at module load time from each step plugin.
+     *
+     * @example
+     * CoreFlowBuilder.registerStepType("myStep", async (step, ctx) => {
+     *   await doWork(ctx.shared);
+     *   return undefined;
+     * });
+     */
+    static registerStepType(type: string, handler: StepHandler): void;
+    private _hooks;
+    /**
+     * Register lifecycle hooks (called by plugin methods, not by consumers).
+     * Returns a dispose function that removes these hooks when called.
+     */
+    protected _setHooks(hooks: Partial<FlowHooks<S, P>>, filter?: StepFilter): () => void;
+    /**
+     * Register a plugin — copies its methods onto `FlowBuilder.prototype`.
+     */
+    static use(plugin: FlowneerPlugin): void;
+    /**
+     * Apply one or more instance-scoped plugins to this builder.
+     * Each plugin is called immediately; plugins are applied in array order
+     * so the first plugin's hooks wrap the later ones.
+     *
+     * @example
+     * const flow = new FlowBuilder<MyState>()
+     *   .with([withTiming(), withRateLimit({ rps: 10 })])
+     *   .then(myStep);
+     */
+    with(plugins: InstancePlugin<S, P> | Array<InstancePlugin<S, P>>): this;
+    /**
+     * Register lifecycle hooks directly on this instance.
+     * Returns a dispose function that removes these hooks when called.
+     */
+    addHooks(hooks: Partial<FlowHooks<S, P>>, filter?: StepFilter): () => void;
+    /** Execute the flow. */
+    run(shared: S, params?: P, options?: RunOptions): Promise<void>;
+    /**
+     * Execute the flow and yield `StreamEvent`s as an async generator.
+     */
+    stream(shared: S, params?: P, options?: RunOptions): AsyncGenerator<StreamEvent<S>>;
+    /** @internal Core execution loop, bypasses beforeFlow/afterFlow hooks. */
+    _execute(shared: S, params: P, signal?: AbortSignal): Promise<void>;
+    private _runStep;
+    /** @internal Run a sub-flow, wrapping errors with context. */
+    _runSub(label: string, fn: () => Promise<void>): Promise<void>;
+    /** @internal Resolve NodeOptions into their stored defaults. */
+    _resolveOptions(options?: NodeOptions<S, P>): {
+        retries: NumberOrFn<S, P>;
+        delaySec: NumberOrFn<S, P>;
+        timeoutMs: NumberOrFn<S, P>;
+        label: string | undefined;
+    };
+    /** @internal Push a step and invalidate the anchor-map cache. */
+    protected _pushStep(step: Step<S, P>): void;
+}
+
+/**
+ * Fluent builder for composable flows.
+ *
+ * Steps execute sequentially in the order added. Call `.run(shared)` to execute.
+ *
+ * **Shared-state safety**: all steps operate on the same shared object.
+ * Mutate it directly; avoid spreading/replacing the entire object.
+ *
+ * Built on top of {@link CoreFlowBuilder} which exposes the raw engine for
+ * advanced use cases (custom step types, zero-assumption base class, etc.).
+ */
+declare class FlowBuilder<S = any, P extends Record<string, unknown> = Record<string, unknown>> extends CoreFlowBuilder<S, P> {
+    /**
+     * Register a plugin — copies its methods onto `FlowBuilder.prototype`.
+     *
+     * Plugins should also call `FlowBuilder.use()` (not just `CoreFlowBuilder.use()`)
+     * so TypeScript module-augmentation on `interface FlowBuilder` resolves
+     * correctly and the method appears on `FlowBuilder` instances specifically.
+     */
+    static use(plugin: FlowneerPlugin): void;
+    /** Set the first step, resetting any prior chain. */
+    startWith(fn: NodeFn<S, P>, options?: NodeOptions<S, P>): this;
+    /** Append a sequential step. */
+    then(fn: NodeFn<S, P>, options?: NodeOptions<S, P>): this;
+    /**
+     * Splice all steps from a `Fragment` into this flow at the current position.
+     *
+     * Fragments are reusable partial flows created with the `fragment()` factory.
+     *
+     * @example
+     * ```ts
+     * const enrich = fragment<S>().then(fetchUser).then(enrichProfile);
+     *
+     * new FlowBuilder<S>().then(init).add(enrich).then(finalize).run(shared);
+     * ```
+     */
+    add(frag: FlowBuilder<S, P>): this;
+    /**
+     * Append a routing step.
+     * `router` returns a key; the matching branch executes, then the chain continues.
+     */
+    branch(router: NodeFn<S, P>, branches: Record<string, NodeFn<S, P>>, options?: NodeOptions<S, P>): this;
+    /**
+     * Append a looping step.
+     * Repeatedly runs `body` while `condition` returns true.
+     */
+    loop(condition: (shared: S, params: P) => Promise<boolean> | boolean, body: (b: FlowBuilder<S, P>) => void, options?: {
+        label?: string;
+    }): this;
+    /**
+     * Append a batch step.
+     * Runs `processor` once per item extracted by `items`, setting
+     * `shared[key]` each time (defaults to `"__batchItem"`).
+     *
+     * Use a unique `key` when nesting batches so each level has its own namespace.
+     */
+    batch(items: (shared: S, params: P) => Promise<any[]> | any[], processor: (b: FlowBuilder<S, P>) => void, options?: {
+        key?: string;
+        label?: string;
+    }): this;
+    /**
+     * Append a parallel step.
+     * Runs all `fns` concurrently against the same shared state.
+     *
+     * When `reducer` is provided each fn receives its own shallow clone of
+     * `shared`; after all fns complete the reducer merges the drafts back
+     * into the original shared object — preventing concurrent mutation races.
+     */
+    parallel(fns: NodeFn<S, P>[], options?: NodeOptions<S, P>, reducer?: (shared: S, drafts: S[]) => void): this;
+    /**
+     * Insert a named anchor. Anchors are no-op markers that can be jumped to
+     * from any `NodeFn` by returning `"#anchorName"`.
+     *
+     * @param name - Anchor identifier, referenced as `"#name"` in goto returns.
+     * @param maxVisits - Optional cycle guard: throws after this many gotos to
+     *   this anchor per `run()`. Replaces the need for a separate `withCycles`
+     *   plugin call.
+     *
+     * @example
+     * ```ts
+     * flow
+     *   .anchor("refine", 5)   // allow up to 5 refinement iterations
+     *   .then(generateDraft)
+     *   .then(s => s.score < 0.9 ? "#refine" : undefined)
+     *   .then(publish);
+     * ```
+     */
+    anchor(name: string, maxVisits?: number): this;
+    private _addFn;
+}
+
+export { type AnchorStep as A, type BatchStep as B, CoreFlowBuilder as C, FlowBuilder as F, type InstancePlugin as I, type LoopStep as L, type NodeFn as N, type ParallelStep as P, type ResolvedHooks as R, type StepFilter as S, type Validator as V, type FlowneerPlugin as a, type NodeOptions as b, type FlowHooks as c, type StepMeta as d, type BranchStep as e, type FnStep as f, type NumberOrFn as g, type RunOptions as h, type Step as i, type StepContext as j, type StepHandler as k, type StreamEvent as l };

package/dist/errors-u-hq7p5N.d.ts

@@ -0,0 +1,16 @@
+/** Wraps step failures with context about which step failed. */
+declare class FlowError extends Error {
+    readonly step: string;
+    readonly cause: unknown;
+    constructor(step: string, cause: unknown);
+}
+/**
+ * Thrown by `interruptIf` to pause a flow.
+ * Catch this in your runner to save `savedShared` and resume later.
+ */
+declare class InterruptError extends Error {
+    readonly savedShared: unknown;
+    constructor(shared: unknown);
+}
+
+export { FlowError as F, InterruptError as I };

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export { F as FlowBuilder, c as FlowHooks, a as FlowneerPlugin, N as NodeFn, b as NodeOptions, f as NumberOrFn, R as RunOptions, S as StepMeta, h as StreamEvent, V as Validator } from './FlowBuilder-C3B91Fzo.js';
-export { FlowError, Fragment, InterruptError, fragment } from './src/index.js';
+export { F as FlowBuilder, c as FlowHooks, a as FlowneerPlugin, N as NodeFn, b as NodeOptions, g as NumberOrFn, h as RunOptions, d as StepMeta, l as StreamEvent, V as Validator } from './FlowBuilder-B0SMJ4um.js';
+export { Fragment, fragment } from './src/index.js';
+export { F as FlowError, I as InterruptError } from './errors-u-hq7p5N.js';