feat: add time mode benchmark (#71)

Fixes: #63

Author: RafaelGSS

README.md

@@ -13,6 +13,7 @@
   <a href="#plugins">Plugins</a>&nbsp;&nbsp;&nbsp;|&nbsp;&nbsp;&nbsp;
   <a href="#using-reporter">Using Reporter</a>&nbsp;&nbsp;&nbsp;|&nbsp;&nbsp;&nbsp;
   <a href="#setup-and-teardown">Setup and Teardown</a>&nbsp;&nbsp;&nbsp;|&nbsp;&nbsp;&nbsp;
+  <a href="#benchmark-modes">Benchmark Modes</a>&nbsp;&nbsp;&nbsp;|&nbsp;&nbsp;&nbsp;
   <a href="#writing-javascript-mistakes">Writing JavaScript Mistakes</a>
 </p>
 
@@ -78,7 +79,9 @@ See the [examples folder](./examples/) for more common usage examples.
     3. [Custom Reporter](#custom-reporter) 
 4. [Setup and Teardown](#setup-and-teardown)
     1. [Managed Benchmarks](#managed-benchmarks)
-
+5. [Benchmark Modes](#benchmark-modes)
+    1. [Operations Mode (Default)](#operations-mode)
+    2. [Time Mode](#time-mode)
 ## Class: `Suite`
 
 > Stability: 1.1 Active Development
@@ -94,6 +97,11 @@ A `Suite` manages and executes benchmark functions. It provides two methods: `ad
       * `opsSec` {string} Operations per second.
       * `iterations` {Number} Number of iterations.
       * `histogram` {Histogram} Histogram instance.
+  * `benchmarkMode` {string} Benchmark mode to use. Can be 'ops' or 'time'. **Default:** `'ops'`.
+    * `'ops'` - Measures operations per second (traditional benchmarking).
+    * `'time'` - Measures actual execution time for a single run.
+  * `useWorkers` {boolean} Whether to run benchmarks in worker threads. **Default:** `false`.
+  * `plugins` {Array} Array of plugin instances to use.
 
 If no `reporter` is provided, results are printed to the console.
 
@@ -130,7 +138,8 @@ Using delete property x 5,853,505 ops/sec (10 runs sampled) min..max=(169ns ...
 ### `suite.run()`
 
 * Returns: `{Promise<Array<Object>>}` An array of benchmark results, each containing:
-  * `opsSec` {number} Operations per second.
+  * `opsSec` {number} Operations per second (Only in 'ops' mode).
+  * `totalTime` {number} Total execution time in seconds (Only in 'time' mode).
   * `iterations` {number} Number of executions of `fn`.
   * `histogram` {Histogram} Histogram of benchmark iterations.
   * `name` {string} Benchmark name.
@@ -481,6 +490,79 @@ const suite = new Suite({
 });
 ```
 
+## Benchmark Modes
+
+`bench-node` supports multiple benchmarking modes to measure code performance in different ways.
+
+### Operations Mode
+
+Operations mode (default) measures how many operations can be performed in a given timeframe. 
+This is the traditional benchmarking approach that reports results in operations per second (ops/sec).
+
+This mode is best for:
+- Comparing relative performance between different implementations
+- Measuring throughput of small, fast operations
+- Traditional microbenchmarking
+
+Example output:
+```
+String concatenation x 12,345,678 ops/sec (11 runs sampled) v8-never-optimize=true min..max=(81ns...85ns)
+```
+
+### Time Mode
+
+Time mode measures the actual time taken to execute a function exactly once. 
+This mode is useful when you want to measure the real execution time for operations that have a known, fixed duration.
+
+This mode is best for:
+- Costly operations where multiple instructions are executed in a single run 
+- Benchmarking operations with predictable timing
+- Verifying performance guarantees for time-sensitive functions
+
+To use time mode, set the `benchmarkMode` option to `'time'` when creating a Suite:
+
+```js
+const { Suite } = require('bench-node');
+
+const timeSuite = new Suite({
+    benchmarkMode: 'time' // Enable time mode
+});
+
+// Create a function that takes a predictable amount of time
+const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+
+timeSuite.add('Async Delay 100ms', async () => {
+    await delay(100);
+});
+
+timeSuite.add('Sync Busy Wait 50ms', () => {
+    const start = Date.now();
+    while (Date.now() - start < 50);
+});
+
+// Optional: Run the benchmark multiple times with repeatSuite
+timeSuite.add('Quick Operation with 5 repeats', { repeatSuite: 5 }, () => {
+    // This will run exactly once per repeat (5 times total)
+    // and report the average time
+    let x = 1 + 1;
+});
+
+(async () => {
+    await timeSuite.run();
+})();
+```
+
+In time mode, results include `totalTime` (in seconds) instead of `opsSec`.
+
+Example output:
+```
+Async Delay 100ms x 0.1003s (1 sample) v8-never-optimize=true
+Sync Busy Wait 50ms x 0.0502s (1 sample) v8-never-optimize=true
+Quick Operation with 5 repeats x 0.0000s (5 samples) v8-never-optimize=true
+```
+
+See [examples/time-mode.js](./examples/time-mode.js) for a complete example.
+
 ## Writing JavaScript Mistakes
 
 When working on JavaScript micro-benchmarks, it’s easy to forget that modern engines use

biome.json

@@ -8,7 +8,8 @@
 		"rules": {
 			"recommended": true,
 			"style": {
-				"noParameterAssign": "off"
+				"noParameterAssign": "off",
+				"noUselessElse": "off"
 			}
 		}
 	},

examples/time-mode.js

@@ -0,0 +1,28 @@
+const { Suite } = require('../lib');
+
+const timeSuite = new Suite({
+    benchmarkMode: 'time' // Set mode for the entire suite
+});
+
+const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+
+timeSuite.add('Async Delay 100ms (time)', async () => {
+    await delay(100);
+});
+
+timeSuite.add('Sync Busy Wait 50ms (time)', () => {
+    const start = Date.now();
+    while (Date.now() - start < 50);
+});
+
+timeSuite.add('Quick Sync Op with 5 repeats (time)', { repeatSuite: 5 }, () => {
+    // This will run exactly once per repeat (5 times total)
+    // and report the average time
+    let x = 1 + 1;
+});
+
+
+(async () => {
+    console.log('\nRunning benchmark suite in TIME mode...');
+    await timeSuite.run();
+})();

lib/clock.js

@@ -233,11 +233,21 @@ function createRunner(bench, recommendedCount) {
 	return runner;
 }
 
-async function clockBenchmark(bench, recommendedCount) {
+/**
+ * Executes a benchmark and returns the time taken and number of iterations
+ * @param {import('./index').Benchmark} bench - The benchmark to execute
+ * @param {number} recommendedCount - The recommended number of iterations
+ * @param {Object} [options] - Additional options
+ * @param {boolean} [options.timeMode=false] - If true, runs the benchmark exactly once
+ * @returns {Promise<[number, number]>} - Returns [duration, iterations]
+ */
+async function clockBenchmark(bench, recommendedCount, options = {}) {
 	const runner = createRunner(bench, recommendedCount);
 	const result = await runner();
+
 	// Just to avoid issues with empty fn
 	result[0] = Math.max(MIN_RESOLUTION, result[0]);
+
 	for (const p of bench.plugins) {
 		if (typeof p.onCompleteBenchmark === "function") {
 			// TODO: this won't work when useWorkers=true
@@ -246,7 +256,7 @@ async function clockBenchmark(bench, recommendedCount) {
 	}
 
 	debugBench(
-		`Took ${timer.format(result[0])} to execute ${result[1]} iterations`,
+		`Took ${timer.format(result[0])} to execute ${result[1]} iterations${options.timeMode ? " (time mode)" : ""}`,
 	);
 	return result;
 }

lib/index.js

@@ -27,6 +27,7 @@ const {
 	validateObject,
 	validateString,
 	validateArray,
+	validateBenchmarkMode,
 } = require("./validators");
 
 const getFunctionBody = (string) =>
@@ -94,10 +95,12 @@ class Suite {
 	#reporter;
 	#plugins;
 	#useWorkers;
+	#benchmarkMode;
 
 	constructor(options = {}) {
 		this.#benchmarks = [];
 		validateObject(options, "options");
+
 		if (options?.reporter !== undefined) {
 			if (options?.reporter !== false && options?.reporter !== null) {
 				validateFunction(options.reporter, "reporter");
@@ -108,11 +111,16 @@ class Suite {
 		}
 
 		this.#useWorkers = options.useWorkers || false;
+
 		if (options?.plugins) {
 			validateArray(options.plugins, "plugin");
 			validatePlugins(options.plugins);
 		}
 		this.#plugins = options?.plugins || [new V8NeverOptimizePlugin()];
+
+		// Benchmark Mode setup
+		this.#benchmarkMode = options.benchmarkMode || "ops"; // Default to 'ops'
+		validateBenchmarkMode(this.#benchmarkMode, "options.benchmarkMode");
 	}
 
 	add(name, options, fn) {
@@ -184,16 +192,22 @@ class Suite {
 			// Warmup is calculated to reduce noise/bias on the results
 			const initialIterations = await getInitialIterations(benchmark);
 			debugBench(
-				`Starting ${benchmark.name} with minTime=${benchmark.minTime}, maxTime=${benchmark.maxTime}, repeatSuite=${benchmark.repeatSuite}, minSamples=${benchmark.minSamples}`,
+				`Starting ${benchmark.name} with mode=${this.#benchmarkMode}, minTime=${benchmark.minTime}, maxTime=${benchmark.maxTime}, repeatSuite=${benchmark.repeatSuite}, minSamples=${benchmark.minSamples}`,
 			);
 
 			let result;
 			if (this.#useWorkers) {
+				if (this.#benchmarkMode === "time") {
+					console.warn(
+						"Warning: Worker mode currently doesn't fully support 'time' benchmarkMode.",
+					);
+				}
 				result = await this.runWorkerBenchmark(benchmark, initialIterations);
 			} else {
 				result = await runBenchmark(
 					benchmark,
 					initialIterations,
+					this.#benchmarkMode,
 					benchmark.repeatSuite,
 					benchmark.minSamples,
 				);
@@ -204,35 +218,35 @@ class Suite {
 		if (this.#reporter) {
 			this.#reporter(results);
 		}
+
 		return results;
 	}
 
-	runWorkerBenchmark(benchmark, initialIterations) {
-		benchmark.serializeBenchmark();
-		const worker = new Worker(path.join(__dirname, "./worker-runner.js"));
-
-		worker.postMessage({
-			benchmark,
-			initialIterations,
-			repeatSuite: benchmark.repeatSuite,
-			minSamples: benchmark.minSamples,
-		});
+	async runWorkerBenchmark(benchmark, initialIterations) {
 		return new Promise((resolve, reject) => {
+			const workerPath = path.resolve(__dirname, "./worker-runner.js");
+			const worker = new Worker(workerPath);
+
+			benchmark.serializeBenchmark();
+			worker.postMessage({
+				benchmark,
+				initialIterations,
+				benchmarkMode: this.#benchmarkMode, // Pass suite mode
+				repeatSuite: benchmark.repeatSuite,
+				minSamples: benchmark.minSamples,
+			});
+
 			worker.on("message", (result) => {
 				resolve(result);
-				// TODO: await?
 				worker.terminate();
 			});
-
-			worker.on("error", (err) => {
-				reject(err);
+			worker.on("error", (error) => {
+				reject(error);
 				worker.terminate();
 			});
-
 			worker.on("exit", (code) => {
-				if (code !== 0) {
+				if (code !== 0)
 					reject(new Error(`Worker stopped with exit code ${code}`));
-				}
 			});
 		});
 	}