benchforge 0.1.8 → 0.1.9

package/README.md

@@ -16,39 +16,31 @@ pnpm add benchforge
 
 ## Quick Start
 
-```typescript
-import { parseBenchArgs, runBenchmarks, reportResults, timeSection, runsSection, type BenchSuite } from 'benchforge';
+The simplest way to benchmark a function: export it as the default export and pass the file to `benchforge`.
 
-const suite: BenchSuite = {
-  name: "String Operations",
-  groups: [
-    {
-      name: "Concatenation",
-      benchmarks: [
-        { name: "plus", fn: () => "a" + "b" },
-        { name: "template", fn: () => `a${"b"}` },
-      ],
-    },
-  ],
-};
+```typescript
+// my-bench.ts
+export default function (): string {
+  return "a" + "b";
+}
+```
 
-const args = parseBenchArgs();
-const results = await runBenchmarks(suite, args);
-const table = reportResults(results, [timeSection, runsSection]);
-console.log(table);
+```bash
+benchforge my-bench.ts --gc-stats
 ```
 
-### Setup and Baseline Example
+### BenchSuite Export
 
-Here's a more comprehensive example with shared setup data and baseline comparison:
+For multiple benchmarks with groups, setup data, and baseline comparison, export a `BenchSuite`:
 
 ```typescript
-import { parseBenchArgs, runBenchmarks, defaultReport, type BenchGroup, type BenchSuite } from 'benchforge';
+// sorting.ts
+import type { BenchGroup, BenchSuite } from 'benchforge';
 
 const sortingGroup: BenchGroup<number[]> = {
   name: "Array Sorting (1000 numbers)",
   setup: () => Array.from({ length: 1000 }, () => Math.random()),
-  baseline: { name: "native sort", fn: nativeSort },
+  baseline: { name: "native sort", fn: (arr) => [...arr].sort((a, b) => a - b) },
   benchmarks: [
     { name: "quicksort", fn: quickSort },
     { name: "insertion sort", fn: insertionSort },
@@ -60,10 +52,11 @@ const suite: BenchSuite = {
   groups: [sortingGroup],
 };
 
-const args = parseBenchArgs();
-const results = await runBenchmarks(suite, args);
-const report = defaultReport(results, args);
-console.log(report);
+export default suite;
+```
+
+```bash
+benchforge sorting.ts --gc-stats
 ```
 
 See `examples/simple-cli.ts` for a complete runnable example.
@@ -122,8 +115,8 @@ This eliminates manual caching boilerplate in worker modules.
 ### Filter benchmarks by name
 
 ```bash
-simple-cli.ts --filter "concat"
-simple-cli.ts --filter "^parse" --time 2
+benchforge my-bench.ts --filter "concat"
+benchforge my-bench.ts --filter "^parse" --time 2
 ```
 
 ### Profiling with external debuggers
@@ -132,10 +125,10 @@ Use `--profile` to run benchmarks once for attaching external profilers:
 
 ```bash
 # Use with Chrome DevTools profiler
-node --inspect-brk simple-cli.ts --profile
+node --inspect-brk $(which benchforge) my-bench.ts --profile
 
 # Use with other profiling tools
-node --prof simple-cli.ts --profile
+node --prof $(which benchforge) my-bench.ts --profile
 ```
 
 The `--profile` flag executes exactly one iteration with no warmup, making it ideal for debugging and performance profiling.
@@ -172,7 +165,7 @@ The HTML report displays:
 
 ```bash
 # Generate HTML report, start server, and open in browser
-simple-cli.ts --html
+benchforge my-bench.ts --html
 # Press Ctrl+C to exit when done viewing
 ```
 
@@ -182,11 +175,11 @@ Export benchmark data as a Perfetto-compatible trace file for detailed analysis:
 
 ```bash
 # Export trace file
-simple-cli.ts --perfetto trace.json
+benchforge my-bench.ts --perfetto trace.json
 
 # With V8 GC events (automatically merged after exit)
 node --expose-gc --trace-events-enabled --trace-event-categories=v8,v8.gc \
-  simple-cli.ts --perfetto trace.json
+  benchforge my-bench.ts --perfetto trace.json
 ```
 
 View the trace at https://ui.perfetto.dev by dragging the JSON file.
@@ -203,7 +196,7 @@ Collect detailed garbage collection statistics via V8's `--trace-gc-nvp`:
 
 ```bash
 # Collect GC allocation/collection stats (requires worker mode)
-simple-cli.ts --gc-stats
+benchforge my-bench.ts --gc-stats
 ```
 
 Adds these columns to the output table:
@@ -219,16 +212,16 @@ For allocation profiling including garbage (short-lived objects), use `--heap-sa
 
 ```bash
 # Basic heap sampling
-simple-cli.ts --heap-sample --iterations 100
+benchforge my-bench.ts --heap-sample --iterations 100
 
 # Smaller interval = more samples = better coverage of rare allocations
-simple-cli.ts --heap-sample --heap-interval 4096 --iterations 100
+benchforge my-bench.ts --heap-sample --heap-interval 4096 --iterations 100
 
 # Verbose output with clickable file:// paths
-simple-cli.ts --heap-sample --heap-verbose
+benchforge my-bench.ts --heap-sample --heap-verbose
 
 # Control call stack display depth
-simple-cli.ts --heap-sample --heap-stack 5
+benchforge my-bench.ts --heap-sample --heap-stack 5
 ```
 
 **CLI Options:**

package/dist/bin/benchforge.mjs

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

package/dist/index.d.mts

@@ -138,8 +138,10 @@ declare function reportResults<S extends ReadonlyArray<ResultsMapper<any>>>(grou
 //#endregion
 //#region src/cli/CliArgs.d.ts
 type Configure<T> = (yargs: Argv) => Argv<T>;
-/** CLI args type inferred from cliOptions */
-type DefaultCliArgs = InferredOptionTypes<typeof cliOptions>;
+/** CLI args type inferred from cliOptions, plus optional file positional */
+type DefaultCliArgs = InferredOptionTypes<typeof cliOptions> & {
+  file?: string;
+};
 declare const cliOptions: {
   readonly time: {
     readonly type: "number";

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { A as timeSection, B as parseCliArgs, C as adaptiveSection, D as gcStatsSection, E as gcSection, F as generateHtmlReport, G as truncate, H as formatBytes, I as formatDateWithTimezone, J as loadCaseData, K as isStatefulVariant, L as prepareHtmlData, M as formatConvergence, N as filterMatrix, O as optSection, P as parseMatrixFilter, R as exportPerfettoTrace, S as reportMatrixResults, T as cpuSection, U as integer, V as reportResults, W as timeMs, Y as loadCasesModule, _ as runDefaultMatrixBench, a as cliToMatrixOptions, b as gcStatsColumns, c as exportReports, d as matrixToReportGroups, f as parseBenchArgs, g as runDefaultBench, h as runBenchmarks, i as benchExports, j as totalTimeSection, k as runsSection, l as hasField, m as reportOptStatus, n as getBaselineVersion, o as defaultMatrixReport, p as printHeapReports, q as runMatrix, r as getCurrentGitVersion, s as defaultReport, t as formatGitVersion, u as matrixBenchExports, v as runMatrixSuite, w as buildGenericSections, x as heapTotalColumn, y as gcPauseColumn, z as defaultCliArgs } from "./src-HfimYuW_.mjs";
+import { A as timeSection, B as parseCliArgs, C as adaptiveSection, D as gcStatsSection, E as gcSection, F as generateHtmlReport, G as truncate, H as formatBytes, I as formatDateWithTimezone, J as loadCaseData, K as isStatefulVariant, L as prepareHtmlData, M as formatConvergence, N as filterMatrix, O as optSection, P as parseMatrixFilter, R as exportPerfettoTrace, S as reportMatrixResults, T as cpuSection, U as integer, V as reportResults, W as timeMs, Y as loadCasesModule, _ as runDefaultMatrixBench, a as cliToMatrixOptions, b as gcStatsColumns, c as exportReports, d as matrixToReportGroups, f as parseBenchArgs, g as runDefaultBench, h as runBenchmarks, i as benchExports, j as totalTimeSection, k as runsSection, l as hasField, m as reportOptStatus, n as getBaselineVersion, o as defaultMatrixReport, p as printHeapReports, q as runMatrix, r as getCurrentGitVersion, s as defaultReport, t as formatGitVersion, u as matrixBenchExports, v as runMatrixSuite, w as buildGenericSections, x as heapTotalColumn, y as gcPauseColumn, z as defaultCliArgs } from "./src-Cf_LXwlp.mjs";
 import { o as average } from "./TimingUtils-ClclVQ7E.mjs";
 
 export { adaptiveSection, average, benchExports, buildGenericSections, cliToMatrixOptions, cpuSection, defaultCliArgs, defaultMatrixReport, defaultReport, exportPerfettoTrace, exportReports, filterMatrix, formatBytes, formatConvergence, formatDateWithTimezone, formatGitVersion, gcPauseColumn, gcSection, gcStatsColumns, gcStatsSection, generateHtmlReport, getBaselineVersion, getCurrentGitVersion, hasField, heapTotalColumn, integer, isStatefulVariant, loadCaseData, loadCasesModule, matrixBenchExports, matrixToReportGroups, optSection, parseBenchArgs, parseCliArgs, parseMatrixFilter, prepareHtmlData, printHeapReports, reportMatrixResults, reportOptStatus, reportResults, runBenchmarks, runDefaultBench, runDefaultMatrixBench, runMatrix, runMatrixSuite, runsSection, timeMs, timeSection, totalTimeSection, truncate };

package/dist/{src-HfimYuW_.mjs → src-Cf_LXwlp.mjs}

@@ -1,10 +1,10 @@
 import { a as createAdaptiveWrapper, c as BasicRunner, i as createRunner, l as computeStats, n as getElapsed, o as average, r as getPerfNow, s as bootstrapDifferenceCI, t as debugWorkerTiming, u as discoverVariants } from "./TimingUtils-ClclVQ7E.mjs";
 import { n as parseGcLine, t as aggregateGcStats } from "./GcStats-ByEovUi1.mjs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { execSync, fork, spawn } from "node:child_process";
 import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
-import path, { dirname, extname, join, resolve } from "node:path";
+import path, { basename, dirname, extname, join, resolve } from "node:path";
 import pico from "picocolors";
 import { table } from "table";
 import yargs from "yargs";
@@ -944,7 +944,12 @@ const cliOptions = {
 };
 /** @return yargs with standard benchmark options */
 function defaultCliArgs(yargsInstance) {
-	return yargsInstance.options(cliOptions).help().strict();
+	return yargsInstance.command("$0 [file]", "run benchmarks", (y) => {
+		y.positional("file", {
+			type: "string",
+			describe: "benchmark file to run"
+		});
+	}).options(cliOptions).help().strict();
 }
 /** @return parsed command line arguments */
 function parseCliArgs(args, configure = defaultCliArgs) {
@@ -2559,7 +2564,26 @@ async function runDefaultBench(suite, configureArgs) {
 	const args = parseBenchArgs(configureArgs);
 	if (args.url) await browserBenchExports(args);
 	else if (suite) await benchExports(suite, args);
-	else throw new Error("Either --url or a BenchSuite is required.");
+	else if (args.file) await fileBenchExports(args.file, args);
+	else throw new Error("Provide a benchmark file, --url for browser mode, or pass a BenchSuite directly.");
+}
+/** Import a file and run it as a benchmark based on what it exports */
+async function fileBenchExports(filePath, args) {
+	const candidate = (await import(pathToFileURL(resolve(filePath)).href)).default;
+	if (candidate && Array.isArray(candidate.groups)) await benchExports(candidate, args);
+	else if (typeof candidate === "function") {
+		const name = basename(filePath).replace(/\.[^.]+$/, "");
+		await benchExports({
+			name,
+			groups: [{
+				name,
+				benchmarks: [{
+					name,
+					fn: candidate
+				}]
+			}]
+		}, args);
+	}
 }
 /** Convert CLI args to runner options */
 function cliToRunnerOptions(args) {
@@ -2846,4 +2870,4 @@ function getMostRecentModifiedDate(dir) {
 
 //#endregion
 export { timeSection as A, parseCliArgs as B, adaptiveSection as C, gcStatsSection as D, gcSection as E, generateHtmlReport as F, truncate as G, formatBytes as H, formatDateWithTimezone as I, loadCaseData as J, isStatefulVariant as K, prepareHtmlData as L, formatConvergence as M, filterMatrix as N, optSection as O, parseMatrixFilter as P, exportPerfettoTrace as R, reportMatrixResults as S, cpuSection as T, integer as U, reportResults as V, timeMs as W, loadCasesModule as Y, runDefaultMatrixBench as _, cliToMatrixOptions as a, gcStatsColumns as b, exportReports as c, matrixToReportGroups as d, parseBenchArgs as f, runDefaultBench as g, runBenchmarks as h, benchExports as i, totalTimeSection as j, runsSection as k, hasField as l, reportOptStatus as m, getBaselineVersion as n, defaultMatrixReport as o, printHeapReports as p, runMatrix as q, getCurrentGitVersion as r, defaultReport as s, formatGitVersion as t, matrixBenchExports as u, runMatrixSuite as v, buildGenericSections as w, heapTotalColumn as x, gcPauseColumn as y, defaultCliArgs as z };
-//# sourceMappingURL=src-HfimYuW_.mjs.map
+//# sourceMappingURL=src-Cf_LXwlp.mjs.map