Hierarchical Timing Profiler

Measure nested operations with hierarchical timers and hit counters, producing a readable tree report. Timing calls should form a parent/child structure that mirrors how work is nested, and counters should surface alongside their related timers. Repeated timers with the same label under a parent should merge into one node that accumulates duration and hits.

Capabilities

Nested timings form a tree

• Timing a root section that wraps two child sections yields a report with the root at depth 0 and each child indented beneath it, each showing a positive duration in milliseconds. @test

Async-safe timing results

• Wrapping an async callback with timing returns the callback's resolved value unchanged while capturing its elapsed duration in the tree. @test

Hit counting

• Incrementing a named counter multiple times appears in the report alongside that timer label, showing the total hit count. @test

Debug auto-reporting

• When a provided debug pattern matches the root label, disposing the profiler logs the formatted tree exactly once and returns the same text. @test

Implementation

@generates

The profiler should:

• Default the root label to root when none is provided.
• Treat each time or start/stop cycle as a hit on the corresponding node.
• Use a two-space indent per depth when formatting the report text.
• Round durations in the report text to two decimal places and include the unit ms.

API

export interface TimerNode {
  label: string;
  durationMs: number;
  hits: number;
  children: TimerNode[];
}

export interface Profiler {
  time<T>(label: string, fn: () => T | Promise<T>): T | Promise<T>;
  start(label: string): () => void;
  hit(label: string): void;
  report(): { tree: TimerNode; text: string };
  reset(): void;
  dispose(): string;
}

export interface ProfilerOptions {
  rootLabel?: string;
  debugPattern?: string;
  log?: (text: string) => void;
  timeSource?: () => number;
}

export function createProfiler(options?: ProfilerOptions): Profiler;

Dependencies { .dependencies }

@tailwindcss/node { .dependency }

Provides hierarchical timing and hit-count instrumentation for building reports.