measure-fn 3.2.0 → 3.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 7flash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -162,6 +162,31 @@ await api.measure('GET /users', async () => {
 // → [api:a] ✓ GET /users 45ms → [...]
 ```
 
+### Bun.serve — handling Response
+
+`measure()` returns `null` on error instead of throwing. In `Bun.serve`, the fetch handler **must** return a `Response` — returning `null` crashes. Two solutions:
+
+```typescript
+// ✅ measure.assert — throws on error, use with Bun.serve error handler
+Bun.serve({
+  fetch: (req) => measure.assert('Handle', async () => {
+    return new Response('ok');
+  }),
+  error: () => new Response('Internal Server Error', { status: 500 }),
+});
+
+// ✅ Nullish coalescing — graceful 500 fallback
+Bun.serve({
+  fetch: async (req) => {
+    return (await measure('Handle', async () => {
+      return new Response('ok');
+    })) ?? new Response('Internal Server Error', { status: 500 });
+  },
+});
+```
+
+> **Why not plain `measure()`?** On error it returns `null`, not a `Response`. This is by design — `measure` never throws (except `.assert()`).
+
 ### `configure(opts)` — runtime config
 
 ```typescript
@@ -193,9 +218,61 @@ formatDuration(91234);              // "1m 31s"
 resetCounter();                     // reset ID counter for tests
 ```
 
-## Error Handling
+## Why `measure` Never Throws
+
+This is a deliberate design choice, not a shortcut.
+
+**Measure is observability, not error handling.** It answers "what happened, how long did it take, did it fail?" — not "how should I recover from this specific error?" That's your job, inside the callback.
+
+**The Go inspiration (and where it differs):** Go's `result, err := doSomething()` treats errors as values. `measure` takes the same philosophy — errors don't crash your pipeline — but it intentionally discards the error *to the caller*. Why? Because every error is **already logged** with `✗`, timing, stack trace, and cause chain. There are no silent failures. The error is visible, just not returned.
 
-**measure never throws** (except `.assert()`). On error: logs `✗`, returns `null`, prints stack to stderr.
+**Handle recoverable errors inside, let measure catch the rest:**
+
+```typescript
+const user = await measure('Fetch user', async () => {
+  try {
+    return await fetchUser(1);
+  } catch (e) {
+    if (e instanceof NetworkError) {
+      return await fetchFromCache(1);  // recover from known error
+    }
+    throw e;  // unexpected — measure catches, logs ✗, returns null
+  }
+});
+```
+
+This is the correct mental model: **try/catch inside for errors you know how to handle**, `null` outside for everything unexpected. You don't wrap measure in try/catch — you put recovery logic *within* it.
+
+**When you need the result to be non-null:**
+
+```typescript
+// .assert() — re-throws, guarantees non-null
+const user = await measure.assert('Get user', () => fetchUser(1));
+
+// ?? — graceful fallback
+const user = (await measure('Get user', () => fetchUser(1))) ?? defaultUser;
+```
+
+**Summary:**
+
+| Method | On error | Use when |
+|--------|----------|----------|
+| `measure()` | logs `✗`, returns `null` | Default — pipeline keeps running |
+| `try/catch` inside | you handle it | Recoverable errors (network, retries) |
+| `measure.assert()` | logs `✗`, then throws (`.cause` = original error) | Must have non-null (Bun.serve, etc.) |
+| `?? fallback` | returns fallback | Graceful degradation |
+
+**Watch out: layered architectures.** When you have `measure → handler → handler's own try/catch`, a `null` return is ambiguous — did the handler catch the error and return a valid fallback, or did measure catch it and swallow it? If your handler has its own error handling, use `measure.assert()` instead of `measure()` so measure stays out of the error path:
+
+```typescript
+// ✗ Ambiguous: did handler or measure catch the error?
+const response = await measure('Handle', () => handler(req));  // null = ???
+
+// ✓ Clear: measure observes, handler handles its own errors
+const response = await measure.assert('Handle', () => handler(req));
+// handler's try/catch runs first → returns error Response
+// measure only catches if handler ITSELF throws (unexpected)
+```
 
 ## Types
 

package/SKILL.md

@@ -3,111 +3,229 @@ name: measure-fn
 description: Zero-dependency function performance measurement with hierarchical logging. Use this to structure ALL programs as measured, observable pipelines.
 ---
 
-# measure-fn — Structured Program Measurement
+# measure-fn — Write Observable Code
 
-**Every program you write should be observable from day one.**
+**Every function you write should be measured.** Don't write blind code — wrap operations in `measure` so every success, failure, and timing is automatically visible. This is the default way to structure programs.
 
-## Installation
+## Install
 
 ```bash
 bun add measure-fn
 ```
 
-## Output Format
+## The Rule
 
-```
-[id] ... label          — start (async / sync with children)
-[id] ✓ label Nms → val  — success with auto-printed result
-[id] ✗ label Nms (err)  — error
-[id] = label            — annotation / progress
+> If a function does I/O, computation, or anything non-trivial — **wrap it in `measure`**.
+
+```typescript
+// ✗ BAD — blind, silent, no timing, no error visibility
+const users = await fetchUsers();
+const config = loadConfig();
+
+// ✓ GOOD — observable, timed, errors auto-logged
+const users = await measure('Fetch users', () => fetchUsers());
+const config = measureSync('Load config', () => loadConfig());
 ```
 
-No indentation, no colors. IDs encode hierarchy. Smart duration: `0.10ms` → `1.2s` → `2m 5s`.
+## Patterns
 
-## Core API
+### 1. Every entry point is a measured pipeline
 
 ```typescript
-import { measure, measureSync, createMeasure, configure } from 'measure-fn';
+import { measure, measureSync } from 'measure-fn';
+
+async function main() {
+  const config = measureSync('Load config', () => readConfig());
+  const db = await measure('Connect DB', () => connectDatabase(config));
+  const users = await measure('Fetch users', () => db.query('SELECT * FROM users'));
+  await measure('Send emails', () => sendEmails(users));
+}
+```
 
-// Async
-const users = await measure('Fetch users', () => fetchUsers());
+Output:
+```
+[a] ✓ Load config 0.12ms → {"env":"prod"}
+[b] ... Connect DB
+[b] ✓ Connect DB 45ms → [DB]
+[c] ... Fetch users
+[c] ✓ Fetch users 23ms → [{"id":1},{"id":2}]
+[d] ... Send emails
+[d] ✓ Send emails 102ms
+```
 
-// Sync (leaf = single line)
-const config = measureSync('Load config', () => loadConfig());
+### 2. Nested operations use the child measure
 
-// Nested + parallel
+```typescript
 await measure('Pipeline', async (m) => {
-  await Promise.all([
-    m({ label: 'Fetch', userId: 1 }, () => fetchUser(1)),
-    m({ label: 'Fetch', userId: 2 }, () => fetchUser(2)),
+  const raw = await m('Fetch', () => fetchData());
+  const parsed = m('Parse', () => parseData(raw));
+  await m('Save', () => saveResult(parsed));
+});
+```
+
+### 3. Parallel work with `Promise.all`
+
+```typescript
+await measure('Load all', async (m) => {
+  const [users, posts, settings] = await Promise.all([
+    m('Users', () => fetchUsers()),
+    m('Posts', () => fetchPosts()),
+    m('Settings', () => fetchSettings()),
   ]);
+  return { users, posts, settings };
 });
+```
+
+### 4. Wrap reusable functions once
 
-// Wrap: decorator pattern — wrap once, measure every call
+```typescript
 const getUser = measure.wrap('Get user', fetchUser);
-await getUser(1);
-await getUser(2);
+// Every call is now measured automatically
+await getUser(1);  // → [a] ✓ Get user 82ms → {...}
+await getUser(2);  // → [b] ✓ Get user 75ms → {...}
+```
+
+### 5. Process arrays with progress
+
+```typescript
+await measure.batch('Process users', userIds, async (id) => {
+  return await processUser(id);
+}, { every: 100 });
+// → [a] ... Process users (500 items)
+// → [a] = 100/500 (1.2s, 83/s)
+// → [a] ✓ Process users (500 items) 5.3s → "500/500 ok"
+```
+
+### 6. Retry flaky operations
+
+```typescript
+const result = await measure.retry('External API', {
+  attempts: 3, delay: 1000, backoff: 2
+}, () => callExternalService());
+```
+
+### 7. Budget warnings for slow ops
+
+```typescript
+await measure({ label: 'DB query', budget: 100 }, () => heavyQuery());
+// → [a] ✓ DB query 245ms → [...] ⚠ OVER BUDGET (100ms)
+```
 
-// Batch: process array with progress logging
-await measure.batch('Process', items, async (item) => transform(item), { every: 100 });
+### 8. Assert non-null results
 
-// Retry: automatic retry with backoff
-await measure.retry('Flaky', { attempts: 3, delay: 1000, backoff: 2 }, () => flakyApi());
+```typescript
+// Guaranteed non-null — throws if the function returns null/undefined
+const user = await measure.assert('Get user', () => findUser(id));
+```
 
-// Assert: throws if null (type-narrowing)
-const user = await measure.assert('Get user', () => fetchUser(1));
+### 9. Scoped instances for subsystems
 
-// Budget: warn when operation exceeds time limit
-await measure({ label: 'DB query', budget: 100 }, () => query());
+```typescript
+const api = createMeasure('api');
+const db = createMeasure('db');
 
-// Scoped: separate namespace and counter
-const api = createMeasure('api');  // → [api:a], [api:b], ...
-const db = createMeasure('db');    // → [db:a], [db:b], ...
+await api.measure('GET /users', async () => {
+  return await db.measure('SELECT', () => query('SELECT * FROM users'));
+});
+// → [api:a] ... GET /users
+// → [db:a] ✓ SELECT 44ms → [...]
+// → [api:a] ✓ GET /users 45ms → [...]
+```
+
+### 10. Annotations for checkpoints
+
+```typescript
+await measure('Server ready');           // → [a] = Server ready
+measureSync('Config loaded');             // → [b] = Config loaded
+```
+
+### 11. Bun.serve — always use `measure.assert` or fallback
+
+`measure()` returns `null` on error. In a fetch handler, you **must** return a `Response`:
+
+```typescript
+// ✅ measure.assert — throws on error, pair with Bun.serve error handler
+Bun.serve({
+  fetch: (req) => measure.assert('Handle', async () => {
+    return new Response('ok');
+  }),
+  error: () => new Response('Internal Server Error', { status: 500 }),
+});
+
+// ✅ Nullish coalescing fallback
+Bun.serve({
+  fetch: async (req) => {
+    return (await measure('Handle', async () => {
+      return new Response('ok');
+    })) ?? new Response('Internal Server Error', { status: 500 });
+  },
+});
 ```
 
 ## Configuration
 
 ```typescript
+import { configure } from 'measure-fn';
+
 configure({
-  silent: true,            // suppress output
+  silent: true,            // suppress output (for benchmarks)
   timestamps: true,        // [HH:MM:SS.mmm] prefix
   maxResultLength: 200,    // result truncation (default: 80)
-  logger: (event) => ...,  // custom event handler
+  logger: (event) => {     // custom telemetry
+    myTracker.send(event);
+  },
 });
 ```
 
-Env: `MEASURE_SILENT=1`, `MEASURE_TIMESTAMPS=1`
+Env vars: `MEASURE_SILENT=1`, `MEASURE_TIMESTAMPS=1`
 
-## Utilities
+## Programmatic Timing
 
 ```typescript
-import { safeStringify, formatDuration, resetCounter } from 'measure-fn';
+const { result, duration } = await measure.timed('Fetch', () => fetchUsers());
+if (duration > 1000) alert('Slow!');
 ```
 
-## API Reference
+## Error Model — measure Never Throws
 
-| Export | Description |
-|--------|-------------|
-| `measure(label, fn?)` | Async measurement |
-| `measure.timed(label, fn?)` | Returns `{ result, duration }` |
-| `measure.retry(label, opts, fn)` | Retry with backoff |
-| `measure.assert(label, fn)` | Throws if null |
-| `measure.wrap(label, fn)` | Returns measured version of fn |
-| `measure.batch(label, items, fn, opts?)` | Array processing with progress |
-| `measureSync(label, fn?)` | Sync measurement |
-| `measureSync.timed/assert/wrap` | Sync variants |
-| `createMeasure(prefix)` | Scoped instance |
-| `configure(opts)` | Runtime configuration |
-| `resetCounter()` | Reset global ID counter |
-| `safeStringify(value)` | Safe JSON with circular ref handling |
-| `formatDuration(ms)` | Smart duration formatting |
+Like Go's `result, err` pattern, `measure` treats errors as values: returns `null` on failure, **always** logs the error with timing and stack trace. One failing step doesn't crash the pipeline.
+
+| Method | On error | Use when |
+|--------|----------|----------|
+| `measure()` | returns `null` | Default — resilient pipelines |
+| `measure.assert()` | throws | Must have non-null (e.g. Bun.serve) |
+| `?? fallback` | returns fallback | Graceful degradation |
 
-## Testing
+## Anti-Patterns
 
 ```typescript
-import { resetCounter, configure } from 'measure-fn';
-beforeEach(() => {
-  resetCounter();
-  configure({ silent: false, logger: null, timestamps: false });
+// ✗ Don't measure trivial synchronous expressions
+const x = measureSync('Add', () => 1 + 1);
+
+// ✗ Don't nest measure inside measure without using child `m`
+await measure('Outer', async () => {
+  await measure('Inner', () => work());  // creates flat siblings, not hierarchy
+});
+
+// ✓ Use child measure for hierarchy
+await measure('Outer', async (m) => {
+  await m('Inner', () => work());  // proper parent → child
 });
 ```
+
+## Quick Reference
+
+| Export | Use |
+|--------|-----|
+| `measure(label, fn?)` | Async measurement |
+| `measureSync(label, fn?)` | Sync measurement |
+| `measure.wrap(label, fn)` | Decorator — wrap once, measure every call |
+| `measure.batch(label, items, fn, opts?)` | Array + progress |
+| `measure.retry(label, opts, fn)` | Retry with backoff |
+| `measure.assert(label, fn)` | Throws if null |
+| `measure.timed(label, fn)` | Returns `{ result, duration }` |
+| `createMeasure(prefix)` | Scoped instance |
+| `configure(opts)` | Runtime config |
+| `safeStringify(value)` | Safe JSON (circular refs, truncation) |
+| `formatDuration(ms)` | Smart duration: `0.10ms` → `1.2s` → `2m 5s` |
+| `resetCounter()` | Reset ID counter |

package/bench.ts

@@ -0,0 +1,54 @@
+
+import { measure, measureSync, configure } from "./index.ts";
+
+const ITERATIONS = 100_000;
+
+function noop() { }
+
+async function run() {
+    console.log(`Running benchmark with ${ITERATIONS.toLocaleString()} iterations...`);
+    configure({ silent: true }); // Disable logging to measure pure overhead
+
+    // Baseline
+    const startBase = performance.now();
+    for (let i = 0; i < ITERATIONS; i++) {
+        noop();
+    }
+    const timeBase = performance.now() - startBase;
+    const perOpBase = timeBase / ITERATIONS;
+    console.log(`Baseline (noop): ${(timeBase).toFixed(2)}ms total, ${perOpBase.toFixed(6)}ms/op`);
+
+    // measureSync overhead
+    const startSync = performance.now();
+    for (let i = 0; i < ITERATIONS; i++) {
+        measureSync('test', noop);
+    }
+    const timeSync = performance.now() - startSync;
+    const overheadSync = (timeSync - timeBase) / ITERATIONS;
+    console.log(`measureSync:     ${(timeSync).toFixed(2)}ms total, ${overheadSync.toFixed(6)}ms overhead/op`);
+
+    // measure (async) overhead
+    const startAsync = performance.now();
+    for (let i = 0; i < ITERATIONS; i++) {
+        await measure('test', async () => { });
+    }
+    const timeAsync = performance.now() - startAsync;
+    const overheadAsync = (timeAsync - timeBase) / ITERATIONS;
+    console.log(`measure (async): ${(timeAsync).toFixed(2)}ms total, ${overheadAsync.toFixed(6)}ms overhead/op`);
+
+    // Nested overhead (depth 3)
+    const startNested = performance.now();
+    for (let i = 0; i < ITERATIONS / 10; i++) { // reduce iterations
+        measureSync('root', (m) => {
+            m('child', (m2) => {
+                m2('leaf', noop);
+            });
+        });
+    }
+    const timeNested = performance.now() - startNested;
+    // 3 measurements per iteration
+    const perOpNested = timeNested / (ITERATIONS / 10);
+    console.log(`Nested (depth 3): ${(timeNested).toFixed(2)}ms total, ${perOpNested.toFixed(6)}ms per tree (3 ops)`);
+}
+
+run();

package/bun.lock

@@ -1,25 +1,26 @@
-{
-  "lockfileVersion": 1,
-  "workspaces": {
-    "": {
-      "name": "ments-utils",
-      "devDependencies": {
-        "@types/bun": "latest",
-      },
-      "peerDependencies": {
-        "typescript": "^5",
-      },
-    },
-  },
-  "packages": {
-    "@types/bun": ["@types/bun@1.2.17", "", { "dependencies": { "bun-types": "1.2.17" } }, "sha512-l/BYs/JYt+cXA/0+wUhulYJB6a6p//GTPiJ7nV+QHa8iiId4HZmnu/3J/SowP5g0rTiERY2kfGKXEK5Ehltx4Q=="],
-
-    "@types/node": ["@types/node@24.0.4", "", { "dependencies": { "undici-types": "~7.8.0" } }, "sha512-ulyqAkrhnuNq9pB76DRBTkcS6YsmDALy6Ua63V8OhrOBgbcYt6IOdzpw5P1+dyRIyMerzLkeYWBeOXPpA9GMAA=="],
-
-    "bun-types": ["bun-types@1.2.17", "", { "dependencies": { "@types/node": "*" } }, "sha512-ElC7ItwT3SCQwYZDYoAH+q6KT4Fxjl8DtZ6qDulUFBmXA8YB4xo+l54J9ZJN+k2pphfn9vk7kfubeSd5QfTVJQ=="],
-
-    "typescript": ["typescript@5.8.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ=="],
-
-    "undici-types": ["undici-types@7.8.0", "", {}, "sha512-9UJ2xGDvQ43tYyVMpuHlsgApydB8ZKfVYTsLDhXkFL/6gfkp+U8xTGdh8pMJv1SpZna0zxG1DwsKZsreLbXBxw=="],
-  }
-}
+{
+  "lockfileVersion": 1,
+  "configVersion": 0,
+  "workspaces": {
+    "": {
+      "name": "ments-utils",
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.2.17", "", { "dependencies": { "bun-types": "1.2.17" } }, "sha512-l/BYs/JYt+cXA/0+wUhulYJB6a6p//GTPiJ7nV+QHa8iiId4HZmnu/3J/SowP5g0rTiERY2kfGKXEK5Ehltx4Q=="],
+
+    "@types/node": ["@types/node@24.0.4", "", { "dependencies": { "undici-types": "~7.8.0" } }, "sha512-ulyqAkrhnuNq9pB76DRBTkcS6YsmDALy6Ua63V8OhrOBgbcYt6IOdzpw5P1+dyRIyMerzLkeYWBeOXPpA9GMAA=="],
+
+    "bun-types": ["bun-types@1.2.17", "", { "dependencies": { "@types/node": "*" } }, "sha512-ElC7ItwT3SCQwYZDYoAH+q6KT4Fxjl8DtZ6qDulUFBmXA8YB4xo+l54J9ZJN+k2pphfn9vk7kfubeSd5QfTVJQ=="],
+
+    "typescript": ["typescript@5.8.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ=="],
+
+    "undici-types": ["undici-types@7.8.0", "", {}, "sha512-9UJ2xGDvQ43tYyVMpuHlsgApydB8ZKfVYTsLDhXkFL/6gfkp+U8xTGdh8pMJv1SpZna0zxG1DwsKZsreLbXBxw=="],
+  }
+}

package/example.ts

@@ -98,4 +98,60 @@ async function main() {
   });
 }
 
-main().then(() => console.log('\n✅ Done.'));
+// ─── Bun.serve patterns ──────────────────────────────────────────────
+// measure() returns T | null — on error it returns null instead of throwing.
+// In Bun.serve, the fetch handler MUST return a Response. If measure()
+// swallows the error and returns null, Bun crashes.
+//
+// Solution: use measure.assert() which re-throws on error,
+// or use nullish coalescing to provide a fallback Response.
+
+async function bunServeExample() {
+  console.log('\n─── Bun.serve Patterns ─────────────────────────────');
+
+  // ✅ Pattern 1: measure.assert — throws on error, Bun gets a proper crash
+  const server1 = Bun.serve({
+    port: 0, // random port
+    fetch: (req) => measure.assert('Handle request', async () => {
+      const url = new URL(req.url);
+      if (url.pathname === '/fail') throw new Error('Route error');
+      return new Response(`ok: ${url.pathname}`);
+    }),
+  });
+
+  // ✅ Pattern 2: nullish coalescing — graceful 500 fallback
+  const server2 = Bun.serve({
+    port: 0,
+    fetch: async (req) => {
+      return (await measure('Handle request', async () => {
+        const url = new URL(req.url);
+        if (url.pathname === '/fail') throw new Error('Route error');
+        return new Response(`ok: ${url.pathname}`);
+      })) ?? new Response('Internal Server Error', { status: 500 });
+    },
+  });
+
+  // Test both servers
+  const r1 = await fetch(`http://localhost:${server1.port}/hello`);
+  console.log(`  assert pattern (ok): ${r1.status} ${await r1.text()}`);
+
+  try {
+    await fetch(`http://localhost:${server1.port}/fail`);
+  } catch {
+    console.log(`  assert pattern (fail): server rejected (expected)`);
+  }
+
+  const r2ok = await fetch(`http://localhost:${server2.port}/hello`);
+  console.log(`  fallback pattern (ok): ${r2ok.status} ${await r2ok.text()}`);
+
+  const r2fail = await fetch(`http://localhost:${server2.port}/fail`);
+  console.log(`  fallback pattern (fail): ${r2fail.status} ${await r2fail.text()}`);
+
+  server1.stop();
+  server2.stop();
+}
+
+main()
+  .then(() => console.log('\n✅ Done.'))
+  .then(() => bunServeExample())
+  .then(() => console.log('\n✅ Bun.serve example done.'));

package/index.test.ts

@@ -394,13 +394,15 @@ describe("measure.assert", () => {
         expect(r).toBe(42);
     });
 
-    test("throws on error", async () => {
+    test("throws on error with original cause", async () => {
         const out = captureConsole();
+        const original = new Error("connection refused");
         try {
-            await measure.assert("fail", async () => { throw new Error("x"); });
+            await measure.assert("fail", async () => { throw original; });
             expect(true).toBe(false);
         } catch (e: any) {
             expect(e.message).toContain("fail");
+            expect(e.cause).toBe(original);
         }
         out.restore();
     });
@@ -411,13 +413,15 @@ describe("measure.assert", () => {
         out.restore();
     });
 
-    test("sync assert throws", () => {
+    test("sync assert throws with original cause", () => {
         const out = captureConsole();
+        const original = new Error("parse error");
         try {
-            measureSync.assert("fail", () => { throw new Error("x"); });
+            measureSync.assert("fail", () => { throw original; });
             expect(true).toBe(false);
         } catch (e: any) {
             expect(e.message).toContain("fail");
+            expect(e.cause).toBe(original);
         }
         out.restore();
     });
@@ -585,3 +589,60 @@ describe("ID generation", () => {
         expect(out.logs[52]).toStartWith("[aa]");
     });
 });
+
+// ─── Bun.serve patterns ─────────────────────────────────────────────
+
+describe("Bun.serve pattern", () => {
+    beforeEach(() => {
+        resetCounter();
+        configure({ silent: false, logger: null, timestamps: false });
+    });
+
+    test("measure returns null on error — breaks fetch handler", async () => {
+        const out = captureConsole();
+        const result = await measure("handle", async () => {
+            throw new Error("route error");
+            return new Response("ok");
+        });
+        out.restore();
+        expect(result).toBeNull(); // Bun.serve would crash with null
+    });
+
+    test("measure.assert returns Response on success", async () => {
+        const out = captureConsole();
+        const result = await measure.assert("handle", async () => {
+            return new Response("ok");
+        });
+        out.restore();
+        expect(result).toBeInstanceOf(Response);
+        expect(await result.text()).toBe("ok");
+    });
+
+    test("measure.assert throws on error with cause — Bun.serve can catch it", async () => {
+        const out = captureConsole();
+        const original = new Error("route error");
+        try {
+            await measure.assert("handle", async () => {
+                throw original;
+                return new Response("ok");
+            });
+            expect(true).toBe(false); // should not reach
+        } catch (e: any) {
+            expect(e.message).toContain("handle");
+            expect(e.cause).toBe(original);
+        }
+        out.restore();
+    });
+
+    test("nullish coalescing fallback pattern", async () => {
+        const out = captureConsole();
+        const result = (await measure("handle", async () => {
+            throw new Error("route error");
+            return new Response("ok");
+        })) ?? new Response("Internal Server Error", { status: 500 });
+        out.restore();
+        expect(result).toBeInstanceOf(Response);
+        expect(result.status).toBe(500);
+        expect(await result.text()).toBe("Internal Server Error");
+    });
+});

package/index.ts

@@ -249,6 +249,7 @@ export const resetCounter = () => {
 
 const createMeasureImpl = (prefix?: string, counterRef?: { value: number }) => {
   const counter = counterRef ?? { get value() { return globalRootCounter; }, set value(v) { globalRootCounter = v; } };
+  let _lastError: unknown = null;
 
   const _measureInternal = async <U>(
     fnInternal: (measure: MeasureFn) => Promise<U>,
@@ -283,6 +284,7 @@ const createMeasureImpl = (prefix?: string, counterRef?: { value: number }) => {
     } catch (error) {
       const duration = performance.now() - start;
       emit({ type: 'error', id: idStr, label, depth, duration, error, budget }, prefix);
+      _lastError = error;
       return null;
     }
   };
@@ -323,6 +325,7 @@ const createMeasureImpl = (prefix?: string, counterRef?: { value: number }) => {
     } catch (error) {
       const duration = performance.now() - start;
       emit({ type: 'error', id: idStr, label, depth, duration, error, budget }, prefix);
+      _lastError = error;
       return null;
     }
   };
@@ -405,7 +408,9 @@ const createMeasureImpl = (prefix?: string, counterRef?: { value: number }) => {
   ): Promise<T> => {
     const result = await measureFn(arg1, arg2 as any);
     if (result === null) {
-      throw new Error(`measure.assert: "${buildActionLabel(arg1)}" returned null`);
+      const cause = _lastError;
+      _lastError = null;
+      throw new Error(`measure.assert: "${buildActionLabel(arg1)}" failed`, { cause });
     }
     return result;
   };
@@ -507,7 +512,9 @@ const createMeasureImpl = (prefix?: string, counterRef?: { value: number }) => {
   ): T => {
     const result = measureSyncFn(arg1, arg2 as any);
     if (result === null) {
-      throw new Error(`measureSync.assert: "${buildActionLabel(arg1)}" returned null`);
+      const cause = _lastError;
+      _lastError = null;
+      throw new Error(`measureSync.assert: "${buildActionLabel(arg1)}" failed`, { cause });
     }
     return result;
   };

package/package.json

@@ -2,7 +2,7 @@
   "name": "measure-fn",
   "module": "index.ts",
   "main": "./index.ts",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "type": "module",
   "private": false,
   "description": "Zero-dependency function performance measurement with hierarchical logging",