traceperf 0.2.1 → 1.3.0

package/dist/esm/core/allocations.d.ts

@@ -0,0 +1,38 @@
+export interface AllocationSite {
+    functionName: string;
+    url: string;
+    line: number;
+    column: number;
+    /** Estimated bytes allocated at this site */
+    bytes: number;
+}
+export interface AllocationProfile<T> {
+    result: T;
+    /** Estimated total bytes allocated while fn ran */
+    allocatedBytes: number;
+    /** Top allocation sites, largest first */
+    sites: AllocationSite[];
+    /**
+     * Whether allocations that were garbage-collected before the profile
+     * ended are included (V8 >= 11, i.e. Node.js 20+). When false, only
+     * allocations still alive at the end are counted.
+     */
+    countsCollected: boolean;
+}
+export interface ProfileAllocationsOptions {
+    /** Average bytes between samples; smaller = more precise, more overhead (default 16384) */
+    samplingInterval?: number;
+    /** Number of sites to return (default 10) */
+    top?: number;
+}
+/**
+ * Profile the allocations of `fn` (sync or async).
+ *
+ *   const { result, allocatedBytes, sites } = await profileAllocations(() => buildReport(data));
+ *
+ * Needs Node.js 20+ to include allocations that were collected again
+ * (see `countsCollected`). Only one profile can run at a time per process. Estimates are
+ * statistical: expect accuracy within a few percent for allocations well
+ * above the sampling interval.
+ */
+export declare function profileAllocations<T>(fn: () => T | Promise<T>, options?: ProfileAllocationsOptions): Promise<AllocationProfile<Awaited<T>>>;

package/dist/esm/core/allocations.js

@@ -0,0 +1,82 @@
+/**
+ * Allocation profiling with V8's sampling heap profiler (Node.js only).
+ *
+ * The heap delta shown in trees is "heap after - heap before", which GC and
+ * concurrent work distort. This measures what a piece of code actually
+ * allocated, including objects that were collected again, and where.
+ */
+import { loadNodeBuiltin } from './env.js';
+const v8Major = () => {
+    const proc = typeof process !== 'undefined' ? process : undefined;
+    return proc && proc.versions && proc.versions.v8 ? parseInt(proc.versions.v8, 10) : 0;
+};
+let active = false;
+/**
+ * Profile the allocations of `fn` (sync or async).
+ *
+ *   const { result, allocatedBytes, sites } = await profileAllocations(() => buildReport(data));
+ *
+ * Needs Node.js 20+ to include allocations that were collected again
+ * (see `countsCollected`). Only one profile can run at a time per process. Estimates are
+ * statistical: expect accuracy within a few percent for allocations well
+ * above the sampling interval.
+ */
+export async function profileAllocations(fn, options = {}) {
+    var _a, _b;
+    const inspector = loadNodeBuiltin('inspector');
+    if (!inspector || typeof inspector.Session !== 'function') {
+        throw new Error('profileAllocations requires Node.js (node:inspector)');
+    }
+    if (active)
+        throw new Error('profileAllocations: another profile is already running');
+    active = true;
+    const session = new inspector.Session();
+    const post = (method, params) => new Promise((resolve, reject) => session.post(method, params, (err, res) => (err ? reject(err) : resolve(res))));
+    session.connect();
+    try {
+        await post('HeapProfiler.enable');
+        await post('HeapProfiler.startSampling', {
+            samplingInterval: Math.max(1, (_a = options.samplingInterval) !== null && _a !== void 0 ? _a : 16384),
+            // Count objects that were collected again too (V8 >= 11; ignored by older versions)
+            includeObjectsCollectedByMajorGC: true,
+            includeObjectsCollectedByMinorGC: true,
+        });
+        let result;
+        let stopped;
+        try {
+            result = await fn();
+        }
+        finally {
+            stopped = await post('HeapProfiler.stopSampling');
+            await post('HeapProfiler.disable');
+        }
+        const bySite = new Map();
+        let total = 0;
+        const visit = (node) => {
+            var _a;
+            if (node.selfSize > 0) {
+                const cf = node.callFrame;
+                const key = `${cf.functionName}|${cf.url}|${cf.lineNumber}|${cf.columnNumber}`;
+                const site = (_a = bySite.get(key)) !== null && _a !== void 0 ? _a : {
+                    functionName: cf.functionName || '(anonymous)',
+                    url: cf.url,
+                    line: cf.lineNumber + 1,
+                    column: cf.columnNumber + 1,
+                    bytes: 0,
+                };
+                site.bytes += node.selfSize;
+                bySite.set(key, site);
+                total += node.selfSize;
+            }
+            (node.children || []).forEach(visit);
+        };
+        visit(stopped.profile.head);
+        const sites = [...bySite.values()].sort((a, b) => b.bytes - a.bytes).slice(0, Math.max(0, (_b = options.top) !== null && _b !== void 0 ? _b : 10));
+        return { result, allocatedBytes: total, sites, countsCollected: v8Major() >= 11 };
+    }
+    finally {
+        session.disconnect();
+        active = false;
+    }
+}
+//# sourceMappingURL=allocations.js.map

package/dist/esm/core/allocations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"allocations.js","sourceRoot":"","sources":["../../../src/core/allocations.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/cpu-profile.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Line-level detail for slow calls: runs the V8 sampling profiler (Node.js
+ * inspector) and, for every top-level call slower than `threshold`, reports
+ * the functions that were on the CPU during it - including code that is not
+ * tracked at all.
+ *
+ *   tp.use(profileSlowCalls({
+ *     threshold: 200,
+ *     onProfile: (call, p) => console.log(call.label, p.hotspots),
+ *   }));
+ *
+ * The profiler runs in windows (default 2 s); results arrive when the window
+ * containing the call closes. Samples are process-wide, so concurrent work
+ * shows up too. Sampling every 1 ms costs a few percent CPU: enable it while
+ * investigating, or on a fraction of instances.
+ */
+import type { ExecutionRecord, TracePerfPlugin } from './records.js';
+export interface Hotspot {
+    /** Function name ("(anonymous)" when unnamed) */
+    functionName: string;
+    /** Script URL or path ("" for native code) */
+    url: string;
+    /** 1-based line and column */
+    line: number;
+    column: number;
+    /** CPU time sampled in this function itself, in ms */
+    selfMs: number;
+}
+export interface SlowCallProfile {
+    /** Functions with the most self time during the call, largest first */
+    hotspots: Hotspot[];
+    /** Time the thread was idle (waiting for I/O or timers) during the call, ms */
+    idleMs: number;
+    /** Time in garbage collection during the call, ms */
+    gcMs: number;
+    /** Time on the CPU during the call, ms (hotspots are the top of this) */
+    cpuMs: number;
+    /** Number of samples that fell within the call */
+    samples: number;
+}
+export interface ProfileSlowCallsOptions {
+    /** Profile top-level calls at least this slow (ms, default 100) */
+    threshold?: number;
+    /** Called once per slow call with its profile */
+    onProfile: (call: ExecutionRecord, profile: SlowCallProfile) => void;
+    /** Profiler window length in ms (default 2000) */
+    window?: number;
+    /** Sampling interval in microseconds (default 1000) */
+    samplingIntervalUs?: number;
+    /** Number of hotspots to report (default 5) */
+    top?: number;
+    /** Skip functions from these paths, e.g. /node_modules/ (default: none) */
+    exclude?: RegExp;
+}
+export interface SlowCallProfiler extends TracePerfPlugin {
+    /** Whether the inspector was available (false in browsers and edge runtimes) */
+    readonly available: boolean;
+    /** Close the current window now and deliver pending profiles */
+    flush(): Promise<void>;
+    /** Stop profiling (pending profiles are delivered first) */
+    stop(): Promise<void>;
+}
+/** A node in a V8 CPU profile */
+export interface CpuProfileNode {
+    id: number;
+    callFrame: {
+        functionName: string;
+        url: string;
+        lineNumber: number;
+        columnNumber: number;
+    };
+}
+/** A V8 CPU profile (inspector Profiler.stop result) */
+export interface CpuProfile {
+    nodes: CpuProfileNode[];
+    startTime: number;
+    samples: number[];
+    timeDeltas: number[];
+}
+/** Summarise the samples of a profile that fall within [start, end] (ms, profile clock) */
+export declare function summariseProfile(profile: CpuProfile, start: number, end: number, top?: number, exclude?: RegExp): SlowCallProfile;
+/** Text rendering: "  42.0 ms  parseRow  /app/csv.js:18" */
+export declare function formatHotspots(profile: SlowCallProfile): string;
+export declare function profileSlowCalls(options: ProfileSlowCallsOptions): SlowCallProfiler;

package/dist/esm/core/cpu-profile.js

@@ -0,0 +1,176 @@
+import { loadNodeBuiltin } from './env.js';
+/** Summarise the samples of a profile that fall within [start, end] (ms, profile clock) */
+export function summariseProfile(profile, start, end, top = 5, exclude) {
+    var _a;
+    const nodes = new Map(profile.nodes.map(n => [n.id, n]));
+    const self = new Map();
+    let idleMs = 0;
+    let gcMs = 0;
+    let cpuMs = 0;
+    let samples = 0;
+    let t = profile.startTime / 1000;
+    for (let i = 0; i < profile.samples.length; i++) {
+        t += (profile.timeDeltas[i] || 0) / 1000;
+        // Each sample stands for the interval up to the next one
+        const next = i + 1 < profile.timeDeltas.length ? (profile.timeDeltas[i + 1] || 0) / 1000 : 0;
+        if (t < start || t > end)
+            continue;
+        samples++;
+        const node = nodes.get(profile.samples[i]);
+        if (!node)
+            continue;
+        const { functionName, url, lineNumber, columnNumber } = node.callFrame;
+        if (functionName === '(idle)') {
+            idleMs += next;
+            continue;
+        }
+        if (functionName === '(garbage collector)') {
+            gcMs += next;
+            continue;
+        }
+        if (functionName === '(program)' || functionName === '(root)') {
+            cpuMs += next;
+            continue;
+        }
+        cpuMs += next;
+        if (exclude && exclude.test(url))
+            continue;
+        const key = `${functionName}|${url}|${lineNumber}|${columnNumber}`;
+        const entry = (_a = self.get(key)) !== null && _a !== void 0 ? _a : {
+            functionName: functionName || '(anonymous)', url, line: lineNumber + 1, column: columnNumber + 1, selfMs: 0,
+        };
+        entry.selfMs += next;
+        self.set(key, entry);
+    }
+    const hotspots = [...self.values()].sort((a, b) => b.selfMs - a.selfMs).slice(0, top);
+    return { hotspots, idleMs, gcMs, cpuMs, samples };
+}
+function mergeProfiles(a, b, top) {
+    const all = new Map();
+    for (const h of [...a.hotspots, ...b.hotspots]) {
+        const key = `${h.functionName}|${h.url}|${h.line}|${h.column}`;
+        const e = all.get(key);
+        if (e)
+            e.selfMs += h.selfMs;
+        else
+            all.set(key, { ...h });
+    }
+    return {
+        hotspots: [...all.values()].sort((x, y) => y.selfMs - x.selfMs).slice(0, top),
+        idleMs: a.idleMs + b.idleMs,
+        gcMs: a.gcMs + b.gcMs,
+        cpuMs: a.cpuMs + b.cpuMs,
+        samples: a.samples + b.samples,
+    };
+}
+/** Text rendering: "  42.0 ms  parseRow  /app/csv.js:18" */
+export function formatHotspots(profile) {
+    const lines = profile.hotspots.map(h => `  ${h.selfMs.toFixed(1).padStart(7)} ms  ${h.functionName}  ${h.url ? `${h.url.replace(/^file:\/\//, '')}:${h.line}` : '(native)'}`);
+    lines.push(`  cpu ${profile.cpuMs.toFixed(1)} ms, idle ${profile.idleMs.toFixed(1)} ms, gc ${profile.gcMs.toFixed(1)} ms`);
+    return lines.join('\n');
+}
+/** Same clock as ExecutionRecord.startTime */
+const nowMs = () => {
+    const perf = globalThis.performance || (loadNodeBuiltin('perf_hooks') || {}).performance;
+    return perf ? perf.now() : Date.now();
+};
+export function profileSlowCalls(options) {
+    var _a, _b, _c, _d;
+    const threshold = (_a = options.threshold) !== null && _a !== void 0 ? _a : 100;
+    const windowMs = (_b = options.window) !== null && _b !== void 0 ? _b : 2000;
+    const interval = (_c = options.samplingIntervalUs) !== null && _c !== void 0 ? _c : 1000;
+    const top = (_d = options.top) !== null && _d !== void 0 ? _d : 5;
+    const inspector = loadNodeBuiltin('inspector');
+    const available = !!(inspector && inspector.Session);
+    let session;
+    let pending = [];
+    /** performance.now() at the profile's start, and the profile's own start (ms) */
+    let windowStartNow = 0;
+    let stopped = false;
+    let timer;
+    let busy = Promise.resolve();
+    /** The previous window, for calls that started before the current one */
+    let previous;
+    const post = (method, params) => new Promise((resolve, reject) => {
+        session.post(method, params || {}, (err, result) => (err ? reject(err) : resolve(result)));
+    });
+    const startWindow = async () => {
+        windowStartNow = nowMs();
+        await post('Profiler.start');
+    };
+    const rotate = (restart) => {
+        busy = busy.then(async () => {
+            if (!session)
+                return;
+            const calls = pending;
+            pending = [];
+            const startNow = windowStartNow;
+            const { profile } = await post('Profiler.stop');
+            if (restart && !stopped)
+                await startWindow();
+            // Map the call's times (performance.now clock) onto the profile clock
+            const offset = profile.startTime / 1000 - startNow;
+            for (const call of calls) {
+                let result = summariseProfile(profile, call.startTime + offset, call.endTime + offset, top, options.exclude);
+                if (previous && call.startTime < startNow) {
+                    const earlier = summariseProfile(previous.profile, call.startTime + previous.offset, call.endTime + previous.offset, top, options.exclude);
+                    result = mergeProfiles(earlier, result, top);
+                }
+                try {
+                    options.onProfile(call, result);
+                }
+                catch (_a) {
+                    // a failing callback must not stop profiling
+                }
+            }
+            previous = { profile, offset, startNow };
+        }).catch(() => undefined);
+        return busy;
+    };
+    if (available) {
+        try {
+            session = new inspector.Session();
+            session.connect();
+            busy = post('Profiler.enable')
+                .then(() => post('Profiler.setSamplingInterval', { interval }))
+                .then(startWindow)
+                .catch(() => { session = undefined; });
+            timer = setInterval(() => rotate(true), windowMs);
+            if (timer && typeof timer.unref === 'function')
+                timer.unref();
+        }
+        catch (_e) {
+            session = undefined;
+        }
+    }
+    return {
+        name: 'profile-slow-calls',
+        available,
+        onComplete(root) {
+            if (!session || stopped || root.duration < threshold)
+                return;
+            // Calls reaching back further than the previous window are skipped
+            if (root.startTime >= (previous ? previous.startNow : windowStartNow))
+                pending.push(root);
+        },
+        flush: () => rotate(true),
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            if (timer)
+                clearInterval(timer);
+            await rotate(false);
+            await busy;
+            if (session) {
+                try {
+                    await post('Profiler.disable');
+                }
+                catch ( /* ignore */_a) { /* ignore */ }
+                session.disconnect();
+                session = undefined;
+            }
+        },
+    };
+}
+//# sourceMappingURL=cpu-profile.js.map

package/dist/esm/core/cpu-profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cpu-profile.js","sourceRoot":"","sources":["../../../src/core/cpu-profile.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAgExC,2FAA2F;AAC3F,MAAM,UAAU,gBAAgB,CAAC,OAAmB,EAAE,KAAa,EAAE,GAAW,EAAE,GAAG,GAAG,CAAC,EAAE,OAAgB;;IACzG,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACzD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAmB,CAAC;IACxC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,CAAC,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChD,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;QACzC,yDAAyD;QACzD,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7F,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,GAAG;YAAE,SAAS;QACnC,OAAO,EAAE,CAAC;QACV,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,UAAU,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC;QACvE,IAAI,YAAY,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,IAAI,IAAI,CAAC;YACf,SAAS;QACX,CAAC;QACD,IAAI,YAAY,KAAK,qBAAqB,EAAE,CAAC;YAC3C,IAAI,IAAI,IAAI,CAAC;YACb,SAAS;QACX,CAAC;QACD,IAAI,YAAY,KAAK,WAAW,IAAI,YAAY,KAAK,QAAQ,EAAE,CAAC;YAC9D,KAAK,IAAI,IAAI,CAAC;YACd,SAAS;QACX,CAAC;QACD,KAAK,IAAI,IAAI,CAAC;QACd,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,SAAS;QAC3C,MAAM,GAAG,GAAG,GAAG,YAAY,IAAI,GAAG,IAAI,UAAU,IAAI,YAAY,EAAE,CAAC;QACnE,MAAM,KAAK,GAAG,MAAA,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,mCAAI;YAC7B,YAAY,EAAE,YAAY,IAAI,aAAa,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,GAAG,CAAC,EAAE,MAAM,EAAE,YAAY,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;SAC5G,CAAC;QACF,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC;QACrB,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACvB,CAAC;IACD,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACtF,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACpD,CAAC;AAED,SAAS,aAAa,CAAC,CAAkB,EAAE,CAAkB,EAAE,GAAW;IACxE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAmB,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/C,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;QAC/D,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC;YAAE,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,CAAC;;YACvB,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QAC7E,MAAM,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM;QAC3B,IAAI,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI;QACrB,KAAK,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK;QACxB,OAAO,EAAE,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;KAC/B,CAAC;AACJ,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,cAAc,CAAC,OAAwB;IACrD,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC;IAC9K,KAAK,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,aAAa,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAC3H,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,8CAA8C;AAC9C,MAAM,KAAK,GAAG,GAAW,EAAE;IACzB,MAAM,IAAI,GAAS,UAAkB,CAAC,WAAW,IAAI,CAAC,eAAe,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC;IACvG,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;AACxC,CAAC,CAAC;AAEF,MAAM,UAAU,gBAAgB,CAAC,OAAgC;;IAC/D,MAAM,SAAS,GAAG,MAAA,OAAO,CAAC,SAAS,mCAAI,GAAG,CAAC;IAC3C,MAAM,QAAQ,GAAG,MAAA,OAAO,CAAC,MAAM,mCAAI,IAAI,CAAC;IACxC,MAAM,QAAQ,GAAG,MAAA,OAAO,CAAC,kBAAkB,mCAAI,IAAI,CAAC;IACpD,MAAM,GAAG,GAAG,MAAA,OAAO,CAAC,GAAG,mCAAI,CAAC,CAAC;IAC7B,MAAM,SAAS,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,CAAC,CAAC,CAAC,SAAS,IAAI,SAAS,CAAC,OAAO,CAAC,CAAC;IACrD,IAAI,OAAY,CAAC;IACjB,IAAI,OAAO,GAAsB,EAAE,CAAC;IACpC,iFAAiF;IACjF,IAAI,cAAc,GAAG,CAAC,CAAC;IACvB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,KAAU,CAAC;IACf,IAAI,IAAI,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAC5C,yEAAyE;IACzE,IAAI,QAA+E,CAAC;IAEpF,MAAM,IAAI,GAAG,CAAC,MAAc,EAAE,MAAe,EAAgB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC9F,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE,CAAC,GAAY,EAAE,MAAe,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC/G,CAAC,CAAC,CAAC;IAEH,MAAM,WAAW,GAAG,KAAK,IAAI,EAAE;QAC7B,cAAc,GAAG,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAC/B,CAAC,CAAC;IAEF,MAAM,MAAM,GAAG,CAAC,OAAgB,EAAiB,EAAE;QACjD,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE;YAC1B,IAAI,CAAC,OAAO;gBAAE,OAAO;YACrB,MAAM,KAAK,GAAG,OAAO,CAAC;YACtB,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,QAAQ,GAAG,cAAc,CAAC;YAChC,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,CAAC;YAChD,IAAI,OAAO,IAAI,CAAC,OAAO;gBAAE,MAAM,WAAW,EAAE,CAAC;YAC7C,sEAAsE;YACtE,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,GAAG,QAAQ,CAAC;YACnD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,MAAM,GAAG,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,GAAG,MAAM,EAAE,IAAI,CAAC,OAAO,GAAG,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;gBAC7G,IAAI,QAAQ,IAAI,IAAI,CAAC,SAAS,GAAG,QAAQ,EAAE,CAAC;oBAC1C,MAAM,OAAO,GAAG,gBAAgB,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,GAAG,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;oBAC3I,MAAM,GAAG,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;gBAC/C,CAAC;gBACD,IAAI,CAAC;oBACH,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;gBAClC,CAAC;gBAAC,WAAM,CAAC;oBACP,6CAA6C;gBAC/C,CAAC;YACH,CAAC;YACD,QAAQ,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;QAC3C,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,IAAI,SAAS,EAAE,CAAC;QACd,IAAI,CAAC;YACH,OAAO,GAAG,IAAI,SAAS,CAAC,OAAO,EAAE,CAAC;YAClC,OAAO,CAAC,OAAO,EAAE,CAAC;YAClB,IAAI,GAAG,IAAI,CAAC,iBAAiB,CAAC;iBAC3B,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,8BAA8B,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;iBAC9D,IAAI,CAAC,WAAW,CAAC;iBACjB,KAAK,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;YACzC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;YAClD,IAAI,KAAK,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,UAAU;gBAAE,KAAK,CAAC,KAAK,EAAE,CAAC;QAChE,CAAC;QAAC,WAAM,CAAC;YACP,OAAO,GAAG,SAAS,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,oBAAoB;QAC1B,SAAS;QACT,UAAU,CAAC,IAAI;YACb,IAAI,CAAC,OAAO,IAAI,OAAO,IAAI,IAAI,CAAC,QAAQ,GAAG,SAAS;gBAAE,OAAO;YAC7D,mEAAmE;YACnE,IAAI,IAAI,CAAC,SAAS,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC;gBAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5F,CAAC;QACD,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC;QACzB,KAAK,CAAC,IAAI;YACR,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,IAAI,KAAK;gBAAE,aAAa,CAAC,KAAK,CAAC,CAAC;YAChC,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,IAAI,CAAC;YACX,IAAI,OAAO,EAAE,CAAC;gBACZ,IAAI,CAAC;oBAAC,MAAM,IAAI,CAAC,kBAAkB,CAAC,CAAC;gBAAC,CAAC;gBAAC,QAAQ,YAAY,IAAd,CAAC,CAAC,YAAY,CAAC,CAAC;gBAC9D,OAAO,CAAC,UAAU,EAAE,CAAC;gBACrB,OAAO,GAAG,SAAS,CAAC;YACtB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/esm/core/env.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Environment helpers (internal, not part of the public API).
+ */
+/**
+ * Hand Node built-ins to loadNodeBuiltin. Node-only entry points (traceperf/auto)
+ * import them statically and call this, because the ESM build has no `require`
+ * and `process.getBuiltinModule` only exists from Node 20.16 / 22.3.
+ */
+export declare const provideNodeBuiltins: (modules: Record<string, any>) => void;
+export declare const loadNodeBuiltin: (id: string) => any;

package/dist/esm/core/env.js

@@ -0,0 +1,35 @@
+/**
+ * Environment helpers (internal, not part of the public API).
+ */
+/**
+ * Load a Node.js built-in module without a static import, so the package
+ * still loads (and bundles) in browsers. Returns undefined outside Node.
+ */
+const provided = {};
+/**
+ * Hand Node built-ins to loadNodeBuiltin. Node-only entry points (traceperf/auto)
+ * import them statically and call this, because the ESM build has no `require`
+ * and `process.getBuiltinModule` only exists from Node 20.16 / 22.3.
+ */
+export const provideNodeBuiltins = (modules) => {
+    Object.assign(provided, modules);
+};
+export const loadNodeBuiltin = (id) => {
+    if (provided[id])
+        return provided[id];
+    try {
+        const proc = typeof process !== 'undefined' ? process : undefined;
+        if (!proc || !proc.versions || !proc.versions.node)
+            return undefined;
+        if (typeof proc.getBuiltinModule === 'function') {
+            return proc.getBuiltinModule(id);
+        }
+        // Indirect require so browser bundlers don't try to bundle the module
+        const req = typeof require === 'function' ? require : undefined;
+        return req ? req(id) : undefined;
+    }
+    catch (_a) {
+        return undefined;
+    }
+};
+//# sourceMappingURL=env.js.map

package/dist/esm/core/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../../src/core/env.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,MAAM,QAAQ,GAAwB,EAAE,CAAC;AAEzC;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,OAA4B,EAAQ,EAAE;IACxE,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AACnC,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,EAAU,EAAO,EAAE;IACjD,IAAI,QAAQ,CAAC,EAAE,CAAC;QAAE,OAAO,QAAQ,CAAC,EAAE,CAAC,CAAC;IACtC,IAAI,CAAC;QACH,MAAM,IAAI,GAAQ,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;QACvE,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI;YAAE,OAAO,SAAS,CAAC;QACrE,IAAI,OAAO,IAAI,CAAC,gBAAgB,KAAK,UAAU,EAAE,CAAC;YAChD,OAAO,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;QACnC,CAAC;QACD,sEAAsE;QACtE,MAAM,GAAG,GAAwC,OAAO,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;QACrG,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACnC,CAAC;IAAC,WAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC,CAAC"}

package/dist/esm/core/event-loop.d.ts

@@ -0,0 +1,30 @@
+/** Event-loop delay distribution in milliseconds */
+export interface EventLoopStats {
+    min: number;
+    max: number;
+    mean: number;
+    stddev: number;
+    p50: number;
+    p90: number;
+    p99: number;
+}
+export interface EventLoopMonitor {
+    /** False outside Node.js (or Node < 11.10); stats() then returns null */
+    readonly supported: boolean;
+    /** Delay distribution since start (or the last reset) */
+    stats(): EventLoopStats | null;
+    /** Start a new measurement window */
+    reset(): void;
+    /** Stop sampling */
+    stop(): void;
+}
+/**
+ * Start sampling event-loop delay.
+ *
+ *   const loop = monitorEventLoop();
+ *   // ... later
+ *   console.log(loop.stats()); // { p99: 12.3, max: 48.1, ... } (ms)
+ */
+export declare function monitorEventLoop(options?: {
+    resolution?: number;
+}): EventLoopMonitor;

package/dist/esm/core/event-loop.js

@@ -0,0 +1,40 @@
+/**
+ * Event-loop delay monitoring (Node.js only).
+ *
+ * A tracked call tells you how long *it* took; event-loop delay tells you
+ * whether something blocked everything else. Node's monitorEventLoopDelay
+ * samples the delay with negligible overhead.
+ */
+import { loadNodeBuiltin } from './env.js';
+/**
+ * Start sampling event-loop delay.
+ *
+ *   const loop = monitorEventLoop();
+ *   // ... later
+ *   console.log(loop.stats()); // { p99: 12.3, max: 48.1, ... } (ms)
+ */
+export function monitorEventLoop(options = {}) {
+    var _a;
+    const perfHooks = loadNodeBuiltin('perf_hooks');
+    if (!perfHooks || typeof perfHooks.monitorEventLoopDelay !== 'function') {
+        return { supported: false, stats: () => null, reset: () => undefined, stop: () => undefined };
+    }
+    const histogram = perfHooks.monitorEventLoopDelay({ resolution: Math.max(1, (_a = options.resolution) !== null && _a !== void 0 ? _a : 10) });
+    histogram.enable();
+    const ms = (ns) => (Number.isFinite(ns) ? ns / 1e6 : 0);
+    return {
+        supported: true,
+        stats: () => ({
+            min: ms(histogram.min),
+            max: ms(histogram.max),
+            mean: ms(histogram.mean),
+            stddev: ms(histogram.stddev),
+            p50: ms(histogram.percentile(50)),
+            p90: ms(histogram.percentile(90)),
+            p99: ms(histogram.percentile(99)),
+        }),
+        reset: () => histogram.reset(),
+        stop: () => histogram.disable(),
+    };
+}
+//# sourceMappingURL=event-loop.js.map

package/dist/esm/core/event-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-loop.js","sourceRoot":"","sources":["../../../src/core/event-loop.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,OAAO,CAAC;AAwBxC;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAmC,EAAE;;IACpE,MAAM,SAAS,GAAG,eAAe,CAAC,YAAY,CAAC,CAAC;IAChD,IAAI,CAAC,SAAS,IAAI,OAAO,SAAS,CAAC,qBAAqB,KAAK,UAAU,EAAE,CAAC;QACxE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC;IAChG,CAAC;IACD,MAAM,SAAS,GAAG,SAAS,CAAC,qBAAqB,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAA,OAAO,CAAC,UAAU,mCAAI,EAAE,CAAC,EAAE,CAAC,CAAC;IACzG,SAAS,CAAC,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,OAAO;QACL,SAAS,EAAE,IAAI;QACf,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;YACZ,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC;YACtB,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC;YACtB,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC;YACxB,MAAM,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC;YAC5B,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YACjC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YACjC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;SAClC,CAAC;QACF,KAAK,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE;QAC9B,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE;KAChC,CAAC;AACJ,CAAC"}

package/dist/esm/core/explain.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Plain-English explanations of finished trees: what made a call slow.
+ *
+ *   const findings = explain(roots);
+ *   console.log(formatFindings(findings));
+ *
+ * Works on records from onComplete / a trace recorder, or on files via
+ * `traceperf explain <file>`. Every finding is a heuristic with the numbers
+ * that triggered it, so it can be checked against the tree.
+ */
+/** The fields explain() reads; ExecutionRecord satisfies it */
+export interface ExplainNode {
+    label: string;
+    /** Start time in ms (any clock, consistent within one input) */
+    startTime: number;
+    duration: number;
+    selfDuration: number;
+    /** Synchronous part in ms (blocked the event loop); defaults to 0 for async calls */
+    syncDuration?: number;
+    async?: boolean;
+    error?: unknown;
+    children: ExplainNode[];
+}
+export type FindingKind = 'blocked' | 'blocking' | 'sequential' | 'repeated' | 'dominant' | 'error';
+export interface Finding {
+    kind: FindingKind;
+    /** Top-level call the finding is about */
+    root: string;
+    /** One-sentence explanation */
+    message: string;
+    /** Estimated milliseconds involved (delay, possible saving, or time taken) */
+    ms: number;
+}
+export interface ExplainOptions {
+    /** Synchronous work at least this long counts as blocking (ms, default 10) */
+    blockingMs?: number;
+    /** Ignore findings smaller than this (ms, default 5) */
+    minMs?: number;
+    /** A child taking at least this fraction of its parent is "dominant" (default 0.6) */
+    dominantShare?: number;
+    /** Same label this many times under one parent is "repeated" (default 5) */
+    repeatCount?: number;
+    /** Return at most this many findings, largest first (default 20) */
+    max?: number;
+}
+export declare function explain(roots: ExplainNode[], options?: ExplainOptions): Finding[];
+/** Render findings as text, one per line */
+export declare function formatFindings(findings: Finding[]): string;