measure-fn 2.0.0

package/README.md

@@ -0,0 +1,285 @@
+# measure-fn
+
+**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, beautifully.
+
+```
+> [a] Build Dashboard
+> [a-a] Fetch users
+< [a-a] ✓ 245.12ms
+> [a-b] Process users
+> [a-b-a] Enrich user (userId=1)
+< [a-b-a] ✓ 12.34ms
+> [a-b-b] Enrich user (userId=2)
+< [a-b-b] ✓ 11.89ms
+< [a-b] ✓ 25.67ms
+> [a-c] Generate report
+< [a-c] ✓ 8.91ms
+< [a] ✓ 281.23ms
+```
+
+No setup. No dashboards to configure. No telemetry SDKs. Just wrap your functions and your entire program becomes observable.
+
+## Why Structure Your Programs With measure-fn
+
+Most codebases are **opaque by default**. When something is slow, you add `console.time`. When something crashes, you add `try/catch`. When you need tracing, you integrate a monitoring SDK. You bolt observability on *after* the problems arrive.
+
+**measure-fn inverts this.** You structure your program with `measure` from the start, and you get:
+
+- ⏱️ **Every operation timed** — no more "which step is slow?"
+- 🌳 **Hierarchical trace** — see exactly how operations nest and compose
+- 🛡️ **Errors caught and logged automatically** — with stack traces, causes, and unique IDs for every operation
+- 📍 **Unique alphabetic IDs** — `[a-b-c]` tells you exactly which step in which pipeline failed
+- 🔄 **Zero disruption** — errors return `null`, they never crash your program. Handle failures, don't fight them.
+
+The result: your logs tell a **complete story**. You can read them top-to-bottom and understand exactly what happened, what took how long, and what failed — without adding a single breakpoint.
+
+### The Philosophy: Programs as Measured Pipelines
+
+Think of your program not as a flat list of statements, but as a **tree of measured operations**. Every meaningful unit of work — an API call, a database query, a transformation, a batch process — becomes a node in this tree.
+
+```typescript
+// ❌ Typical blind code
+async function processOrder(orderId: string) {
+  const order = await fetchOrder(orderId);
+  const inventory = await checkInventory(order.items);
+  await chargePayment(order);
+  await shipOrder(order);
+}
+
+// ✅ Measured code — observable from day one
+async function processOrder(orderId: string) {
+  await measure({ label: 'Process Order', orderId }, async (m) => {
+    const order = await m('Fetch order', () => fetchOrder(orderId));
+    if (!order) return; // error already logged + traced
+
+    await m('Check inventory', () => checkInventory(order.items));
+    await m('Charge payment', () => chargePayment(order));
+    await m('Ship order', () => shipOrder(order));
+  });
+}
+```
+
+The measured version costs you **one extra line per operation**. In return, you get timing, error isolation, hierarchical tracing, and structured logs — forever.
+
+## Install
+
+```sh
+bun add measure-fn
+# or
+npm install measure-fn
+```
+
+## Quick Start
+
+```typescript
+import { measure, measureSync } from 'measure-fn';
+
+// Label first, function second — reads like a sentence
+await measure('Fetch data', async () => {
+  const res = await fetch('https://api.example.com/data');
+  return res.json();
+});
+
+// Sync operations work the same way
+const config = measureSync('Parse config', () => {
+  return JSON.parse(configString);
+});
+```
+
+## API
+
+### `measure(label, fn?)` — async
+
+```typescript
+// Simple: wrap any async operation
+const user = await measure('Fetch user', async () => {
+  return await fetchUser(1);
+});
+
+// Nested: receive `m` for composing sub-operations into a tree
+await measure('Pipeline', async (m) => {
+  const user = await m('Get user', () => fetchUser(1));
+  const posts = await m('Get posts', () => fetchPosts(user.id));
+
+  // Arbitrarily deep nesting
+  await m('Enrich posts', async (m2) => {
+    for (const post of posts) {
+      await m2({ label: 'Get comments', postId: post.id }, () =>
+        fetchComments(post.id)
+      );
+    }
+  });
+});
+
+// Annotation — log a marker without timing anything
+await measure('checkpoint reached');
+```
+
+### `measureSync(label, fn?)` — synchronous
+
+```typescript
+const result = measureSync('Compute hash', () => {
+  return computeExpensiveHash(data);
+});
+
+// Nested sync operations
+measureSync('Build report', (m) => {
+  const data = m('Parse CSV', () => parseCSV(raw));
+  const summary = m('Summarize', () => summarize(data));
+  return summary;
+});
+```
+
+### Label formats
+
+Labels can be a string or an object with a `.label` property. Extra properties are logged as metadata — perfect for recording request IDs, user IDs, or any context:
+
+```typescript
+await measure('Simple string label', async () => fetchUser(1));
+
+await measure({ label: 'Fetch user', userId: 1, region: 'us-east' }, async () => fetchUser(1));
+// Logs: > [a] Fetch user (userId=1 region="us-east")
+```
+
+### `resetCounter()`
+
+Resets the global alphabetic ID counter. Essential for deterministic test output:
+
+```typescript
+import { resetCounter } from 'measure-fn';
+beforeEach(() => resetCounter());
+```
+
+## Error Handling — Errors Are Data, Not Crashes
+
+This is the most important design decision in `measure-fn`: **errors never propagate**. When a measured function throws:
+
+1. The error is logged with `✗`, the duration, and the error message
+2. The full stack trace and `cause` (if present) go to `console.error` with the operation's unique ID
+3. The function returns `null`
+
+```typescript
+const result = await measure('Risky operation', async () => {
+  throw new Error('Network timeout', { cause: { url: '/api', retries: 3 } });
+});
+
+// result === null — no crash, no try/catch needed
+```
+
+```
+> [a] Risky operation
+< [a] ✗ 2.31ms (Network timeout)
+[a] Error: Network timeout
+    at ... (stack trace)
+[a] Cause: { url: "/api", retries: 3 }
+```
+
+This makes your programs **resilient by default**. A failing sub-operation doesn't take down the parent — it returns `null` and you decide what to do:
+
+```typescript
+await measure('User Pipeline', async (m) => {
+  const user = await m('Get user', () => fetchUser(999));
+  if (user === null) {
+    // The error was already logged with full context.
+    // Skip dependent operations gracefully.
+    return;
+  }
+  await m('Get posts', () => fetchPosts(user.id));
+});
+```
+
+No try/catch pyramids. No error-swallowing. Every error is captured, attributed to a specific operation ID, and visible in plain text.
+
+## Output Format
+
+| Prefix | Meaning |
+|--------|---------|
+| `>` | Operation started |
+| `<` | Operation completed |
+| `=` | Annotation (label-only, no timing) |
+| `✓` | Success |
+| `✗` | Error |
+
+IDs are alphabetic and hierarchical: `[a]`, `[a-a]`, `[a-b]`, `[a-b-a]`, etc. After `z` it wraps: `aa`, `ab`, `ac`...
+
+Every ID is a **unique address** for that operation in that execution. You can grep for `[a-c-b]` and find exactly one operation — making log analysis trivial.
+
+## Real-World Patterns
+
+### Server Request Handler
+
+```typescript
+app.get('/api/dashboard', async (req, res) => {
+  const data = await measure({ label: 'GET /api/dashboard', ip: req.ip }, async (m) => {
+    const session = await m('Validate session', () => validateSession(req));
+    if (!session) return null;
+
+    const [users, stats] = await Promise.all([
+      m('Fetch users', () => db.users.all()),
+      m('Compute stats', () => computeStats()),
+    ]);
+
+    return { users, stats };
+  });
+
+  res.json(data ?? { error: 'Failed' });
+});
+```
+
+### Background Job
+
+```typescript
+async function processBatch(batchId: string) {
+  await measure({ label: 'Process Batch', batchId }, async (m) => {
+    const items = await m('Load items', () => loadBatch(batchId));
+    if (!items) return;
+
+    await m('Transform', async (m2) => {
+      for (const item of items) {
+        await m2({ label: 'Process item', itemId: item.id }, () => 
+          transform(item)
+        );
+      }
+    });
+
+    await m('Save results', () => saveBatch(batchId, items));
+  });
+}
+```
+
+### CLI Tool
+
+```typescript
+measureSync('Build Project', (m) => {
+  const config = m('Load config', () => loadConfig('./project.toml'));
+  if (!config) process.exit(1);
+
+  m('Compile', () => compile(config));
+  m('Bundle', () => bundle(config));
+  m('Write output', () => writeOutput(config.outDir));
+});
+```
+
+## Types
+
+```typescript
+export type MeasureFn = {
+  <U>(label: string | object, fn: () => Promise<U>): Promise<U | null>;
+  <U>(label: string | object, fn: (m: MeasureFn) => Promise<U>): Promise<U | null>;
+  (label: string | object): Promise<null>;
+};
+
+export type MeasureSyncFn = {
+  <U>(label: string | object, fn: () => U): U | null;
+  <U>(label: string | object, fn: (m: MeasureSyncFn) => U): U | null;
+  (label: string | object): null;
+};
+```
+
+## Zero Dependencies
+
+`measure-fn` has **zero runtime dependencies**. It uses only `performance.now()` and `console.log`/`console.error`. It works in Bun, Node, Deno, or any JavaScript runtime.
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: measure-fn
+description: Zero-dependency function performance measurement with hierarchical logging. Use this to structure ALL programs as measured, observable pipelines.
+---
+
+# measure-fn — Structured Program Measurement
+
+**Every program you write should be observable from day one.** `measure-fn` wraps any function — async or sync — with automatic performance timing, hierarchical structured logging, and graceful error isolation. No SDK, no config, no dashboards — just wrap your functions.
+
+## The Rule: If It Does Work, Measure It
+
+When building any program — a server, a CLI tool, a background job, a pipeline — **wrap every meaningful operation with `measure`**. This is not optional overhead; it's the difference between debugging blind and having a complete execution trace.
+
+```typescript
+import { measure } from 'measure-fn';
+
+// ❌ Don't write blind functions
+async function handleRequest(req) {
+  const user = await getUser(req.userId);
+  const data = await fetchData(user);
+  return transform(data);
+}
+
+// ✅ Make every step visible
+async function handleRequest(req) {
+  return await measure({ label: 'Handle Request', userId: req.userId }, async (m) => {
+    const user = await m('Get user', () => getUser(req.userId));
+    if (!user) return null; // error already logged
+    const data = await m('Fetch data', () => fetchData(user));
+    if (!data) return null;
+    return m('Transform', () => transform(data));
+  });
+}
+```
+
+## Installation
+
+```bash
+bun add measure-fn
+```
+
+## Core Patterns
+
+### 1. Label First, Function Second
+
+```typescript
+// Reads like a sentence: "measure 'Fetch users' by running this function"
+const users = await measure('Fetch users', () => fetchUsers());
+
+// Sync equivalent
+const config = measureSync('Load config', () => loadConfig());
+```
+
+### 2. Nested Measurement Trees
+
+The callback receives a nested `m` for composing sub-operations:
+
+```typescript
+await measure('Build Dashboard', async (m) => {
+  const data = await m('Fetch', () => fetchData());
+  await m('Process', async (m2) => {
+    await m2('Step A', () => stepA(data));
+    await m2('Step B', () => stepB(data));
+  });
+  await m('Render', () => render(data));
+});
+```
+
+Output:
+```
+> [a] Build Dashboard
+> [a-a] Fetch
+< [a-a] ✓ 120.00ms
+> [a-b] Process
+> [a-b-a] Step A
+< [a-b-a] ✓ 15.00ms
+> [a-b-b] Step B
+< [a-b-b] ✓ 22.00ms
+< [a-b] ✓ 38.00ms
+> [a-c] Render
+< [a-c] ✓ 5.00ms
+< [a] ✓ 165.00ms
+```
+
+### 3. Object Labels with Metadata
+
+```typescript
+await measure({ label: 'Fetch User', userId: 5, region: 'us-east' }, async () => fetchUser(5));
+// Logs: > [a] Fetch User (userId=5 region="us-east")
+```
+
+### 4. Error Isolation — Errors Are Data, Not Crashes
+
+**measure never throws.** On error: logs it, returns `null`. Your program keeps running.
+
+```typescript
+await measure('Pipeline', async (m) => {
+  const result = await m('Risky step', () => riskyOperation());
+  if (result === null) {
+    // Error was already logged with ID, stack trace, and cause
+    // Decide: skip, fallback, or abort
+    return;
+  }
+  await m('Next step', () => useResult(result));
+});
+```
+
+### 5. Annotations (Label-Only)
+
+Log a marker without wrapping a function:
+
+```typescript
+await measure('Checkpoint: all users processed');
+measureSync({ label: 'Config loaded', env: 'production' });
+```
+
+## When to Use
+
+- **Always.** Every server handler, every background job, every CLI command, every pipeline.
+- **API handlers** — wrap the full request lifecycle
+- **Database operations** — time queries, transactions, migrations
+- **External calls** — HTTP requests, file I/O, SDK calls
+- **Batch processing** — measure each item in a loop
+- **CLI tools** — structure the entire command as a measured tree
+
+## Testing
+
+Use `resetCounter()` for deterministic IDs:
+
+```typescript
+import { resetCounter } from 'measure-fn';
+beforeEach(() => resetCounter());
+```
+
+## API Reference
+
+| Export | Signature | Description |
+|--------|-----------|-------------|
+| `measure` | `(label, fn?) => Promise<T \| null>` | Async measurement |
+| `measureSync` | `(label, fn?) => T \| null` | Sync measurement |
+| `resetCounter` | `() => void` | Reset global ID counter |
+| `MeasureFn` | type | Nested async measure function type |
+| `MeasureSyncFn` | type | Nested sync measure function type |
+
+## Output Symbols
+
+| Symbol | Meaning |
+|--------|---------|
+| `>` | Start |
+| `<` | Complete |
+| `=` | Annotation |
+| `✓` | Success |
+| `✗` | Error |
+
+IDs are alphabetic: `[a]`, `[a-a]`, `[a-b-c]`. Every ID uniquely addresses one operation — grep for it to find exactly what happened.

package/bun.lock

@@ -0,0 +1,25 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "ments-utils",
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.2.17", "", { "dependencies": { "bun-types": "1.2.17" } }, "sha512-l/BYs/JYt+cXA/0+wUhulYJB6a6p//GTPiJ7nV+QHa8iiId4HZmnu/3J/SowP5g0rTiERY2kfGKXEK5Ehltx4Q=="],
+
+    "@types/node": ["@types/node@24.0.4", "", { "dependencies": { "undici-types": "~7.8.0" } }, "sha512-ulyqAkrhnuNq9pB76DRBTkcS6YsmDALy6Ua63V8OhrOBgbcYt6IOdzpw5P1+dyRIyMerzLkeYWBeOXPpA9GMAA=="],
+
+    "bun-types": ["bun-types@1.2.17", "", { "dependencies": { "@types/node": "*" } }, "sha512-ElC7ItwT3SCQwYZDYoAH+q6KT4Fxjl8DtZ6qDulUFBmXA8YB4xo+l54J9ZJN+k2pphfn9vk7kfubeSd5QfTVJQ=="],
+
+    "typescript": ["typescript@5.8.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ=="],
+
+    "undici-types": ["undici-types@7.8.0", "", {}, "sha512-9UJ2xGDvQ43tYyVMpuHlsgApydB8ZKfVYTsLDhXkFL/6gfkp+U8xTGdh8pMJv1SpZna0zxG1DwsKZsreLbXBxw=="],
+  }
+}

package/example.ts

@@ -0,0 +1,73 @@
+import { measure, measureSync, type MeasureFn } from "./index.ts";
+
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+
+async function fetchUser(userId: number) {
+  await sleep(100);
+  if (userId === 999) throw new Error('User not found', { cause: { userId } });
+  return { id: userId, name: `User ${userId}` };
+}
+
+async function fetchPosts(userId: number) {
+  await sleep(150);
+  return [{ id: 1, title: 'First Post', userId }];
+}
+async function fetchComments(postId: number) {
+  await sleep(80);
+  return [{ id: 1, text: 'Great post!', postId }];
+}
+function syncFetch() {
+  do {
+  } while (Math.random() < 0.99999999);
+  return 42;
+}
+
+async function comprehensiveWorkflow() {
+  // Sync: label first, fn second
+  const syncValue = measureSync('get sync value', syncFetch);
+
+  // Annotation-only call (label only, no fn)
+  if (syncValue !== null) {
+    measureSync(`sync returned ${syncValue}`);
+  }
+
+  // Async: label first, fn second
+  await measure('Comprehensive Workflow Example', async (m) => {
+    const syncValue = await m('get sync value', syncFetch);
+    await m({ label: 'noop measure object', values: [syncValue] });
+
+    const user1 = await m(
+      { label: 'Fetch User', userId: 1 },
+      () => fetchUser(1)
+    );
+
+    // @note measure never throws, only returns null in case of exception
+    await m(
+      { label: 'Fetch Invalid User', userId: 999 },
+      () => fetchUser(999)
+    );
+
+    await m('Fetch Multiple Users in Parallel', async (m2: MeasureFn) => {
+      const userPromises = [2, 3, 4].map(id =>
+        m2({ label: 'Fetch User', userId: id }, () => fetchUser(id))
+      );
+      await Promise.all(userPromises);
+    });
+
+    if (user1 === null) return;
+
+    await m('Enrich Posts with Comments', async (m2: MeasureFn) => {
+      const posts = await m2({ label: 'Fetch Posts', userId: user1.id }, () => fetchPosts(user1.id));
+
+      if (posts === null) return;
+      for (const post of posts) {
+        await m2({ label: 'Fetch Comments', postId: post.id }, () => fetchComments(post.id));
+      }
+    });
+  });
+}
+
+// To run it:
+comprehensiveWorkflow().then(() => {
+  console.log('\n✅ Workflow complete.');
+});

package/index.test.ts

@@ -0,0 +1,277 @@
+import { describe, test, expect, beforeEach, spyOn } from "bun:test";
+import { measure, measureSync, resetCounter } from "./index.ts";
+
+// Capture console output for assertions
+function captureConsole() {
+    const logs: string[] = [];
+    const errors: string[] = [];
+
+    const logSpy = spyOn(console, "log").mockImplementation((...args: any[]) => {
+        logs.push(args.map(String).join(" "));
+    });
+    const errorSpy = spyOn(console, "error").mockImplementation((...args: any[]) => {
+        errors.push(args.map(String).join(" "));
+    });
+
+    return {
+        logs,
+        errors,
+        restore: () => {
+            logSpy.mockRestore();
+            errorSpy.mockRestore();
+        },
+    };
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+// ─── measure (async) ─────────────────────────────────────────────────
+
+describe("measure (async)", () => {
+    beforeEach(() => resetCounter());
+
+    test("runs a function and returns its result", async () => {
+        const out = captureConsole();
+        const result = await measure("my op", async () => 42);
+        out.restore();
+
+        expect(result).toBe(42);
+    });
+
+    test("logs start and success", async () => {
+        const out = captureConsole();
+        await measure("fetch data", async () => "ok");
+        out.restore();
+
+        expect(out.logs[0]).toStartWith("> [a] fetch data");
+        expect(out.logs[1]).toMatch(/< \[a\] ✓ \d+\.\d+ms/);
+    });
+
+    test("returns null and logs error on throw", async () => {
+        const out = captureConsole();
+        const result = await measure("will fail", async () => {
+            throw new Error("boom");
+        });
+        out.restore();
+
+        expect(result).toBeNull();
+        expect(out.logs[1]).toMatch(/< \[a\] ✗ \d+\.\d+ms \(boom\)/);
+        expect(out.errors.length).toBeGreaterThan(0);
+    });
+
+    test("logs error cause when present", async () => {
+        const out = captureConsole();
+        await measure("caused error", async () => {
+            throw new Error("fail", { cause: { reason: "test" } });
+        });
+        out.restore();
+
+        const causeLog = out.errors.find((e) => e.includes("Cause:"));
+        expect(causeLog).toBeDefined();
+    });
+
+    test("label-only call (no function) logs start and returns null", async () => {
+        const out = captureConsole();
+        const result = await measure("annotation only");
+        out.restore();
+
+        expect(result).toBeNull();
+        expect(out.logs[0]).toStartWith("> [a] annotation only");
+        expect(out.logs.length).toBe(1); // no completion log
+    });
+
+    test("object label extracts .label and logs extra params", async () => {
+        const out = captureConsole();
+        await measure({ label: "Fetch User", userId: 5 }, async () => "ok");
+        out.restore();
+
+        expect(out.logs[0]).toContain("Fetch User");
+        expect(out.logs[0]).toContain("userId=5");
+    });
+
+    test("nested measure produces hierarchical IDs", async () => {
+        const out = captureConsole();
+        await measure("parent", async (m) => {
+            await m("child A", async () => 1);
+            await m("child B", async () => 2);
+        });
+        out.restore();
+
+        expect(out.logs[0]).toStartWith("> [a] parent");
+        expect(out.logs[1]).toStartWith("> [a-a] child A");
+        expect(out.logs[3]).toStartWith("> [a-b] child B");
+    });
+
+    test("deeply nested measure produces correct IDs", async () => {
+        const out = captureConsole();
+        await measure("root", async (m) => {
+            await m("level 1", async (m2) => {
+                await m2("level 2", async () => "deep");
+            });
+        });
+        out.restore();
+
+        expect(out.logs[0]).toStartWith("> [a] root");
+        expect(out.logs[1]).toStartWith("> [a-a] level 1");
+        expect(out.logs[2]).toStartWith("> [a-a-a] level 2");
+    });
+
+    test("multiple top-level calls get sequential IDs", async () => {
+        const out = captureConsole();
+        await measure("first", async () => 1);
+        await measure("second", async () => 2);
+        out.restore();
+
+        expect(out.logs[0]).toStartWith("> [a] first");
+        expect(out.logs[2]).toStartWith("> [b] second");
+    });
+
+    test("nested annotation (label only) inside measure", async () => {
+        const out = captureConsole();
+        await measure("parent", async (m) => {
+            await m("just a note");
+            await m("do work", async () => 42);
+        });
+        out.restore();
+
+        // Annotation uses '=' prefix
+        expect(out.logs[1]).toStartWith("= [a] just a note");
+    });
+
+    test("child error does not crash parent", async () => {
+        const out = captureConsole();
+        const result = await measure("parent", async (m) => {
+            const childResult = await m("failing child", async () => {
+                throw new Error("child error");
+            });
+            expect(childResult).toBeNull();
+            return "parent ok";
+        });
+        out.restore();
+
+        expect(result).toBe("parent ok");
+    });
+
+    test("non-Error throw is handled gracefully", async () => {
+        const out = captureConsole();
+        const result = await measure("string throw", async () => {
+            throw "raw string error";
+        });
+        out.restore();
+
+        expect(result).toBeNull();
+        expect(out.logs[1]).toContain("raw string error");
+    });
+});
+
+// ─── measureSync ─────────────────────────────────────────────────────
+
+describe("measureSync", () => {
+    beforeEach(() => resetCounter());
+
+    test("runs a function and returns its result", () => {
+        const out = captureConsole();
+        const result = measureSync("compute", () => 100);
+        out.restore();
+
+        expect(result).toBe(100);
+    });
+
+    test("logs start and success", () => {
+        const out = captureConsole();
+        measureSync("parse json", () => JSON.parse('{"a":1}'));
+        out.restore();
+
+        expect(out.logs[0]).toStartWith("> [a] parse json");
+        expect(out.logs[1]).toMatch(/< \[a\] ✓ \d+\.\d+ms/);
+    });
+
+    test("returns null and logs error on throw", () => {
+        const out = captureConsole();
+        const result = measureSync("will fail", () => {
+            throw new Error("sync boom");
+        });
+        out.restore();
+
+        expect(result).toBeNull();
+        expect(out.logs[1]).toMatch(/✗/);
+        expect(out.logs[1]).toContain("sync boom");
+    });
+
+    test("label-only call returns null", () => {
+        const out = captureConsole();
+        const result = measureSync("just a note");
+        out.restore();
+
+        expect(result).toBeNull();
+        expect(out.logs[0]).toStartWith("> [a] just a note");
+    });
+
+    test("nested measureSync produces hierarchical IDs", () => {
+        const out = captureConsole();
+        measureSync("parent", (m) => {
+            m("child X", () => 10);
+            m("child Y", () => 20);
+            return 30;
+        });
+        out.restore();
+
+        expect(out.logs[0]).toStartWith("> [a] parent");
+        expect(out.logs[1]).toStartWith("> [a-a] child X");
+        expect(out.logs[3]).toStartWith("> [a-b] child Y");
+    });
+
+    test("child error does not crash parent (sync)", () => {
+        const out = captureConsole();
+        const result = measureSync("parent", (m) => {
+            const bad = m("fail", () => {
+                throw new Error("nope");
+            });
+            expect(bad).toBeNull();
+            return "still ok";
+        });
+        out.restore();
+
+        expect(result).toBe("still ok");
+    });
+});
+
+// ─── toAlpha / ID generation ─────────────────────────────────────────
+
+describe("ID generation", () => {
+    beforeEach(() => resetCounter());
+
+    test("generates sequential alpha IDs for many calls", async () => {
+        const out = captureConsole();
+        for (let i = 0; i < 28; i++) {
+            await measure(`op-${i}`, async () => null);
+        }
+        out.restore();
+
+        // First 26: a-z, then 27th = aa, 28th = ab
+        expect(out.logs[0]).toStartWith("> [a]");
+        expect(out.logs[50]).toStartWith("> [z]"); // 26th call (index 25) => lines 50,51
+        expect(out.logs[52]).toStartWith("> [aa]"); // 27th
+        expect(out.logs[54]).toStartWith("> [ab]"); // 28th
+    });
+});
+
+// ─── resetCounter ────────────────────────────────────────────────────
+
+describe("resetCounter", () => {
+    test("resets global ID counter", async () => {
+        resetCounter();
+
+        const out1 = captureConsole();
+        await measure("first run", async () => null);
+        out1.restore();
+        expect(out1.logs[0]).toStartWith("> [a]");
+
+        resetCounter();
+
+        const out2 = captureConsole();
+        await measure("second run", async () => null);
+        out2.restore();
+        expect(out2.logs[0]).toStartWith("> [a]"); // back to [a]
+    });
+});

package/index.ts

@@ -0,0 +1,219 @@
+const toAlpha = (num: number): string => {
+  let result = '';
+  let n = num;
+  do {
+    result = String.fromCharCode(97 + (n % 26)) + result;
+    n = Math.floor(n / 26) - 1;
+  } while (n >= 0);
+  return result;
+};
+
+// Shared helpers
+const buildActionLabel = (actionInternal: string | object): string => {
+  return typeof actionInternal === 'object' && actionInternal !== null && 'label' in actionInternal
+    ? String(actionInternal.label)
+    : String(actionInternal);
+};
+
+const buildLogMessage = (
+  prefix: string,
+  actionLabel: string,
+  actionInternal: string | object,
+  fullIdChainStr: string
+): string => {
+  let logMessage = `${prefix} ${fullIdChainStr} ${actionLabel}`;
+  if (typeof actionInternal === 'object' && actionInternal !== null) {
+    const details = { ...actionInternal };
+    if ('label' in details) delete details.label;
+    if (Object.keys(details).length > 0) {
+      const params = Object.entries(details)
+        .map(([key, value]) => `${key}=${JSON.stringify(value)}`)
+        .join(' ');
+      logMessage += ` (${params})`;
+    }
+  }
+  return logMessage;
+};
+
+const logStart = (fullIdChainStr: string, actionInternal: string | object) => {
+  const actionLabel = buildActionLabel(actionInternal);
+  const logMessage = buildLogMessage('>', actionLabel, actionInternal, fullIdChainStr);
+  console.log(logMessage);
+};
+
+const logNested = (fullIdChainStr: string, actionInternalNested: string | object) => {
+  if (!actionInternalNested) return;
+  const actionLabelNested = buildActionLabel(actionInternalNested);
+  const logMessageNested = buildLogMessage('=', actionLabelNested, actionInternalNested, fullIdChainStr);
+  console.log(logMessageNested);
+};
+
+const logSuccess = (fullIdChainStr: string, duration: number) => {
+  console.log(`< ${fullIdChainStr} ✓ ${duration.toFixed(2)}ms`);
+};
+
+const logError = (fullIdChainStr: string, duration: number, error: unknown) => {
+  const errorMsg = error instanceof Error ? error.message : String(error);
+  console.log(`< ${fullIdChainStr} ✗ ${duration.toFixed(2)}ms (${errorMsg})`);
+  if (error instanceof Error) {
+    console.error(`${fullIdChainStr}`, error.stack ?? error.message);
+    if (error.cause) {
+      console.error(`${fullIdChainStr} Cause:`, error.cause);
+    }
+  } else {
+    console.error(`${fullIdChainStr}`, error);
+  }
+};
+
+/** Nested measure function — label first, fn second (or just a label for annotation) */
+export type MeasureFn = {
+  <U>(label: string | object, fn: () => Promise<U>): Promise<U | null>;
+  <U>(label: string | object, fn: (m: MeasureFn) => Promise<U>): Promise<U | null>;
+  (label: string | object): Promise<null>;
+};
+
+/** Nested measureSync function — label first, fn second (or just a label for annotation) */
+export type MeasureSyncFn = {
+  <U>(label: string | object, fn: () => U): U | null;
+  <U>(label: string | object, fn: (m: MeasureSyncFn) => U): U | null;
+  (label: string | object): null;
+};
+
+const createNestedResolver = (
+  isAsync: boolean,
+  fullIdChain: string[],
+  childCounterRef: { value: number },
+  resolver: <U>(fn: any, action: any, chain: (string | number)[]) => Promise<U | null> | (U | null)
+) => {
+  return (...args: any[]) => {
+    // New order: (label, fn?) — label is always first
+    const label = args[0];
+    const fn = args[1];
+
+    if (typeof fn === 'function') {
+      const childParentChain = [...fullIdChain, childCounterRef.value++];
+      return resolver(fn, label, childParentChain);
+    } else {
+      logNested(`[${fullIdChain.join('-')}]`, label);
+      return isAsync ? Promise.resolve(null) : null;
+    }
+  };
+};
+
+let globalRootCounter = 0;
+
+/** Reset the global counter — useful for deterministic test output */
+export const resetCounter = () => {
+  globalRootCounter = 0;
+};
+
+/**
+ * Measure an async operation with hierarchical logging.
+ *
+ * @param label - A string or object describing the operation
+ * @param fn - The async function to measure (receives nested `measure` as argument)
+ *
+ * @example
+ * ```ts
+ * await measure('Fetch users', async (m) => {
+ *   const user = await m('Get user 1', () => fetchUser(1));
+ *   await m('Get posts', () => fetchPosts(user.id));
+ * });
+ * ```
+ */
+export const measure = async <T = null>(
+  arg1: string | object,
+  arg2?: ((measure: MeasureFn) => Promise<T>)
+): Promise<T | null> => {
+  const _measureInternal = async <U>(
+    fnInternal: (measure: MeasureFn) => Promise<U>,
+    actionInternal: string | object,
+    parentIdChain: (string | number)[]
+  ): Promise<U | null> => {
+    const start = performance.now();
+    const childCounterRef = { value: 0 };
+
+    const currentId = toAlpha(parentIdChain.pop() ?? 0);
+    const fullIdChain = [...parentIdChain, currentId];
+    const fullIdChainStr = `[${fullIdChain.join('-')}]`;
+
+    logStart(fullIdChainStr, actionInternal);
+
+    const measureForNextLevel = createNestedResolver(true, fullIdChain, childCounterRef, _measureInternal);
+
+    try {
+      const result = await fnInternal(measureForNextLevel as MeasureFn);
+      const duration = performance.now() - start;
+      logSuccess(fullIdChainStr, duration);
+      return result;
+    } catch (error) {
+      const duration = performance.now() - start;
+      logError(fullIdChainStr, duration, error);
+      return null;
+    }
+  };
+
+  if (typeof arg2 === 'function') {
+    return _measureInternal(arg2, arg1, [globalRootCounter++]) as Promise<T | null>;
+  } else {
+    const currentId = toAlpha(globalRootCounter++);
+    const fullIdChainStr = `[${currentId}]`;
+    logStart(fullIdChainStr, arg1);
+    return Promise.resolve(null);
+  }
+};
+
+/**
+ * Measure a synchronous operation with hierarchical logging.
+ *
+ * @param label - A string or object describing the operation
+ * @param fn - The sync function to measure (receives nested `measureSync` as argument)
+ *
+ * @example
+ * ```ts
+ * const result = measureSync('Parse config', () => {
+ *   return JSON.parse(configStr);
+ * });
+ * ```
+ */
+export const measureSync = <T = null>(
+  arg1: string | object,
+  arg2?: ((measure: MeasureSyncFn) => T)
+): T | null => {
+  const _measureInternalSync = <U>(
+    fnInternal: (measure: MeasureSyncFn) => U,
+    actionInternal: string | object,
+    parentIdChain: (string | number)[]
+  ): U | null => {
+    const start = performance.now();
+    const childCounterRef = { value: 0 };
+
+    const currentId = toAlpha(parentIdChain.pop() ?? 0);
+    const fullIdChain = [...parentIdChain, currentId];
+    const fullIdChainStr = `[${fullIdChain.join('-')}]`;
+
+    logStart(fullIdChainStr, actionInternal);
+
+    const measureForNextLevel = createNestedResolver(false, fullIdChain, childCounterRef, _measureInternalSync);
+
+    try {
+      const result = fnInternal(measureForNextLevel as MeasureSyncFn);
+      const duration = performance.now() - start;
+      logSuccess(fullIdChainStr, duration);
+      return result;
+    } catch (error) {
+      const duration = performance.now() - start;
+      logError(fullIdChainStr, duration, error);
+      return null;
+    }
+  };
+
+  if (typeof arg2 === 'function') {
+    return _measureInternalSync(arg2, arg1, [globalRootCounter++]) as T | null;
+  } else {
+    const currentId = toAlpha(globalRootCounter++);
+    const fullIdChainStr = `[${currentId}]`;
+    logStart(fullIdChainStr, arg1);
+    return null;
+  }
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "measure-fn",
+  "module": "index.ts",
+  "main": "./index.ts",
+  "version": "2.0.0",
+  "type": "module",
+  "private": false,
+  "description": "Zero-dependency function performance measurement with hierarchical logging",
+  "keywords": [
+    "measure",
+    "performance",
+    "timing",
+    "logging",
+    "tracing",
+    "hierarchical"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/7flash/measure-fn"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "scripts": {
+    "test": "bun test",
+    "example": "bun run example.ts"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}