I'm transitioning to a full-time open source career. Your support would be greatly appreciated 🙌
Tinybench 🔎
Benchmark your code easily with Tinybench, a simple, tiny and light-weight 7KB (2KB minified and gzipped)
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
EventandEventTargetcompatible events- Statistically analyzed values
- Calculated Percentiles
- Fully detailed results
- No dependencies
In case you need more tiny libraries like tinypool or tinyspy, please consider submitting an RFC
Installing
$ npm install -D tinybenchUsage
You can start benchmarking by instantiating the Bench class and adding
benchmark tasks to it.
import { Bench } from 'tinybench';
const bench = new Bench({ time: 100 });
bench
.add('faster task', () => {
console.log('I am faster')
})
.add('slower task', async () => {
await new Promise(r => setTimeout(r, 1)) // we wait 1ms :)
console.log('I am slower')
})
.todo('unimplemented bench')
await bench.warmup(); // make results more reliable, ref: https://github.com/tinylibs/tinybench/pull/50
await bench.run();
console.table(bench.table());
// Output:
// ┌─────────┬───────────────┬──────────┬────────────────────┬───────────┬─────────┐
// │ (index) │ Task Name │ ops/sec │ Average Time (ns) │ Margin │ Samples │
// ├─────────┼───────────────┼──────────┼────────────────────┼───────────┼─────────┤
// │ 0 │ 'faster task' │ '41,621' │ 24025.791819761525 │ '±20.50%' │ 4257 │
// │ 1 │ 'slower task' │ '828' │ 1207382.7838323202 │ '±7.07%' │ 83 │
// └─────────┴───────────────┴──────────┴────────────────────┴───────────┴─────────┘
console.table(
bench.table((task) => ({'Task name': task.name}))
);
// Output:
// ┌─────────┬───────────────────────┐
// │ (index) │ Task name │
// ├─────────┼───────────────────────┤
// │ 0 │ 'unimplemented bench' │
// └─────────┴───────────────────────┘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.
Docs
Bench
The Benchmark instance for keeping track of the benchmark tasks and controlling them.
Options:
export type Options = {
/**
* time needed for running a benchmark task (milliseconds) @default 500
*/
time?: number;
/**
* number of times that a task should run if even the time option is finished @default 10
*/
iterations?: number;
/**
* function to get the current timestamp in milliseconds
*/
now?: () => number;
/**
* An AbortSignal for aborting the benchmark
*/
signal?: AbortSignal;
/**
* Throw if a task fails (events will not work if true)
*/
throws?: boolean;
/**
* warmup time (milliseconds) @default 100ms
*/
warmupTime?: number;
/**
* warmup iterations @default 5
*/
warmupIterations?: number;
/**
* setup function to run before each benchmark task (cycle)
*/
setup?: Hook;
/**
* teardown function to run after each benchmark task (cycle)
*/
teardown?: Hook;
};
export type Hook = (task: Task, mode: "warmup" | "run") => void | Promise<void>;async run(): run the added tasks that were registered using theaddmethodasync runConcurrently(threshold: number = Infinity, mode: "bench" | "task" = "bench"): similar to therunmethod but runs concurrently rather than sequentially. See the Concurrency section.async warmup(): warm up the benchmark tasksasync warmupConcurrently(threshold: number = Infinity, mode: "bench" | "task" = "bench"): warm up the benchmark tasks concurrentlyreset(): reset each task and remove its resultadd(name: string, fn: Fn, opts?: FnOpts): add a benchmark task to the task mapFn:() => any | Promise<any>FnOpts:{}: a set of optional functions run during the benchmark lifecycle that can be used to set up or tear down test data or fixtures without affecting the timing of each taskbeforeAll?: () => any | Promise<any>: invoked once before iterations offnbeginbeforeEach?: () => any | Promise<any>: invoked before each timefnis executedafterEach?: () => any | Promise<any>: invoked after each timefnis executedafterAll?: () => any | Promise<any>: invoked once after all iterations offnhave finished
remove(name: string): remove a benchmark task from the task maptable(): table of the tasks resultsget results(): (TaskResult | undefined)[]: (getter) tasks results as an arrayget tasks(): Task[]: (getter) tasks as an arraygetTask(name: string): Task | undefined: get a task based on the nametodo(name: string, fn?: Fn, opts: FnOptions): add a benchmark todo to the todo mapget todos(): Task[]: (getter) tasks todos as an array
Task
A class that represents each benchmark task in Tinybench. It keeps track of the results, name, Bench instance, the task function and the number of times the task function has been executed.
constructor(bench: Bench, name: string, fn: Fn, opts: FnOptions = {})bench: Benchname: string: task namefn: Fn: the task functionopts: FnOptions: Task optionsruns: number: the number of times the task function has been executedresult?: TaskResult: the result objectasync run(): run the current task and write the results inTask.resultobjectasync warmup(): warm up the current tasksetResult(result: Partial<TaskResult>): change the result object valuesreset(): reset the task to make theTask.runsa zero-value and remove theTask.resultobject
export interface FnOptions {
/**
* An optional function that is run before iterations of this task begin
*/
beforeAll?: (this: Task) => void | Promise<void>;
/**
* An optional function that is run before each iteration of this task
*/
beforeEach?: (this: Task) => void | Promise<void>;
/**
* An optional function that is run after each iteration of this task
*/
afterEach?: (this: Task) => void | Promise<void>;
/**
* An optional function that is run after all iterations of this task end
*/
afterAll?: (this: Task) => void | Promise<void>;
}TaskResult
the benchmark task result object.
export type TaskResult = {
/*
* the last error that was thrown while running the task
*/
error?: unknown;
/**
* The amount of time in milliseconds to run the benchmark task (cycle).
*/
totalTime: number;
/**
* the minimum value in the samples
*/
min: number;
/**
* the maximum value in the samples
*/
max: number;
/**
* the number of operations per second
*/
hz: number;
/**
* how long each operation takes (ms)
*/
period: number;
/**
* task samples of each task iteration time (ms)
*/
samples: number[];
/**
* samples mean/average (estimate of the population mean)
*/
mean: number;
/**
* samples variance (estimate of the population variance)
*/
variance: number;
/**
* samples standard deviation (estimate of the population standard deviation)
*/
sd: number;
/**
* standard error of the mean (a.k.a. the standard deviation of the sampling distribution of the sample mean)
*/
sem: number;
/**
* degrees of freedom
*/
df: number;
/**
* critical value of the samples
*/
critical: number;
/**
* margin of error
*/
moe: number;
/**
* relative margin of error
*/
rme: number;
/**
* p75 percentile
*/
p75: number;
/**
* p99 percentile
*/
p99: number;
/**
* p995 percentile
*/
p995: number;
/**
* p999 percentile
*/
p999: number;
};Events
Both the Task and Bench objects extend the EventTarget object, so you can attach listeners to different types of events
in each class instance using the universal addEventListener and
removeEventListener.
/**
* Bench events
*/
export type BenchEvents =
| "abort" // when a signal aborts
| "complete" // when running a benchmark finishes
| "error" // when the benchmark task throws
| "reset" // when the reset function gets called
| "start" // when running the benchmarks gets started
| "warmup" // when the benchmarks start getting warmed up (before start)
| "cycle" // when running each benchmark task gets done (cycle)
| "add" // when a Task gets added to the Bench
| "remove" // when a Task gets removed of the Bench
| "todo"; // when a todo Task gets added to the Bench
/**
* task events
*/
export type TaskEvents =
| "abort"
| "complete"
| "error"
| "reset"
| "start"
| "warmup"
| "cycle";For instance:
// runs on each benchmark task's cycle
bench.addEventListener("cycle", (e) => {
const task = e.task!;
});
// runs only on this benchmark task's cycle
task.addEventListener("cycle", (e) => {
const task = e.task!;
});BenchEvent
export type BenchEvent = Event & {
task: Task | null;
};process.hrtime
if you want more accurate results for nodejs with process.hrtime, then import
the hrtimeNow function from the library and pass it to the Bench options.
import { hrtimeNow } from 'tinybench';It may make your benchmarks slower, check #42.
Concurrency
- When
modeis set tonull(default), concurrency is disabled. - When
modeis set to 'task', each task's iterations (calls of a task function) run concurrently. - When
modeis set to 'bench', different tasks within the bench run concurrently. Concurrent cycles.
// options way (recommended)
bench.threshold = 10 // The maximum number of concurrent tasks to run. Defaults to Infinity.
bench.concurrency = "task" // The concurrency mode to determine how tasks are run.
// await bench.warmup()
await bench.run()
// standalone method way
// await bench.warmupConcurrently(10, "task")
await bench.runConcurrently(10, "task") // with runConcurrently, mode is set to 'bench' by defaultPrior art
Authors
 Mohammad Bagher |
|---|
Credits
 Uzlopak |
 poyoho |
|---|
Contributing
Feel free to create issues/discussions and then PRs for the project!
Sponsors
Your sponsorship can make a huge difference in continuing our work in open source!
