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

src/bench.ts

@@ -24,6 +24,7 @@ import { BenchEvent } from './event'
 import { Task } from './task'
 import {
   assert,
+  calibrateTimerOverhead,
   defaultConvertTaskResultForConsoleTable,
   getTimestampProvider,
   runtime,
@@ -95,6 +96,13 @@ export class Bench extends EventTarget implements BenchLike {
    */
   readonly signal?: AbortSignal
 
+  /**
+   * Whether to subtract an estimated timestamp provider call overhead from
+   * each raw latency sample.
+   * @default false
+   */
+  readonly subtractTimerOverhead: boolean
+
   /**
    * A teardown function that runs after each task execution.
    */
@@ -120,6 +128,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 +212,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 ?? false
+    assert(
+      !(this.subtractTimerOverhead && this.concurrency === 'task'),
+      '`subtractTimerOverhead` is incompatible with `concurrency: "task"` — overhead is calibrated sequentially and does not reflect concurrent execution cost'
+    )
+    this.timerOverhead = this.subtractTimerOverhead
+      ? calibrateTimerOverhead(this.timestampProvider)
+      : undefined
 
     if (this.signal) {
       this.signal.addEventListener(

src/index.ts

@@ -37,4 +37,16 @@ export type {
   TimestampProvider,
   TimestampValue,
 } from './types'
-export { formatNumber, hrtimeNow, performanceNow as now, nToMs } from './utils'
+export type {
+  CalibrateTimerOverheadOptions,
+  TimerOverheadEstimator,
+} from './utils'
+export {
+  calibrateTimerOverhead,
+  detectTimerSaturation,
+  estimateResolution,
+  formatNumber,
+  hrtimeNow,
+  performanceNow as now,
+  nToMs,
+} from './utils'

src/task.ts

@@ -20,6 +20,8 @@ import { BenchEvent } from './event'
 import {
   assert,
   computeStatistics,
+  detectTimerSaturation,
+  estimateResolution,
   isFnAsyncResource,
   isPromiseLike,
   isValidSamples,
@@ -70,6 +72,17 @@ export class Task extends EventTarget {
     options?: RemoveEventListenerOptionsArgument
   ) => void
 
+  /**
+   * The estimated effective timer resolution observed during the last run,
+   * computed as the smallest strictly positive latency sample that appears
+   * at least twice in the sample set.
+   * @returns The resolution in milliseconds, or `undefined` when no run has
+   *   produced a strictly positive sample
+   */
+  get detectedResolution (): number | undefined {
+    return this.#detectedResolution
+  }
+
   /**
    * The name of the task.
    * @returns The task name as a string
@@ -116,6 +129,11 @@ export class Task extends EventTarget {
    */
   readonly #bench: BenchLike
 
+  /**
+   * The estimated effective timer resolution from the last run.
+   */
+  #detectedResolution: number | undefined = undefined
+
   /**
    * The task function
    */
@@ -217,6 +235,7 @@ export class Task extends EventTarget {
    */
   reset (emit = true): void {
     this.#runs = 0
+    this.#detectedResolution = undefined
     this.#result = this.#aborted ? abortedTaskResult : notStartedTaskResult
 
     if (emit) this.dispatchEvent(new BenchEvent('reset', this))
@@ -233,14 +252,14 @@ export class Task extends EventTarget {
     this.#result = { state: 'started' }
     this.dispatchEvent(new BenchEvent('start', this))
     await this.#bench.setup(this, 'run')
-    const { error, samples: latencySamples } = await this.#benchmark(
-      'run',
-      this.#bench.time,
-      this.#bench.iterations
-    )
+    const {
+      error,
+      isOverridden,
+      samples: latencySamples,
+    } = await this.#benchmark('run', this.#bench.time, this.#bench.iterations)
     await this.#bench.teardown(this, 'run')
 
-    this.#processRunResult({ error, latencySamples })
+    this.#processRunResult({ error, isOverridden, latencySamples })
 
     return this
   }
@@ -267,19 +286,19 @@ export class Task extends EventTarget {
       '`setup` function must be sync when using `runSync()`'
     )
 
-    const { error, samples: latencySamples } = this.#benchmarkSync(
-      'run',
-      this.#bench.time,
-      this.#bench.iterations
-    )
+    const {
+      error,
+      isOverridden,
+      samples: latencySamples,
+    } = this.#benchmarkSync('run', this.#bench.time, this.#bench.iterations)
 
     const teardownResult = this.#bench.teardown(this, 'run')
     assert(
       !isPromiseLike(teardownResult),
       '`teardown` function must be sync when using `runSync()`'
     )
 
-    this.#processRunResult({ error, latencySamples })
+    this.#processRunResult({ error, isOverridden, latencySamples })
 
     return this
   }
@@ -339,7 +358,8 @@ export class Task extends EventTarget {
     time: number,
     iterations: number
   ): Promise<
-    { error: Error; samples?: never } | { error?: never; samples?: Samples }
+    | { error: Error; isOverridden?: never; samples?: never }
+    | { error?: never; isOverridden?: boolean[]; samples?: Samples }
   > {
     try {
       if (this.#fnOpts.beforeAll) {
@@ -348,6 +368,8 @@ export class Task extends EventTarget {
 
       let totalTime = 0 // ms
       const samples: number[] = []
+      const isOverridden: boolean[] | undefined =
+        this.#bench.timerOverhead !== undefined ? [] : undefined
 
       const benchmarkTask = async () => {
         if (this.#aborted) {
@@ -358,11 +380,12 @@ export class Task extends EventTarget {
             await this.#fnOpts.beforeEach.call(this, mode)
           }
 
-          const taskTime = this.#async
+          const { overridden, taskTime } = this.#async
             ? await this.#measure()
             : this.#measureSync()
 
           samples.push(taskTime)
+          isOverridden?.push(overridden)
           totalTime += taskTime
         } finally {
           if (this.#fnOpts.afterEach != null) {
@@ -395,7 +418,7 @@ export class Task extends EventTarget {
         await this.#fnOpts.afterAll.call(this, mode)
       }
 
-      return isValidSamples(samples) ? { samples } : {}
+      return isValidSamples(samples) ? { isOverridden, samples } : {}
     } catch (error) {
       return { error: toError(error) }
     }
@@ -411,7 +434,9 @@ export class Task extends EventTarget {
     mode: 'run' | 'warmup',
     time: number,
     iterations: number
-  ): { error: Error; samples?: never } | { error?: never; samples?: Samples } {
+  ):
+    | { error: Error; isOverridden?: never; samples?: never }
+    | { error?: never; isOverridden?: boolean[]; samples?: Samples } {
     try {
       if (this.#fnOpts.beforeAll) {
         const beforeAllResult = this.#fnOpts.beforeAll.call(this, mode)
@@ -423,6 +448,8 @@ export class Task extends EventTarget {
 
       let totalTime = 0
       const samples: number[] = []
+      const isOverridden: boolean[] | undefined =
+        this.#bench.timerOverhead !== undefined ? [] : undefined
 
       const benchmarkTask = () => {
         if (this.#aborted) {
@@ -437,9 +464,10 @@ export class Task extends EventTarget {
             )
           }
 
-          const taskTime = this.#measureSync()
+          const { overridden, taskTime } = this.#measureSync()
 
           samples.push(taskTime)
+          isOverridden?.push(overridden)
           totalTime += taskTime
         } finally {
           if (this.#fnOpts.afterEach) {
@@ -467,17 +495,18 @@ export class Task extends EventTarget {
           '`afterAll` function must be sync when using `runSync()`'
         )
       }
-      return isValidSamples(samples) ? { samples } : {}
+      return isValidSamples(samples) ? { isOverridden, samples } : {}
     } catch (error) {
       return { error: toError(error) }
     }
   }
 
   /**
    * Measures a single execution of the task function asynchronously.
-   * @returns The measured execution time
+   * @returns The measured execution time and whether it was supplied by the
+   *   task function via `overriddenDuration`
    */
-  async #measure (): Promise<number> {
+  async #measure (): Promise<{ overridden: boolean; taskTime: number }> {
     const taskStart = this.#timestampFn() as unknown as number
     // eslint-disable-next-line no-useless-call
     const fnResult = await this.#fn.call(this)
@@ -487,16 +516,17 @@ export class Task extends EventTarget {
 
     const overriddenDuration = getOverriddenDurationFromFnResult(fnResult)
     if (overriddenDuration !== undefined) {
-      return overriddenDuration
+      return { overridden: true, taskTime: overriddenDuration }
     }
-    return taskTime
+    return { overridden: false, taskTime }
   }
 
   /**
    * Measures a single execution of the task function synchronously.
-   * @returns The measured execution time
+   * @returns The measured execution time and whether it was supplied by the
+   *   task function via `overriddenDuration`
    */
-  #measureSync (): number {
+  #measureSync (): { overridden: boolean; taskTime: number } {
     const taskStart = this.#timestampFn() as unknown as number
     // eslint-disable-next-line no-useless-call
     const fnResult = this.#fn.call(this)
@@ -510,9 +540,9 @@ export class Task extends EventTarget {
     )
     const overriddenDuration = getOverriddenDurationFromFnResult(fnResult)
     if (overriddenDuration !== undefined) {
-      return overriddenDuration
+      return { overridden: true, taskTime: overriddenDuration }
     }
-    return taskTime
+    return { overridden: false, taskTime }
   }
 
   /**
@@ -555,26 +585,84 @@ export class Task extends EventTarget {
   /**
    * Processes the result of a benchmark run and updates the task result.
    * Calculates statistics from the collected samples and dispatches appropriate events.
-   * @param options - An object containing the error and latency samples from the run
+   *
+   * Ordering:
+   * 1. Apply overhead correction in-place on the collection-order sample array
+   *    (alignment with `isOverridden` preserved — `latencySamples[i]` still
+   *    matches `isOverridden[i]` because no sort has been performed yet).
+   *    Samples whose duration was supplied via `overriddenDuration` are skipped.
+   * 2. Build a measured-only view (excluding `overriddenDuration` samples) used
+   *    for timer-saturation detection. Constant `overriddenDuration` values would
+   *    otherwise trigger a spurious low-distinct-count warning.
+   * 3. Sort the working array for the final statistics and diagnostics.
+   * 4. Compute `detectedResolution` from the sorted samples.
+   * 5. Compute the final statistics on the (possibly corrected) sorted samples.
+   * 6. Run timer-saturation detection on the measured-only subset.
+   * 7. Dispatch `'cycle'` and `'complete'` events; dispatch `'warning'` if
+   *    timer saturation was detected.
+   * @param options - An object containing the run results
    * @param options.error - The error that occurred during the run, if any
+   * @param options.isOverridden - Parallel boolean array (collection order) indicating
+   *   which samples were supplied by the task function via `overriddenDuration`,
+   *   or `undefined` when overhead correction is disabled
    * @param options.latencySamples - The array of latency samples collected during the run
    */
   #processRunResult ({
     error,
+    isOverridden,
     latencySamples,
   }: {
     error?: Error
+    isOverridden?: boolean[]
     latencySamples?: number[]
   }): void {
     if (isValidSamples(latencySamples)) {
       this.#runs = latencySamples.length
 
+      const overhead = this.#bench.timerOverhead
+      const hasOverhead = overhead !== undefined && overhead > 0
+
+      // Phase 1 — Subtract overhead while isOverridden[i] is still aligned with
+      // latencySamples[i] (both in collection order, pre-sort).
+      if (hasOverhead) {
+        for (let i = 0; i < latencySamples.length; i++) {
+          if (isOverridden?.[i] !== true) {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            latencySamples[i] = Math.max(0, latencySamples[i]! - overhead)
+          }
+        }
+      }
+
+      // Phase 2 — Capture measured-only samples (alignment with isOverridden
+      // is still valid since the array has not been sorted yet).
+      const hasAnyOverridden = isOverridden?.some(v => v) ?? false
+      const measuredOnly: number[] = hasAnyOverridden
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        ? latencySamples.filter((_, i) => isOverridden![i] !== true)
+        : latencySamples
+
+      // Phase 3 — Single sort of the working array.
       sortSamples(latencySamples)
 
+      // Phase 4 — Resolution diagnostic on sorted samples.
+      this.#detectedResolution = estimateResolution(latencySamples)
+
+      // Phase 5 — Final statistics on (possibly corrected) sorted samples.
       const latencyStatistics = computeStatistics(
         latencySamples,
         this.#retainSamples
       )
+
+      // Phase 6 — Saturation detection on measured-only samples.
+      let saturated = false
+      if (measuredOnly === latencySamples) {
+        saturated = detectTimerSaturation(latencySamples, latencyStatistics.mad)
+      } else if (isValidSamples(measuredOnly)) {
+        sortSamples(measuredOnly)
+        const measuredStats = computeStatistics(measuredOnly, false)
+        saturated = detectTimerSaturation(measuredOnly, measuredStats.mad)
+      }
+
       const latencyStatisticsMean = latencyStatistics.mean
 
       let totalTime = 0
@@ -606,6 +694,12 @@ export class Task extends EventTarget {
         totalTime,
       }
       /* eslint-enable perfectionist/sort-objects */
+
+      if (saturated) {
+        const warningEv = new BenchEvent('warning', this)
+        this.dispatchEvent(warningEv)
+        this.#bench.dispatchEvent(warningEv)
+      }
     } else if (this.#aborted) {
       // If aborted with no samples, still set the aborted flag
       this.#result = abortedTaskResult