flowneer 0.6.0 → 0.7.0

package/README.md

@@ -263,6 +263,61 @@ await new FlowBuilder<RefineState>()
 
 > **Tip:** Pair with [`withCycles`](#withcycles) to cap the maximum number of jumps.
 
+### `fragment()` and `.add(fragment)`
+
+Fragments are reusable partial flows — composable step chains that can be spliced into any `FlowBuilder`. Think of them like Zod partials for flows.
+
+Create a fragment with the `fragment()` factory, chain steps on it, then embed it with `.add()`:
+
+```typescript
+import { FlowBuilder, fragment } from "flowneer";
+
+interface State {
+  input: string;
+  enriched: boolean;
+  summary: string;
+}
+
+// Define reusable fragments
+const enrich = fragment<State>()
+  .then(async (s) => {
+    s.enriched = true;
+  })
+  .then(async (s) => {
+    s.input = s.input.trim();
+  });
+
+const summarise = fragment<State>().loop(
+  (s) => !s.summary,
+  (b) =>
+    b.then(async (s) => {
+      s.summary = s.input.slice(0, 10);
+    }),
+);
+
+// Compose into a full flow
+await new FlowBuilder<State>()
+  .startWith(async (s) => {
+    s.input = "  hello world  ";
+  })
+  .add(enrich) // splices enrich's steps inline
+  .add(summarise) // splices summarise's steps inline
+  .then(async (s) => console.log(s.summary))
+  .run({ input: "", enriched: false, summary: "" });
+// → hello worl
+```
+
+Fragments support all step types — `.then()`, `.loop()`, `.batch()`, `.branch()`, `.parallel()`, `.anchor()`. They **cannot** be run directly — calling `.run()` or `.stream()` on a fragment throws.
+
+The same fragment can be reused across multiple flows:
+
+```typescript
+const validate = fragment<State>().then(checkInput).then(sanitize);
+
+const flowA = new FlowBuilder<State>().add(validate).then(handleA);
+const flowB = new FlowBuilder<State>().add(validate).then(handleB);
+```
+
 ## using with `withCycles` plugin
 
 `withCycles` guards against infinite anchor-jump loops. Each call registers one limit; multiple calls stack.

package/dist/{FlowBuilder-Dqppgla9.d.ts → FlowBuilder-C3B91Fzo.d.ts}

@@ -147,13 +147,12 @@ type Step<S, P extends Record<string, unknown>> = FnStep<S, P> | BranchStep<S, P
 declare class FlowBuilder<S = any, P extends Record<string, unknown> = Record<string, unknown>> {
     protected steps: Step<S, P>[];
     private _hooksList;
-    /** Cached flat arrays of present hooks — invalidated whenever a hook is added. */
-    private _cachedHooks;
-    private _getHooks;
-    /** Register a plugin — copies its methods onto `FlowBuilder.prototype`. */
-    static use(plugin: FlowneerPlugin): void;
+    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`. */
+    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. */
@@ -180,7 +179,7 @@ declare class FlowBuilder<S = any, P extends Record<string, unknown> = Record<st
     add(frag: FlowBuilder<S, P>): this;
     /**
      * Append a routing step.
-     * `router` returns a key; the matching branch flow executes, then the chain continues.
+     * `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;
     /**
@@ -236,12 +235,19 @@ declare class FlowBuilder<S = any, P extends Record<string, unknown> = Record<st
      */
     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.
+     */
+    private _dispatchStep;
+    private _runParallel;
     private _addFn;
-    /** Resolve a NumberOrFn value against the current shared state and params. */
-    private _res;
     private _runSub;
-    private _retry;
-    private _withTimeout;
 }
 
-export { FlowBuilder as F, type NodeFn as N, type RunOptions as R, type StepMeta as S, type Validator as V, type NodeOptions as a, type FlowneerPlugin as b, type FlowHooks as c, type NumberOrFn as d, type StreamEvent as e };
+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 };

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { F as FlowBuilder, c as FlowHooks, b as FlowneerPlugin, N as NodeFn, a as NodeOptions, d as NumberOrFn, R as RunOptions, S as StepMeta, e as StreamEvent, V as Validator } from './FlowBuilder-Dqppgla9.js';
+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';

package/dist/index.js

@@ -21,42 +21,93 @@ var InterruptError = class extends Error {
 };
 
 // src/FlowBuilder.ts
+function buildHookCache(list) {
+  const pick = (key) => list.map((h) => h[key]).filter(Boolean);
+  return {
+    beforeFlow: pick("beforeFlow"),
+    beforeStep: pick("beforeStep"),
+    wrapStep: pick("wrapStep"),
+    afterStep: pick("afterStep"),
+    wrapParallelFn: pick("wrapParallelFn"),
+    onError: pick("onError"),
+    afterFlow: pick("afterFlow")
+  };
+}
+function resolveNumber(val, fallback, shared, params) {
+  if (val === void 0) return fallback;
+  return typeof val === "function" ? val(shared, params) : val;
+}
+async function retry(times, delaySec, fn) {
+  if (times === 1) return fn();
+  while (true) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (!--times) throw err;
+      if (delaySec > 0)
+        await new Promise((r) => setTimeout(r, delaySec * 1e3));
+    }
+  }
+}
+function withTimeout(ms, fn) {
+  let timer;
+  return Promise.race([
+    fn().finally(() => clearTimeout(timer)),
+    new Promise((_, reject) => {
+      timer = setTimeout(
+        () => reject(new Error(`step timed out after ${ms}ms`)),
+        ms
+      );
+    })
+  ]);
+}
+function isAnchorTarget(value) {
+  return typeof value === "string" && value[0] === "#";
+}
+async function runFnResult(result, shared) {
+  if (result != null && typeof result[Symbol.asyncIterator] === "function") {
+    const gen = result;
+    let next = await gen.next();
+    while (!next.done) {
+      shared.__stream?.(next.value);
+      next = await gen.next();
+    }
+    return isAnchorTarget(next.value) ? next.value.slice(1) : void 0;
+  }
+  return isAnchorTarget(result) ? result.slice(1) : void 0;
+}
+function buildAnchorMap(steps) {
+  const map = /* @__PURE__ */ new Map();
+  for (let i = 0; i < steps.length; i++) {
+    const s = steps[i];
+    if (s.type === "anchor") map.set(s.name, i);
+  }
+  return map;
+}
 var FlowBuilder = class _FlowBuilder {
   steps = [];
   _hooksList = [];
-  /** Cached flat arrays of present hooks — invalidated whenever a hook is added. */
-  _cachedHooks = null;
-  _getHooks() {
-    if (this._cachedHooks) return this._cachedHooks;
-    const hl = this._hooksList;
-    this._cachedHooks = {
-      beforeFlow: hl.map((h) => h.beforeFlow).filter(Boolean),
-      beforeStep: hl.map((h) => h.beforeStep).filter(Boolean),
-      wrapStep: hl.map((h) => h.wrapStep).filter(Boolean),
-      afterStep: hl.map((h) => h.afterStep).filter(Boolean),
-      wrapParallelFn: hl.map((h) => h.wrapParallelFn).filter(Boolean),
-      onError: hl.map((h) => h.onError).filter(Boolean),
-      afterFlow: hl.map((h) => h.afterFlow).filter(Boolean)
-    };
-    return this._cachedHooks;
+  _hooksCache = null;
+  // -------------------------------------------------------------------------
+  // Hooks & plugins
+  // -------------------------------------------------------------------------
+  _hooks() {
+    return this._hooksCache ??= buildHookCache(this._hooksList);
+  }
+  /** Register lifecycle hooks (called by plugin methods, not by consumers). */
+  _setHooks(hooks) {
+    this._hooksList.push(hooks);
+    this._hooksCache = null;
   }
-  // -----------------------------------------------------------------------
-  // Plugin registration
-  // -----------------------------------------------------------------------
   /** Register a plugin — copies its methods onto `FlowBuilder.prototype`. */
   static use(plugin) {
     for (const [name, fn] of Object.entries(plugin)) {
       _FlowBuilder.prototype[name] = fn;
     }
   }
-  /** Register lifecycle hooks (called by plugin methods, not by consumers). */
-  _setHooks(hooks) {
-    this._hooksList.push(hooks);
-    this._cachedHooks = null;
-  }
-  // -----------------------------------------------------------------------
-  // Public API
-  // -----------------------------------------------------------------------
+  // -------------------------------------------------------------------------
+  // Builder API
+  // -------------------------------------------------------------------------
   /** Set the first step, resetting any prior chain. */
   startWith(fn, options) {
     this.steps = [];
@@ -91,7 +142,7 @@ var FlowBuilder = class _FlowBuilder {
   }
   /**
    * Append a routing step.
-   * `router` returns a key; the matching branch flow executes, then the chain continues.
+   * `router` returns a key; the matching branch executes, then the chain continues.
    */
   branch(router, branches, options) {
     this.steps.push({
@@ -133,12 +184,11 @@ var FlowBuilder = class _FlowBuilder {
   batch(items, processor, options) {
     const inner = new _FlowBuilder();
     processor(inner);
-    const key = options?.key ?? "__batchItem";
     this.steps.push({
       type: "batch",
       itemsExtractor: items,
       processor: inner,
-      key
+      key: options?.key ?? "__batchItem"
     });
     return this;
   }
@@ -169,10 +219,13 @@ var FlowBuilder = class _FlowBuilder {
     this.steps.push({ type: "anchor", name });
     return this;
   }
+  // -------------------------------------------------------------------------
+  // Execution API
+  // -------------------------------------------------------------------------
   /** Execute the flow. */
   async run(shared, params, options) {
     const p = params ?? {};
-    const hooks = this._getHooks();
+    const hooks = this._hooks();
     for (const h of hooks.beforeFlow) await h(shared, p);
     try {
       await this._execute(shared, p, options?.signal);
@@ -193,24 +246,18 @@ var FlowBuilder = class _FlowBuilder {
    */
   async *stream(shared, params, options) {
     const queue = [];
-    let resolve = null;
+    let notify = null;
     const push = (event) => {
       queue.push(event);
-      if (resolve) {
-        resolve();
-        resolve = null;
-      }
+      notify?.();
+      notify = null;
     };
-    const pull = () => queue.length > 0 ? Promise.resolve() : new Promise((r) => {
-      resolve = r;
+    const drain = () => queue.length > 0 ? Promise.resolve() : new Promise((r) => {
+      notify = r;
     });
     this._setHooks({
-      beforeStep: (meta) => {
-        push({ type: "step:before", meta });
-      },
-      afterStep: (meta, s) => {
-        push({ type: "step:after", meta, shared: s });
-      }
+      beforeStep: (meta) => push({ type: "step:before", meta }),
+      afterStep: (meta, s) => push({ type: "step:after", meta, shared: s })
     });
     const prevStream = shared.__stream;
     shared.__stream = (chunk) => {
@@ -219,7 +266,7 @@ var FlowBuilder = class _FlowBuilder {
     };
     this.run(shared, params, options).catch((err) => push({ type: "error", error: err })).then(() => push(null));
     while (true) {
-      await pull();
+      await drain();
       while (queue.length > 0) {
         const event = queue.shift();
         if (event === null) {
@@ -230,18 +277,13 @@ var FlowBuilder = class _FlowBuilder {
       }
     }
   }
-  // -----------------------------------------------------------------------
-  // Internal execution
-  // -----------------------------------------------------------------------
+  // -------------------------------------------------------------------------
+  // Internal execution engine
+  // -------------------------------------------------------------------------
   async _execute(shared, params, signal) {
-    const hooks = this._getHooks();
-    const labels = /* @__PURE__ */ new Map();
-    if (this.steps.some((s) => s.type === "anchor")) {
-      for (let j = 0; j < this.steps.length; j++) {
-        const s = this.steps[j];
-        if (s.type === "anchor") labels.set(s.name, j);
-      }
-    }
+    const hooks = this._hooks();
+    const hasAnchors = this.steps.some((s) => s.type === "anchor");
+    const labels = hasAnchors ? buildAnchorMap(this.steps) : /* @__PURE__ */ new Map();
     for (let i = 0; i < this.steps.length; i++) {
       signal?.throwIfAborted();
       const step = this.steps[i];
@@ -249,123 +291,16 @@ var FlowBuilder = class _FlowBuilder {
       const meta = { index: i, type: step.type };
       try {
         for (const h of hooks.beforeStep) await h(meta, shared, params);
-        let gotoTarget;
-        const runBody = async () => {
-          switch (step.type) {
-            case "fn": {
-              const result = await this._retry(
-                this._res(step.retries, 1, shared, params),
-                this._res(step.delaySec, 0, shared, params),
-                () => step.fn(shared, params)
-              );
-              if (result != null && typeof result[Symbol.asyncIterator] === "function") {
-                const gen = result;
-                let genResult = await gen.next();
-                while (!genResult.done) {
-                  shared.__stream?.(genResult.value);
-                  genResult = await gen.next();
-                }
-                if (typeof genResult.value === "string" && genResult.value[0] === "#")
-                  gotoTarget = genResult.value.slice(1);
-              } else if (typeof result === "string" && result[0] === "#") {
-                gotoTarget = result.slice(1);
-              }
-              break;
-            }
-            case "branch": {
-              const bRetries = this._res(step.retries, 1, shared, params);
-              const bDelay = this._res(step.delaySec, 0, shared, params);
-              const action = await this._retry(
-                bRetries,
-                bDelay,
-                () => step.router(shared, params)
-              );
-              const key = action ? String(action) : "default";
-              const fn = step.branches[key] ?? step.branches["default"];
-              if (fn) {
-                const branchResult = await this._retry(
-                  bRetries,
-                  bDelay,
-                  () => fn(shared, params)
-                );
-                if (typeof branchResult === "string" && branchResult[0] === "#")
-                  gotoTarget = branchResult.slice(1);
-              }
-              break;
-            }
-            case "loop":
-              while (await step.condition(shared, params))
-                await this._runSub(
-                  `loop (step ${i})`,
-                  () => step.body._execute(shared, params, signal)
-                );
-              break;
-            case "batch": {
-              const k = step.key;
-              const prev = shared[k];
-              const hadKey = Object.prototype.hasOwnProperty.call(shared, k);
-              const list = await step.itemsExtractor(shared, params);
-              for (const item of list) {
-                shared[k] = item;
-                await this._runSub(
-                  `batch (step ${i})`,
-                  () => step.processor._execute(shared, params, signal)
-                );
-              }
-              if (!hadKey) delete shared[k];
-              else shared[k] = prev;
-              break;
-            }
-            case "parallel": {
-              const pfnWrappers = hooks.wrapParallelFn;
-              const pRetries = this._res(step.retries, 1, shared, params);
-              const pDelay = this._res(step.delaySec, 0, shared, params);
-              if (step.reducer) {
-                const drafts = [];
-                await Promise.all(
-                  step.fns.map(async (fn, fi) => {
-                    const draft = { ...shared };
-                    drafts[fi] = draft;
-                    const exec = () => this._retry(pRetries, pDelay, () => fn(draft, params));
-                    const wrapped2 = pfnWrappers.reduceRight(
-                      (next, wrap) => () => wrap(meta, fi, next, draft, params),
-                      async () => {
-                        await exec();
-                      }
-                    );
-                    await wrapped2();
-                  })
-                );
-                step.reducer(shared, drafts);
-              } else {
-                await Promise.all(
-                  step.fns.map((fn, fi) => {
-                    const exec = () => this._retry(pRetries, pDelay, () => fn(shared, params));
-                    const wrapped2 = pfnWrappers.reduceRight(
-                      (next, wrap) => () => wrap(meta, fi, next, shared, params),
-                      async () => {
-                        await exec();
-                      }
-                    );
-                    return wrapped2();
-                  })
-                );
-              }
-              break;
-            }
-          }
-        };
-        const rawTimeout = step.timeoutMs;
-        const resolvedTimeout = this._res(rawTimeout, 0, shared, params);
-        const baseExec = () => resolvedTimeout > 0 ? this._withTimeout(resolvedTimeout, runBody) : runBody();
-        const wrappers = hooks.wrapStep;
-        const wrapped = wrappers.reduceRight(
-          (next, wrap) => () => wrap(meta, next, shared, params),
-          baseExec
+        const gotoTarget = await this._runStep(
+          step,
+          meta,
+          shared,
+          params,
+          signal,
+          hooks
         );
-        await wrapped();
         for (const h of hooks.afterStep) await h(meta, shared, params);
-        if (gotoTarget) {
+        if (gotoTarget !== void 0) {
           const target = labels.get(gotoTarget);
           if (target === void 0)
             throw new Error(`goto target anchor "${gotoTarget}" not found`);
@@ -375,11 +310,121 @@ var FlowBuilder = class _FlowBuilder {
         if (err instanceof InterruptError) throw err;
         for (const h of hooks.onError) h(meta, err, shared, params);
         if (err instanceof FlowError) throw err;
-        const stepLabel = step.type === "fn" ? `step ${i}` : `${step.type} (step ${i})`;
-        throw new FlowError(stepLabel, err);
+        const label = step.type === "fn" ? `step ${i}` : `${step.type} (step ${i})`;
+        throw new FlowError(label, err);
+      }
+    }
+  }
+  /**
+   * 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`.
+   */
+  async _runStep(step, meta, shared, params, signal, hooks) {
+    let gotoTarget;
+    const execute = async () => {
+      gotoTarget = await this._dispatchStep(
+        step,
+        meta,
+        shared,
+        params,
+        signal,
+        hooks
+      );
+    };
+    const timeoutMs = resolveNumber(
+      step.timeoutMs,
+      0,
+      shared,
+      params
+    );
+    const baseExec = timeoutMs > 0 ? () => withTimeout(timeoutMs, execute) : execute;
+    const wrapped = hooks.wrapStep.reduceRight(
+      (next, wrap) => () => wrap(meta, next, shared, params),
+      baseExec
+    );
+    await wrapped();
+    return gotoTarget;
+  }
+  /**
+   * Pure step dispatch — no timeout, no `wrapStep`. Returns goto target if any.
+   */
+  async _dispatchStep(step, meta, shared, params, signal, hooks) {
+    switch (step.type) {
+      case "fn": {
+        const result = await retry(
+          resolveNumber(step.retries, 1, shared, params),
+          resolveNumber(step.delaySec, 0, shared, params),
+          () => step.fn(shared, params)
+        );
+        return runFnResult(result, shared);
+      }
+      case "branch": {
+        const r = resolveNumber(step.retries, 1, shared, params);
+        const d = resolveNumber(step.delaySec, 0, shared, params);
+        const action = await retry(r, d, () => step.router(shared, params));
+        const key = action ? String(action) : "default";
+        const fn = step.branches[key] ?? step.branches["default"];
+        if (fn) {
+          const result = await retry(r, d, () => fn(shared, params));
+          if (isAnchorTarget(result)) return result.slice(1);
+        }
+        return void 0;
+      }
+      case "loop": {
+        while (await step.condition(shared, params))
+          await this._runSub(
+            `loop (step ${meta.index})`,
+            () => step.body._execute(shared, params, signal)
+          );
+        return void 0;
+      }
+      case "batch": {
+        const { key, itemsExtractor, processor } = step;
+        const prev = shared[key];
+        const hadKey = Object.prototype.hasOwnProperty.call(shared, key);
+        const list = await itemsExtractor(shared, params);
+        for (const item of list) {
+          shared[key] = item;
+          await this._runSub(
+            `batch (step ${meta.index})`,
+            () => processor._execute(shared, params, signal)
+          );
+        }
+        if (!hadKey) delete shared[key];
+        else shared[key] = prev;
+        return void 0;
+      }
+      case "parallel": {
+        await this._runParallel(step, meta, shared, params, hooks);
+        return void 0;
       }
     }
   }
+  async _runParallel(step, meta, shared, params, hooks) {
+    const r = resolveNumber(step.retries, 1, shared, params);
+    const d = resolveNumber(step.delaySec, 0, shared, params);
+    const wrappers = hooks.wrapParallelFn;
+    const runFn = (fn, s, fi) => {
+      const exec = async () => {
+        await retry(r, d, () => fn(s, params));
+      };
+      return wrappers.reduceRight(
+        (next, wrap) => () => wrap(meta, fi, next, s, params),
+        exec
+      )();
+    };
+    if (step.reducer) {
+      const drafts = step.fns.map(() => ({ ...shared }));
+      await Promise.all(step.fns.map((fn, fi) => runFn(fn, drafts[fi], fi)));
+      step.reducer(shared, drafts);
+    } else {
+      await Promise.all(step.fns.map((fn, fi) => runFn(fn, shared, fi)));
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Private helpers
+  // -------------------------------------------------------------------------
   _addFn(fn, options) {
     this.steps.push({
       type: "fn",
@@ -390,11 +435,6 @@ var FlowBuilder = class _FlowBuilder {
     });
     return this;
   }
-  /** Resolve a NumberOrFn value against the current shared state and params. */
-  _res(val, def, shared, params) {
-    if (val === void 0) return def;
-    return typeof val === "function" ? val(shared, params) : val;
-  }
   async _runSub(label, fn) {
     try {
       return await fn();
@@ -402,30 +442,6 @@ var FlowBuilder = class _FlowBuilder {
       throw new FlowError(label, err instanceof FlowError ? err.cause : err);
     }
   }
-  async _retry(times, delaySec, fn) {
-    if (times === 1) return fn();
-    while (true) {
-      try {
-        return await fn();
-      } catch (err) {
-        if (!--times) throw err;
-        if (delaySec > 0)
-          await new Promise((r) => setTimeout(r, delaySec * 1e3));
-      }
-    }
-  }
-  _withTimeout(ms, fn) {
-    let timer;
-    return Promise.race([
-      fn().finally(() => clearTimeout(timer)),
-      new Promise((_, reject) => {
-        timer = setTimeout(
-          () => reject(new Error(`step timed out after ${ms}ms`)),
-          ms
-        );
-      })
-    ]);
-  }
 };
 
 // src/Fragment.ts
@@ -437,6 +453,8 @@ var Fragment = class extends FlowBuilder {
     );
   }
   /** @internal Fragments cannot be streamed — embed them via `.add()`. */
+  // v8 ignore next 5 — async generator has an implicit "resume after yield"
+  // branch that is unreachable here because we always throw before yielding.
   async *stream(_shared, _params) {
     throw new Error(
       "Fragment cannot be streamed directly \u2014 use .add() to embed it in a FlowBuilder"