measure-fn 3.5.0 → 3.7.0

package/README.md

@@ -1,302 +1,262 @@
-# 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.
+<p align="center">
+  <b>Replace try-catch + timing boilerplate in TypeScript with a single line of code.</b>
+</p>
 
-```
-[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"
-```
+<p align="center">
+  <a href="https://www.npmjs.com/package/measure-fn"><img src="https://img.shields.io/npm/v/measure-fn.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/measure-fn"><img src="https://img.shields.io/npm/dm/measure-fn.svg" alt="npm downloads"></a>
+  <a href="https://github.com/7flash/measure-fn/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License"></a>
+</p>
 
-No setup. No dashboards. Just wrap your functions.
+Whenever a function needs error handling so it doesn't crash, and timing so you know how long it took, you usually end up adding this boilerplate manually:
 
-## Install
+**Before:**
 
-```sh
-bun add measure-fn
+```typescript
+let users = null;
+try {
+  const start = performance.now();
+  users = await fetchUsers();
+  const ms = (performance.now() - start).toFixed(2);
+  console.log(`[a] ··········· ${ms}ms → ${JSON.stringify(users)}`);
+} catch (e) {
+  console.log(`[a] ✗ Fetch users (${e.message})`);
+  console.error(e.stack);
+}
 ```
 
-## Quick Start
+**After:** measure-fn does the exact same thing in one line. Completely type-safe (infers `T | null`) and never crashes.
 
 ```typescript
-import { measure, measureSync } from 'measure-fn';
+import { measure } 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());
+// → [a] ··········· 86ms → [{"id":1},{"id":2}]
 ```
 
-## Output Format
+## Installation
 
-| 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` |
+```sh
+npm install measure-fn
+# or bun add / pnpm add / yarn add
+```
 
-**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 automatically:
 
-## API
+- 🛡️ **Catches errors** → logs `✗` with a stack trace and returns `null` (no unhandled rejections)
+- ⏱️ **Logs timing** → prints `label Nms → result` using `performance.now()`
+- 🌳 **Assigns a trace ID** → `[a]`, `[b]`, `[a-a]` for zero-config nested hierarchy
 
-### `measure(label, fn?)` — async
+## 🌳 Nested Calls (Tracing)
 
-```typescript
-// Simple
-const user = await measure('Fetch user', () => fetchUser(1));
+Pass a child `m` function to get hierarchical APM-like tracing for free:
 
-// 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 user = await m('Fetch user', () => fetchUser(1));
+  const posts = await m('Fetch posts', () => fetchPosts(user.id));
+  return posts;
 });
+```
 
-// Annotation
-await measure('checkpoint');
+```
+[a] ... Pipeline
+[a-a] ·········· 82ms → {"id":1}
+[a-b] ··········· 45ms → [...]
+[a] ········ 128ms
 ```
 
-### `measureSync(label, fn?)` — synchronous
+Parallel execution works cleanly too:
 
 ```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));
+await measure('Load all', async (m) => {
+  const [users, posts] = await Promise.all([
+    m('Users', () => fetchUsers()),
+    m('Posts', () => fetchPosts()),
+  ]);
 });
 ```
 
-### `measure.wrap(label, fn)` — decorator
+## 🛡️ Error Handling
 
-Wrap a function once, every call is measured:
+By default, errors return `null` so your pipelines can continue safely:
 
 ```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('Fetch user', () => fetchUser(1));
+// If it throws → logs ✗, user = null
 ```
 
-### `measure.batch(label, items, fn, opts?)` — array processing with progress
+**Custom Fallbacks:** Pass `onError` as the 3rd argument:
 
 ```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"
+const user = await measure('Fetch user', () => fetchUser(1),
+  (error) => defaultUser
+);
+// If it throws → logs ✗, user = defaultUser
 ```
 
-### `measure.retry(label, opts, fn)` — retry with backoff
-
-```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"}
-```
+If the `onError` fallback itself throws, that's also safely caught and returns `null`. measure never crashes.
 
-### `measure.assert(label, fn)` — throw if null
+**Fail-Fast (`.assert`):** Use `.assert()` when you need a guaranteed non-null result:
 
 ```typescript
 const user = await measure.assert('Get user', () => fetchUser(1));
-// guaranteed non-null, or throws
+// If it throws → logs ✗, re-throws with .cause = original error
 ```
 
-### Budget — warn on slow operations
+| Pattern | On error | Return Type |
+|---------|----------|-------------|
+| `measure(label, fn)` | returns `null` | `T \| null` |
+| `measure(label, fn, onError)` | returns `onError(error)` | `T` |
+| `measure.assert(label, fn)` | throws with `.cause` | `T` |
 
-```typescript
-await measure({ label: 'DB query', budget: 100 }, async () => {
-  return await db.query('SELECT * FROM users');
-});
-// → [a] ✓ DB query 245ms → [...] ⚠ OVER BUDGET (100ms)
-```
+## 🚦 Timeouts & Budgets
 
-### `createMeasure(prefix)` — scoped instances
+The first argument can be a label string, or an options object:
 
-```typescript
-const api = createMeasure('api');
-const db = createMeasure('db');
+| Field | Type | Effect |
+|-------|------|--------|
+| `label` | `string` | Display name (required if object) |
+| `timeout` | `number` | Aborts after N ms (returns `null`) |
+| `budget` | `number` | Warns if slower than N ms (doesn't abort) |
+| any other | `any` | Logged inline as context metadata |
 
-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 → [...]
+**Timeout** (enforce):
+
+```typescript
+const data = await measure({ label: 'Slow API', timeout: 5000 }, () => fetchSlowApi());
+// > 5s → ✗ Slow API 5.0s (Timeout (5.0s)), returns null
 ```
 
-### Bun.serve — handling Response
+Works with `onError` fallback too.
 
-`measure()` returns `null` on error instead of throwing. In `Bun.serve`, the fetch handler **must** return a `Response` — returning `null` crashes. Two solutions:
+**Budget** (warn):
 
 ```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({ label: 'DB query', budget: 100 }, () => db.query('...'));
+// → [a] ········ 245ms → [...] ⚠ OVER BUDGET (100ms)
 ```
 
-> **Why not plain `measure()`?** On error it returns `null`, not a `Response`. This is by design — `measure` never throws (except `.assert()`).
+Combine both — budget warns early, timeout enforces a hard stop:
+
+```typescript
+await measure({ label: 'Query', budget: 100, timeout: 5000 }, () => query());
+```
 
-### `configure(opts)` — runtime config
+**Metadata context:**
 
 ```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({ label: 'Fetch user', userId: 1 }, () => fetchUser(1));
+// → [a] ... Fetch user (userId=1)
 ```
 
-Env: `MEASURE_SILENT=1`, `MEASURE_TIMESTAMPS=1`
+## 🧰 Extensions
 
-### `measure.timed(label, fn?)` — programmatic timing
+### `measure.wrap(label, fn)`
+
+Wrap a function once, measure every time it's called:
 
 ```typescript
-const { result, duration } = await measure.timed('Fetch', () => fetchUsers());
+const getUser = measure.wrap('Get user', fetchUser);
+await getUser(1);  // → [a] ········ 82ms
+await getUser(2);  // → [b] ········ 75ms
 ```
 
-### Utilities
+### `measure.batch(label, items, fn, opts?)`
 
-```typescript
-import { safeStringify, formatDuration, resetCounter } from 'measure-fn';
+Process arrays with built-in progress logs:
 
-safeStringify({ circular: self }); // handles circular refs, truncates
-formatDuration(91234);              // "1m 31s"
-resetCounter();                     // reset ID counter for tests
+```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] ················· 5.3s → "500/500 ok"
 ```
 
-## Error Handling
+### `measure.retry(label, opts, fn)`
 
-`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`:
+Automatic retries with delay and backoff:
 
 ```typescript
-// Default: returns null on error
-const user = await measure('Fetch user', () => fetchUser(1));
+const result = await measure.retry('Flaky API', {
+  attempts: 3, delay: 1000, backoff: 2
+}, () => fetchFlakyApi());
+// → [a] ✗ Flaky API [1/3] 102ms (timeout)
+// → [b] ················· 89ms → {"status":"ok"}
+```
 
-// With recovery: returns fallback on error
-const user = await measure('Fetch user', () => fetchUser(1),
-  (error) => defaultUser
-);
+### `measure.timed(label, fn?)`
 
-// 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
-  }
-);
+Get duration programmatically alongside the result:
 
-// Rethrow all: transparent observability (same as .assert())
-const user = await measure('Fetch user', () => fetchUser(1),
-  (error) => { throw error }
-);
+```typescript
+const { result, duration } = await measure.timed('Fetch', () => fetchUsers());
 ```
 
-**Bun.serve — never return null:**
+### `createMeasure(prefix)`
+
+Scoped instances with custom prefixes:
 
 ```typescript
-Bun.serve({
-  fetch: (req) => measure(
-    { label: `${req.method} ${req.url}` },
-    () => handleRequest(req),
-    (error) => new Response(`Error: ${error.message}`, { status: 500 })
-  ),
+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] ······ 44ms
+// → [api:a] ·········· 45ms
 ```
 
-**`.assert()` is sugar for the rethrow pattern:**
+### Annotations & Sync
 
 ```typescript
-// These are equivalent:
-await measure.assert('Op', () => work());
-await measure('Op', () => work(), (e) => { throw e });
+import { measureSync } from 'measure-fn';
 
-// .assert() wraps the error with .cause for inspection:
-// e.message → 'measure.assert: "Op" failed'
-// e.cause   → original error
-```
-
-**Summary:**
+const config = measureSync('Parse config', () => JSON.parse(raw));
 
-| 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 |
+await measure('Server ready');
+// → [a] = Server ready
+```
 
-## Types
+## ⚙️ Configuration
 
 ```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 };
+import { configure } from 'measure-fn';
+
+configure({
+  silent: true,            // suppress all output
+  timestamps: true,        // prepend [HH:MM:SS.mmm]
+  maxResultLength: 200,    // truncate results (default: 80)
+  dotEndLabel: false,      // show full label on end lines (default: true = dots)
+  dotChar: '.',            // character for dot fill (default: '·')
+  logger: (event) => {     // custom event handler
+    myTelemetry.track(event);
+  }
+});
 ```
 
-## Zero Dependencies
+Env vars: `MEASURE_SILENT=1`, `MEASURE_TIMESTAMPS=1`
+
+## Output Format
+
+| Symbol | Meaning | Example |
+|--------|---------|---------|
+| `...` | Started | `[a] ... Fetch users` |
+| `···` | Success | `[a] ··········· 86ms → [...]` |
+| `✗` | Error | `[a] ✗ ··········· (Network Error)` |
+| `=` | Annotation | `[a] = Server ready` |
 
-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
@@ -170,11 +178,11 @@ Bun.serve({
 });
 ```
 
-`.assert()` is sugar for `(e) => { throw e }` with `.cause`:
+`.assert()` re-throws on error with `.cause` = original error:
 
 ```typescript
 await measure.assert('Op', () => work());
-// equivalent to: measure('Op', () => work(), (e) => { throw e })
+// throws: Error('measure.assert: "Op" failed', { cause: originalError })
 ```
 
 ## Error Model
@@ -230,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/index.test.ts

@@ -31,12 +31,12 @@ describe("measure (async)", () => {
         expect(result).toBe(42);
     });
 
-    test("logs start ... and success ✓ with result", async () => {
+    test("logs start ... and success with result", async () => {
         const out = captureConsole();
         await measure("fetch", async () => "ok");
         out.restore();
         expect(out.logs[0]).toBe("[a] ... fetch");
-        expect(out.logs[1]).toMatch(/\[a\] ✓ fetch .* → "ok"/);
+        expect(out.logs[1]).toMatch(/\[a\] ····· .* → "ok"/);
     });
 
     test("no arrow for undefined", async () => {
@@ -123,7 +123,7 @@ describe("measureSync", () => {
         measureSync("compute", () => 100);
         out.restore();
         expect(out.logs.length).toBe(1);
-        expect(out.logs[0]).toMatch(/\[a\] ✓ compute .* → 100/);
+        expect(out.logs[0]).toMatch(/\[a\] ······· .* → 100/);
     });
 
     test("with children = start + end", () => {
@@ -131,8 +131,8 @@ describe("measureSync", () => {
         measureSync("parent", (m) => { m("child", () => 10); return 20; });
         out.restore();
         expect(out.logs[0]).toBe("[a] ... parent");
-        expect(out.logs[1]).toMatch(/\[a-a\] ✓ child .* → 10/);
-        expect(out.logs[2]).toMatch(/\[a\] ✓ parent .* → 20/);
+        expect(out.logs[1]).toMatch(/\[a-a\] ····· .* → 10/);
+        expect(out.logs[2]).toMatch(/\[a\] ······ .* → 20/);
     });
 
     test("error returns null", () => {
@@ -354,7 +354,7 @@ describe("measure.retry", () => {
         const r = await measure.retry("op", { attempts: 3, delay: 10 }, async () => 42);
         out.restore();
         expect(r).toBe(42);
-        expect(out.logs[1]).toContain("✓");
+        expect(out.logs[1]).not.toContain("✗");
         expect(out.logs[0]).toContain("[1/3]");
     });
 
@@ -368,7 +368,7 @@ describe("measure.retry", () => {
         out.restore();
         expect(r).toBe("ok");
         expect(out.logs.filter(l => l.includes("✗")).length).toBe(2);
-        expect(out.logs.filter(l => l.includes("✓")).length).toBe(1);
+        expect(out.logs.filter(l => !l.includes("✗") && !l.includes("...")).length).toBe(1);
     });
 
     test("all attempts exhausted returns null", async () => {
@@ -463,16 +463,11 @@ describe("onError (3rd argument)", () => {
         expect(captured).toBe(original);
     });
 
-    test("onError can rethrow (same as assert)", async () => {
+    test("onError rethrow returns null (caught by safety net)", 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);
-        }
+        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 () => {
@@ -487,27 +482,6 @@ describe("onError (3rd argument)", () => {
         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) });
@@ -533,8 +507,72 @@ describe("onError (3rd argument)", () => {
         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", () => {
@@ -551,7 +589,7 @@ describe("measure.wrap", () => {
         out.restore();
         expect(r).toBe(42);
         expect(out.logs[0]).toBe("[a] ... double");
-        expect(out.logs[1]).toContain("✓");
+        expect(out.logs[1]).not.toContain("✗");
     });
 
     test("multiple calls get sequential IDs", async () => {
@@ -572,7 +610,7 @@ describe("measure.wrap", () => {
         const r = wrapped(7);
         out.restore();
         expect(r).toBe(21);
-        expect(out.logs[0]).toContain("✓ triple");
+        expect(out.logs[0]).toContain("······");
     });
 });
 
@@ -590,7 +628,6 @@ describe("measure.batch", () => {
         out.restore();
         expect(results).toEqual([2, 4, 6]);
         expect(out.logs[0]).toContain("3 items");
-        expect(out.logs.at(-1)).toContain("✓");
         expect(out.logs.at(-1)).toContain("3/3 ok");
     });
 

package/index.ts

@@ -54,7 +54,7 @@ const formatDuration = (ms: number): string => {
 // ─── Timestamps ──────────────────────────────────────────────────────
 
 let timestamps =
-  process.env.MEASURE_TIMESTAMPS === '1' || process.env.MEASURE_TIMESTAMPS === 'true';
+  typeof process !== 'undefined' && (process.env.MEASURE_TIMESTAMPS === '1' || process.env.MEASURE_TIMESTAMPS === 'true');
 
 const ts = (): string => {
   if (!timestamps) return '';
@@ -83,7 +83,10 @@ export type MeasureEvent = {
 // ─── Configuration ───────────────────────────────────────────────────
 
 export let silent =
-  process.env.MEASURE_SILENT === '1' || process.env.MEASURE_SILENT === 'true';
+  typeof process !== 'undefined' && (process.env.MEASURE_SILENT === '1' || process.env.MEASURE_SILENT === 'true');
+
+let dotEndLabel = true;
+let dotChar = '·';
 
 export let logger: ((event: MeasureEvent) => void) | null = null;
 
@@ -92,6 +95,8 @@ export type ConfigureOpts = {
   logger?: ((event: MeasureEvent) => void) | null;
   timestamps?: boolean;
   maxResultLength?: number;
+  dotEndLabel?: boolean;
+  dotChar?: string;
 };
 
 export const configure = (opts: ConfigureOpts) => {
@@ -99,6 +104,8 @@ export const configure = (opts: ConfigureOpts) => {
   if (opts.logger !== undefined) logger = opts.logger;
   if (opts.timestamps !== undefined) timestamps = opts.timestamps;
   if (opts.maxResultLength !== undefined) maxResultLen = opts.maxResultLength;
+  if (opts.dotEndLabel !== undefined) dotEndLabel = opts.dotEndLabel;
+  if (opts.dotChar !== undefined) dotChar = opts.dotChar;
 };
 
 // ─── Shared Helpers ──────────────────────────────────────────────────
@@ -115,6 +122,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 };
@@ -151,20 +164,22 @@ const defaultLogger = (event: MeasureEvent, prefix?: string) => {
       console.log(`${t}${id} ... ${event.label}${formatMeta(event.meta)}`);
       break;
     case 'success': {
+      const endLabel = dotEndLabel ? dotChar.repeat(event.label.length) : event.label;
       const resultStr = event.result !== undefined ? safeStringify(event.result) : '';
       const arrow = resultStr ? ` → ${resultStr}` : '';
       const budgetWarn = event.budget && event.duration! > event.budget
         ? ` ⚠ OVER BUDGET (${formatDuration(event.budget)})`
         : '';
-      console.log(`${t}${id} ✓ ${event.label} ${formatDuration(event.duration!)}${arrow}${budgetWarn}`);
+      console.log(`${t}${id} ${endLabel} ${formatDuration(event.duration!)}${arrow}${budgetWarn}`);
       break;
     }
     case 'error': {
+      const endLabel = dotEndLabel ? dotChar.repeat(event.label.length) : event.label;
       const errorMsg = event.error instanceof Error ? event.error.message : String(event.error);
       const budgetWarn = event.budget && event.duration! > event.budget
         ? ` ⚠ OVER BUDGET (${formatDuration(event.budget)})`
         : '';
-      console.log(`${t}${id} ✗ ${event.label} ${formatDuration(event.duration!)} (${errorMsg})${budgetWarn}`);
+      console.log(`${t}${id} ✗ ${endLabel} ${formatDuration(event.duration!)} (${errorMsg})${budgetWarn}`);
       if (event.error instanceof Error) {
         console.error(`${id}`, event.error.stack ?? event.error.message);
         if (event.error.cause) {
@@ -263,6 +278,7 @@ const createMeasureImpl = (prefix?: string, counterRef?: { value: number }) => {
     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];
@@ -279,7 +295,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;
@@ -287,7 +313,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) return onError(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;
     }
   };
@@ -296,8 +330,7 @@ const createMeasureImpl = (prefix?: string, counterRef?: { value: number }) => {
     fnInternal: (measure: MeasureSyncFn) => U,
     actionInternal: string | object,
     parentIdChain: (string | number)[],
-    depth: number,
-    onError?: (error: unknown) => any
+    depth: number
   ): U | null => {
     const start = performance.now();
     const childCounterRef = { value: 0 };
@@ -330,7 +363,6 @@ 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;
     }
   };

package/package.json

@@ -3,7 +3,7 @@
   "module": "index.ts",
   "main": "./index.ts",
   "types": "./index.ts",
-  "version": "3.5.0",
+  "version": "3.7.0",
   "type": "module",
   "private": false,
   "description": "Zero-dependency function performance measurement with hierarchical logging",