flowneer 0.7.0 → 0.7.1

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-C3B91Fzo.d.ts → FlowBuilder-DJkzGH5l.d.ts}

@@ -53,6 +53,8 @@ interface NodeOptions<S = any, P extends Record<string, unknown> = Record<string
     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;
@@ -95,6 +97,31 @@ interface FlowHooks<S = any, P extends Record<string, unknown> = Record<string,
  * ```
  */
 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";
@@ -102,6 +129,7 @@ interface FnStep<S, P extends Record<string, unknown>> {
     retries: NumberOrFn<S, P>;
     delaySec: NumberOrFn<S, P>;
     timeoutMs: NumberOrFn<S, P>;
+    label?: string;
 }
 interface BranchStep<S, P extends Record<string, unknown>> {
     type: "branch";
@@ -110,17 +138,20 @@ interface BranchStep<S, P extends Record<string, unknown>> {
     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: FlowBuilder<S, P>;
+    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: FlowBuilder<S, P>;
+    processor: CoreFlowBuilder<S, P>;
     key: string;
+    label?: string;
 }
 interface ParallelStep<S, P extends Record<string, unknown>> {
     type: "parallel";
@@ -129,13 +160,119 @@ interface ParallelStep<S, P extends Record<string, unknown>> {
     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>>): () => 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>>): () => 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.
  *
@@ -143,15 +280,18 @@ type Step<S, P extends Record<string, unknown>> = FnStep<S, P> | BranchStep<S, P
  *
  * **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>> {
-    protected steps: Step<S, P>[];
-    private _hooksList;
-    private _hooksCache;
-    private _hooks;
-    /** Register lifecycle hooks (called by plugin methods, not by consumers). */
-    protected _setHooks(hooks: Partial<FlowHooks<S, P>>): void;
-    /** Register a plugin — copies its methods onto `FlowBuilder.prototype`. */
+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;
@@ -161,19 +301,12 @@ declare class FlowBuilder<S = any, P extends Record<string, unknown> = Record<st
      * Splice all steps from a `Fragment` into this flow at the current position.
      *
      * Fragments are reusable partial flows created with the `fragment()` factory.
-     * Steps are copied by reference (same semantics as `loop` / `batch` inners).
      *
      * @example
      * ```ts
-     * const enrich = fragment<S>()
-     *   .then(fetchUser)
-     *   .then(enrichProfile);
+     * const enrich = fragment<S>().then(fetchUser).then(enrichProfile);
      *
-     * new FlowBuilder<S>()
-     *   .then(init)
-     *   .add(enrich)
-     *   .then(finalize)
-     *   .run(shared);
+     * new FlowBuilder<S>().then(init).add(enrich).then(finalize).run(shared);
      * ```
      */
     add(frag: FlowBuilder<S, P>): this;
@@ -186,25 +319,19 @@ declare class FlowBuilder<S = any, P extends Record<string, unknown> = Record<st
      * 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): this;
+    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:
-     * ```ts
-     * .batch(s => s.users, b => b
-     *   .startWith(s => { console.log(s.__batch_user); })
-     *   .batch(s => s.__batch_user.posts, p => p
-     *     .startWith(s => { console.log(s.__batch_post); })
-     *   , { key: '__batch_post' })
-     * , { key: '__batch_user' })
-     * ```
+     * 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.
@@ -218,36 +345,23 @@ declare class FlowBuilder<S = any, P extends Record<string, unknown> = Record<st
     /**
      * Insert a named anchor. Anchors are no-op markers that can be jumped to
      * from any `NodeFn` by returning `"#anchorName"`.
-     */
-    anchor(name: string): this;
-    /** Execute the flow. */
-    run(shared: S, params?: P, options?: RunOptions): Promise<void>;
-    /**
-     * Execute the flow and yield `StreamEvent`s as an async generator.
      *
-     * Events include `step:before`, `step:after`, `chunk` (from `emit()`),
-     * `error`, and `done`. This is an additive API — `.run()` is unchanged.
+     * @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
-     * for await (const event of flow.stream(shared)) {
-     *   if (event.type === "chunk") process.stdout.write(event.data);
-     * }
-     */
-    stream(shared: S, params?: P, options?: RunOptions): AsyncGenerator<StreamEvent<S>>;
-    protected _execute(shared: S, params: P, signal?: AbortSignal): Promise<void>;
-    /**
-     * Apply timeout and `wrapStep` middleware around a single step, then
-     * delegate to `_dispatchStep`. Returns an anchor target if the step
-     * issued a goto, otherwise `undefined`.
-     */
-    private _runStep;
-    /**
-     * Pure step dispatch — no timeout, no `wrapStep`. Returns goto target if any.
+     * ```ts
+     * flow
+     *   .anchor("refine", 5)   // allow up to 5 refinement iterations
+     *   .then(generateDraft)
+     *   .then(s => s.score < 0.9 ? "#refine" : undefined)
+     *   .then(publish);
+     * ```
      */
-    private _dispatchStep;
-    private _runParallel;
+    anchor(name: string, maxVisits?: number): this;
     private _addFn;
-    private _runSub;
 }
 
-export { type AnchorStep as A, type BatchStep as B, FlowBuilder as F, type LoopStep as L, type NodeFn as N, type ParallelStep as P, type RunOptions as R, type StepMeta as S, type Validator as V, type FlowneerPlugin as a, type NodeOptions as b, type FlowHooks as c, type BranchStep as d, type FnStep as e, type NumberOrFn as f, type Step as g, type StreamEvent as h };
+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 StepMeta as S, type Validator as V, type FlowneerPlugin as a, type NodeOptions as b, type FlowHooks as c, type BranchStep as d, type FnStep as e, type NumberOrFn as f, type RunOptions as g, type Step as h, type StepContext as i, type StepHandler as j, type StreamEvent as k };

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-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 { F as FlowBuilder, c as FlowHooks, a as FlowneerPlugin, N as NodeFn, b as NodeOptions, f as NumberOrFn, g as RunOptions, S as StepMeta, k as StreamEvent, V as Validator } from './FlowBuilder-DJkzGH5l.js';
 export { FlowError, Fragment, InterruptError, fragment } from './src/index.js';