@mtharrison/pkg-profiler 2.0.0 → 2.1.0

package/dist/index.cjs

@@ -12,6 +12,9 @@ let node_url = require("node:url");
 * Tracks the time between async resource init (when the I/O op is started)
 * and the first before callback (when the callback fires), attributing
 * that wait time to the package/file/function that initiated the operation.
+*
+* Intervals are buffered and merged at disable() time so that overlapping
+* concurrent I/O is not double-counted.
 */
 /** Async resource types worth tracking — I/O and timers, not promises. */
 const TRACKED_TYPES = new Set([
@@ -32,6 +35,37 @@ const TRACKED_TYPES = new Set([
 	"Timeout"
 ]);
 /**
+* Merge overlapping or adjacent intervals. Returns a new sorted array
+* of non-overlapping intervals.
+*/
+function mergeIntervals(intervals) {
+	if (intervals.length <= 1) return intervals.slice();
+	const sorted = intervals.slice().sort((a, b) => a.startUs - b.startUs);
+	const merged = [{ ...sorted[0] }];
+	for (let i = 1; i < sorted.length; i++) {
+		const current = sorted[i];
+		const last = merged[merged.length - 1];
+		if (current.startUs <= last.endUs) {
+			if (current.endUs > last.endUs) last.endUs = current.endUs;
+		} else merged.push({ ...current });
+	}
+	return merged;
+}
+/**
+* Sum the durations of a list of (presumably non-overlapping) intervals.
+*/
+function sumIntervals(intervals) {
+	let total = 0;
+	for (const iv of intervals) total += iv.endUs - iv.startUs;
+	return total;
+}
+/**
+* Convert an hrtime tuple to absolute microseconds.
+*/
+function hrtimeToUs(hr) {
+	return hr[0] * 1e6 + Math.round(hr[1] / 1e3);
+}
+/**
 * Parse a single line from an Error().stack trace into file path and function id.
 * Returns null for lines that don't match V8's stack frame format or are node internals.
 *
@@ -55,22 +89,34 @@ function parseStackLine(line) {
 }
 var AsyncTracker = class {
 	resolver;
-	store;
 	thresholdUs;
 	hook = null;
 	pending = /* @__PURE__ */ new Map();
+	/** Buffered intervals keyed by "pkg\0file\0fn" */
+	keyedIntervals = /* @__PURE__ */ new Map();
+	/** Flat list of all intervals for global merging */
+	globalIntervals = [];
+	/** Origin time in absolute microseconds, set when enable() is called */
+	originUs = 0;
+	/** Merged global total set after flush() */
+	_mergedTotalUs = 0;
 	/**
 	* @param resolver - PackageResolver for mapping file paths to packages
-	* @param store - SampleStore to record async wait times into
+	* @param store - SampleStore to record async wait times into (used at flush time)
 	* @param thresholdUs - Minimum wait duration in microseconds to record (default 1000 = 1ms)
 	*/
 	constructor(resolver, store, thresholdUs = 1e3) {
-		this.resolver = resolver;
 		this.store = store;
+		this.resolver = resolver;
 		this.thresholdUs = thresholdUs;
 	}
+	/** Merged global async total in microseconds, available after disable(). */
+	get mergedTotalUs() {
+		return this._mergedTotalUs;
+	}
 	enable() {
 		if (this.hook) return;
+		this.originUs = hrtimeToUs(process.hrtime());
 		this.hook = (0, node_async_hooks.createHook)({
 			init: (asyncId, type) => {
 				if (!TRACKED_TYPES.has(type)) return;
@@ -103,9 +149,23 @@ var AsyncTracker = class {
 			before: (asyncId) => {
 				const op = this.pending.get(asyncId);
 				if (!op) return;
-				const elapsed = process.hrtime(op.startHrtime);
-				const durationUs = elapsed[0] * 1e6 + Math.round(elapsed[1] / 1e3);
-				if (durationUs >= this.thresholdUs) this.store.record(op.pkg, op.file, op.fn, durationUs);
+				const endHr = process.hrtime();
+				const startUs = hrtimeToUs(op.startHrtime);
+				const endUs = hrtimeToUs(endHr);
+				if (endUs - startUs >= this.thresholdUs) {
+					const interval = {
+						startUs,
+						endUs
+					};
+					const key = `${op.pkg}\0${op.file}\0${op.fn}`;
+					let arr = this.keyedIntervals.get(key);
+					if (!arr) {
+						arr = [];
+						this.keyedIntervals.set(key, arr);
+					}
+					arr.push(interval);
+					this.globalIntervals.push(interval);
+				}
 				this.pending.delete(asyncId);
 			},
 			destroy: (asyncId) => {
@@ -117,19 +177,43 @@ var AsyncTracker = class {
 	disable() {
 		if (!this.hook) return;
 		this.hook.disable();
-		const now = process.hrtime();
+		const nowUs = hrtimeToUs(process.hrtime());
 		for (const [, op] of this.pending) {
-			let secs = now[0] - op.startHrtime[0];
-			let nanos = now[1] - op.startHrtime[1];
-			if (nanos < 0) {
-				secs -= 1;
-				nanos += 1e9;
+			const startUs = hrtimeToUs(op.startHrtime);
+			if (nowUs - startUs >= this.thresholdUs) {
+				const interval = {
+					startUs,
+					endUs: nowUs
+				};
+				const key = `${op.pkg}\0${op.file}\0${op.fn}`;
+				let arr = this.keyedIntervals.get(key);
+				if (!arr) {
+					arr = [];
+					this.keyedIntervals.set(key, arr);
+				}
+				arr.push(interval);
+				this.globalIntervals.push(interval);
 			}
-			const durationUs = secs * 1e6 + Math.round(nanos / 1e3);
-			if (durationUs >= this.thresholdUs) this.store.record(op.pkg, op.file, op.fn, durationUs);
 		}
 		this.pending.clear();
 		this.hook = null;
+		this.flush();
+	}
+	/**
+	* Merge buffered intervals and record to the store.
+	* Sets mergedTotalUs to the global merged duration.
+	*/
+	flush() {
+		for (const [key, intervals] of this.keyedIntervals) {
+			const totalUs = sumIntervals(mergeIntervals(intervals));
+			if (totalUs > 0) {
+				const parts = key.split("\0");
+				this.store.record(parts[0], parts[1], parts[2], totalUs);
+			}
+		}
+		this._mergedTotalUs = sumIntervals(mergeIntervals(this.globalIntervals));
+		this.keyedIntervals.clear();
+		this.globalIntervals = [];
 	}
 };
 
@@ -566,9 +650,59 @@ function generateCss() {
     .other-item.indent-1 { padding-left: 2rem; }
     .other-item.indent-2 { padding-left: 3.25rem; }
 
+    /* Sort control */
+    .sort-control {
+      display: inline-flex;
+      align-items: center;
+      gap: 0.5rem;
+      margin-left: 1.5rem;
+      font-size: 0.85rem;
+    }
+
+    .sort-control label {
+      font-weight: 600;
+      color: var(--muted);
+      text-transform: uppercase;
+      letter-spacing: 0.04em;
+      font-size: 0.8rem;
+    }
+
+    .sort-toggle {
+      display: inline-flex;
+      border: 1px solid var(--border);
+      border-radius: 4px;
+      overflow: hidden;
+    }
+
+    .sort-toggle button {
+      font-family: var(--font-sans);
+      font-size: 0.8rem;
+      padding: 0.25rem 0.6rem;
+      border: none;
+      background: #fff;
+      color: var(--muted);
+      cursor: pointer;
+      transition: background 0.15s, color 0.15s;
+    }
+
+    .sort-toggle button + button {
+      border-left: 1px solid var(--border);
+    }
+
+    .sort-toggle button.active {
+      background: var(--bar-fill);
+      color: #fff;
+    }
+
+    .sort-toggle button.active-async {
+      background: var(--bar-fill-async);
+      color: #fff;
+    }
+
     @media (max-width: 600px) {
       body { padding: 1rem; }
       .bar-cell { width: 25%; }
+      .sort-control { margin-left: 0; margin-top: 0.5rem; }
     }
   `;
 }
@@ -601,14 +735,27 @@ function generateJs() {
       .replace(/'/g, '&#39;');
   }
 
+  var sortBy = 'cpu';
+
+  function metricTime(entry) {
+    return sortBy === 'async' ? (entry.asyncTimeUs || 0) : entry.timeUs;
+  }
+
+  function sortDesc(arr) {
+    return arr.slice().sort(function(a, b) { return metricTime(b) - metricTime(a); });
+  }
+
   function applyThreshold(data, pct) {
-    var threshold = data.totalTimeUs * (pct / 100);
+    var totalBase = sortBy === 'async' ? (data.totalAsyncTimeUs || 0) : data.totalTimeUs;
+    var threshold = totalBase * (pct / 100);
     var filtered = [];
     var otherCount = 0;
 
-    for (var i = 0; i < data.packages.length; i++) {
-      var pkg = data.packages[i];
-      if (pkg.timeUs < threshold) {
+    var pkgs = sortDesc(data.packages);
+
+    for (var i = 0; i < pkgs.length; i++) {
+      var pkg = pkgs[i];
+      if (metricTime(pkg) < threshold) {
         otherCount++;
         continue;
       }
@@ -616,9 +763,11 @@ function generateJs() {
       var files = [];
       var fileOtherCount = 0;
 
-      for (var j = 0; j < pkg.files.length; j++) {
-        var file = pkg.files[j];
-        if (file.timeUs < threshold) {
+      var sortedFiles = sortDesc(pkg.files);
+
+      for (var j = 0; j < sortedFiles.length; j++) {
+        var file = sortedFiles[j];
+        if (metricTime(file) < threshold) {
           fileOtherCount++;
           continue;
         }
@@ -626,9 +775,11 @@ function generateJs() {
         var functions = [];
         var funcOtherCount = 0;
 
-        for (var k = 0; k < file.functions.length; k++) {
-          var fn = file.functions[k];
-          if (fn.timeUs < threshold) {
+        var sortedFns = sortDesc(file.functions);
+
+        for (var k = 0; k < sortedFns.length; k++) {
+          var fn = sortedFns[k];
+          if (metricTime(fn) < threshold) {
             funcOtherCount++;
             continue;
           }
@@ -665,18 +816,21 @@ function generateJs() {
     return { packages: filtered, otherCount: otherCount };
   }
 
-  function renderTable(packages, otherCount, totalTimeUs) {
+  function renderTable(packages, otherCount, totalTimeUs, totalAsyncTimeUs) {
     var rows = '';
+    var isAsync = sortBy === 'async';
+    var barTotal = isAsync ? (totalAsyncTimeUs || 0) : totalTimeUs;
     for (var i = 0; i < packages.length; i++) {
       var pkg = packages[i];
       var cls = pkg.isFirstParty ? 'first-party' : 'dependency';
-      var pctVal = totalTimeUs > 0 ? (pkg.timeUs / totalTimeUs) * 100 : 0;
+      var barVal = isAsync ? (pkg.asyncTimeUs || 0) : pkg.timeUs;
+      var pctVal = barTotal > 0 ? (barVal / barTotal) * 100 : 0;
       rows += '<tr class="' + cls + '">' +
         '<td class="pkg-name">' + escapeHtml(pkg.name) + '</td>' +
         '<td class="numeric">' + escapeHtml(formatTime(pkg.timeUs)) + '</td>' +
         '<td class="bar-cell"><div class="bar-container">' +
           '<div class="bar-track"><div class="bar-fill" style="width:' + pctVal.toFixed(1) + '%"></div></div>' +
-          '<span class="bar-pct">' + escapeHtml(formatPct(pkg.timeUs, totalTimeUs)) + '</span>' +
+          '<span class="bar-pct">' + escapeHtml(formatPct(barVal, barTotal)) + '</span>' +
         '</div></td>' +
         '<td class="numeric">' + pkg.sampleCount + '</td>';
       if (HAS_ASYNC) {
@@ -698,9 +852,9 @@ function generateJs() {
       rows += '</tr>';
     }
 
-    var headers = '<th>Package</th><th>Wall Time</th><th>% of Total</th><th>Samples</th>';
+    var headers = '<th>Package</th><th>CPU Time</th><th>% of Total</th><th>Samples</th>';
     if (HAS_ASYNC) {
-      headers += '<th>Async Wait</th><th>Async Ops</th>';
+      headers += '<th>Async I/O Wait</th><th>Async Ops</th>';
     }
 
     return '<table><thead><tr>' + headers + '</tr></thead><tbody>' + rows + '</tbody></table>';
@@ -714,34 +868,39 @@ function generateJs() {
     return ' <span class="tree-async">| ' + escapeHtml(formatTime(at)) + ' async &middot; ' + ac + ' ops</span>';
   }
 
-  function renderTree(packages, otherCount, totalTimeUs) {
+  function renderTree(packages, otherCount, totalTimeUs, totalAsyncTimeUs) {
     var html = '<div class="tree">';
+    var isAsync = sortBy === 'async';
+    var pctTotal = isAsync ? (totalAsyncTimeUs || 0) : totalTimeUs;
 
     for (var i = 0; i < packages.length; i++) {
       var pkg = packages[i];
       var fpCls = pkg.isFirstParty ? ' fp-pkg' : '';
+      var pkgTime = isAsync ? (pkg.asyncTimeUs || 0) : pkg.timeUs;
       html += '<details class="level-0' + fpCls + '"><summary>';
       html += '<span class="tree-label pkg">pkg</span>';
       html += '<span class="tree-name">' + escapeHtml(pkg.name) + '</span>';
-      html += '<span class="tree-stats">' + escapeHtml(formatTime(pkg.timeUs)) + ' &middot; ' + escapeHtml(formatPct(pkg.timeUs, totalTimeUs)) + ' &middot; ' + pkg.sampleCount + ' samples</span>';
+      html += '<span class="tree-stats">' + escapeHtml(formatTime(pkgTime)) + ' &middot; ' + escapeHtml(formatPct(pkgTime, pctTotal)) + ' &middot; ' + pkg.sampleCount + ' samples</span>';
       html += asyncStats(pkg);
       html += '</summary>';
 
       for (var j = 0; j < pkg.files.length; j++) {
         var file = pkg.files[j];
+        var fileTime = isAsync ? (file.asyncTimeUs || 0) : file.timeUs;
         html += '<details class="level-1"><summary>';
         html += '<span class="tree-label file">file</span>';
         html += '<span class="tree-name">' + escapeHtml(file.name) + '</span>';
-        html += '<span class="tree-stats">' + escapeHtml(formatTime(file.timeUs)) + ' &middot; ' + escapeHtml(formatPct(file.timeUs, totalTimeUs)) + ' &middot; ' + file.sampleCount + ' samples</span>';
+        html += '<span class="tree-stats">' + escapeHtml(formatTime(fileTime)) + ' &middot; ' + escapeHtml(formatPct(fileTime, pctTotal)) + ' &middot; ' + file.sampleCount + ' samples</span>';
         html += asyncStats(file);
         html += '</summary>';
 
         for (var k = 0; k < file.functions.length; k++) {
           var fn = file.functions[k];
+          var fnTime = isAsync ? (fn.asyncTimeUs || 0) : fn.timeUs;
           html += '<div class="level-2">';
           html += '<span class="tree-label fn">fn</span> ';
           html += '<span class="tree-name">' + escapeHtml(fn.name) + '</span>';
-          html += ' <span class="tree-stats">' + escapeHtml(formatTime(fn.timeUs)) + ' &middot; ' + escapeHtml(formatPct(fn.timeUs, totalTimeUs)) + ' &middot; ' + fn.sampleCount + ' samples</span>';
+          html += ' <span class="tree-stats">' + escapeHtml(formatTime(fnTime)) + ' &middot; ' + escapeHtml(formatPct(fnTime, pctTotal)) + ' &middot; ' + fn.sampleCount + ' samples</span>';
           html += asyncStats(fn);
           html += '</div>';
         }
@@ -768,12 +927,26 @@ function generateJs() {
     return html;
   }
 
+  var currentThreshold = 5;
+
   function update(pct) {
+    currentThreshold = pct;
     var result = applyThreshold(DATA, pct);
     var summaryEl = document.getElementById('summary-container');
     var treeEl = document.getElementById('tree-container');
-    if (summaryEl) summaryEl.innerHTML = renderTable(result.packages, result.otherCount, DATA.totalTimeUs);
-    if (treeEl) treeEl.innerHTML = renderTree(result.packages, result.otherCount, DATA.totalTimeUs);
+    if (summaryEl) summaryEl.innerHTML = renderTable(result.packages, result.otherCount, DATA.totalTimeUs, DATA.totalAsyncTimeUs);
+    if (treeEl) treeEl.innerHTML = renderTree(result.packages, result.otherCount, DATA.totalTimeUs, DATA.totalAsyncTimeUs);
+  }
+
+  function updateSortButtons() {
+    var btns = document.querySelectorAll('.sort-toggle button');
+    for (var i = 0; i < btns.length; i++) {
+      var btn = btns[i];
+      btn.className = '';
+      if (btn.getAttribute('data-sort') === sortBy) {
+        btn.className = sortBy === 'async' ? 'active-async' : 'active';
+      }
+    }
   }
 
   document.addEventListener('DOMContentLoaded', function() {
@@ -787,6 +960,15 @@ function generateJs() {
         update(val);
       });
     }
+
+    var sortBtns = document.querySelectorAll('.sort-toggle button');
+    for (var i = 0; i < sortBtns.length; i++) {
+      sortBtns[i].addEventListener('click', function() {
+        sortBy = this.getAttribute('data-sort') || 'cpu';
+        updateSortButtons();
+        update(currentThreshold);
+      });
+    }
   });
 })();
 `;
@@ -825,10 +1007,10 @@ function renderSummaryTable(packages, otherCount, totalTimeUs, hasAsync) {
       <thead>
         <tr>
           <th>Package</th>
-          <th>Wall Time</th>
+          <th>CPU Time</th>
           <th>% of Total</th>
           <th>Samples</th>${hasAsync ? `
-          <th>Async Wait</th>
+          <th>Async I/O Wait</th>
           <th>Async Ops</th>` : ""}
         </tr>
       </thead>
@@ -891,8 +1073,11 @@ function renderHtml(data) {
 	const tree = renderTree(data.packages, data.otherCount, data.totalTimeUs, hasAsync);
 	const totalFormatted = escapeHtml(formatTime(data.totalTimeUs));
 	const titleName = escapeHtml(data.projectName);
-	let metaLine = `Generated ${escapeHtml(data.timestamp)} &middot; Total wall time: ${totalFormatted}`;
-	if (hasAsync) metaLine += ` &middot; Total async wait: ${escapeHtml(formatTime(data.totalAsyncTimeUs))}`;
+	const wallFormatted = data.wallTimeUs ? escapeHtml(formatTime(data.wallTimeUs)) : null;
+	let metaLine = `Generated ${escapeHtml(data.timestamp)}`;
+	if (wallFormatted) metaLine += ` &middot; Wall time: ${wallFormatted}`;
+	metaLine += ` &middot; CPU time: ${totalFormatted}`;
+	if (hasAsync) metaLine += ` &middot; Async I/O wait: ${escapeHtml(formatTime(data.totalAsyncTimeUs))}`;
 	const safeJson = JSON.stringify(data).replace(/</g, "\\u003c");
 	return `<!DOCTYPE html>
 <html lang="en">
@@ -911,7 +1096,14 @@ function renderHtml(data) {
   <div class="threshold-control">
     <label>Threshold</label>
     <input type="range" id="threshold-slider" min="0" max="20" step="0.5" value="5">
-    <span id="threshold-value">5.0%</span>
+    <span id="threshold-value">5.0%</span>${hasAsync ? `
+    <span class="sort-control">
+      <label>Sort by</label>
+      <span class="sort-toggle">
+        <button data-sort="cpu" class="active">CPU Time</button>
+        <button data-sort="async">Async I/O Wait</button>
+      </span>
+    </span>` : ""}
   </div>
   <div id="summary-container">${summaryTable}</div>
 
@@ -950,6 +1142,8 @@ var PkgProfile = class {
 	projectName;
 	/** Total async wait time in microseconds (undefined when async tracking not enabled) */
 	totalAsyncTimeUs;
+	/** Elapsed wall time in microseconds from start() to stop() */
+	wallTimeUs;
 	/** @internal */
 	constructor(data) {
 		this.timestamp = data.timestamp;
@@ -958,6 +1152,7 @@ var PkgProfile = class {
 		this.otherCount = data.otherCount;
 		this.projectName = data.projectName;
 		this.totalAsyncTimeUs = data.totalAsyncTimeUs;
+		this.wallTimeUs = data.wallTimeUs;
 	}
 	/**
 	* Write a self-contained HTML report to disk.
@@ -972,7 +1167,8 @@ var PkgProfile = class {
 			packages: this.packages,
 			otherCount: this.otherCount,
 			projectName: this.projectName,
-			totalAsyncTimeUs: this.totalAsyncTimeUs
+			totalAsyncTimeUs: this.totalAsyncTimeUs,
+			wallTimeUs: this.wallTimeUs
 		});
 		let filepath;
 		if (path) filepath = (0, node_path.resolve)(path);
@@ -1003,9 +1199,10 @@ function sumStore(store) {
 * @param asyncStore - Optional SampleStore with async wait time data
 * @returns ReportData with all packages sorted desc by time, no threshold applied
 */
-function aggregate(store, projectName, asyncStore) {
+function aggregate(store, projectName, asyncStore, globalAsyncTimeUs, wallTimeUs) {
 	const totalTimeUs = sumStore(store);
 	const totalAsyncTimeUs = asyncStore ? sumStore(asyncStore) : 0;
+	const headerAsyncTimeUs = globalAsyncTimeUs ?? totalAsyncTimeUs;
 	if (totalTimeUs === 0 && totalAsyncTimeUs === 0) return {
 		timestamp: (/* @__PURE__ */ new Date()).toLocaleString(),
 		totalTimeUs: 0,
@@ -1110,7 +1307,8 @@ function aggregate(store, projectName, asyncStore) {
 		otherCount: 0,
 		projectName
 	};
-	if (totalAsyncTimeUs > 0) result.totalAsyncTimeUs = totalAsyncTimeUs;
+	if (headerAsyncTimeUs > 0) result.totalAsyncTimeUs = headerAsyncTimeUs;
+	if (wallTimeUs !== void 0) result.wallTimeUs = wallTimeUs;
 	return result;
 }
 
@@ -1194,6 +1392,7 @@ var SampleStore = class {
 //#region src/sampler.ts
 let session = null;
 let profiling = false;
+let startHrtime = null;
 const store = new SampleStore();
 const asyncStore = new SampleStore();
 const resolver = new PackageResolver(process.cwd());
@@ -1250,15 +1449,20 @@ function buildEmptyProfile() {
 */
 function stopSync() {
 	if (!profiling || !session) return buildEmptyProfile();
+	const elapsed = startHrtime ? process.hrtime(startHrtime) : null;
+	const wallTimeUs = elapsed ? elapsed[0] * 1e6 + Math.round(elapsed[1] / 1e3) : void 0;
+	startHrtime = null;
 	const { profile } = postSync("Profiler.stop");
 	postSync("Profiler.disable");
 	profiling = false;
+	let globalAsyncTimeUs;
 	if (asyncTracker) {
 		asyncTracker.disable();
+		globalAsyncTimeUs = asyncTracker.mergedTotalUs;
 		asyncTracker = null;
 	}
 	processProfile(profile);
-	const data = aggregate(store, readProjectName(process.cwd()), asyncStore.packages.size > 0 ? asyncStore : void 0);
+	const data = aggregate(store, readProjectName(process.cwd()), asyncStore.packages.size > 0 ? asyncStore : void 0, globalAsyncTimeUs, wallTimeUs);
 	store.clear();
 	asyncStore.clear();
 	return new PkgProfile(data);
@@ -1280,6 +1484,7 @@ async function start(options) {
 	if (options?.interval !== void 0) await postAsync("Profiler.setSamplingInterval", { interval: options.interval });
 	await postAsync("Profiler.start");
 	profiling = true;
+	startHrtime = process.hrtime();
 	if (options?.trackAsync) {
 		asyncTracker = new AsyncTracker(resolver, asyncStore);
 		asyncTracker.enable();
@@ -1303,6 +1508,7 @@ async function clear() {
 		postSync("Profiler.disable");
 		profiling = false;
 	}
+	startHrtime = null;
 	store.clear();
 	if (asyncTracker) {
 		asyncTracker.disable();