feat: add timer-overhead correction, saturation warning, and resolution diagnostic

README.md

@@ -87,6 +87,12 @@ Both the `Task` and `Bench` classes extend the `EventTarget` object. So you can
 bench.addEventListener('cycle', (evt) => {
   const task = evt.task!;
 });
+
+// runs when timer saturation is detected for a task's measured samples
+bench.addEventListener('warning', (evt) => {
+  const task = evt.task!;
+  const reason = evt.reason; // 'zero-dominated' | 'low-distinct' | 'zero-mad'
+});
 ```
 
 #### [`TaskEvents`](https://tinylibs.github.io/tinybench/types/TaskEvents.html)
@@ -147,8 +153,10 @@ await bench.run()
 - When `mode` is set to 'bench', different tasks within the bench run concurrently. Concurrent cycles.
 
 ```ts
-bench.threshold = 10 // The maximum number of concurrent tasks to run. Defaults to Number.POSITIVE_INFINITY.
-bench.concurrency = 'task' // The concurrency mode to determine how tasks are run.
+const bench = new Bench({
+  concurrency: 'task', // The concurrency mode to determine how tasks are run.
+  threshold: 10, // The maximum number of concurrent tasks to run. Defaults to Number.POSITIVE_INFINITY.
+})
 await bench.run()
 ```
 
@@ -286,6 +294,99 @@ const bench = new Bench({
 })
 ```
 
+## Timer Overhead Correction
+
+Each timer call (`performance.now()`, `process.hrtime.bigint()`, …) has a
+non-zero call cost `C`. For a task whose true duration `X` is comparable
+to `C`, the raw measured sample `X + C` is dominated by the timer rather
+than the task.
+
+When `subtractTimerOverhead: true` is set, an estimate `Ĉ` is computed
+once at construction time via [`calibrateTimerOverhead`](https://tinylibs.github.io/tinybench/functions/calibrateTimerOverhead.html),
+and `Math.max(0, raw_sample - Ĉ)` is used as each non-overridden sample
+before statistics are computed.
+
+```ts
+const bench = new Bench({ subtractTimerOverhead: true })
+console.log(bench.timerOverhead) // calibrated Ĉ in ms (or undefined)
+```
+
+The calibration helper is also exported for direct use, with a
+configurable estimator strategy (`'median'` default, or `'min'` / `'p05'`):
+
+```ts
+import { calibrateTimerOverhead, hrtimeNowTimestampProvider } from 'tinybench'
+
+const overhead = calibrateTimerOverhead(hrtimeNowTimestampProvider, {
+  estimator: 'p05',
+  pairs: 1024,
+  warmupPairs: 64,
+})
+```
+
+**Caveats.**
+
+- Incompatible with `concurrency: 'task'` — overhead is calibrated
+  sequentially and does not reflect concurrent execution cost.
+  Construction (and `run()`) throws if both are set.
+- For sub-overhead measurements (`X ≈ Ĉ`) the `max(0, …)` clamp
+  truncates the lower tail and biases statistics; prefer
+  `overriddenDuration` (see below).
+- When the timer is too coarse to resolve the call cost — fewer than half
+  of the calibration pairs produce a positive delta (call cost `C < R / 2`,
+  e.g. a `Date.now`-class timer with `>= 1 ms` resolution) — the calibration
+  returns `0` and the option becomes a no-op.
+
+## Per-Sample Override (`overriddenDuration`)
+
+A task function may return an object containing `overriddenDuration`
+(in ms). That value is recorded in place of the timer-measured sample:
+the timer still brackets the task function, but its measurement is
+discarded and overhead correction is not applied to the substituted
+value. Useful for externally-timed work or sub-overhead measurements
+that the timer cannot resolve.
+
+```ts
+bench.add('externally-timed', () => {
+  const start = process.hrtime.bigint()
+  doWork()
+  const elapsedMs = Number(process.hrtime.bigint() - start) / 1e6
+  return { overriddenDuration: elapsedMs }
+})
+```
+
+Overridden samples are excluded from `Task.detectedResolution` and
+from timer-saturation detection.
+
+## Timer Diagnostics
+
+After `bench.run()` (or `runSync()`), each task exposes
+`detectedResolution` — the smallest reproducibly observed positive
+sample (in ms) among the timer-measured samples, or `undefined` when no
+positive timer measurement was seen (e.g. every sample was overridden).
+
+```ts
+const task = bench.getTask('foo')
+console.log(task?.detectedResolution) // e.g. 0.000041 (≈ 41 ns)
+```
+
+When the timer's resolution dominates a task's measured distribution
+(more than half zero samples, fewer than `max(3, min(10, ⌊n / 1000⌋))`
+distinct values, or zero MAD with `n > 100`), tinybench dispatches a
+`'warning'` event on both the task and the bench, carrying the matching
+[`TimerSaturationReason`](https://tinylibs.github.io/tinybench/types/TimerSaturationReason.html):
+
+```ts
+bench.addEventListener('warning', evt => {
+  console.warn(`timer-saturated: ${evt.task?.name} — ${evt.reason}`)
+})
+```
+
+The same heuristic and estimator are exposed as standalone helpers for
+custom analysis: [`detectTimerSaturation`](https://tinylibs.github.io/tinybench/functions/detectTimerSaturation.html),
+[`classifyTimerSaturation`](https://tinylibs.github.io/tinybench/functions/classifyTimerSaturation.html),
+and [`estimateResolution`](https://tinylibs.github.io/tinybench/functions/estimateResolution.html).
+
 ## Aborting Benchmarks
 
 Tinybench supports aborting benchmarks using `AbortSignal` at both the bench and task levels:

src/bench.ts

@@ -24,12 +24,16 @@ import { BenchEvent } from './event'
 import { Task } from './task'
 import {
   assert,
+  calibrateTimerOverhead,
   defaultConvertTaskResultForConsoleTable,
   getTimestampProvider,
   runtime,
   runtimeVersion,
 } from './utils'
 
+const subtractTimerOverheadConcurrencyError =
+  '`subtractTimerOverhead` cannot be used with `concurrency: "task"` — set `concurrency` to `null` or `"bench"`, or disable `subtractTimerOverhead`'
+
 /**
  * The Bench class keeps track of the benchmark tasks and controls them.
  */
@@ -95,6 +99,18 @@ export class Bench extends EventTarget implements BenchLike {
    */
   readonly signal?: AbortSignal
 
+  /**
+   * Whether to subtract an estimated timestamp provider call overhead from
+   * each raw latency sample.
+   *
+   * Incompatible with `concurrency: 'task'`. Enforced at construction and
+   * re-checked at the start of {@link Bench.run} to guard against untyped
+   * (JS-side) mutation of the `readonly` `concurrency` field after
+   * construction.
+   * @default false
+   */
+  readonly subtractTimerOverhead: boolean
+
   /**
    * A teardown function that runs after each task execution.
    */
@@ -120,6 +136,15 @@ export class Bench extends EventTarget implements BenchLike {
    */
   readonly time: number
 
+  /**
+   * The estimated cost of one timestamp provider call in milliseconds.
+   *
+   * `undefined` when {@link subtractTimerOverhead} is `false`.
+   * Otherwise calibrated once at construction time via
+   * {@link calibrateTimerOverhead}.
+   */
+  readonly timerOverhead: number | undefined
+
   /**
    * A timestamp provider and its related functions.
    */
@@ -195,6 +220,14 @@ export class Bench extends EventTarget implements BenchLike {
     this.throws = restOptions.throws ?? false
     this.signal = restOptions.signal
     this.retainSamples = restOptions.retainSamples === true
+    this.subtractTimerOverhead = restOptions.subtractTimerOverhead === true
+    assert(
+      !(this.subtractTimerOverhead && this.concurrency === 'task'),
+      subtractTimerOverheadConcurrencyError
+    )
+    this.timerOverhead = this.subtractTimerOverhead
+      ? calibrateTimerOverhead(this.timestampProvider)
+      : undefined
 
     if (this.signal) {
       this.signal.addEventListener(
@@ -264,6 +297,10 @@ export class Bench extends EventTarget implements BenchLike {
    * @returns the tasks array
    */
   async run (): Promise<Task[]> {
+    assert(
+      !(this.subtractTimerOverhead && this.concurrency === 'task'),
+      subtractTimerOverheadConcurrencyError
+    )
     if (this.warmup) {
       await this.#warmupTasks()
     }

src/event.ts

@@ -4,6 +4,7 @@ import type {
   BenchEventsOptionalTask,
   BenchEventsWithError,
   BenchEventsWithTask,
+  TimerSaturationReason,
 } from './types'
 
 /**
@@ -24,6 +25,20 @@ class BenchEvent<
     return this.#error as K extends BenchEventsWithError ? Error : undefined
   }
 
+  /**
+   * The reason a `'warning'` event was dispatched.
+   * @returns The {@link TimerSaturationReason} for `'warning'` events;
+   *   `undefined` for every other event type and for `'warning'` events
+   *   dispatched without a reason
+   */
+  get reason (): K extends 'warning'
+    ? TimerSaturationReason | undefined
+    : undefined {
+    return this.#reason as K extends 'warning'
+      ? TimerSaturationReason | undefined
+      : undefined
+  }
+
   /**
    * The task associated with the event.
    * @returns The task if the event type is one that includes a task; otherwise, undefined
@@ -41,15 +56,25 @@ class BenchEvent<
   }
 
   #error?: Error
+  #reason?: TimerSaturationReason
   #task?: Task
 
+  constructor (type: 'warning', task: Task, reason?: TimerSaturationReason)
   constructor (type: BenchEventsWithError, task: Task, error: Error)
   constructor (type: BenchEventsWithTask, task: Task)
   constructor (type: BenchEventsOptionalTask, task?: Task)
-  constructor (type: BenchEvents, task?: Task, error?: Error) {
+  constructor (
+    type: BenchEvents,
+    task?: Task,
+    errorOrReason?: Error | TimerSaturationReason
+  ) {
     super(type)
     this.#task = task
-    this.#error = error
+    if (typeof errorOrReason === 'string') {
+      this.#reason = errorOrReason
+    } else {
+      this.#error = errorOrReason
+    }
   }
 }
 

src/index.ts

@@ -32,9 +32,27 @@ export type {
   TaskResultStarted,
   TaskResultTimestampProviderInfo,
   TaskResultWithStatistics,
+  TimerSaturationReason,
   TimestampFn,
   TimestampFns,
   TimestampProvider,
   TimestampValue,
 } from './types'
-export { formatNumber, hrtimeNow, mToNs, performanceNow as now, nToMs } from './utils'
+export type {
+  CalibrateTimerOverheadOptions,
+  TimerOverheadEstimatorKind,
+} from './utils'
+export {
+  calibrateTimerOverhead,
+  classifyTimerSaturation,
+  detectTimerSaturation,
+  estimateResolution,
+  formatNumber,
+  hrtimeNow,
+  hrtimeNowTimestampProvider,
+  medianAbsoluteDeviation,
+  mToNs,
+  performanceNow as now,
+  nToMs,
+  performanceNowTimestampProvider,
+} from './utils'