README.md

tatami-ng

Cross JavaScript runtime benchmarking library and CLI

• CLI and JS library support ✔
• Library API backward compatible with mitata up to version 0.1.14 ✔
• Benchmark latency and throughput ✔
• Support for sync and async benchmark ✔
• Advanced benchmark statistics: significance, error margin, variance, standard deviation, p-quantiles, ... ✔
• Multiple JS runtime support at zero cost abstraction (primary support for node, deno, bun and browsers but works with all JS runtime) ✔
• Support for CommonJS, ESM and TypeScript ✔

Table of contents

• Library installation
  • Node
    • npmjs
    • JSR
  • Deno
  • Bun
    • npmjs
    • JSR
  • Browser
• Library usage example
• CLI installation
  • Node
  • Deno
  • Bun
• CLI standalone binary
  • Deno
  • Bun
• CLI usage examples
• Development
• License

Library installation

Node

npmjs

npm install tatami-ng

JSR

npx jsr add @poolifier/tatami-ng

Deno

deno add @poolifier/tatami-ng

Deno versions >= 1.40.x are supported.

The --allow-hrtime permission flag is recommended to allow high-resolution time measurement with Deno v1.x.x.

Bun

npmjs

bun add tatami-ng

JSR

bunx jsr add @poolifier/tatami-ng

Bun versions >= 1.x are supported.

Browser

<script type="module">
import {
 ...
} from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/browser/index.js'
</script>

Library usage example

// adapt import to the targeted JS runtime
import { baseline, bench, bmf, group, run } from 'tatami-ng'

bench('noop', () => {})
bench('noop2', () => {})

group('group', () => {
  baseline('baseline', () => {})
  bench('Date.now()', () => {
    Date.now()
  })
  bench('performance.now()', () => {
    performance.now()
  })
})

group({ name: 'group2', summary: false }, () => {
  bench('new Array(0)', () => {
    new Array(0)
  })
  bench('new Array(1024)', () => {
    new Array(1024)
  })
})

await run({
  units: false, // print units cheatsheet (default: false)
  silent: false, // enable/disable stdout output (default: false)
  json: false, // enable/disable json output or set json output indentation (default: false)
  reporter: bmf // custom reporter function (default: undefined)
  file: 'results.json', // write json output to file (default: undefined)
  colors: true, // enable/disable colors (default: true)
  now: () => 1e6 * performance.now(), // custom nanoseconds timestamp function to replace default one (default: undefined)
  samples: 128, // minimum number of benchmark samples (default: 128)
  time: 1_000_000_000, // minimum benchmark execution time in nanoseconds (default: 1_000_000_000)
  warmup: true, // enable/disable benchmark warmup or set benchmark warmup run(s) (default: true)
  warmupTime: 250_000_000, // minimum warmup execution time in nanoseconds (default: 250_000_000)
  latency: true, // enable/disable time/iter column (default: true)
  throughput: true, // enable/disable iters/s column (default: true)
  latencyMinMax: true, // enable/disable latency (min...max) column (default: true)
  latencyPercentiles: false, // enable/disable latency percentile columns (default: true)
})

The tests directory contains more examples.

CLI installation

Node

npm install tatami-ng -g

Deno

deno install -g --allow-read --allow-run --allow-sys -n tatami npm:tatami-ng

Bun

bun add tatami-ng -g

Ensure the global installation directory is in your path:

• Unix: ${HOME}/.bun/bin
• Windows: TODO

CLI standalone binary

In the cloned repository root directory, run:

Deno

bun build:cli:deno

Bun

bun build:cli:bun

The standalone binary in ./dist/<runtime_name> can be moved to a directory in your path.

CLI usage examples

tatami --help

tatami --bench 'hexdump <file>' --bench 'xxd <file>'

Development

The JavaScript runtime environment used for development is bun.

License

MIT © Evan, Jerome Benoit