benchforge 0.1.1 → 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/bin/benchforge.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/bin/benchforge.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { g as runDefaultBench } from "../src-cYpHvc40.mjs";
+import { g as runDefaultBench } from "../src-D7zxOFGA.mjs";
 
 //#region src/bin/benchforge.ts
 await runDefaultBench();