@mtharrison/pkg-profiler 1.1.0 → 2.1.0

package/src/sampler.ts

@@ -1,21 +1,130 @@
-import { Session } from 'node:inspector/promises';
-import type { Profiler } from 'node:inspector';
-import { parseFrame } from './frame-parser.js';
-import { PackageResolver } from './package-resolver.js';
-import { generateReport } from './reporter.js';
-import { SampleStore } from './sample-store.js';
-import type { RawCallFrame } from './types.js';
+import { readFileSync } from "node:fs";
+import type { Profiler } from "node:inspector";
+import { Session } from "node:inspector";
+import { join } from "node:path";
+import { AsyncTracker } from "./async-tracker.js";
+import { parseFrame } from "./frame-parser.js";
+import { PackageResolver } from "./package-resolver.js";
+import { PkgProfile } from "./pkg-profile.js";
+import { aggregate } from "./reporter/aggregate.js";
+import { SampleStore } from "./sample-store.js";
+import type {
+  ProfileCallbackOptions,
+  RawCallFrame,
+  StartOptions,
+} from "./types.js";
 
 // Module-level state -- lazy initialization
 let session: Session | null = null;
 let profiling = false;
+let startHrtime: [number, number] | null = null;
 const store = new SampleStore();
+const asyncStore = new SampleStore();
 const resolver = new PackageResolver(process.cwd());
+let asyncTracker: AsyncTracker | null = null;
+
+/**
+ * Promisify session.post for the normal async API path.
+ */
+function postAsync(method: string, params?: object): Promise<any> {
+  return new Promise<any>((resolve, reject) => {
+    const cb: any = (err: Error | null, result?: any) => {
+      if (err) reject(err);
+      else resolve(result);
+    };
+    if (params !== undefined) {
+      session!.post(method, params, cb);
+    } else {
+      session!.post(method, cb);
+    }
+  });
+}
+
+/**
+ * Synchronous session.post — works because the V8 inspector executes
+ * callbacks synchronously for in-process sessions.
+ */
+function postSync(method: string): any {
+  let result: any;
+  let error: Error | null = null;
+  const cb: any = (err: Error | null, params?: any) => {
+    error = err;
+    result = params;
+  };
+  session!.post(method, cb);
+  if (error) throw error;
+  return result;
+}
+
+function readProjectName(cwd: string): string {
+  try {
+    const raw = readFileSync(join(cwd, "package.json"), "utf-8");
+    const pkg = JSON.parse(raw) as { name?: string };
+    return pkg.name ?? "app";
+  } catch {
+    return "app";
+  }
+}
+
+function buildEmptyProfile(): PkgProfile {
+  const projectName = readProjectName(process.cwd());
+  return new PkgProfile({
+    timestamp: new Date().toLocaleString(),
+    totalTimeUs: 0,
+    packages: [],
+    otherCount: 0,
+    projectName,
+  });
+}
+
+/**
+ * Shared logic for stopping the profiler and building a PkgProfile.
+ * Synchronous — safe to call from process `exit` handlers.
+ */
+function stopSync(): PkgProfile {
+  if (!profiling || !session) {
+    return buildEmptyProfile();
+  }
+
+  const elapsed = startHrtime ? process.hrtime(startHrtime) : null;
+  const wallTimeUs = elapsed ? elapsed[0] * 1_000_000 + Math.round(elapsed[1] / 1000) : undefined;
+  startHrtime = null;
+
+  const { profile } = postSync("Profiler.stop") as Profiler.StopReturnType;
+  postSync("Profiler.disable");
+  profiling = false;
+
+  let globalAsyncTimeUs: number | undefined;
+  if (asyncTracker) {
+    asyncTracker.disable();
+    globalAsyncTimeUs = asyncTracker.mergedTotalUs;
+    asyncTracker = null;
+  }
+
+  processProfile(profile);
+
+  const projectName = readProjectName(process.cwd());
+  const data = aggregate(
+    store,
+    projectName,
+    asyncStore.packages.size > 0 ? asyncStore : undefined,
+    globalAsyncTimeUs,
+    wallTimeUs,
+  );
+  store.clear();
+  asyncStore.clear();
+
+  return new PkgProfile(data);
+}
 
 /**
  * Start the V8 CPU profiler. If already profiling, this is a safe no-op.
+ *
+ * @param options - Optional configuration.
+ * @param options.interval - Sampling interval in microseconds passed to V8 (defaults to 1000µs). Lower values = higher fidelity but more overhead.
+ * @returns Resolves when the profiler is successfully started
  */
-export async function track(options?: { interval?: number }): Promise<void> {
+export async function start(options?: StartOptions): Promise<void> {
   if (profiling) return;
 
   if (session === null) {
@@ -23,16 +132,32 @@ export async function track(options?: { interval?: number }): Promise<void> {
     session.connect();
   }
 
-  await session.post('Profiler.enable');
+  await postAsync("Profiler.enable");
 
   if (options?.interval !== undefined) {
-    await session.post('Profiler.setSamplingInterval', {
+    await postAsync("Profiler.setSamplingInterval", {
       interval: options.interval,
     });
   }
 
-  await session.post('Profiler.start');
+  await postAsync("Profiler.start");
   profiling = true;
+  startHrtime = process.hrtime();
+
+  if (options?.trackAsync) {
+    asyncTracker = new AsyncTracker(resolver, asyncStore);
+    asyncTracker.enable();
+  }
+}
+
+/**
+ * Stop the profiler, process collected samples, and return a PkgProfile
+ * containing the aggregated data. Resets the store afterward.
+ *
+ * @returns A PkgProfile with the profiling results, or a PkgProfile with empty data if no samples were collected.
+ */
+export async function stop(): Promise<PkgProfile> {
+  return stopSync();
 }
 
 /**
@@ -40,44 +165,73 @@ export async function track(options?: { interval?: number }): Promise<void> {
  */
 export async function clear(): Promise<void> {
   if (profiling && session) {
-    await session.post('Profiler.stop');
-    await session.post('Profiler.disable');
+    postSync("Profiler.stop");
+    postSync("Profiler.disable");
     profiling = false;
   }
+  startHrtime = null;
   store.clear();
+  if (asyncTracker) {
+    asyncTracker.disable();
+    asyncTracker = null;
+  }
+  asyncStore.clear();
 }
 
 /**
- * Stop the profiler, process collected samples through the data pipeline
- * (parseFrame -> PackageResolver -> SampleStore), generate an HTML report,
- * and return the file path. Resets the store after reporting (clean slate
- * for next cycle).
+ * High-level convenience for common profiling patterns.
  *
- * Returns the absolute path to the generated HTML file, or empty string
- * if no samples were collected.
+ * Overload 1: Profile a block of code — runs `fn`, stops the profiler, returns PkgProfile.
+ * Overload 2: Long-running mode — starts profiler, registers exit handlers, calls `onExit` on shutdown.
  */
-export async function report(): Promise<string> {
-  if (!profiling || !session) {
-    console.log('no samples collected');
-    return '';
+export async function profile(
+  fn: () => void | Promise<void>,
+): Promise<PkgProfile>;
+export async function profile(options: ProfileCallbackOptions): Promise<void>;
+export async function profile(
+  fnOrOptions: (() => void | Promise<void>) | ProfileCallbackOptions,
+): Promise<PkgProfile | void> {
+  if (typeof fnOrOptions === "function") {
+    await start();
+    try {
+      await fnOrOptions();
+    } finally {
+      return stop();
+    }
   }
 
-  const { profile } = await session.post('Profiler.stop');
-  await session.post('Profiler.disable');
-  profiling = false;
+  // Long-running / onExit mode
+  const { onExit, ...startOpts } = fnOrOptions;
+  await start(startOpts);
 
-  processProfile(profile);
+  let handled = false;
 
-  let filepath = '';
+  const handler = (signal?: NodeJS.Signals) => {
+    if (handled) return;
+    handled = true;
 
-  if (store.packages.size > 0) {
-    filepath = generateReport(store);
-  } else {
-    console.log('no samples collected');
-  }
+    process.removeListener("SIGINT", onSignal);
+    process.removeListener("SIGTERM", onSignal);
+    process.removeListener("exit", onProcessExit);
 
-  store.clear();
-  return filepath;
+    const result = stopSync();
+    onExit(result);
+
+    if (signal) {
+      process.kill(process.pid, signal);
+    }
+  };
+
+  const onSignal = (signal: NodeJS.Signals) => {
+    handler(signal);
+  };
+  const onProcessExit = () => {
+    handler();
+  };
+
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+  process.once("exit", onProcessExit);
 }
 
 /**
@@ -97,11 +251,16 @@ function processProfile(profile: Profiler.Profile): void {
     const deltaUs = timeDeltas[i] ?? 0;
     const parsed = parseFrame(node.callFrame as RawCallFrame);
 
-    if (parsed.kind === 'user') {
-      if (parsed.filePath.startsWith('node:')) {
+    if (parsed.kind === "user") {
+      if (parsed.filePath.startsWith("node:")) {
         // Node.js built-in: attribute to "node (built-in)" package
         const relativePath = parsed.filePath.slice(5);
-        store.record('node (built-in)', relativePath, parsed.functionId, deltaUs);
+        store.record(
+          "node (built-in)",
+          relativePath,
+          parsed.functionId,
+          deltaUs,
+        );
       } else {
         const { packageName, relativePath } = resolver.resolve(parsed.filePath);
         store.record(packageName, relativePath, parsed.functionId, deltaUs);

package/src/types.ts

@@ -27,6 +27,9 @@ export interface ReportEntry {
   timeUs: number;       // accumulated microseconds
   pct: number;          // percentage of total (0-100)
   sampleCount: number;  // number of samples attributed
+  asyncTimeUs?: number;   // accumulated async wait microseconds
+  asyncPct?: number;      // percentage of total async time (0-100)
+  asyncOpCount?: number;  // number of async operations attributed
 }
 
 export interface FunctionEntry extends ReportEntry {}
@@ -48,4 +51,24 @@ export interface ReportData {
   packages: PackageEntry[];
   otherCount: number;
   projectName: string;
+  totalAsyncTimeUs?: number;
+  wallTimeUs?: number;
+}
+
+/**
+ * Options for `start()`.
+ */
+export interface StartOptions {
+  /** Sampling interval in microseconds. Default: 1000 */
+  interval?: number;
+  /** Enable async I/O wait time tracking via async_hooks. Default: false */
+  trackAsync?: boolean;
+}
+
+/**
+ * Options for `profile()` when used in long-running/server mode with an exit callback.
+ */
+export interface ProfileCallbackOptions extends StartOptions {
+  /** Called with the PkgProfile when the process receives SIGINT/SIGTERM or beforeExit fires. */
+  onExit: (result: import('./pkg-profile.js').PkgProfile) => void;
 }

package/src/reporter.ts

@@ -1,42 +0,0 @@
-/**
- * Reporter orchestrator.
- *
- * Aggregates SampleStore data, renders HTML, writes file to cwd,
- * and returns the file path.
- */
-
-import { readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import type { SampleStore } from './sample-store.js';
-import { aggregate } from './reporter/aggregate.js';
-import { renderHtml } from './reporter/html.js';
-
-function generateFilename(): 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`;
-}
-
-function readProjectName(cwd: string): string {
-  try {
-    const raw = readFileSync(join(cwd, 'package.json'), 'utf-8');
-    const pkg = JSON.parse(raw) as { name?: string };
-    return pkg.name ?? 'app';
-  } catch {
-    return 'app';
-  }
-}
-
-export function generateReport(store: SampleStore, cwd?: string): string {
-  const resolvedCwd = cwd ?? process.cwd();
-  const projectName = readProjectName(resolvedCwd);
-  const data = aggregate(store, projectName);
-  const html = renderHtml(data);
-  const filename = generateFilename();
-  const filepath = join(resolvedCwd, filename);
-  writeFileSync(filepath, html, 'utf-8');
-  console.log(`Report written to ./${filename}`);
-  return filepath;
-}