nano-benchmark 1.0.14 → 1.0.16

package/README.md

@@ -93,6 +93,37 @@ npx nano-watch bench-strings-concat.js backticks
 
 See [wiki](https://github.com/uhop/nano-bench/wiki) for more details.
 
+## User Timing API integration
+
+Pass `-o` / `--observe` to `nano-bench` to emit
+[User Timing](https://developer.mozilla.org/en-US/docs/Web/API/Performance_API/User_timing)
+marks at calibration and sampling phase boundaries. Marks are written to the
+standard performance timeline and are observable via `PerformanceObserver` or
+visible in DevTools / `node --inspect` traces — useful for correlating
+benchmark variability with GC pauses, V8 optimization events, etc.
+
+Mark / measure names follow `nano-bench/<function-name>/<phase>`, where phase is
+`find-level` (calibration) or `series` / `series-par` (sample collection).
+
+```js
+import {PerformanceObserver} from 'node:perf_hooks';
+
+const obs = new PerformanceObserver(list => {
+  for (const e of list.getEntries()) {
+    console.log(e.name, e.duration.toFixed(2), 'ms');
+  }
+});
+obs.observe({entryTypes: ['measure']});
+```
+
+Marks have a small fixed cost per phase (no per-sample overhead), so leaving
+`--observe` on does not affect measurement accuracy. Default is off.
+
+Library users can opt in directly: `findLevel` / `benchmarkSeries` /
+`benchmarkSeriesPar` / `measure` / `measurePar` all accept an `observe` option
+(`boolean | string`) &mdash; `false` / unset for no marks, `true` for the default
+label, or a string for a custom label.
+
 ## AI agents and contributing
 
 AI agents and AI-assisted developers: read [AGENTS.md](./AGENTS.md) first for project rules
@@ -111,6 +142,8 @@ BSD 3-Clause License
 
 ## Release history
 
+- 1.0.16: _Added User Timing API integration: `--observe` flag._
+- 1.0.15: _Updated dependencies._
 - 1.0.14: _Fixed Kruskal-Wallis post-hoc (Conover-Iman) pairwise comparison bug: corrected rank variance computation and critical value distribution. Added regression test._
 - 1.0.13: _Improved CLI help texts and documentation for brevity and clarity._
 - 1.0.12: _Added AI coding skills for writing benchmark files (write-bench, write-watch), shipped via npm. Added findLevel() tests. Expanded test suite._
@@ -126,3 +159,5 @@ BSD 3-Clause License
 - 1.0.2: _Added the `--self` option._
 - 1.0.1: _Added "self" argument to utilities so it can be used with Deno, Bun, etc._
 - 1.0.0: _Initial release._
+
+The full release notes are in the wiki: [Release notes](https://github.com/uhop/nano-bench/wiki/Release-notes).

package/bin/nano-bench.js

@@ -62,6 +62,10 @@ program
   .option('-s, --samples <samples>', 'number of samples', toInt, 100)
   .option('-p, --parallel', 'collect samples in parallel')
   .option('-b, --bootstrap <bootstrap>', 'number of bootstrap samples', toInt, 1000)
+  .option(
+    '-o, --observe',
+    'emit User Timing marks at phase boundaries (PerformanceObserver/DevTools)'
+  )
   .option('--self', 'print the file name to stdout and exit')
   .showHelpAfterError('(add --help to see available options)');
 
@@ -246,7 +250,11 @@ while (iterations.length < names.length) {
 
   const batchSize = await findLevel(
     fn,
-    {threshold: options.ms, startFrom: options.minIterations},
+    {
+      threshold: options.ms,
+      startFrom: options.minIterations,
+      observe: options.observe ? names[index] : undefined
+    },
     async (name, data) => {
       if (name === 'finding-level-next') {
         iterations[index] = data.n;
@@ -264,7 +272,10 @@ while (iterations.length < names.length) {
 
 for (let i = 0; i < iterations.length; ++i) {
   const batchSize = iterations[i],
-    samples = await benchSeries(fns[names[i]], batchSize, {nSeries: options.samples});
+    samples = await benchSeries(fns[names[i]], batchSize, {
+      nSeries: options.samples,
+      observe: options.observe ? names[i] : undefined
+    });
   normalizeSamples(samples, batchSize);
   results.push(samples);
   stats.push(getStats(samples));

package/llms-full.txt

@@ -38,6 +38,7 @@ nano-bench [options] <file>
 - `-b, --bootstrap <bootstrap>` — number of bootstrap resamples for CI estimation (default: 1000).
 - `-a, --alpha <alpha>` — significance level for confidence interval and tests (default: 0.05 = 95% CI).
 - `-p, --parallel` — collect samples in parallel (useful for async benchmarks).
+- `-o, --observe` — emit User Timing marks at calibration and sampling phase boundaries, observable via `PerformanceObserver` or DevTools / `node --inspect` traces. Mark names follow `nano-bench/<function-name>/<phase>`. Default: off.
 - `-e, --export <name>` — name of the export to use from the file (default: `"default"`).
 - `--self` — print the script's file path to stdout and exit (for Deno/Bun usage).
 
@@ -206,3 +207,58 @@ Used by nano-watch for indefinite monitoring with constant memory:
 
 - **StatCounter** — Welford's online algorithm for streaming mean, variance (M2), skewness (M3), and kurtosis (M4). Numerically stable single-pass computation.
 - **MedianCounter** — approximate streaming median using a hierarchical median-of-three structure. Provides O(1) memory approximate median without storing all values.
+
+---
+
+## User Timing API integration
+
+The `nano-bench` CLI accepts `-o` / `--observe`. When set, calibration and sampling phases emit `performance.mark` and `performance.measure` entries to the standard performance timeline. Observers can subscribe via `PerformanceObserver`; the entries are also visible in DevTools / `node --inspect` traces.
+
+Mark and measure names follow the convention `nano-bench/<label>/<phase>`:
+
+- Start mark: `nano-bench/<label>/<phase>:start`
+- Measure: `nano-bench/<label>/<phase>` (with the start mark as its start)
+
+Phases are:
+
+- `find-level` — calibration (auto-discovery of batch size).
+- `series` — sequential sample collection.
+- `series-par` — parallel sample collection (when `--parallel` is set).
+
+The CLI uses each function's exported name as the label, so multiple benchmarks in one run produce distinct entries (e.g., `nano-bench/strings/find-level`, `nano-bench/backticks/series`, etc.).
+
+### Consumer example
+
+```js
+import {PerformanceObserver} from 'node:perf_hooks';
+
+const obs = new PerformanceObserver(list => {
+  for (const e of list.getEntries()) {
+    console.log(`${e.name}: ${e.duration.toFixed(2)} ms`);
+  }
+});
+obs.observe({entryTypes: ['measure']});
+```
+
+### Library API
+
+The orchestrating runner functions accept an `observe` option (`boolean | string`):
+
+- `false` / `undefined` — no instrumentation (default).
+- `true` — emit marks with the default label `"default"`.
+- string — emit marks with the given label.
+
+The option is supported by `findLevel`, `benchmarkSeries`, `benchmarkSeriesPar`, `measure`, and `measurePar`. `measure` / `measurePar` thread it through to the inner `findLevel` and `benchmarkSeries` / `benchmarkSeriesPar` calls so a single `observe` argument produces both calibration and sample-collection entries.
+
+```js
+import {measure} from 'nano-benchmark/bench/runner.js';
+
+const fn = n => { let s = 0; for (let i = 0; i < n; ++i) s += i; };
+const stats = await measure(fn, {nSeries: 50, observe: 'sum-loop'});
+```
+
+### Cost
+
+Marks have a small fixed cost per phase (one `performance.mark` + one `performance.measure` per phase boundary, not per sample). Per-sample timing remains pure `performance.now()` deltas, so observe-mode does not measurably affect benchmark accuracy. The default is off purely to keep the perf timeline buffer empty for users who don't need the integration.
+
+The `nano-watch` CLI deliberately does **not** expose `--observe` because its sample loop is unbounded by default; library users who want to instrument continuous monitoring should manage their own buffer (e.g., `performance.clearMarks()` periodically) via the library API.

package/llms.txt

@@ -30,7 +30,7 @@ npx nano-bench benchmark.js
 npx nano-bench -s 200 -b 2000 -a 0.01 benchmark.js
 ```
 
-Options: `--ms` (measurement time, default 50), `--iterations` (overrides --ms), `--samples` (default 100), `--bootstrap` (default 1000), `--alpha` (significance level, default 0.05), `--parallel`, `--export` (default "default"), `--self`.
+Options: `--ms` (measurement time, default 50), `--iterations` (overrides --ms), `--samples` (default 100), `--bootstrap` (default 1000), `--alpha` (significance level, default 0.05), `--parallel`, `--observe` (emit User Timing marks at phase boundaries), `--export` (default "default"), `--self`.
 
 ### nano-watch
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nano-benchmark",
-  "version": "1.0.14",
-  "description": "CLI micro-benchmarking with nonparametric statistics and significance testing.",
+  "version": "1.0.16",
+  "description": "CLI micro-benchmarking for Node, Deno, and Bun with nonparametric statistics and significance testing.",
   "type": "module",
   "main": "src/index.js",
   "exports": {
@@ -23,7 +23,8 @@
     "test:seq:bun": "bun run `tape6-seq --self` --flags FO",
     "test:seq:deno": "deno run -A `tape6-seq --self` --flags FO",
     "lint": "prettier --check .",
-    "lint:fix": "prettier --write ."
+    "lint:fix": "prettier --write .",
+    "js-check": "tsc --project tsconfig.check.json"
   },
   "repository": {
     "type": "git",
@@ -33,14 +34,20 @@
     "benchmark",
     "micro-benchmark",
     "performance",
-    "profiling",
     "statistics",
+    "nonparametric",
     "significance",
+    "confidence-interval",
     "bootstrap",
     "mann-whitney",
     "kruskal-wallis",
     "cli",
-    "compare"
+    "watch",
+    "compare",
+    "cross-runtime",
+    "nodejs",
+    "deno",
+    "bun"
   ],
   "author": "Eugene Lazutkin <eugene.lazutkin@gmail.com> (https://www.lazutkin.com/)",
   "license": "BSD-3-Clause",
@@ -60,13 +67,15 @@
     "llms-full.txt"
   ],
   "devDependencies": {
-    "prettier": "^3.8.1",
-    "tape-six": "^1.7.12",
-    "tape-six-proc": "^1.2.7"
+    "@types/node": "^25.6.0",
+    "prettier": "^3.8.3",
+    "tape-six": "^1.9.0",
+    "tape-six-proc": "^1.2.9",
+    "typescript": "^6.0.3"
   },
   "dependencies": {
     "commander": "^14.0.3",
-    "console-toolkit": "^1.2.14"
+    "console-toolkit": "^1.3.0"
   },
   "tape6": {
     "tests": [

package/src/bench/runner.js

@@ -1,5 +1,21 @@
 import {performance} from 'node:perf_hooks';
 
+/**
+ * @typedef {boolean | string} Observe
+ *   false / undefined — no instrumentation; true — emit marks with label "default";
+ *   string — emit marks with the given label.
+ */
+
+const makeObserver = (observe, defaultLabel) => {
+  if (!observe) return null;
+  const label = typeof observe === 'string' ? observe : defaultLabel;
+  const prefix = `nano-bench/${label}`;
+  return {
+    mark: phase => performance.mark(`${prefix}/${phase}:start`),
+    measure: phase => performance.measure(`${prefix}/${phase}`, `${prefix}/${phase}:start`)
+  };
+};
+
 export const nextLevel = n => {
   if (n < 1) return 1;
   let exp = 0;
@@ -20,33 +36,45 @@ export const nextLevel = n => {
   return n;
 };
 
-export const findLevel = (fn, {threshold = 20, startFrom = 1, timeout = 5} = {}, report) =>
-  new Promise((resolve, reject) => {
-    const bench = async n => {
-      report && (await report('finding-level', {n}));
-      try {
-        const start = performance.now(),
-          result = fn(n),
-          finish = performance.now();
-        if (result && typeof result.then == 'function') {
-          // thenable
-          result.then(async () => {
-            const finish = performance.now();
-            if (finish - start >= threshold) return resolve(n);
-            report && (await report('finding-level-next', {n, time: finish - start}));
-            setTimeout(bench, timeout, nextLevel(n));
-          }, reject);
-          return;
+/**
+ * @param {{threshold?: number, startFrom?: number, timeout?: number, observe?: Observe}} [opts]
+ * @param {Function} [report]
+ */
+export const findLevel = async (fn, opts = {}, report) => {
+  const {threshold = 20, startFrom = 1, timeout = 5, observe} = opts;
+  const obs = makeObserver(observe, 'default');
+  obs?.mark('find-level');
+  try {
+    return await new Promise((resolve, reject) => {
+      const bench = async n => {
+        report && (await report('finding-level', {n}));
+        try {
+          const start = performance.now(),
+            result = fn(n),
+            finish = performance.now();
+          if (result && typeof result.then == 'function') {
+            // thenable
+            result.then(async () => {
+              const finish = performance.now();
+              if (finish - start >= threshold) return resolve(n);
+              report && (await report('finding-level-next', {n, time: finish - start}));
+              setTimeout(bench, timeout, nextLevel(n));
+            }, reject);
+            return;
+          }
+          if (finish - start >= threshold) return resolve(n);
+          report && (await report('finding-level-next', {n, time: finish - start}));
+          setTimeout(bench, timeout, nextLevel(n));
+        } catch (error) {
+          reject(error);
         }
-        if (finish - start >= threshold) return resolve(n);
-        report && (await report('finding-level-next', {n, time: finish - start}));
-        setTimeout(bench, timeout, nextLevel(n));
-      } catch (error) {
-        reject(error);
-      }
-    };
-    bench(startFrom);
-  });
+      };
+      bench(startFrom);
+    });
+  } finally {
+    obs?.measure('find-level');
+  }
+};
 
 export const benchmark = (fn, n) =>
   new Promise((resolve, reject) => {
@@ -68,42 +96,72 @@ export const benchmark = (fn, n) =>
     }
   });
 
-export const benchmarkSeries = async (
-  fn,
-  n,
-  {nSeries = 100, timeout = 5, DataArray = Array} = {}
-) => {
-  const data = new DataArray(nSeries);
-
-  const bench = async (nSeries, resolve, reject) => {
-    --nSeries;
-    try {
-      data[nSeries] = await benchmark(fn, n);
-      if (nSeries) {
-        setTimeout(bench, timeout, nSeries, resolve, reject);
-      } else {
-        resolve();
+/**
+ * @param {{nSeries?: number, timeout?: number, DataArray?: ArrayConstructor, observe?: Observe}} [opts]
+ */
+export const benchmarkSeries = async (fn, n, opts = {}) => {
+  const {nSeries = 100, timeout = 5, DataArray = Array, observe} = opts;
+  const obs = makeObserver(observe, 'default');
+  obs?.mark('series');
+  try {
+    const data = new DataArray(nSeries);
+
+    const bench = async (nSeries, resolve, reject) => {
+      --nSeries;
+      try {
+        data[nSeries] = await benchmark(fn, n);
+        if (nSeries) {
+          setTimeout(bench, timeout, nSeries, resolve, reject);
+        } else {
+          resolve();
+        }
+      } catch (error) {
+        reject(error);
       }
-    } catch (error) {
-      reject(error);
-    }
-  };
+    };
 
-  await new Promise((resolve, reject) => bench(nSeries, resolve, reject));
+    await new Promise((resolve, reject) => bench(nSeries, resolve, reject));
 
-  return data;
+    return data;
+  } finally {
+    obs?.measure('series');
+  }
 };
 
-export const benchmarkSeriesPar = async (fn, n, {nSeries = 100, DataArray = Array} = {}) => {
-  const benchmarks = [];
-  for (; nSeries > 0; --nSeries) benchmarks.push(benchmark(fn, n));
-  const results = await Promise.all(benchmarks);
-  return DataArray === Array ? results : DataArray.from(results);
+/**
+ * @param {{nSeries?: number, DataArray?: ArrayConstructor, observe?: Observe}} [opts]
+ */
+export const benchmarkSeriesPar = async (fn, n, opts = {}) => {
+  let {nSeries = 100} = opts;
+  const {DataArray = Array, observe} = opts;
+  const obs = makeObserver(observe, 'default');
+  obs?.mark('series-par');
+  try {
+    const benchmarks = [];
+    for (; nSeries > 0; --nSeries) benchmarks.push(benchmark(fn, n));
+    const results = await Promise.all(benchmarks);
+    return DataArray === Array ? results : DataArray.from(results);
+  } finally {
+    obs?.measure('series-par');
+  }
 };
 
+/**
+ * @typedef {object} StatsInit
+ * @property {number[]} data
+ * @property {number} reps
+ * @property {number} [time]
+ * @property {boolean} [sorted]
+ */
+
 export class Stats {
+  /** @param {StatsInit} object */
   constructor(object) {
-    Object.assign(this, object);
+    /** @type {number[]} */
+    this.data = object.data;
+    this.reps = object.reps;
+    this.time = object.time;
+    this.sorted = object.sorted ?? false;
   }
 
   static sortNumbersAsc = (a, b) => a - b;
@@ -134,34 +192,52 @@ export class Stats {
   }
 }
 
-export const measure = async (
-  fn,
-  {nSeries = 100, threshold = 20, startFrom = 1, timeout = 5, DataArray = Array} = {},
-  report
-) => {
+/**
+ * @param {{nSeries?: number, threshold?: number, startFrom?: number, timeout?: number, DataArray?: ArrayConstructor, observe?: Observe}} [opts]
+ * @param {Function} [report]
+ */
+export const measure = async (fn, opts = {}, report) => {
+  const {
+    nSeries = 100,
+    threshold = 20,
+    startFrom = 1,
+    timeout = 5,
+    DataArray = Array,
+    observe
+  } = opts;
   report?.('finding-reps');
-  const reps = startFrom < 0 ? -startFrom : await findLevel(fn, {threshold, startFrom, timeout});
+  const reps =
+    startFrom < 0 ? -startFrom : await findLevel(fn, {threshold, startFrom, timeout, observe});
   report?.('found-reps', {reps});
   report?.('starting-benchmarks', {nSeries, reps});
   const start = performance.now(),
-    data = await benchmarkSeries(fn, reps, {nSeries, timeout, DataArray}),
+    data = await benchmarkSeries(fn, reps, {nSeries, timeout, DataArray, observe}),
     finish = performance.now(),
     result = {data, reps, time: finish - start};
   report?.('finished-benchmarks', {...result, nSeries});
   return new Stats(result);
 };
 
-export const measurePar = async (
-  fn,
-  {nSeries = 100, threshold = 20, startFrom = 1, timeout = 5, DataArray = Array} = {},
-  report
-) => {
+/**
+ * @param {{nSeries?: number, threshold?: number, startFrom?: number, timeout?: number, DataArray?: ArrayConstructor, observe?: Observe}} [opts]
+ * @param {Function} [report]
+ */
+export const measurePar = async (fn, opts = {}, report) => {
+  const {
+    nSeries = 100,
+    threshold = 20,
+    startFrom = 1,
+    timeout = 5,
+    DataArray = Array,
+    observe
+  } = opts;
   report?.('finding-reps');
-  const reps = startFrom < 0 ? -startFrom : await findLevel(fn, {threshold, startFrom, timeout});
+  const reps =
+    startFrom < 0 ? -startFrom : await findLevel(fn, {threshold, startFrom, timeout, observe});
   report?.('found-reps', {reps});
   report?.('starting-benchmarks', {nSeries, reps});
   const start = performance.now(),
-    data = await benchmarkSeriesPar(fn, reps, {nSeries, DataArray}),
+    data = await benchmarkSeriesPar(fn, reps, {nSeries, DataArray, observe}),
     finish = performance.now(),
     result = {data, reps, time: finish - start};
   report?.('finished-benchmarks', {...result, nSeries});