measure-fn 3.3.0 → 3.6.0

package/README.md

@@ -1,296 +1,229 @@
-# measure-fn
+<p align="center">
+  <img src="banner.png" alt="measure-fn" width="100%" />
+</p>
 
-**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.
-
-```
-[18:50:04.893] [a] ✓ Load config 0.09ms → {"env":"prod","port":3000}
-[18:50:04.894] [b] = App ready
-[18:50:04.895] [e] ... Parallel Fetch
-[18:50:04.895] [e-a] ... Fetch User (userId=1)
-[18:50:04.895] [e-b] ... Fetch User (userId=2)
-[18:50:04.950] [e-b] ✓ Fetch User 55.58ms → {"id":2,"name":"User 2"}
-[18:50:04.981] [e-a] ✓ Fetch User 85.93ms → {"id":1,"name":"User 1"}
-[18:50:04.981] [e] ✓ Parallel Fetch 86.08ms
-[18:50:05.072] [f] ✓ DB query 91.12ms → {"rows":42} ⚠ OVER BUDGET (30.00ms)
-[18:50:05.775] [m] ... Fetch all users (20 items)
-[18:50:06.179] [m] = 5/20 (0.4s, 12/s)
-[18:50:07.450] [m] ✓ Fetch all users (20 items) 1.7s → "20/20 ok"
-[18:50:07.450] [api:a] ... GET /users
-[18:50:07.450] [db:a] ... SELECT users
-[18:50:07.493] [db:a] ✓ SELECT users 43.07ms → [{"id":1},{"id":2}]
-[18:50:07.493] [api:a] ✓ GET /users 43.32ms → [{"id":1},{"id":2}]
-[18:50:08.721] [o] ✓ Slow op 1.2s → "slow"
-```
-
-No setup. No dashboards. Just wrap your functions.
-
-## Install
+Wrap functions with automatic try-catch, timing, timeouts, and structured logging.
 
 ```sh
 bun add measure-fn
 ```
 
-## Quick Start
-
 ```typescript
 import { measure, measureSync } from 'measure-fn';
 
-// Sync leaf — single line with auto-printed result
-const config = measureSync('Parse config', () => JSON.parse(str));
-// → [a] ✓ Parse config 0.20ms → {"port":3000}
-
-// Async — start + end
-const data = await measure('Fetch data', async () => {
-  return await fetch(url).then(r => r.json());
-});
-// → [b] ... Fetch data
-// → [b] ✓ Fetch data 245.12ms → [{"id":1}]
+const users = await measure('Fetch users', () => fetchUsers());
+const config = measureSync('Parse config', () => JSON.parse(raw));
 ```
 
-## Output Format
-
-| Pattern | When | Example |
-|---------|------|---------|
-| `[id] ... label` | Async start / sync with children | `[a] ... Pipeline` |
-| `[id] ✓ label Nms → value` | Success | `[a] ✓ Fetch 102ms → {"id":1}` |
-| `[id] ✗ label Nms (err)` | Error | `[a] ✗ Fetch 2ms (timeout)` |
-| `[id] = label` | Annotation | `[a] = checkpoint` |
+```
+[a] ... Fetch users
+[a] ✓ Fetch users 86ms → [{"id":1},{"id":2}]
+[b] ✓ Parse config 0.09ms → {"env":"prod","port":3000}
+```
 
-**No indentation, no colors.** IDs encode hierarchy. Return values auto-print. Circular refs → `[Circular]`, long values truncated.
+## Defaults
 
-**Smart duration**: `0.10ms` → `1.2s` → `2m 5s`
+Every `measure` call:
+- **catches errors** → logs `✗` with stack trace, returns `null` (no unhandled rejections)
+- **logs timing** → `✓ label Nms → result`
+- **assigns an ID** → `[a]`, `[b]`, `[a-a]` for nested calls
 
-## API
+## Error Handling
 
-### `measure(label, fn?)` — async
+By default, errors return `null`:
 
 ```typescript
-// Simple
 const user = await measure('Fetch user', () => fetchUser(1));
-
-// Nested + parallel
-await measure('Pipeline', async (m) => {
-  await Promise.all([
-    m({ label: 'Fetch', userId: 1 }, () => fetchUser(1)),
-    m({ label: 'Fetch', userId: 2 }, () => fetchUser(2)),
-  ]);
-});
-
-// Annotation
-await measure('checkpoint');
+// throws → logs ✗, user = null
 ```
 
-### `measureSync(label, fn?)` — synchronous
+Pass `onError` as 3rd argument to provide a fallback:
 
 ```typescript
-// Leaf — single line
-const hash = measureSync('Hash', () => computeHash(data));
-
-// With children — start + end
-measureSync('Report', (m) => {
-  const data = m('Parse', () => parse(raw));
-  return m('Summarize', () => summarize(data));
-});
+const user = await measure('Fetch user', () => fetchUser(1),
+  (error) => defaultUser
+);
+// throws → logs ✗, user = defaultUser
 ```
 
-### `measure.wrap(label, fn)` — decorator
+If `onError` itself throws, that's also caught — returns `null`. Measure never crashes.
 
-Wrap a function once, every call is measured:
+Use `.assert()` when you need a guaranteed non-null result:
 
 ```typescript
-const getUser = measure.wrap('Get user', fetchUser);
-await getUser(1); // → [a] ... Get user → [a] ✓ Get user 82ms → {...}
-await getUser(2); // → [b] ... Get user → [b] ✓ Get user 75ms → {...}
+const user = await measure.assert('Get user', () => fetchUser(1));
+// throws → logs ✗, re-throws with .cause = original error
 ```
 
-### `measure.batch(label, items, fn, opts?)` — array processing with progress
+| Pattern | On error |
+|---------|----------|
+| `measure(label, fn)` | returns `null` |
+| `measure(label, fn, onError)` | returns `onError(error)` |
+| `measure.assert(label, fn)` | throws with `.cause` |
 
-```typescript
-const results = await measure.batch('Process users', userIds, async (id) => {
-  return await processUser(id);
-}, { every: 100 }); // log progress every 100 items
-```
-Output:
-```
-[a] ... Process users (500 items)
-[a] = 100/500 (1.2s, 83/s)
-[a] = 200/500 (2.1s, 95/s)
-[a] ✓ Process users (500 items) 5.3s → "500/500 ok"
-```
+## Timeout
 
-### `measure.retry(label, opts, fn)` — retry with backoff
+Set `timeout` in the label object to abort after N milliseconds:
 
 ```typescript
-const result = await measure.retry('Flaky API', {
-  attempts: 3, delay: 1000, backoff: 2
-}, () => fetchFlakyApi());
-```
-```
-[a] ... Flaky API [1/3]
-[a] ✗ Flaky API [1/3] 102ms (timeout)
-[b] ... Flaky API [2/3]
-[b] ✓ Flaky API [2/3] 89ms → {"status":"ok"}
+const data = await measure({ label: 'Slow API', timeout: 5000 }, () => fetchSlowApi());
+// > 5s → ✗ Slow API 5.0s (Timeout (5.0s)), returns null
 ```
 
-### `measure.assert(label, fn)` — throw if null
+Works with `onError`:
 
 ```typescript
-const user = await measure.assert('Get user', () => fetchUser(1));
-// guaranteed non-null, or throws
+const data = await measure({ label: 'Slow API', timeout: 5000 }, () => fetchSlowApi(),
+  (error) => cachedData
+);
 ```
 
-### Budget — warn on slow operations
+## Budget
+
+Set `budget` to log a warning when a call exceeds the expected time (doesn't abort):
 
 ```typescript
-await measure({ label: 'DB query', budget: 100 }, async () => {
-  return await db.query('SELECT * FROM users');
-});
+await measure({ label: 'DB query', budget: 100 }, () => db.query('...'));
 // → [a] ✓ DB query 245ms → [...] ⚠ OVER BUDGET (100ms)
 ```
 
-### `createMeasure(prefix)` — scoped instances
+Combine both — budget warns, timeout enforces:
 
 ```typescript
-const api = createMeasure('api');
-const db = createMeasure('db');
-
-await api.measure('GET /users', async () => {
-  return await db.measure('SELECT', () => query('...'));
-});
-// → [api:a] ... GET /users
-// → [db:a] ✓ SELECT 44ms → [...]
-// → [api:a] ✓ GET /users 45ms → [...]
+await measure({ label: 'Query', budget: 100, timeout: 5000 }, () => query());
 ```
 
-### Bun.serve — handling Response
+## Nested Calls
 
-`measure()` returns `null` on error instead of throwing. In `Bun.serve`, the fetch handler **must** return a `Response` — returning `null` crashes. Two solutions:
+Pass a child `m` to create hierarchy:
 
 ```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 });
-  },
+await measure('Pipeline', async (m) => {
+  const user = await m('Fetch user', () => fetchUser(1));
+  const posts = await m('Fetch posts', () => fetchPosts(user.id));
+  return posts;
 });
 ```
 
-> **Why not plain `measure()`?** On error it returns `null`, not a `Response`. This is by design — `measure` never throws (except `.assert()`).
+```
+[a] ... Pipeline
+[a-a] ✓ Fetch user 82ms → {"id":1}
+[a-b] ✓ Fetch posts 45ms → [...]
+[a] ✓ Pipeline 128ms
+```
 
-### `configure(opts)` — runtime config
+Parallel:
 
 ```typescript
-configure({
-  silent: true,            // suppress all output
-  timestamps: true,        // prepend [HH:MM:SS.mmm]
-  maxResultLength: 200,    // truncate results (default: 80)
-  logger: (event) => {     // custom event handler
-    myTelemetry.track(event);
-  }
+await measure('Load all', async (m) => {
+  const [users, posts] = await Promise.all([
+    m('Users', () => fetchUsers()),
+    m('Posts', () => fetchPosts()),
+  ]);
 });
 ```
 
-Env: `MEASURE_SILENT=1`, `MEASURE_TIMESTAMPS=1`
+## Label Object
+
+The first argument can be a string or an object. Object fields:
 
-### `measure.timed(label, fn?)` — programmatic timing
+| Field | Type | Effect |
+|-------|------|--------|
+| `label` | `string` | Display name (required if object) |
+| `timeout` | `number` | Abort after N ms |
+| `budget` | `number` | Warn if slower than N ms |
+| any other | `any` | Logged as metadata |
 
 ```typescript
-const { result, duration } = await measure.timed('Fetch', () => fetchUsers());
+await measure({ label: 'Fetch user', userId: 1, timeout: 3000 }, () => fetchUser(1));
+// → [a] ... Fetch user (userId=1)
 ```
 
-### Utilities
+## Extensions
 
-```typescript
-import { safeStringify, formatDuration, resetCounter } from 'measure-fn';
+### `measure.wrap(label, fn)` — wrap once, measure every call
 
-safeStringify({ circular: self }); // handles circular refs, truncates
-formatDuration(91234);              // "1m 31s"
-resetCounter();                     // reset ID counter for tests
+```typescript
+const getUser = measure.wrap('Get user', fetchUser);
+await getUser(1);  // → [a] ✓ Get user 82ms
+await getUser(2);  // → [b] ✓ Get user 75ms
 ```
 
-## Why `measure` Never Throws
+### `measure.batch(label, items, fn, opts?)` — array with progress
 
-This is a deliberate design choice, not a shortcut.
+```typescript
+const results = await measure.batch('Process', userIds, async (id) => {
+  return await processUser(id);
+}, { every: 100 });
+// → [a] ... Process (500 items)
+// → [a] = 100/500 (1.2s, 83/s)
+// → [a] ✓ Process (500 items) 5.3s → "500/500 ok"
+```
 
-**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.
+### `measure.retry(label, opts, fn)` — retry with backoff
 
-**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
+const result = await measure.retry('Flaky API', {
+  attempts: 3, delay: 1000, backoff: 2
+}, () => fetchFlakyApi());
+// → [a] ✗ Flaky API [1/3] 102ms (timeout)
+// → [b] ✓ Flaky API [2/3] 89ms → {"status":"ok"}
+```
 
-**Handle recoverable errors inside, let measure catch the rest:**
+### `measure.timed(label, fn?)` — get duration programmatically
 
 ```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
-  }
-});
+const { result, duration } = await measure.timed('Fetch', () => fetchUsers());
 ```
 
-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:**
+### `createMeasure(prefix)` — scoped instance
 
 ```typescript
-// .assert() — re-throws, guarantees non-null
-const user = await measure.assert('Get user', () => fetchUser(1));
+const api = createMeasure('api');
+const db = createMeasure('db');
 
-// ?? — graceful fallback
-const user = (await measure('Get user', () => fetchUser(1))) ?? defaultUser;
+await api.measure('GET /users', async () => {
+  return await db.measure('SELECT', () => query('...'));
+});
+// → [api:a] ... GET /users
+// → [db:a] ✓ SELECT 44ms
+// → [api:a] ✓ GET /users 45ms
 ```
 
-**Summary:**
+### Annotations
 
-| 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 |
+```typescript
+await measure('Server ready');
+// → [a] = Server ready
+```
 
-**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:
+## Configure
 
 ```typescript
-// ✗ Ambiguous: did handler or measure catch the error?
-const response = await measure('Handle', () => handler(req));  // null = ???
+import { configure } from 'measure-fn';
 
-// ✓ 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)
+configure({
+  silent: true,            // suppress all output
+  timestamps: true,        // prepend [HH:MM:SS.mmm]
+  maxResultLength: 200,    // truncate results (default: 80)
+  logger: (event) => {     // custom event handler
+    myTelemetry.track(event);
+  }
+});
 ```
 
-## Types
+Env vars: `MEASURE_SILENT=1`, `MEASURE_TIMESTAMPS=1`
 
-```typescript
-export type MeasureEvent = {
-  type: 'start' | 'success' | 'error' | 'annotation';
-  id: string; label: string; depth: number;
-  duration?: number; result?: unknown; error?: unknown;
-  meta?: Record<string, unknown>; budget?: number;
-};
-export type TimedResult<T> = { result: T | null; duration: number };
-export type RetryOpts = { attempts?: number; delay?: number; backoff?: number };
-export type BatchOpts = { every?: number };
-```
+## Output Format
 
-## Zero Dependencies
+| Symbol | Meaning |
+|--------|---------|
+| `[a] ...` | started |
+| `[a] ✓` | success |
+| `[a] ✗` | error |
+| `[a] =` | annotation |
 
-Works in Bun, Node, Deno. Uses only `performance.now()` and `console`.
+IDs encode hierarchy: `[a]` → root, `[a-a]` → first child, `[a-b]` → second child.
 
 ## License
 

package/SKILL.md

@@ -104,11 +104,19 @@ const result = await measure.retry('External API', {
 }, () => callExternalService());
 ```
 
-### 7. Budget warnings for slow ops
+### 7. Budget warnings and timeouts
 
 ```typescript
+// Budget: warns but doesn't stop
 await measure({ label: 'DB query', budget: 100 }, () => heavyQuery());
 // → [a] ✓ DB query 245ms → [...] ⚠ OVER BUDGET (100ms)
+
+// Timeout: aborts after N ms, returns null
+await measure({ label: 'External API', timeout: 5000 }, () => fetchSlowApi());
+// > 5s → [a] ✗ External API 5.0s (Timeout (5.0s))
+
+// Both together: budget warns, timeout enforces
+await measure({ label: 'Query', budget: 100, timeout: 5000 }, () => db.query('...'));
 ```
 
 ### 8. Assert non-null results
@@ -139,29 +147,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()` re-throws on error with `.cause` = original error:
+
+```typescript
+await measure.assert('Op', () => work());
+// throws: Error('measure.assert: "Op" failed', { cause: originalError })
 ```
 
+## 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 +217,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
@@ -217,7 +238,7 @@ await measure('Outer', async (m) => {
 
 | Export | Use |
 |--------|-----|
-| `measure(label, fn?)` | Async measurement |
+| `measure(label, fn?, onError?)` | Async measurement (onError handles expected errors) |
 | `measureSync(label, fn?)` | Sync measurement |
 | `measure.wrap(label, fn)` | Decorator — wrap once, measure every call |
 | `measure.batch(label, items, fn, opts?)` | Array + progress |

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,152 @@ 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 rethrow returns null (caught by safety net)", async () => {
+        const out = captureConsole();
+        const result = await measure('Op', async () => { throw new Error('critical'); }, (e) => { throw e; });
+        out.restore();
+        expect(result).toBeNull();
+    });
+
+    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("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');
+    });
+
+    test("if onError itself throws, returns null instead of crashing", async () => {
+        const out = captureConsole();
+        const result = await measure('Primary DB', async () => {
+            throw new Error('primary failed');
+        }, (error) => {
+            // fallback DB call also fails
+            throw new Error('backup DB also failed');
+        });
+        out.restore();
+        expect(result).toBeNull();
+        // should log both errors
+        expect(out.errors.some(l => l.includes('primary failed'))).toBe(true);
+        expect(out.errors.some(l => l.includes('backup DB also failed'))).toBe(true);
+    });
+});
+
+// ─── timeout ─────────────────────────────────────────────────────────
+
+describe("timeout", () => {
+    beforeEach(() => {
+        resetCounter();
+        configure({ silent: false, logger: null, timestamps: false });
+    });
+
+    test("aborts and returns null if function exceeds timeout", async () => {
+        const out = captureConsole();
+        const result = await measure(
+            { label: 'Slow op', timeout: 50 },
+            async () => {
+                await new Promise(r => setTimeout(r, 200));
+                return 'done';
+            }
+        );
+        out.restore();
+        expect(result).toBeNull();
+        expect(out.errors.some(l => l.includes('Timeout'))).toBe(true);
+    });
+
+    test("succeeds if function completes within timeout", async () => {
+        const out = captureConsole();
+        const result = await measure(
+            { label: 'Fast op', timeout: 200 },
+            async () => {
+                await new Promise(r => setTimeout(r, 10));
+                return 'done';
+            }
+        );
+        out.restore();
+        expect(result).toBe('done');
+    });
+
+    test("timeout with onError returns fallback", async () => {
+        const out = captureConsole();
+        const result = await measure(
+            { label: 'Slow op', timeout: 50 },
+            async () => {
+                await new Promise(r => setTimeout(r, 200));
+                return 'done';
+            },
+            (error) => 'timed-out'
+        );
+        out.restore();
+        expect(result).toBe('timed-out');
+    });
+});
 // ─── measure.wrap ────────────────────────────────────────────────────
 
 describe("measure.wrap", () => {

package/index.ts

@@ -115,6 +115,12 @@ const extractBudget = (actionInternal: string | object): number | undefined => {
   return undefined;
 };
 
+const extractTimeout = (actionInternal: string | object): number | undefined => {
+  if (typeof actionInternal !== 'object' || actionInternal === null) return undefined;
+  if ('timeout' in actionInternal) return Number((actionInternal as any).timeout);
+  return undefined;
+};
+
 const extractMeta = (actionInternal: string | object): Record<string, unknown> | undefined => {
   if (typeof actionInternal !== 'object' || actionInternal === null) return undefined;
   const details = { ...actionInternal };
@@ -214,16 +220,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,12 +262,14 @@ 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 };
     const label = buildActionLabel(actionInternal);
     const budget = extractBudget(actionInternal);
+    const timeout = extractTimeout(actionInternal);
 
     const currentId = toAlpha(parentIdChain.pop() ?? 0);
     const fullIdChain = [...parentIdChain, currentId];
@@ -277,7 +286,17 @@ const createMeasureImpl = (prefix?: string, counterRef?: { value: number }) => {
     const measureForNextLevel = createNestedResolver(true, fullIdChain, childCounterRef, depth, _measureInternal, prefix);
 
     try {
-      const result = await fnInternal(measureForNextLevel as MeasureFn);
+      let result: U;
+      if (timeout && timeout > 0) {
+        result = await Promise.race([
+          fnInternal(measureForNextLevel as MeasureFn),
+          new Promise<never>((_, reject) =>
+            setTimeout(() => reject(new Error(`Timeout (${formatDuration(timeout)})`)), timeout)
+          ),
+        ]);
+      } else {
+        result = await fnInternal(measureForNextLevel as MeasureFn);
+      }
       const duration = performance.now() - start;
       emit({ type: 'success', id: idStr, label, depth, duration, result, budget }, prefix);
       return result;
@@ -285,6 +304,15 @@ 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) {
+        try {
+          return onError(error);
+        } catch (onErrorError) {
+          emit({ type: 'error', id: idStr, label: `${label} (onError)`, depth, duration: performance.now() - start, error: onErrorError, budget }, prefix);
+          _lastError = onErrorError;
+          return null;
+        }
+      }
       return null;
     }
   };
@@ -334,10 +362,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.6.0",
   "type": "module",
   "private": false,
   "description": "Zero-dependency function performance measurement with hierarchical logging",
@@ -29,4 +30,4 @@
     "test": "bun test",
     "example": "bun run example.ts"
   }
-}
+}