@mtharrison/pkg-profiler 1.1.0 → 2.1.0

package/src/pkg-profile.ts

@@ -0,0 +1,77 @@
+/**
+ * Immutable profiling result returned by `stop()` and `profile()`.
+ *
+ * Contains aggregated per-package timing data and a convenience method
+ * to write a self-contained HTML report to disk.
+ */
+
+import { writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import type { PackageEntry, ReportData } from './types.js';
+import { renderHtml } from './reporter/html.js';
+
+function generateFilename(timestamp: string): string {
+  const now = new Date();
+  const pad = (n: number) => String(n).padStart(2, '0');
+  const date = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+  const time = `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+  return `where-you-at-${date}-${time}.html`;
+}
+
+export class PkgProfile {
+  /** When the profile was captured */
+  readonly timestamp: string;
+  /** Total sampled wall time in microseconds */
+  readonly totalTimeUs: number;
+  /** Package breakdown sorted by time descending (all packages, no threshold applied) */
+  readonly packages: PackageEntry[];
+  /** Always 0 — threshold filtering is now applied client-side in the HTML report */
+  readonly otherCount: number;
+  /** Project name (from package.json) */
+  readonly projectName: string;
+  /** Total async wait time in microseconds (undefined when async tracking not enabled) */
+  readonly totalAsyncTimeUs?: number;
+  /** Elapsed wall time in microseconds from start() to stop() */
+  readonly wallTimeUs?: number;
+
+  /** @internal */
+  constructor(data: ReportData) {
+    this.timestamp = data.timestamp;
+    this.totalTimeUs = data.totalTimeUs;
+    this.packages = data.packages;
+    this.otherCount = data.otherCount;
+    this.projectName = data.projectName;
+    this.totalAsyncTimeUs = data.totalAsyncTimeUs;
+    this.wallTimeUs = data.wallTimeUs;
+  }
+
+  /**
+   * Write a self-contained HTML report to disk.
+   *
+   * @param path - Output file path. Defaults to `./where-you-at-{timestamp}.html` in cwd.
+   * @returns Absolute path to the written file.
+   */
+  writeHtml(path?: string): string {
+    const data: ReportData = {
+      timestamp: this.timestamp,
+      totalTimeUs: this.totalTimeUs,
+      packages: this.packages,
+      otherCount: this.otherCount,
+      projectName: this.projectName,
+      totalAsyncTimeUs: this.totalAsyncTimeUs,
+      wallTimeUs: this.wallTimeUs,
+    };
+    const html = renderHtml(data);
+
+    let filepath: string;
+    if (path) {
+      filepath = resolve(path);
+    } else {
+      const filename = generateFilename(this.timestamp);
+      filepath = join(process.cwd(), filename);
+    }
+
+    writeFileSync(filepath, html, 'utf-8');
+    return filepath;
+  }
+}

package/src/reporter/aggregate.ts

@@ -1,10 +1,9 @@
 /**
- * Transform raw SampleStore data into a sorted, thresholded ReportData structure.
+ * Transform raw SampleStore data into a sorted ReportData structure.
  *
- * Pure function: reads nested Maps from SampleStore, applies a 5% threshold
- * at every level (package, file, function) relative to the total profiled time,
- * aggregates below-threshold entries into an "other" count, and sorts by
- * timeUs descending at each level.
+ * Pure function: reads nested Maps from SampleStore, computes percentages,
+ * and sorts by timeUs descending at each level. No threshold filtering —
+ * all entries are included so the HTML report can apply thresholds client-side.
  */
 
 import type { SampleStore } from '../sample-store.js';
@@ -15,27 +14,38 @@ import type {
   FunctionEntry,
 } from '../types.js';
 
-const THRESHOLD_PCT = 0.05;
-
 /**
- * Aggregate SampleStore data into a ReportData structure.
- *
- * @param store - SampleStore with accumulated microseconds and sample counts
- * @param projectName - Name of the first-party project (for isFirstParty flag)
- * @returns ReportData with packages sorted desc by time, thresholded at 5%
+ * Sum all microseconds in a SampleStore.
  */
-export function aggregate(store: SampleStore, projectName: string): ReportData {
-  // 1. Calculate total user-attributed time
-  let totalTimeUs = 0;
+function sumStore(store: SampleStore): number {
+  let total = 0;
   for (const fileMap of store.packages.values()) {
     for (const funcMap of fileMap.values()) {
       for (const us of funcMap.values()) {
-        totalTimeUs += us;
+        total += us;
       }
     }
   }
+  return total;
+}
 
-  if (totalTimeUs === 0) {
+/**
+ * Aggregate SampleStore data into a ReportData structure.
+ *
+ * @param store - SampleStore with accumulated microseconds and sample counts
+ * @param projectName - Name of the first-party project (for isFirstParty flag)
+ * @param asyncStore - Optional SampleStore with async wait time data
+ * @returns ReportData with all packages sorted desc by time, no threshold applied
+ */
+export function aggregate(store: SampleStore, projectName: string, asyncStore?: SampleStore, globalAsyncTimeUs?: number, wallTimeUs?: number): ReportData {
+  // 1. Calculate total user-attributed time
+  const totalTimeUs = sumStore(store);
+  // Per-entry percentages use the raw sum so they add up to 100%
+  const totalAsyncTimeUs = asyncStore ? sumStore(asyncStore) : 0;
+  // Header total uses the merged (de-duplicated) global value when available
+  const headerAsyncTimeUs = globalAsyncTimeUs ?? totalAsyncTimeUs;
+
+  if (totalTimeUs === 0 && totalAsyncTimeUs === 0) {
     return {
       timestamp: new Date().toLocaleString(),
       totalTimeUs: 0,
@@ -45,26 +55,29 @@ export function aggregate(store: SampleStore, projectName: string): ReportData {
     };
   }
 
-  const threshold = totalTimeUs * THRESHOLD_PCT;
+  // Collect all package names from both stores
+  const allPackageNames = new Set<string>();
+  for (const name of store.packages.keys()) allPackageNames.add(name);
+  if (asyncStore) {
+    for (const name of asyncStore.packages.keys()) allPackageNames.add(name);
+  }
+
   const packages: PackageEntry[] = [];
-  let topLevelOtherCount = 0;
 
   // 2. Process each package
-  for (const [packageName, fileMap] of store.packages) {
-    // Sum total time for this package
+  for (const packageName of allPackageNames) {
+    const fileMap = store.packages.get(packageName);
+
+    // Sum total CPU time for this package
     let packageTimeUs = 0;
-    for (const funcMap of fileMap.values()) {
-      for (const us of funcMap.values()) {
-        packageTimeUs += us;
+    if (fileMap) {
+      for (const funcMap of fileMap.values()) {
+        for (const us of funcMap.values()) {
+          packageTimeUs += us;
+        }
       }
     }
 
-    // Apply threshold at package level
-    if (packageTimeUs < threshold) {
-      topLevelOtherCount++;
-      continue;
-    }
-
     // Sum total sample count for this package
     let packageSampleCount = 0;
     const countFileMap = store.sampleCountsByPackage.get(packageName);
@@ -76,21 +89,46 @@ export function aggregate(store: SampleStore, projectName: string): ReportData {
       }
     }
 
-    // 3. Process files within the package
+    // Async totals for this package
+    let packageAsyncTimeUs = 0;
+    let packageAsyncOpCount = 0;
+    const asyncFileMap = asyncStore?.packages.get(packageName);
+    const asyncCountFileMap = asyncStore?.sampleCountsByPackage.get(packageName);
+    if (asyncFileMap) {
+      for (const funcMap of asyncFileMap.values()) {
+        for (const us of funcMap.values()) {
+          packageAsyncTimeUs += us;
+        }
+      }
+    }
+    if (asyncCountFileMap) {
+      for (const countFuncMap of asyncCountFileMap.values()) {
+        for (const count of countFuncMap.values()) {
+          packageAsyncOpCount += count;
+        }
+      }
+    }
+
+    // 3. Collect all file names from both stores for this package
+    const allFileNames = new Set<string>();
+    if (fileMap) {
+      for (const name of fileMap.keys()) allFileNames.add(name);
+    }
+    if (asyncFileMap) {
+      for (const name of asyncFileMap.keys()) allFileNames.add(name);
+    }
+
     const files: FileEntry[] = [];
-    let fileOtherCount = 0;
 
-    for (const [fileName, funcMap] of fileMap) {
-      // Sum time for this file
-      let fileTimeUs = 0;
-      for (const us of funcMap.values()) {
-        fileTimeUs += us;
-      }
+    for (const fileName of allFileNames) {
+      const funcMap = fileMap?.get(fileName);
 
-      // Apply threshold at file level (relative to total)
-      if (fileTimeUs < threshold) {
-        fileOtherCount++;
-        continue;
+      // Sum CPU time for this file
+      let fileTimeUs = 0;
+      if (funcMap) {
+        for (const us of funcMap.values()) {
+          fileTimeUs += us;
+        }
       }
 
       // Sum sample count for this file
@@ -102,62 +140,116 @@ export function aggregate(store: SampleStore, projectName: string): ReportData {
         }
       }
 
-      // 4. Process functions within the file
-      const functions: FunctionEntry[] = [];
-      let funcOtherCount = 0;
-
-      for (const [funcName, funcTimeUs] of funcMap) {
-        // Apply threshold at function level (relative to total)
-        if (funcTimeUs < threshold) {
-          funcOtherCount++;
-          continue;
+      // Async totals for this file
+      let fileAsyncTimeUs = 0;
+      let fileAsyncOpCount = 0;
+      const asyncFuncMap = asyncFileMap?.get(fileName);
+      const asyncCountFuncMap = asyncCountFileMap?.get(fileName);
+      if (asyncFuncMap) {
+        for (const us of asyncFuncMap.values()) {
+          fileAsyncTimeUs += us;
         }
+      }
+      if (asyncCountFuncMap) {
+        for (const count of asyncCountFuncMap.values()) {
+          fileAsyncOpCount += count;
+        }
+      }
+
+      // 4. Collect all function names from both stores for this file
+      const allFuncNames = new Set<string>();
+      if (funcMap) {
+        for (const name of funcMap.keys()) allFuncNames.add(name);
+      }
+      if (asyncFuncMap) {
+        for (const name of asyncFuncMap.keys()) allFuncNames.add(name);
+      }
+
+      const functions: FunctionEntry[] = [];
 
+      for (const funcName of allFuncNames) {
+        const funcTimeUs = funcMap?.get(funcName) ?? 0;
         const funcSampleCount = countFuncMap?.get(funcName) ?? 0;
+        const funcAsyncTimeUs = asyncFuncMap?.get(funcName) ?? 0;
+        const funcAsyncOpCount = asyncCountFuncMap?.get(funcName) ?? 0;
 
-        functions.push({
+        const entry: FunctionEntry = {
           name: funcName,
           timeUs: funcTimeUs,
-          pct: (funcTimeUs / totalTimeUs) * 100,
+          pct: totalTimeUs > 0 ? (funcTimeUs / totalTimeUs) * 100 : 0,
           sampleCount: funcSampleCount,
-        });
+        };
+
+        if (totalAsyncTimeUs > 0) {
+          entry.asyncTimeUs = funcAsyncTimeUs;
+          entry.asyncPct = (funcAsyncTimeUs / totalAsyncTimeUs) * 100;
+          entry.asyncOpCount = funcAsyncOpCount;
+        }
+
+        functions.push(entry);
       }
 
       // Sort functions by timeUs descending
       functions.sort((a, b) => b.timeUs - a.timeUs);
 
-      files.push({
+      const fileEntry: FileEntry = {
         name: fileName,
         timeUs: fileTimeUs,
-        pct: (fileTimeUs / totalTimeUs) * 100,
+        pct: totalTimeUs > 0 ? (fileTimeUs / totalTimeUs) * 100 : 0,
         sampleCount: fileSampleCount,
         functions,
-        otherCount: funcOtherCount,
-      });
+        otherCount: 0,
+      };
+
+      if (totalAsyncTimeUs > 0) {
+        fileEntry.asyncTimeUs = fileAsyncTimeUs;
+        fileEntry.asyncPct = (fileAsyncTimeUs / totalAsyncTimeUs) * 100;
+        fileEntry.asyncOpCount = fileAsyncOpCount;
+      }
+
+      files.push(fileEntry);
     }
 
     // Sort files by timeUs descending
     files.sort((a, b) => b.timeUs - a.timeUs);
 
-    packages.push({
+    const pkgEntry: PackageEntry = {
       name: packageName,
       timeUs: packageTimeUs,
-      pct: (packageTimeUs / totalTimeUs) * 100,
+      pct: totalTimeUs > 0 ? (packageTimeUs / totalTimeUs) * 100 : 0,
       isFirstParty: packageName === projectName,
       sampleCount: packageSampleCount,
       files,
-      otherCount: fileOtherCount,
-    });
+      otherCount: 0,
+    };
+
+    if (totalAsyncTimeUs > 0) {
+      pkgEntry.asyncTimeUs = packageAsyncTimeUs;
+      pkgEntry.asyncPct = (packageAsyncTimeUs / totalAsyncTimeUs) * 100;
+      pkgEntry.asyncOpCount = packageAsyncOpCount;
+    }
+
+    packages.push(pkgEntry);
   }
 
   // Sort packages by timeUs descending
   packages.sort((a, b) => b.timeUs - a.timeUs);
 
-  return {
+  const result: ReportData = {
     timestamp: new Date().toLocaleString(),
     totalTimeUs,
     packages,
-    otherCount: topLevelOtherCount,
+    otherCount: 0,
     projectName,
   };
+
+  if (headerAsyncTimeUs > 0) {
+    result.totalAsyncTimeUs = headerAsyncTimeUs;
+  }
+
+  if (wallTimeUs !== undefined) {
+    result.wallTimeUs = wallTimeUs;
+  }
+
+  return result;
 }

package/src/reporter/format.ts

@@ -10,6 +10,9 @@
  * - < 1s:  shows rounded milliseconds (e.g. "432ms")
  * - Sub-millisecond values round up to 1ms (never shows "0ms" for nonzero input)
  * - Zero returns "0ms"
+ *
+ * @param us - Time value in microseconds.
+ * @returns Human-readable time string.
  */
 export function formatTime(us: number): string {
   if (us === 0) return '0ms';
@@ -28,6 +31,10 @@ export function formatTime(us: number): string {
 /**
  * Convert microseconds to percentage of total with one decimal place.
  * Returns "0.0%" when totalUs is zero (avoids division by zero).
+ *
+ * @param us - Time value in microseconds.
+ * @param totalUs - Total time in microseconds (denominator).
+ * @returns Percentage string like `"12.3%"`.
  */
 export function formatPct(us: number, totalUs: number): string {
   if (totalUs === 0) return '0.0%';
@@ -38,6 +45,9 @@ export function formatPct(us: number, totalUs: number): string {
  * Escape HTML-special characters to prevent broken markup.
  * Handles: & < > " '
  * Ampersand is replaced first to avoid double-escaping.
+ *
+ * @param str - Raw string to escape.
+ * @returns HTML-safe string.
  */
 export function escapeHtml(str: string): string {
   return str