measure-fn 3.3.0 → 3.5.0

package/README.md

@@ -218,61 +218,67 @@ formatDuration(91234);              // "1m 31s"
 resetCounter();                     // reset ID counter for tests
 ```
 
-## Why `measure` Never Throws
+## Error Handling
 
-This is a deliberate design choice, not a shortcut.
+`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.
 
-**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.
+**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`:
 
-**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.
+```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
+  }
+);
 
-**Handle recoverable errors inside, let measure catch the rest:**
+// Rethrow all: transparent observability (same as .assert())
+const user = await measure('Fetch user', () => fetchUser(1),
+  (error) => { throw error }
+);
+```
+
+**Bun.serve — never return null:**
 
 ```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
-  }
+Bun.serve({
+  fetch: (req) => measure(
+    { label: `${req.method} ${req.url}` },
+    () => handleRequest(req),
+    (error) => new Response(`Error: ${error.message}`, { status: 500 })
+  ),
 });
 ```
 
-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:**
+**`.assert()` is sugar for the rethrow pattern:**
 
 ```typescript
-// .assert() — re-throws, guarantees non-null
-const user = await measure.assert('Get user', () => fetchUser(1));
+// These are equivalent:
+await measure.assert('Op', () => work());
+await measure('Op', () => work(), (e) => { throw e });
 
-// ?? — graceful fallback
-const user = (await measure('Get user', () => fetchUser(1))) ?? defaultUser;
+// .assert() wraps the error with .cause for inspection:
+// e.message → 'measure.assert: "Op" failed'
+// e.cause   → original error
 ```
 
 **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)
-```
+| 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

@@ -139,29 +139,52 @@ await measure('Server ready');           // → [a] = Server ready
 measureSync('Config loaded');             // → [b] = Config loaded
 ```
 
-### 11. Bun.serve — always use `measure.assert` or fallback
+### 11. Error handling — `onError` 3rd argument
 
-`measure()` returns `null` on error. In a fetch handler, you **must** return a `Response`:
+`measure` never throws. Pass an `onError` handler as 3rd argument to handle errors:
 
 ```typescript
-// ✅ measure.assert — throws on error, pair with Bun.serve error handler
+// 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.assert('Handle', async () => {
-    return new Response('ok');
-  }),
-  error: () => new Response('Internal Server Error', { status: 500 }),
+  fetch: (req) => measure(
+    { label: `${req.method} ${req.url}` },
+    () => handleRequest(req),
+    (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 });
-  },
-});
+`.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
@@ -186,16 +209,6 @@ const { result, duration } = await measure.timed('Fetch', () => fetchUsers());
 if (duration > 1000) alert('Slow!');
 ```
 
-## Error Model — measure Never Throws
-
-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 |
-
 ## Anti-Patterns
 
 ```typescript

package/example.ts

@@ -100,18 +100,28 @@ async function main() {
 
 // ─── 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.
+// Use the onError 3rd argument 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
+  // ✅ Pattern 1: onError — graceful 500 fallback with error details
   const server1 = Bun.serve({
-    port: 0, // random port
+    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');
@@ -119,34 +129,23 @@ async function bunServeExample() {
     }),
   });
 
-  // ✅ 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 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()}`);
 
-  // Test both servers
-  const r1 = await fetch(`http://localhost:${server1.port}/hello`);
-  console.log(`  assert pattern (ok): ${r1.status} ${await r1.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:${server1.port}/fail`);
+    await fetch(`http://localhost:${server2.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();
 }

package/index.test.ts

@@ -427,6 +427,114 @@ describe("measure.assert", () => {
     });
 });
 
+// ─── 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", () => {

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',
@@ -255,7 +256,8 @@ const createMeasureImpl = (prefix?: string, counterRef?: { value: number }) => {
     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 };
@@ -285,6 +287,7 @@ const createMeasureImpl = (prefix?: string, counterRef?: { value: number }) => {
       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;
     }
   };
@@ -293,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 };
@@ -326,6 +330,7 @@ const createMeasureImpl = (prefix?: string, counterRef?: { value: number }) => {
       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;
     }
   };
@@ -334,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({

package/package.json

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