measure-fn 3.2.1 → 3.5.0

package/README.md

@@ -1,7 +1,5 @@
 # measure-fn
 
-![CI](https://github.com/7flash/ments-utils/actions/workflows/ci.yml/badge.svg)
-
 **Stop writing blind code.** Every function you write either succeeds or fails, takes some amount of time, and lives inside a larger flow. `measure-fn` makes all of that visible — automatically, hierarchically.
 
 ```
@@ -164,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
@@ -197,7 +220,65 @@ resetCounter();                     // reset ID counter for tests
 
 ## Error Handling
 
-**measure never throws** (except `.assert()`). On error: logs `✗`, returns `null`, prints stack to stderr.
+`measure` never throws. On error it logs `✗` with timing and stack trace, then returns `null`. This keeps pipelines resilient — one failing step doesn't crash the rest.
+
+**When you need to handle the error**, pass an `onError` handler as the 3rd argument. It receives the original error and its return value replaces `null`:
+
+```typescript
+// Default: returns null on error
+const user = await measure('Fetch user', () => fetchUser(1));
+
+// With recovery: returns fallback on error
+const user = await measure('Fetch user', () => fetchUser(1),
+  (error) => defaultUser
+);
+
+// With error inspection: handle known errors, rethrow unknown
+const user = await measure('Fetch user', () => fetchUser(1),
+  (error) => {
+    if (error instanceof NotFoundError) return guestUser;
+    if (error instanceof NetworkError) return cachedUser;
+    throw error;  // unexpected — propagates up
+  }
+);
+
+// Rethrow all: transparent observability (same as .assert())
+const user = await measure('Fetch user', () => fetchUser(1),
+  (error) => { throw error }
+);
+```
+
+**Bun.serve — never return null:**
+
+```typescript
+Bun.serve({
+  fetch: (req) => measure(
+    { label: `${req.method} ${req.url}` },
+    () => handleRequest(req),
+    (error) => new Response(`Error: ${error.message}`, { status: 500 })
+  ),
+});
+```
+
+**`.assert()` is sugar for the rethrow pattern:**
+
+```typescript
+// These are equivalent:
+await measure.assert('Op', () => work());
+await measure('Op', () => work(), (e) => { throw e });
+
+// .assert() wraps the error with .cause for inspection:
+// e.message → 'measure.assert: "Op" failed'
+// e.cause   → original error
+```
+
+**Summary:**
+
+| Pattern | On error | Use when |
+|---------|----------|----------|
+| `measure(label, fn)` | logs `✗`, returns `null` | Default — pipeline resilience |
+| `measure(label, fn, onError)` | logs `✗`, calls `onError(error)` | Recovery, fallbacks, error inspection |
+| `measure.assert(label, fn)` | logs `✗`, throws with `.cause` | Must have non-null |
 
 ## Types
 

package/SKILL.md

@@ -3,111 +3,242 @@ 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 };
 });
+```
 
-// Wrap: decorator pattern — wrap once, measure every call
+### 4. Wrap reusable functions once
+
+```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 → {...}
+```
 
-// Batch: process array with progress logging
-await measure.batch('Process', items, async (item) => transform(item), { every: 100 });
+### 5. Process arrays with progress
 
-// Retry: automatic retry with backoff
-await measure.retry('Flaky', { attempts: 3, delay: 1000, backoff: 2 }, () => flakyApi());
+```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"
+```
 
-// Assert: throws if null (type-narrowing)
-const user = await measure.assert('Get user', () => fetchUser(1));
+### 6. Retry flaky operations
 
-// Budget: warn when operation exceeds time limit
-await measure({ label: 'DB query', budget: 100 }, () => query());
+```typescript
+const result = await measure.retry('External API', {
+  attempts: 3, delay: 1000, backoff: 2
+}, () => callExternalService());
+```
 
-// Scoped: separate namespace and counter
-const api = createMeasure('api');  // → [api:a], [api:b], ...
-const db = createMeasure('db');    // → [db:a], [db:b], ...
+### 7. Budget warnings for slow ops
+
+```typescript
+await measure({ label: 'DB query', budget: 100 }, () => heavyQuery());
+// → [a] ✓ DB query 245ms → [...] ⚠ OVER BUDGET (100ms)
 ```
 
+### 8. Assert non-null results
+
+```typescript
+// Guaranteed non-null — throws if the function returns null/undefined
+const user = await measure.assert('Get user', () => findUser(id));
+```
+
+### 9. Scoped instances for subsystems
+
+```typescript
+const api = createMeasure('api');
+const db = createMeasure('db');
+
+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. Error handling — `onError` 3rd argument
+
+`measure` never throws. Pass an `onError` handler as 3rd argument to handle errors:
+
+```typescript
+// Default: null on error
+const user = await measure('Fetch user', () => fetchUser(1));
+
+// Recovery: fallback on error
+const user = await measure('Fetch user', () => fetchUser(1),
+  (error) => defaultUser
+);
+
+// Error inspection: handle known errors, rethrow unknown
+const user = await measure('Fetch user', () => fetchUser(1),
+  (error) => {
+    if (error instanceof NetworkError) return cachedUser;
+    throw error;
+  }
+);
+
+// Bun.serve: always return a Response
+Bun.serve({
+  fetch: (req) => measure(
+    { label: `${req.method} ${req.url}` },
+    () => handleRequest(req),
+    (error) => new Response('Internal Server Error', { status: 500 })
+  ),
+});
+```
+
+`.assert()` is sugar for `(e) => { throw e }` with `.cause`:
+
+```typescript
+await measure.assert('Op', () => work());
+// equivalent to: measure('Op', () => work(), (e) => { throw e })
+```
+
+## Error Model
+
+| Pattern | On error | Use when |
+|---------|----------|----------|
+| `measure(label, fn)` | logs `✗`, returns `null` | Default — pipeline resilience |
+| `measure(label, fn, onError)` | logs `✗`, calls `onError(error)` | Recovery, fallbacks, error inspection |
+| `measure.assert(label, fn)` | logs `✗`, throws with `.cause` | Must have non-null |
+
 ## 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
+## Anti-Patterns
 
-| 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 |
+```typescript
+// ✗ Don't measure trivial synchronous expressions
+const x = measureSync('Add', () => 1 + 1);
 
-## Testing
+// ✗ Don't nest measure inside measure without using child `m`
+await measure('Outer', async () => {
+  await measure('Inner', () => work());  // creates flat siblings, not hierarchy
+});
 
-```typescript
-import { resetCounter, configure } from 'measure-fn';
-beforeEach(() => {
-  resetCounter();
-  configure({ silent: false, logger: null, timestamps: false });
+// ✓ 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/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,59 @@ async function main() {
   });
 }
 
-main().then(() => console.log('\n✅ Done.'));
+// ─── Bun.serve patterns ──────────────────────────────────────────────
+// measure() returns T | null — on error it returns null instead of throwing.
+// Use the onError 3rd argument to provide a fallback Response.
+
+async function bunServeExample() {
+  console.log('\n─── Bun.serve Patterns ─────────────────────────────');
+
+  // ✅ Pattern 1: onError — graceful 500 fallback with error details
+  const server1 = Bun.serve({
+    port: 0,
+    fetch: (req) => measure(
+      { label: `${req.method} ${new URL(req.url).pathname}` },
+      async () => {
+        const url = new URL(req.url);
+        if (url.pathname === '/fail') throw new Error('Route error');
+        return new Response(`ok: ${url.pathname}`);
+      },
+      (error) => new Response(`Error: ${(error as Error).message}`, { status: 500 })
+    ),
+  });
+
+  // ✅ Pattern 2: measure.assert — throws on error (sugar for onError + throw)
+  const server2 = Bun.serve({
+    port: 0,
+    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}`);
+    }),
+  });
+
+  // Test Pattern 1: onError returns fallback Response
+  const r1ok = await fetch(`http://localhost:${server1.port}/hello`);
+  console.log(`  onError pattern (ok): ${r1ok.status} ${await r1ok.text()}`);
+
+  const r1fail = await fetch(`http://localhost:${server1.port}/fail`);
+  console.log(`  onError pattern (fail): ${r1fail.status} ${await r1fail.text()}`);
+
+  // Test Pattern 2: assert
+  const r2ok = await fetch(`http://localhost:${server2.port}/hello`);
+  console.log(`  assert pattern (ok): ${r2ok.status} ${await r2ok.text()}`);
+
+  try {
+    await fetch(`http://localhost:${server2.port}/fail`);
+  } catch {
+    console.log(`  assert pattern (fail): server rejected (expected)`);
+  }
+
+  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,18 +413,128 @@ 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();
     });
 });
 
+// ─── onError (3rd argument) ──────────────────────────────────────────
+
+describe("onError (3rd argument)", () => {
+    beforeEach(() => {
+        resetCounter();
+        configure({ silent: false, logger: null, timestamps: false });
+    });
+
+    test("returns fallback from onError on failure", async () => {
+        const out = captureConsole();
+        const result = await measure('Fetch user', async () => {
+            throw new Error('not found');
+        }, () => 'fallback');
+        out.restore();
+        expect(result).toBe('fallback');
+    });
+
+    test("returns normal result on success (onError ignored)", async () => {
+        const out = captureConsole();
+        const result = await measure('Fetch user', async () => 42, () => -1);
+        out.restore();
+        expect(result).toBe(42);
+    });
+
+    test("error object is passed to onError handler", async () => {
+        const out = captureConsole();
+        const original = new Error('network timeout');
+        let captured: unknown = null;
+        await measure('Fetch', async () => { throw original; }, (err) => {
+            captured = err;
+            return null;
+        });
+        out.restore();
+        expect(captured).toBe(original);
+    });
+
+    test("onError can rethrow (same as assert)", async () => {
+        const out = captureConsole();
+        const original = new Error('critical');
+        try {
+            await measure('Op', async () => { throw original; }, (e) => { throw e; });
+            expect(true).toBe(false);
+        } catch (e) {
+            expect(e).toBe(original);
+        }
+        out.restore();
+    });
+
+    test("onError can inspect error type and recover", async () => {
+        const out = captureConsole();
+        const result = await measure('Fetch', async () => {
+            throw new TypeError('invalid');
+        }, (error) => {
+            if (error instanceof TypeError) return 'recovered';
+            throw error;
+        });
+        out.restore();
+        expect(result).toBe('recovered');
+    });
+
+    test("sync onError returns fallback", () => {
+        const out = captureConsole();
+        const result = measureSync('Parse', () => {
+            throw new Error('bad input');
+        }, () => 'default');
+        out.restore();
+        expect(result).toBe('default');
+    });
+
+    test("sync onError receives error", () => {
+        const out = captureConsole();
+        const original = new Error('sync fail');
+        let captured: unknown = null;
+        measureSync('Op', () => { throw original; }, (err) => {
+            captured = err;
+            return null;
+        });
+        out.restore();
+        expect(captured).toBe(original);
+    });
+
+    test("still logs error even when onError handles it", async () => {
+        const events: any[] = [];
+        configure({ logger: (e) => events.push(e) });
+        await measure('Op', async () => { throw new Error('x'); }, () => 'fallback');
+        configure({ logger: null });
+        const errorEvent = events.find(e => e.type === 'error');
+        expect(errorEvent).toBeTruthy();
+        expect(errorEvent.label).toBe('Op');
+    });
+
+    test("Bun.serve pattern with onError fallback", async () => {
+        const out = captureConsole();
+        const result = await measure(
+            { label: 'Handle request' },
+            async () => {
+                throw new Error('route error');
+                return new Response('ok');
+            },
+            (error) => new Response(`Error: ${(error as Error).message}`, { status: 500 })
+        );
+        out.restore();
+        expect(result).toBeInstanceOf(Response);
+        expect(result!.status).toBe(500);
+        expect(await result!.text()).toContain('route error');
+    });
+});
+
 // ─── measure.wrap ────────────────────────────────────────────────────
 
 describe("measure.wrap", () => {
@@ -585,3 +697,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

@@ -214,16 +214,17 @@ const createNestedResolver = (
   fullIdChain: string[],
   childCounterRef: { value: number },
   depth: number,
-  resolver: <U>(fn: any, action: any, chain: (string | number)[], depth: number) => Promise<U | null> | (U | null),
+  resolver: <U>(fn: any, action: any, chain: (string | number)[], depth: number, onError?: (error: unknown) => any) => Promise<U | null> | (U | null),
   prefix?: string
 ) => {
   return (...args: any[]) => {
     const label = args[0];
     const fn = args[1];
+    const onError = args[2];
 
     if (typeof fn === 'function') {
       const childParentChain = [...fullIdChain, childCounterRef.value++];
-      return resolver(fn, label, childParentChain, depth + 1);
+      return resolver(fn, label, childParentChain, depth + 1, typeof onError === 'function' ? onError : undefined);
     } else {
       emit({
         type: 'annotation',
@@ -249,12 +250,14 @@ 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>,
     actionInternal: string | object,
     parentIdChain: (string | number)[],
-    depth: number
+    depth: number,
+    onError?: (error: unknown) => any
   ): Promise<U | null> => {
     const start = performance.now();
     const childCounterRef = { value: 0 };
@@ -283,6 +286,8 @@ 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;
+      if (onError) return onError(error);
       return null;
     }
   };
@@ -291,7 +296,8 @@ const createMeasureImpl = (prefix?: string, counterRef?: { value: number }) => {
     fnInternal: (measure: MeasureSyncFn) => U,
     actionInternal: string | object,
     parentIdChain: (string | number)[],
-    depth: number
+    depth: number,
+    onError?: (error: unknown) => any
   ): U | null => {
     const start = performance.now();
     const childCounterRef = { value: 0 };
@@ -323,6 +329,8 @@ 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;
+      if (onError) return onError(error);
       return null;
     }
   };
@@ -331,10 +339,11 @@ const createMeasureImpl = (prefix?: string, counterRef?: { value: number }) => {
 
   const measureFn = async <T = null>(
     arg1: string | object,
-    arg2?: ((measure: MeasureFn) => Promise<T>)
+    arg2?: ((measure: MeasureFn) => Promise<T>) | ((measure: MeasureFn) => T),
+    arg3?: (error: unknown) => any
   ): Promise<T | null> => {
     if (typeof arg2 === 'function') {
-      return _measureInternal(arg2, arg1, [counter.value++], 0) as Promise<T | null>;
+      return _measureInternal(arg2 as any, arg1, [counter.value++], 0, arg3) as Promise<T | null>;
     } else {
       const currentId = toAlpha(counter.value++);
       emit({
@@ -405,7 +414,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 +518,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,8 @@
   "name": "measure-fn",
   "module": "index.ts",
   "main": "./index.ts",
-  "version": "3.2.1",
+  "types": "./index.ts",
+  "version": "3.5.0",
   "type": "module",
   "private": false,
   "description": "Zero-dependency function performance measurement with hierarchical logging",
@@ -17,7 +18,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/7flash/ments-utils"
+    "url": "https://github.com/7flash/measure-fn"
   },
   "devDependencies": {
     "@types/bun": "latest"

package/.github/workflows/ci.yml

@@ -1,20 +0,0 @@
-
-name: CI
-
-on:
-  push:
-    branches: [master, main]
-  pull_request:
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: oven-sh/setup-bun@v1
-        with:
-          bun-version: latest
-      
-      - run: bun install
-      - run: bun test
-      - run: bun run example.ts