lightflow-engine 0.2.6 → 0.2.8

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.js

@@ -12,18 +12,19 @@
  */
 import { Engine, registerWorkflow } from "../index.js";
 import { workflowIdFor } from "./workflow.js";
-let sharedEngine = null;
-let sharedStore = null;
+const g = globalThis;
+if (!g.__lightflowCompat)
+    g.__lightflowCompat = { engine: null, store: null };
 /** Configure the compat layer with a store/engine (call once at boot). */
 export function initWorkflowApi(store, engine) {
-    sharedStore = store;
-    sharedEngine = engine ?? new Engine(store);
+    g.__lightflowCompat.store = store;
+    g.__lightflowCompat.engine = engine ?? new Engine(store);
 }
 export function getEngine() {
-    if (!sharedEngine) {
+    if (!g.__lightflowCompat.engine) {
         throw new Error("workflow/api not initialized — call initWorkflowApi(store) at startup");
     }
-    return sharedEngine;
+    return g.__lightflowCompat.engine;
 }
 /**
  * Register a workflow function under a stable id and start it. Mirrors
@@ -31,7 +32,7 @@ export function getEngine() {
  */
 function makeRunHandle(runId) {
     const engine = getEngine();
-    const store = sharedStore;
+    const store = g.__lightflowCompat.store;
     /** One DB read -> Vercel status vocabulary. */
     const readStatus = async () => {
         const row = await store.getRun(runId);
@@ -65,6 +66,8 @@ function makeRunHandle(runId) {
         return loop();
     };
     const cache = {};
+    let lazyReturnValue;
+    let pendingRejection;
     const handle = {
         runId,
         exists: true,
@@ -76,10 +79,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/index.js

@@ -26,8 +26,13 @@ export class FatalError extends Error {
         this.name = "FatalError";
     }
 }
-const workflows = new Map();
-const steps = new Map();
+const reg = globalThis;
+if (!reg.__lightflowWorkflows)
+    reg.__lightflowWorkflows = new Map();
+if (!reg.__lightflowSteps)
+    reg.__lightflowSteps = new Map();
+const workflows = reg.__lightflowWorkflows;
+const steps = reg.__lightflowSteps;
 export function registerWorkflow(id, fn) {
     workflows.set(id, fn);
 }
@@ -229,6 +234,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,6 +1,6 @@
 {
   "name": "lightflow-engine",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "A tiny durable workflow engine for Node.js and Postgres — with a Vercel Workflow drop-in compat layer.",
   "license": "MIT",
   "type": "module",