tinybench

Tinybench

A simple, tiny and lightweight benchmarking library! You can run your benchmarks in multiple JavaScript runtimes, Tinybench is completely based on the Web APIs with proper timing using process.hrtime or performance.now.

• Accurate and precise timing based on the environment
• Statistically analyzed latency and throughput values: standard deviation, margin of error, variance, percentiles, etc.
• Concurrency support
• Event and EventTarget compatible events
• No dependencies

In case you need more tiny libraries like tinypool or tinyspy, please consider submitting an RFC

Installing

$ npm install -D tinybench

Usage

You can start benchmarking by instantiating the Bench class and adding benchmark tasks to it.

…

The add method accepts a task name and a task function, so it can benchmark it! This method returns a reference to the Bench instance, so it's possible to use it to create an another task for that instance.

Note that the task name should always be unique in an instance, because Tinybench stores the tasks based on their names in a Map.

Also note that tinybench does not log any result by default. You can extract the relevant stats from bench.tasks or any other API after running the benchmark, and process them however you want.

More usage examples can be found in the examples directory.

Docs

FAQ

Bench

Task

TaskResult

Events

Both the Task and Bench classes extend the EventTarget object. So you can attach listeners to different types of events in each class instance using the universal addEventListener and removeEventListener methods.

BenchEvents

// runs on each benchmark task's cycle
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

// runs only on this benchmark task's cycle
task.addEventListener('cycle', (evt) => {
  const task = evt.task;
});

BenchEvent

Async Detection

Tinybench automatically detects if a task function is asynchronous by checking if provided function is an AsyncFunction or if it returns a Promise, by calling the provided function once.

You can also explicitly set the async option to true or false when adding a task, thus avoiding the detection. Set async: false only for a genuinely synchronous task; to measure the synchronous cost of a function that returns a Promise, record it via overriddenDuration instead (see Task-Supplied Measurements).

const bench = new Bench()

bench.add('asyncTask', async () => {}, { async: true })

bench.add('syncTask', () => {}, { async: false })

bench.add(
  'syncTaskReturningPromiseAsAsync',
  () => {
    return Promise.resolve()
  },
  { async: true }
)

await bench.run()

Concurrency

• When mode is set to null (default), concurrency is disabled.
• When mode is set to 'task', each task's iterations (calls of a task function) run concurrently.
• When mode is set to 'bench', different tasks within the bench run concurrently. Concurrent cycles.

const bench = new Bench({
  concurrency: 'task', // The concurrency mode to determine how tasks are run.
  threshold: 10, // Maximum concurrent iterations within a task. Defaults to Infinity.
})
await bench.run()

With concurrency: null or 'bench', each task runs until both its time budget and minimum iteration count are met. With concurrency: 'task', iterations stop being scheduled when either positive limit is reached; threshold limits concurrent iterations within that task, not concurrent benchmark tasks. Disabling the iteration limit with iterations: 0 requires a finite threshold (for example, threshold: 10), not the default Infinity. These rules also apply to warmupTime and warmupIterations in warmup(). Task.warmupSync() always uses the sequential rules, regardless of the configured concurrency.

Convert task results for console.table()

You can convert the benchmark results to a table format suitable for console.table() using the bench.table() method.

const table = bench.table()
console.table(table)

You can also customize the table output by providing a convert-function to the table method.

…

Retaining Samples

By default Tinybench does not keep the samples for latency and throughput to minimize memory usage. Enable sample retention if you need the raw samples for plotting, custom analysis, or exporting results.

You can enable samples retention at the bench level by setting the retainSamples option to true when creating a Bench instance:

const bench = new Bench({ retainSamples: true })

You can also enable samples retention by setting the retainSamples option to true when adding a task:

bench.add(
  'task with samples',
  () => {
    // Task logic here
  },
  { retainSamples: true }
)

Timestamp Providers

Tinybench can utilize different timestamp providers for measuring time intervals. By default it uses performance.now().

The timestampProvider option can be set when creating a Bench instance. It accepts either a TimestampProvider object or shorthands for the common providers hrtimeNow and performanceNow.

If you use bun runtime, you can also use bunNanoseconds shorthand.

You can set the timestampProvider to auto to let Tinybench choose the most precise available timestamp provider based on the runtime.

import { Bench } from 'tinybench'

const bench = new Bench({
  timestampProvider: 'hrtimeNow', // or 'performanceNow', 'bunNanoseconds', 'auto'
})

If you want to provide a custom timestamp provider, you can create an object that implements the TimestampProvider interface:

import { Bench, type TimestampProvider } from 'tinybench'

// Custom timestamp provider using Date.now()
const dateNowTimestampProvider: TimestampProvider = {
  name: 'dateNow', // name of the provider
  fn: Date.now, // function that returns the current timestamp
  toMs: ts => Number(ts), // convert the timestamp to milliseconds
  fromMs: ts => ts, // convert milliseconds to the format used by fn()
}

const bench = new Bench({
  timestampProvider: dateNowTimestampProvider,
})

You can also set the now option to a function that returns the current timestamp. It will be converted to a TimestampProvider internally.

import { Bench } from 'tinybench'

const bench = new Bench({
  now: Date.now,
})

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, and Math.max(0, raw_sample - Ĉ) is used as each non-overridden sample before statistics are computed.

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'):

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.
• 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.
• Each sample brackets a single task call rather than a batched loop, so the per-sample timer floor C is not amortized. This is a deliberate trade-off: it yields a real per-sample distribution (percentiles, MAD, saturation detection) at the cost of a higher sub-C noise floor. For work below the timer grain, use overriddenDuration.
• Ĉ does not cover an async task's await microtask turn — that overhead is inside the measured window but absent from the calibration pairs — so async sub-microsecond samples stay over-measured even with subtractTimerOverhead. Use overriddenDuration for such sub-resolution work.

Task-Supplied Measurements

Per-sample duration (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.

import type { FnReturnedObject } from 'tinybench'

bench.add('externally-timed', (): FnReturnedObject => {
  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.

Iteration cost (overriddenIterationCost)

When one iteration batches several inner calls, the per-call value you want in the statistics differs from what the iteration actually costs the time / warmupTime budget. Return overriddenIterationCost (in ms) to declare the whole iteration's wall-clock cost:

import type { FnReturnedObject } from 'tinybench'

bench.add('batched', () => {
  const innerCalls = 100
  const start = process.hrtime.bigint()
  for (let i = 0; i < innerCalls; i++) parse(input)
  const elapsedMs = Number(process.hrtime.bigint() - start) / 1e6
  return {
    overriddenDuration: elapsedMs / innerCalls, // mean per call in this batch
    overriddenIterationCost: elapsedMs, // budget cost of the iteration
  } satisfies FnReturnedObject
})

Each sample is the mean duration per call in one batch. Percentiles and dispersion describe these batch means, not the individual calls within a batch.

Semantics:

• The sample uses a valid overriddenDuration, otherwise the timer-measured duration. The sequential budget uses a valid overriddenIterationCost, otherwise the sample before timer-overhead correction. Returning only overriddenDuration therefore keeps the historical behavior.
• Task-concurrent run() and warmup() use the real clock for their budgets and do not inspect overriddenIterationCost (neither presence nor value). The cost applies per task with concurrency: 'bench' and in Task.warmupSync() regardless of concurrency.
• Both fields are validated the same way (finite number ≥ 0, -0 included); an invalid value is treated as absent.
• The cost field must be reported as p