measure-fn 3.6.0 → 3.7.0

package/README.md

@@ -2,154 +2,175 @@
   <img src="banner.png" alt="measure-fn" width="100%" />
 </p>
 
-Wrap functions with automatic try-catch, timing, timeouts, and structured logging.
+<p align="center">
+  <b>Replace try-catch + timing boilerplate in TypeScript with a single line of code.</b>
+</p>
 
-```sh
-bun add measure-fn
+<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>
+
+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:
+
+**Before:**
+
+```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);
+}
 ```
 
+**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';
 
 const users = await measure('Fetch users', () => fetchUsers());
-const config = measureSync('Parse config', () => JSON.parse(raw));
+// → [a] ··········· 86ms → [{"id":1},{"id":2}]
 ```
 
-```
-[a] ... Fetch users
-[a] ✓ Fetch users 86ms → [{"id":1},{"id":2}]
-[b] ✓ Parse config 0.09ms → {"env":"prod","port":3000}
-```
+## Installation
 
-## Defaults
+```sh
+npm install measure-fn
+# or bun add / pnpm add / yarn add
+```
 
-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
+## ✨ Defaults
 
-## Error Handling
+Every `measure` call automatically:
 
-By default, errors return `null`:
+- 🛡️ **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
 
-```typescript
-const user = await measure('Fetch user', () => fetchUser(1));
-// throws → logs ✗, user = null
-```
+## 🌳 Nested Calls (Tracing)
 
-Pass `onError` as 3rd argument to provide a fallback:
+Pass a child `m` function to get hierarchical APM-like tracing for free:
 
 ```typescript
-const user = await measure('Fetch user', () => fetchUser(1),
-  (error) => defaultUser
-);
-// throws → logs ✗, user = defaultUser
+await measure('Pipeline', async (m) => {
+  const user = await m('Fetch user', () => fetchUser(1));
+  const posts = await m('Fetch posts', () => fetchPosts(user.id));
+  return posts;
+});
 ```
 
-If `onError` itself throws, that's also caught — returns `null`. Measure never crashes.
+```
+[a] ... Pipeline
+[a-a] ·········· 82ms → {"id":1}
+[a-b] ··········· 45ms → [...]
+[a] ········ 128ms
+```
 
-Use `.assert()` when you need a guaranteed non-null result:
+Parallel execution works cleanly too:
 
 ```typescript
-const user = await measure.assert('Get user', () => fetchUser(1));
-// throws → logs ✗, re-throws with .cause = original error
+await measure('Load all', async (m) => {
+  const [users, posts] = await Promise.all([
+    m('Users', () => fetchUsers()),
+    m('Posts', () => fetchPosts()),
+  ]);
+});
 ```
 
-| Pattern | On error |
-|---------|----------|
-| `measure(label, fn)` | returns `null` |
-| `measure(label, fn, onError)` | returns `onError(error)` |
-| `measure.assert(label, fn)` | throws with `.cause` |
+## 🛡️ Error Handling
 
-## Timeout
-
-Set `timeout` in the label object to abort after N milliseconds:
+By default, errors return `null` so your pipelines can continue safely:
 
 ```typescript
-const data = await measure({ label: 'Slow API', timeout: 5000 }, () => fetchSlowApi());
-// > 5s → ✗ Slow API 5.0s (Timeout (5.0s)), returns null
+const user = await measure('Fetch user', () => fetchUser(1));
+// If it throws → logs ✗, user = null
 ```
 
-Works with `onError`:
+**Custom Fallbacks:** Pass `onError` as the 3rd argument:
 
 ```typescript
-const data = await measure({ label: 'Slow API', timeout: 5000 }, () => fetchSlowApi(),
-  (error) => cachedData
+const user = await measure('Fetch user', () => fetchUser(1),
+  (error) => defaultUser
 );
+// If it throws → logs ✗, user = defaultUser
 ```
 
-## Budget
+If the `onError` fallback itself throws, that's also safely caught and returns `null`. measure never crashes.
 
-Set `budget` to log a warning when a call exceeds the expected time (doesn't abort):
+**Fail-Fast (`.assert`):** Use `.assert()` when you need a guaranteed non-null result:
 
 ```typescript
-await measure({ label: 'DB query', budget: 100 }, () => db.query('...'));
-// → [a] ✓ DB query 245ms → [...] ⚠ OVER BUDGET (100ms)
+const user = await measure.assert('Get user', () => fetchUser(1));
+// If it throws → logs ✗, re-throws with .cause = original error
 ```
 
-Combine both — budget warns, timeout enforces:
+| 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: 'Query', budget: 100, timeout: 5000 }, () => query());
-```
+## 🚦 Timeouts & Budgets
 
-## Nested Calls
+The first argument can be a label string, or an options object:
 
-Pass a child `m` to create hierarchy:
+| 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 |
+
+**Timeout** (enforce):
 
 ```typescript
-await measure('Pipeline', async (m) => {
-  const user = await m('Fetch user', () => fetchUser(1));
-  const posts = await m('Fetch posts', () => fetchPosts(user.id));
-  return posts;
-});
+const data = await measure({ label: 'Slow API', timeout: 5000 }, () => fetchSlowApi());
+// > 5s → ✗ Slow API 5.0s (Timeout (5.0s)), returns null
 ```
 
-```
-[a] ... Pipeline
-[a-a] ✓ Fetch user 82ms → {"id":1}
-[a-b] ✓ Fetch posts 45ms → [...]
-[a] ✓ Pipeline 128ms
-```
+Works with `onError` fallback too.
 
-Parallel:
+**Budget** (warn):
 
 ```typescript
-await measure('Load all', async (m) => {
-  const [users, posts] = await Promise.all([
-    m('Users', () => fetchUsers()),
-    m('Posts', () => fetchPosts()),
-  ]);
-});
+await measure({ label: 'DB query', budget: 100 }, () => db.query('...'));
+// → [a] ········ 245ms → [...] ⚠ OVER BUDGET (100ms)
 ```
 
-## Label Object
+Combine both — budget warns early, timeout enforces a hard stop:
 
-The first argument can be a string or an object. Object fields:
+```typescript
+await measure({ label: 'Query', budget: 100, timeout: 5000 }, () => query());
+```
 
-| 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 |
+**Metadata context:**
 
 ```typescript
-await measure({ label: 'Fetch user', userId: 1, timeout: 3000 }, () => fetchUser(1));
+await measure({ label: 'Fetch user', userId: 1 }, () => fetchUser(1));
 // → [a] ... Fetch user (userId=1)
 ```
 
-## Extensions
+## 🧰 Extensions
+
+### `measure.wrap(label, fn)`
 
-### `measure.wrap(label, fn)` — wrap once, measure every call
+Wrap a function once, measure every time it's called:
 
 ```typescript
 const getUser = measure.wrap('Get user', fetchUser);
-await getUser(1);  // → [a] ✓ Get user 82ms
-await getUser(2);  // → [b] ✓ Get user 75ms
+await getUser(1);  // → [a] ········ 82ms
+await getUser(2);  // → [b] ········ 75ms
 ```
 
-### `measure.batch(label, items, fn, opts?)` — array with progress
+### `measure.batch(label, items, fn, opts?)`
+
+Process arrays with built-in progress logs:
 
 ```typescript
 const results = await measure.batch('Process', userIds, async (id) => {
@@ -157,26 +178,32 @@ const results = await measure.batch('Process', userIds, async (id) => {
 }, { every: 100 });
 // → [a] ... Process (500 items)
 // → [a] = 100/500 (1.2s, 83/s)
-// → [a] ✓ Process (500 items) 5.3s → "500/500 ok"
+// → [a] ················· 5.3s → "500/500 ok"
 ```
 
-### `measure.retry(label, opts, fn)` — retry with backoff
+### `measure.retry(label, opts, fn)`
+
+Automatic retries with delay and backoff:
 
 ```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"}
+// → [b] ················· 89ms → {"status":"ok"}
 ```
 
-### `measure.timed(label, fn?)` — get duration programmatically
+### `measure.timed(label, fn?)`
+
+Get duration programmatically alongside the result:
 
 ```typescript
 const { result, duration } = await measure.timed('Fetch', () => fetchUsers());
 ```
 
-### `createMeasure(prefix)` — scoped instance
+### `createMeasure(prefix)`
+
+Scoped instances with custom prefixes:
 
 ```typescript
 const api = createMeasure('api');
@@ -186,18 +213,22 @@ 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
+// → [db:a] ······ 44ms
+// → [api:a] ·········· 45ms
 ```
 
-### Annotations
+### Annotations & Sync
 
 ```typescript
+import { measureSync } from 'measure-fn';
+
+const config = measureSync('Parse config', () => JSON.parse(raw));
+
 await measure('Server ready');
 // → [a] = Server ready
 ```
 
-## Configure
+## ⚙️ Configuration
 
 ```typescript
 import { configure } from 'measure-fn';
@@ -206,6 +237,8 @@ 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);
   }
@@ -216,12 +249,12 @@ Env vars: `MEASURE_SILENT=1`, `MEASURE_TIMESTAMPS=1`
 
 ## Output Format
 
-| Symbol | Meaning |
-|--------|---------|
-| `[a] ...` | started |
-| `[a] ✓` | success |
-| `[a] ✗` | error |
-| `[a] =` | annotation |
+| Symbol | Meaning | Example |
+|--------|---------|---------|
+| `...` | Started | `[a] ... Fetch users` |
+| `···` | Success | `[a] ··········· 86ms → [...]` |
+| `✗` | Error | `[a] ✗ ··········· (Network Error)` |
+| `=` | Annotation | `[a] = Server ready` |
 
 IDs encode hierarchy: `[a]` → root, `[a-a]` → first child, `[a-b]` → second child.
 

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 () => {
@@ -589,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 () => {
@@ -610,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("······");
     });
 });
 
@@ -628,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 ──────────────────────────────────────────────────
@@ -157,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) {

package/package.json

@@ -3,7 +3,7 @@
   "module": "index.ts",
   "main": "./index.ts",
   "types": "./index.ts",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "type": "module",
   "private": false,
   "description": "Zero-dependency function performance measurement with hierarchical logging",
@@ -30,4 +30,4 @@
     "test": "bun test",
     "example": "bun run example.ts"
   }
-}
+}