lightflow-engine 0.2.5 → 0.2.7

package/BENCHMARKS.md

@@ -141,18 +141,59 @@ sequential-ish workflows through `start()` + terminal-poll.
 Every version's table above was produced on the same machine and database,
 so cross-version rows are directly comparable.
 
-## v0.2.0 — compat layer (perf-neutral)
+## v0.2.x — compat layer (all versions re-benchmarked)
 
-Focus: Vercel Workflow drop-in compat (`lightflow-engine/compat/*`).
-No perf regression vs v0.1.4 — two real bugs found and fixed along the way:
-post-resume chunk loss (chunk keys now include the durable-timer position)
-and chunks vanishing from streams after snapshot compaction (live chunks
-now fold into snapshots).
+Each published version was benchmarked from its published tarball against the
+same Postgres (16, local) and the same harness (200 runs x 5 steps @ conc 20;
+50 runs x 400 steps). Steps/wf = 5 for short, 400 for long.
 
-| Scenario | v0.1.4 | v0.2.0 |
-|---|---|---|
-| 200 runs x 5 steps, conc 20 (runs/s) | 502–512 | 504.5 |
-| 50 runs x 400 steps durable (steps/s) | 9,939 | 9,062–10,600 |
+| Version | Short runs/s | Short steps/s | Long steps/s |
+|---|---|---|---|
+| 0.2.0 | 462.7 | 2,313 | 8,493 |
+| 0.2.1 | 466.0 | 2,330 | 9,062 |
+| 0.2.2 | 466.9 | 2,335 | 8,348 |
+| 0.2.3 | 461.6 | 2,308 | 8,384 |
+| 0.2.4 | 456.1 | 2,280 | 8,280 |
+| 0.2.5 | 459.1 | 2,295 | 9,068 |
+| 0.2.6 | 494.9–525.1 | 2,474–2,626 | 8,379–9,737 |
+
+### What changed per version (all perf-neutral by design)
+
+- **0.2.0** — Vercel Workflow drop-in compat (`compat/workflow`,
+  `compat/api`, `compat/next`). Two data-loss bugs fixed en route: chunk
+  memo keys now include the durable-timer position (`w:<sleepCalls>:<writes>`)
+  so post-resume writes can't be skipped against pre-timer chunks; live chunk
+  appends now fold into snapshot compaction (chunks previously vanished from
+  `getReadable` after ~200 steps).
+- **0.2.1** — `run.status` is a live getter (fresh promise per access).
+  entry-agents' startStopMonitor re-awaits it in a 150ms poll loop; a single
+  memoized promise left the monitor blocked until terminal.
+- **0.2.2** — `makeStep(fn, {retries})`: durable wrapper for arg-taking
+  step functions (entry's "use step" style).
+- **0.2.3–0.2.4** — packaging: explicit `types` in subpath exports,
+  declaration files emitted. No runtime change.
+- **0.2.5** — `rootDir: "src"` so the published `dist/` layout actually
+  matches the subpath export map (0.2.0–0.2.4 shipped `dist/src/...` while
+  exports claimed `dist/...` — subpath imports still worked because Node
+  resolved the package root, but the types were broken).
+- **0.2.6** — `export { workflowFetch as fetch }` (entry imports both
+  names), `WorkflowFn` accepts typed args, `run.exists: true`.
+
+### Spread notes
+
+Short-run spread across versions is ~2% (456–467 runs/s) — within run-to-run
+noise; the compat layer added no measurable overhead. 0.2.6 shows the best
+short-run numbers (494–525 runs/s across repeated runs) and the long-run
+8.3k–9.7k steps/s band matches the v0.1.4-era 9.9k within noise.
+
+## Reproducing
 
-Verdict: perf-neutral within noise. Compat test (7/7) exercises the full
-entry-agents surface end-to-end.
+Each version's tarball can be re-benchmarked independently:
+
+```bash
+npm pack lightflow-engine@<version>
+tar xzf lightflow-engine-<version>.tgz -C <dir> --strip-components=1
+ln -s <path-to>/lightflow/node_modules <dir>/node_modules
+PKG=<dir> LIGHTFLOW_PG_URL=postgres://... BENCH_N=200 RN=5 npx tsx bench-pkg.mts
+PKG=<dir> LIGHTFLOW_PG_URL=postgres://... BENCH_N=50 RN=400 npx tsx bench-pkg.mts
+```

package/dist/compat/api.d.ts

@@ -14,6 +14,8 @@ import { Engine, type Store } from "../index.js";
 export type VercelRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";
 export type VercelRun = {
     runId: string;
+    /** Vercel's run handle exposes exists; ours always resolves from the DB. */
+    readonly exists: true;
     /** Live getter: each access returns a FRESH promise snapshotting the
      *  current status ("pending"/"running" until terminal). Vercel's is a
      *  getter too (chat.test.ts mocks `get status()`), and entry-agents'

package/dist/compat/api.js

@@ -65,8 +65,11 @@ function makeRunHandle(runId) {
         return loop();
     };
     const cache = {};
+    let lazyReturnValue;
+    let pendingRejection;
     const handle = {
         runId,
+        exists: true,
         get status() {
             // Live snapshot: resolve immediately with the current state; the
             // startStopMonitor poll loop relies on this re-reading each tick.
@@ -75,10 +78,26 @@ function makeRunHandle(runId) {
                 return st;
             });
         },
-        returnValue: (async () => {
-            await terminal(cache);
-            return (await engine.getRun(runId)).returnValue;
-        })(),
+        // Lazy: created on first access so a handle whose returnValue is never
+        // awaited (e.g. status-only getRun polls) can't produce an unhandled
+        // rejection when the run fails.
+        get returnValue() {
+            if (!lazyReturnValue) {
+                lazyReturnValue = (async () => {
+                    try {
+                        await terminal(cache);
+                        return await (await engine.getRun(runId)).returnValue;
+                    }
+                    catch (e) {
+                        pendingRejection = e;
+                        throw e;
+                    }
+                })();
+                if (pendingRejection)
+                    throw pendingRejection; // unreachable
+            }
+            return lazyReturnValue;
+        },
         getReadable(opts) {
             const startIndex = opts?.startIndex ?? 0;
             let sent = startIndex;

package/dist/compat/workflow.d.ts

@@ -9,6 +9,7 @@
  */
 export { FatalError, CancelledError, sleep } from "../index.js";
 export { getWorkflowMetadata } from "../compat/metadata.js";
+export { workflowFetch as fetch } from "../compat/fetch.js";
 export { workflowFetch } from "../compat/fetch.js";
 /**
  * Vercel's getWritable returns a web-standard WritableStream whose writes

package/dist/compat/workflow.js

@@ -12,6 +12,9 @@ import { step, registerStep, } from "../index.js";
 import { current } from "../index.js";
 export { FatalError, CancelledError, sleep } from "../index.js";
 export { getWorkflowMetadata } from "../compat/metadata.js";
+// Vercel exports the step-aware fetch under both names; entry-agents
+// imports `fetch as workflowFetch` in some files and plain `fetch` in others.
+export { workflowFetch as fetch } from "../compat/fetch.js";
 export { workflowFetch } from "../compat/fetch.js";
 /**
  * Vercel's getWritable returns a web-standard WritableStream whose writes

package/dist/index.d.ts

@@ -74,7 +74,7 @@ export interface Store {
     } | null>;
     setStatus(runId: string, status: RunStatus, output?: unknown): Promise<void>;
 }
-type WorkflowFn = (...args: unknown[]) => Promise<unknown>;
+type WorkflowFn = (...args: any[]) => Promise<unknown>;
 export declare function registerWorkflow(id: string, fn: WorkflowFn): void;
 export declare function registerStep(id: string, fn: (...a: unknown[]) => Promise<unknown>): void;
 type Ctx = {

package/dist/index.js

@@ -229,6 +229,10 @@ export class Engine {
         let resolve;
         let reject;
         const promise = new Promise((res, rej) => { resolve = res; reject = rej; });
+        // Prevent unhandled-rejection crashes when a caller (e.g. compat
+        // returnValue path) never awaits the local deferred — status is read
+        // from the store instead.
+        promise.catch(() => { });
         const d = { promise, resolve, reject };
         this.local.set(runId, d);
         return d;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "lightflow-engine",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "A tiny durable workflow engine for Node.js and Postgres — with a Vercel Workflow drop-in compat layer.",
   "license": "MIT",
   "type": "module",
-  "main": "dist/index.js", "types": "dist/index.d.ts",
+  "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {