benchforge 0.1.0 → 0.1.2

package/dist/BenchRunner-BLfGX2wQ.d.mts

@@ -0,0 +1,225 @@
+//#region src/heap-sample/HeapSampler.d.ts
+interface ProfileNode {
+  callFrame: {
+    functionName: string;
+    url: string;
+    lineNumber: number;
+    columnNumber?: number;
+  };
+  selfSize: number;
+  children?: ProfileNode[];
+}
+interface HeapProfile {
+  head: ProfileNode;
+  samples?: number[];
+}
+//#endregion
+//#region src/NodeGC.d.ts
+/** Individual GC event for visualization */
+interface GcEvent {
+  /** Offset from collection start (ms) - can be negative for warmup GCs */
+  offset: number;
+  /** Duration of GC pause (ms) */
+  duration: number;
+}
+/** GC time measured by Node's performance hooks */
+interface NodeGCTime {
+  inRun: number;
+  before: number;
+  after: number;
+  total: number;
+  collects: number;
+  /** Individual GC events during sample collection (for visualization) */
+  events: GcEvent[];
+}
+//#endregion
+//#region src/runners/GcStats.d.ts
+/** GC statistics aggregated from V8 trace events.
+*  Node (--trace-gc-nvp) provides all fields.
+*  Browser (CDP Tracing) provides counts, collected, and pause only. */
+interface GcStats {
+  scavenges: number;
+  markCompacts: number;
+  totalCollected: number;
+  gcPauseTime: number;
+  totalAllocated?: number;
+  totalPromoted?: number;
+  totalSurvived?: number;
+}
+//#endregion
+//#region src/MeasuredResults.d.ts
+/** CPU performance counter stats */
+interface CpuCounts {
+  instructions?: number;
+  cycles?: number;
+  branchMisses?: number;
+}
+/** Benchmark results: times in milliseconds, sizes in kilobytes */
+interface MeasuredResults {
+  name: string;
+  /** Raw execution time samples for custom statistics */
+  samples: number[];
+  /** Warmup iteration timings (ms) - captured before gc/settle */
+  warmupSamples?: number[];
+  /** Raw allocation samples per iteration (KB) */
+  allocationSamples?: number[];
+  /** Heap size per sample (bytes) - used for charts */
+  heapSamples?: number[];
+  /** Wall-clock timestamps per sample (μs since process start) - for Perfetto export */
+  timestamps?: number[];
+  /** Execution time in milliseconds (measurement overhead excluded by mitata) */
+  time: {
+    min: number;
+    max: number;
+    avg: number;
+    p25?: number;
+    p50: number;
+    p75: number;
+    p95?: number;
+    p99: number;
+    p999: number;
+    cv?: number;
+    mad?: number;
+    outlierRate?: number;
+  };
+  /** Heap size increase during test run (kilobytes) */
+  heapSize?: {
+    avg: number;
+    min: number;
+    max: number;
+  };
+  /**
+  * Time for explicit gc() call after test execution (milliseconds).
+  * Does not include GC time during test execution.
+  * Only reported by mitata runner.
+  */
+  gcTime?: {
+    avg: number;
+    min: number;
+    max: number;
+  };
+  /** CPU counter stats from @mitata/counters (requires root access) */
+  cpu?: CpuCounts;
+  /** L1 cache miss rate */
+  cpuCacheMiss?: number;
+  /** CPU stall rate (macOS only) */
+  cpuStall?: number;
+  /**
+  * Stop-the-world GC time blocking main thread (milliseconds).
+  * Measured via Node's performance hooks when nodeObserveGC is true.
+  * Excludes parallel thread collection time and indirect slowdowns.
+  */
+  nodeGcTime?: NodeGCTime;
+  /** Total time spent collecting samples (seconds) */
+  totalTime?: number;
+  /** Convergence information for adaptive mode */
+  convergence?: {
+    converged: boolean;
+    confidence: number;
+    reason: string;
+  };
+  /** V8 optimization tier tracking (requires --allow-natives-syntax) */
+  optStatus?: OptStatusInfo;
+  /** Per-sample V8 optimization status codes (for chart visualization) */
+  optSamples?: number[];
+  /** Points where pauses occurred for V8 optimization */
+  pausePoints?: PausePoint[];
+  /** GC stats from V8's --trace-gc-nvp (requires --gc-stats and worker mode) */
+  gcStats?: GcStats;
+  /** Heap sampling allocation profile (requires --heap-sample and worker mode) */
+  heapProfile?: HeapProfile;
+}
+/** A pause point during sample collection for V8 optimization */
+interface PausePoint {
+  /** Sample index where pause occurred (after this iteration) */
+  sampleIndex: number;
+  /** Pause duration in milliseconds */
+  durationMs: number;
+}
+/** V8 optimization tier distribution */
+interface OptTierInfo {
+  count: number;
+  medianMs: number;
+}
+/** V8 optimization status summary */
+interface OptStatusInfo {
+  /** Samples by tier name (e.g., "turbofan", "sparkplug") */
+  byTier: Record<string, OptTierInfo>;
+  /** Number of samples with deopt flag set */
+  deoptCount: number;
+}
+//#endregion
+//#region src/Benchmark.d.ts
+/** Single benchmark function specification */
+interface BenchmarkSpec<T = unknown> {
+  name: string;
+  fn: BenchmarkFunction<T>;
+  /** Path to module exporting the benchmark function (for worker mode) */
+  modulePath?: string;
+  /** Name of the exported function in the module (defaults to default export) */
+  exportName?: string;
+  /** Setup function export name - called once in worker, result passed to fn */
+  setupExportName?: string;
+}
+type BenchmarkFunction<T = unknown> = ((params: T) => void) | (() => void);
+/** Group of benchmarks with shared setup */
+interface BenchGroup<T = unknown> {
+  name: string;
+  /** Prepare parameters for all benchmarks in this group */
+  setup?: () => T | Promise<T>;
+  benchmarks: BenchmarkSpec<T>[];
+  /** Baseline benchmark for comparison */
+  baseline?: BenchmarkSpec<T>;
+  /** Metadata for reporting (e.g., lines of code) */
+  metadata?: Record<string, any>;
+}
+/** Collection of benchmark groups */
+interface BenchSuite {
+  name: string;
+  groups: BenchGroup<any>[];
+}
+//#endregion
+//#region src/runners/BenchRunner.d.ts
+interface RunnerOptions {
+  /** Minimum time to run each benchmark (milliseconds) */
+  minTime?: number;
+  /** Maximum time to run each benchmark - ignored by mitata (milliseconds) */
+  maxTime?: number;
+  /** Maximum iterations per benchmark - ignored by TinyBench */
+  maxIterations?: number;
+  /** Warmup iterations before measurement (default: 0) */
+  warmup?: number;
+  /** Warmup time before measurement (milliseconds) */
+  warmupTime?: number;
+  /** Warmup samples - mitata only, for reducing test time */
+  warmupSamples?: number;
+  /** Warmup threshold - mitata only (nanoseconds) */
+  warmupThreshold?: number;
+  /** Minimum samples required - mitata only */
+  minSamples?: number;
+  /** Force GC after each iteration (requires --expose-gc) */
+  collect?: boolean;
+  /** Enable CPU performance counters (requires root access) */
+  cpuCounters?: boolean;
+  /** Trace V8 optimization tiers (requires --allow-natives-syntax) */
+  traceOpt?: boolean;
+  /** Skip post-warmup settle time (default: false) */
+  noSettle?: boolean;
+  /** Iterations before first pause (then pauseInterval applies) */
+  pauseFirst?: number;
+  /** Iterations between pauses for V8 optimization (0 to disable) */
+  pauseInterval?: number;
+  /** Pause duration in ms for V8 optimization */
+  pauseDuration?: number;
+  /** Collect GC stats via --trace-gc-nvp (requires worker mode) */
+  gcStats?: boolean;
+  /** Heap sampling allocation attribution */
+  heapSample?: boolean;
+  /** Heap sampling interval in bytes */
+  heapInterval?: number;
+  /** Heap sampling stack depth */
+  heapDepth?: number;
+}
+//#endregion
+export { MeasuredResults as a, BenchmarkSpec as i, BenchGroup as n, HeapProfile as o, BenchSuite as r, RunnerOptions as t };
+//# sourceMappingURL=BenchRunner-BLfGX2wQ.d.mts.map

package/dist/HeapSampler-BX3de22o.mjs

@@ -0,0 +1,54 @@
+import { Session } from "node:inspector/promises";
+
+//#region src/heap-sample/HeapSampler.ts
+const defaultOptions = {
+	samplingInterval: 32768,
+	stackDepth: 64,
+	includeMinorGC: true,
+	includeMajorGC: true
+};
+/** Run a function while sampling heap allocations, return profile */
+async function withHeapSampling(options, fn) {
+	const opts = {
+		...defaultOptions,
+		...options
+	};
+	const session = new Session();
+	session.connect();
+	try {
+		await startSampling(session, opts);
+		return {
+			result: await fn(),
+			profile: await stopSampling(session)
+		};
+	} finally {
+		session.disconnect();
+	}
+}
+/** Start heap sampling, falling back if include-collected params aren't supported */
+async function startSampling(session, opts) {
+	const { samplingInterval, stackDepth } = opts;
+	const base = {
+		samplingInterval,
+		stackDepth
+	};
+	const params = {
+		...base,
+		includeObjectsCollectedByMinorGC: opts.includeMinorGC,
+		includeObjectsCollectedByMajorGC: opts.includeMajorGC
+	};
+	try {
+		await session.post("HeapProfiler.startSampling", params);
+	} catch {
+		console.warn("HeapProfiler: include-collected params not supported, falling back");
+		await session.post("HeapProfiler.startSampling", base);
+	}
+}
+async function stopSampling(session) {
+	const { profile } = await session.post("HeapProfiler.stopSampling");
+	return profile;
+}
+
+//#endregion
+export { withHeapSampling };
+//# sourceMappingURL=HeapSampler-BX3de22o.mjs.map

package/dist/HeapSampler-BX3de22o.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"HeapSampler-BX3de22o.mjs","names":[],"sources":["../src/heap-sample/HeapSampler.ts"],"sourcesContent":["import { Session } from \"node:inspector/promises\";\n\nexport interface HeapSampleOptions {\n  samplingInterval?: number; // bytes between samples, default 32768\n  stackDepth?: number; // max stack frames, default 64\n  includeMinorGC?: boolean; // keep objects collected by minor GC, default true\n  includeMajorGC?: boolean; // keep objects collected by major GC, default true\n}\n\nexport interface ProfileNode {\n  callFrame: {\n    functionName: string;\n    url: string;\n    lineNumber: number;\n    columnNumber?: number;\n  };\n  selfSize: number;\n  children?: ProfileNode[];\n}\n\nexport interface HeapProfile {\n  head: ProfileNode;\n  samples?: number[]; // sample IDs (length = number of samples taken)\n}\n\nconst defaultOptions: Required<HeapSampleOptions> = {\n  samplingInterval: 32768,\n  stackDepth: 64,\n  includeMinorGC: true,\n  includeMajorGC: true,\n};\n\n/** Run a function while sampling heap allocations, return profile */\nexport async function withHeapSampling<T>(\n  options: HeapSampleOptions,\n  fn: () => Promise<T> | T,\n): Promise<{ result: T; profile: HeapProfile }> {\n  const opts = { ...defaultOptions, ...options };\n  const session = new Session();\n  session.connect();\n\n  try {\n    await startSampling(session, opts);\n    const result = await fn();\n    const profile = await stopSampling(session);\n    return { result, profile };\n  } finally {\n    session.disconnect();\n  }\n}\n\n/** Start heap sampling, falling back if include-collected params aren't supported */\nasync function startSampling(\n  session: Session,\n  opts: Required<HeapSampleOptions>,\n): Promise<void> {\n  const { samplingInterval, stackDepth } = opts;\n  const base = { samplingInterval, stackDepth };\n  const params = {\n    ...base,\n    includeObjectsCollectedByMinorGC: opts.includeMinorGC,\n    includeObjectsCollectedByMajorGC: opts.includeMajorGC,\n  };\n\n  try {\n    await session.post(\"HeapProfiler.startSampling\", params);\n  } catch {\n    console.warn(\n      \"HeapProfiler: include-collected params not supported, falling back\",\n    );\n    await session.post(\"HeapProfiler.startSampling\", base);\n  }\n}\n\nasync function stopSampling(session: Session): Promise<HeapProfile> {\n  const { profile } = await session.post(\"HeapProfiler.stopSampling\");\n  return profile as HeapProfile;\n}\n"],"mappings":";;;AAyBA,MAAM,iBAA8C;CAClD,kBAAkB;CAClB,YAAY;CACZ,gBAAgB;CAChB,gBAAgB;CACjB;;AAGD,eAAsB,iBACpB,SACA,IAC8C;CAC9C,MAAM,OAAO;EAAE,GAAG;EAAgB,GAAG;EAAS;CAC9C,MAAM,UAAU,IAAI,SAAS;AAC7B,SAAQ,SAAS;AAEjB,KAAI;AACF,QAAM,cAAc,SAAS,KAAK;AAGlC,SAAO;GAAE,QAFM,MAAM,IAAI;GAER,SADD,MAAM,aAAa,QAAQ;GACjB;WAClB;AACR,UAAQ,YAAY;;;;AAKxB,eAAe,cACb,SACA,MACe;CACf,MAAM,EAAE,kBAAkB,eAAe;CACzC,MAAM,OAAO;EAAE;EAAkB;EAAY;CAC7C,MAAM,SAAS;EACb,GAAG;EACH,kCAAkC,KAAK;EACvC,kCAAkC,KAAK;EACxC;AAED,KAAI;AACF,QAAM,QAAQ,KAAK,8BAA8B,OAAO;SAClD;AACN,UAAQ,KACN,qEACD;AACD,QAAM,QAAQ,KAAK,8BAA8B,KAAK;;;AAI1D,eAAe,aAAa,SAAwC;CAClE,MAAM,EAAE,YAAY,MAAM,QAAQ,KAAK,4BAA4B;AACnE,QAAO"}