Tinybench

A simple, tiny and lightweight benchmarking library!

Performance
tinylibs/tinybenchtinybench

README

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
- Event and EventTarget compatible 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


  1. ``` sh
  2. $ npm install -D tinybench
  3. ```

Usage


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

  1. ``` js
  2. import { Bench } from 'tinybench';

  4. const bench = new Bench({ time: 100 });

  6. bench
  7.   .add('switch 1', () => {
  8.     let a = 1;
  9.     let b = 2;
  10.     const c = a;
  11.     a = b;
  12.     b = c;
  13.   })
  14.   .add('switch 2', () => {
  15.     let a = 1;
  16.     let b = 10;
  17.     a = b + a;
  18.     b = a - b;
  19.     a = b - a;
  20.   });

  22. await bench.run();

  24. console.table(bench.tasks.map(({ name, result }) => ({ "Task Name": name, "Average Time (ps)": result?.mean * 1000, "Variance (ps)": result?.variance * 1000 })));

  26. // Output:
  27. // ┌─────────┬────────────┬────────────────────┬────────────────────┐
  28. // │ (index) │ Task Name  │ Average Time (ps)  │   Variance (ps)    │
  29. // ├─────────┼────────────┼────────────────────┼────────────────────┤
  30. // │    0    │ 'switch 1' │ 1.8458325710527104 │ 1.2113875253341617 │
  31. // │    1    │ 'switch 2' │ 1.8746935152109603 │ 1.2254725890767446 │
  32. // └─────────┴────────────┴────────────────────┴────────────────────┘
  33. ```

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:

  1. ```ts
  2. export type Options = {
  3.   /**
  4.    * time needed for running a benchmark task (milliseconds) @default 500
  5.    */
  6.   time?: number;

  8.   /**
  9.    * number of times that a task should run if even the time option is finished @default 10
  10.    */
  11.   iterations?: number;

  13.   /**
  14.    * function to get the current timestamp in milliseconds
  15.    */
  16.   now?: () => number;

  18.   /**
  19.    * An AbortSignal for aborting the benchmark
  20.    */
  21.   signal?: AbortSignal;

  23.   /**
  24.    * warmup time (milliseconds) @default 100ms
  25.    */
  26.   warmupTime?: number;

  28.   /**
  29.    * warmup iterations @default 5
  30.    */
  31.   warmupIterations?: number;

  33.   /**
  34.    * setup function to run before each benchmark task (cycle)
  35.    */
  36.   setup?: Hook;

  38.   /**
  39.    * teardown function to run after each benchmark task (cycle)
  40.    */
  41.   teardown?: Hook;
  42. };

  44. export type Hook = (task: Task, mode: "warmup" | "run") => void | Promise<void>;
  45. ```

- async run(): run the added tasks that were registered using the add method
- async warmup(): warm up the benchmark tasks
- reset(): reset each task and remove its result
- add(name: string, fn: Fn): add a benchmark task to the task map
- - `Fn`: `() => any | Promise`
- remove(name: string): remove a benchmark task from the task map
- get results(): (TaskResult | undefined)[]: (getter) tasks results as an array
- get tasks(): Task[]: (getter) tasks as an array
- getTask(name: string): Task | undefined: get a task based on the name

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)
- bench: Bench
- name: string: task name
- fn: Fn: the task function
- runs: number: the number of times the task function has been executed
- result?: TaskResult: the result object
- async run(): run the current task and write the results in Task.result object
- async warmup(): warm up the current task
- `setResult(result: Partial)`: change the result object values
- reset(): reset the task to make the Task.runs a zero-value and remove the Task.result object

TaskResult


the benchmark task result object.

  1. ```ts
  2. export type TaskResult = {

  4.   /*
  5.    * the last error that was thrown while running the task
  6.    */
  7.   error?: unknown;

  9.   /**
  10.    * The amount of time in milliseconds to run the benchmark task (cycle).
  11.    */
  12.   totalTime: number;

  14.   /**
  15.    * the minimum value in the samples
  16.    */
  17.   min: number;
  18.   /**
  19.    * the maximum value in the samples
  20.    */
  21.   max: number;

  23.   /**
  24.    * the number of operations per second
  25.    */
  26.   hz: number;

  28.   /**
  29.    * how long each operation takes (ms)
  30.    */
  31.   period: number;

  33.   /**
  34.    * task samples of each task iteration time (ms)
  35.    */
  36.   samples: number[];

  38.   /**
  39.    * samples mean/average (estimate of the population mean)
  40.    */
  41.   mean: number;

  43.   /**
  44.    * samples variance (estimate of the population variance)
  45.    */
  46.   variance: number;

  48.   /**
  49.    * samples standard deviation (estimate of the population standard deviation)
  50.    */
  51.   sd: number;

  53.   /**
  54.    * standard error of the mean (a.k.a. the standard deviation of the sampling distribution of the sample mean)
  55.    */
  56.   sem: number;

  58.   /**
  59.    * degrees of freedom
  60.    */
  61.   df: number;

  63.   /**
  64.    * critical value of the samples
  65.    */
  66.   critical: number;

  68.   /**
  69.    * margin of error
  70.    */
  71.   moe: number;

  73.   /**
  74.    * relative margin of error
  75.    */
  76.   rme: number;

  78.   /**
  79.    * p75 percentile
  80.    */
  81.   p75: number;

  83.   /**
  84.    * p99 percentile
  85.    */
  86.   p99: number;

  88.   /**
  89.    * p995 percentile
  90.    */
  91.   p995: number;

  93.   /**
  94.    * p999 percentile
  95.    */
  96.   p999: number;
  97. };
  98. ```

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.

  1. ```ts
  2. /**
  3. * Bench events
  4. */
  5. export type BenchEvents =
  6.   | "abort" // when a signal aborts
  7.   | "complete" // when running a benchmark finishes
  8.   | "error" // when the benchmark task throws
  9.   | "reset" // when the reset function gets called
  10.   | "start" // when running the benchmarks gets started
  11.   | "warmup" // when the benchmarks start getting warmed up (before start)
  12.   | "cycle" // when running each benchmark task gets done (cycle)
  13.   | "add" // when a Task gets added to the Bench
  14.   | "remove"; // when a Task gets removed of the Bench

  16. /**
  17. * task events
  18. */
  19. export type TaskEvents =
  20.   | "abort"
  21.   | "complete"
  22.   | "error"
  23.   | "reset"
  24.   | "start"
  25.   | "warmup"
  26.   | "cycle";
  27. ```

For instance:

  1. ``` js
  2. // runs on each benchmark task's cycle
  3. bench.addEventListener("cycle", (e) => {
  4.   const task = e.task!;
  5. });

  7. // runs only on this benchmark task's cycle
  8. task.addEventListener("cycle", (e) => {
  9.   const task = e.task!;
  10. });
  11. ```

BenchEvent


  1. ```ts
  2. export type BenchEvent = Event & {
  3.   task: Task | null;
  4. };
  5. ```

Prior art


- Benchmark.js
- Mitata
- Bema

Authors


------------------------------------------------------------------------------------------------------------------------------------------------

Credits


-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Contributing


Feel free to create issues/discussions and then PRs for the project!