flowneer 0.1.0

package/dist/plugins/observability/index.js

@@ -0,0 +1,56 @@
+// plugins/observability/withTiming.ts
+var withTiming = {
+  withTiming() {
+    const starts = /* @__PURE__ */ new Map();
+    this._setHooks({
+      beforeStep: (meta) => {
+        starts.set(meta.index, Date.now());
+      },
+      afterStep: (meta, shared) => {
+        const start = starts.get(meta.index) ?? Date.now();
+        if (!shared.__timings) shared.__timings = {};
+        shared.__timings[meta.index] = Date.now() - start;
+        starts.delete(meta.index);
+      }
+    });
+    return this;
+  }
+};
+
+// plugins/observability/withHistory.ts
+var withHistory = {
+  withHistory() {
+    this._setHooks({
+      afterStep: (meta, shared) => {
+        if (!Array.isArray(shared.__history)) shared.__history = [];
+        const { __history: _h, ...rest } = shared;
+        shared.__history.push({
+          index: meta.index,
+          type: meta.type,
+          snapshot: { ...rest }
+        });
+      }
+    });
+    return this;
+  }
+};
+
+// plugins/observability/withVerbose.ts
+var withVerbose = {
+  withVerbose() {
+    this._setHooks({
+      afterStep: (meta, shared) => {
+        console.log(
+          `[flowneer] step ${meta.index} (${meta.type}):`,
+          JSON.stringify(shared, null, 2)
+        );
+      }
+    });
+    return this;
+  }
+};
+export {
+  withHistory,
+  withTiming,
+  withVerbose
+};

package/dist/plugins/persistence/index.d.ts

@@ -0,0 +1,51 @@
+import { FlowneerPlugin } from '../../index.js';
+
+interface CheckpointStore<S = any> {
+    /** Called after each successful step with the step index and current shared state. */
+    save: (stepIndex: number, shared: S) => void | Promise<void>;
+}
+declare module "../../Flowneer" {
+    interface FlowBuilder<S, P> {
+        /** Saves `shared` to `store` after each successful step. */
+        withCheckpoint(store: CheckpointStore<S>): this;
+    }
+}
+declare const withCheckpoint: FlowneerPlugin;
+
+interface AuditEntry<S = any> {
+    stepIndex: number;
+    type: string;
+    timestamp: number;
+    /** Deep clone of `shared` at the time of the event. */
+    shared: S;
+    /** Error message, present only on failed steps. */
+    error?: string;
+}
+interface AuditLogStore<S = any> {
+    append: (entry: AuditEntry<S>) => void | Promise<void>;
+}
+declare module "../../Flowneer" {
+    interface FlowBuilder<S, P> {
+        /**
+         * Writes an immutable audit entry to `store` after each step (success and error).
+         * The `shared` snapshot in each entry is a deep clone via `JSON.parse/stringify`.
+         */
+        withAuditLog(store: AuditLogStore<S>): this;
+    }
+}
+declare const withAuditLog: FlowneerPlugin;
+
+declare module "../../Flowneer" {
+    interface FlowBuilder<S, P> {
+        /**
+         * Skips execution of all steps before `fromStep`.
+         * Combine with `.withCheckpoint()`: restore `shared` from the checkpoint
+         * store before calling `.run()`, then call `.withReplay(lastSavedIndex + 1)`
+         * so only future steps execute.
+         */
+        withReplay(fromStep: number): this;
+    }
+}
+declare const withReplay: FlowneerPlugin;
+
+export { type AuditEntry, type AuditLogStore, type CheckpointStore, withAuditLog, withCheckpoint, withReplay };

package/dist/plugins/persistence/index.js

@@ -0,0 +1,56 @@
+// plugins/persistence/withCheckpoint.ts
+var withCheckpoint = {
+  withCheckpoint(store) {
+    this._setHooks({
+      afterStep: async (meta, shared) => {
+        await store.save(meta.index, shared);
+      }
+    });
+    return this;
+  }
+};
+
+// plugins/persistence/withAuditLog.ts
+var withAuditLog = {
+  withAuditLog(store) {
+    const clone = (v) => JSON.parse(JSON.stringify(v));
+    this._setHooks({
+      afterStep: async (meta, shared) => {
+        await store.append({
+          stepIndex: meta.index,
+          type: meta.type,
+          timestamp: Date.now(),
+          shared: clone(shared)
+        });
+      },
+      onError: (meta, err, shared) => {
+        store.append({
+          stepIndex: meta.index,
+          type: meta.type,
+          timestamp: Date.now(),
+          shared: clone(shared),
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    });
+    return this;
+  }
+};
+
+// plugins/persistence/withReplay.ts
+var withReplay = {
+  withReplay(fromStep) {
+    this._setHooks({
+      wrapStep: async (meta, next) => {
+        if (meta.index < fromStep) return;
+        await next();
+      }
+    });
+    return this;
+  }
+};
+export {
+  withAuditLog,
+  withCheckpoint,
+  withReplay
+};

package/dist/plugins/resilience/index.d.ts

@@ -0,0 +1,46 @@
+import { FlowneerPlugin } from '../../index.js';
+
+declare module "../../Flowneer" {
+    interface FlowBuilder<S, P> {
+        /**
+         * Catches any step error and calls `fn` instead of propagating.
+         * The flow continues normally after the fallback runs.
+         */
+        withFallback(fn: NodeFn<S, P>): this;
+    }
+}
+declare const withFallback: FlowneerPlugin;
+
+interface CircuitBreakerOptions {
+    /** Number of consecutive failures that open the circuit. Default: 3 */
+    maxFailures?: number;
+    /**
+     * Milliseconds after which the circuit resets and allows one probe attempt.
+     * Default: 30 000
+     */
+    resetMs?: number;
+}
+declare module "../../Flowneer" {
+    interface FlowBuilder<S, P> {
+        /**
+         * Trips an open-circuit after `maxFailures` consecutive failures.
+         * While open, every step throws immediately without executing.
+         * Resets after `resetMs` milliseconds.
+         */
+        withCircuitBreaker(opts?: CircuitBreakerOptions): this;
+    }
+}
+declare const withCircuitBreaker: FlowneerPlugin;
+
+declare module "../../Flowneer" {
+    interface FlowBuilder<S, P> {
+        /**
+         * Applies a per-step wall-clock timeout to every step.
+         * Throws `"step N timed out after Xms"` if any step exceeds the limit.
+         */
+        withTimeout(ms: number): this;
+    }
+}
+declare const withTimeout: FlowneerPlugin;
+
+export { type CircuitBreakerOptions, withCircuitBreaker, withFallback, withTimeout };

package/dist/plugins/resilience/index.js

@@ -0,0 +1,71 @@
+// plugins/resilience/withFallback.ts
+var withFallback = {
+  withFallback(fn) {
+    this._setHooks({
+      wrapStep: async (_meta, next, shared, params) => {
+        try {
+          await next();
+        } catch {
+          await fn(shared, params);
+        }
+      }
+    });
+    return this;
+  }
+};
+
+// plugins/resilience/withCircuitBreaker.ts
+var withCircuitBreaker = {
+  withCircuitBreaker(opts = {}) {
+    const { maxFailures = 3, resetMs = 3e4 } = opts;
+    let consecutiveFailures = 0;
+    let openedAt = null;
+    this._setHooks({
+      beforeStep: () => {
+        if (openedAt !== null) {
+          if (Date.now() - openedAt >= resetMs) {
+            consecutiveFailures = 0;
+            openedAt = null;
+          } else {
+            throw new Error(
+              `circuit open after ${consecutiveFailures} consecutive failures`
+            );
+          }
+        }
+      },
+      afterStep: () => {
+        consecutiveFailures = 0;
+      },
+      onError: () => {
+        consecutiveFailures += 1;
+        if (consecutiveFailures >= maxFailures) {
+          openedAt = Date.now();
+        }
+      }
+    });
+    return this;
+  }
+};
+
+// plugins/resilience/withTimeout.ts
+var withTimeout = {
+  withTimeout(ms) {
+    this._setHooks({
+      wrapStep: (meta, next) => Promise.race([
+        next(),
+        new Promise(
+          (_, reject) => setTimeout(
+            () => reject(new Error(`step ${meta.index} timed out after ${ms}ms`)),
+            ms
+          )
+        )
+      ])
+    });
+    return this;
+  }
+};
+export {
+  withCircuitBreaker,
+  withFallback,
+  withTimeout
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "flowneer",
+  "version": "0.1.0",
+  "description": "Zero-dependency fluent flow builder for AI agents",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./plugins": "./dist/plugins/index.js",
+    "./plugins/observability": "./dist/plugins/observability/index.js",
+    "./plugins/resilience": "./dist/plugins/resilience/index.js",
+    "./plugins/persistence": "./dist/plugins/persistence/index.js",
+    "./plugins/llm": "./dist/plugins/llm/index.js",
+    "./plugins/dev": "./dist/plugins/dev/index.js"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "flow",
+    "agent",
+    "llm",
+    "pipeline",
+    "fluent",
+    "builder"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "bun test && bun run build"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "dotenv": "17.3.1",
+    "openai": "6.22.0",
+    "tsup": "^8.5.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}