mitata

Mitata provides high-performance benchmarking for both JavaScript and C++.

In JavaScript, use run, bench, boxplot, and summary to define and execute benchmarks. You can use generators to pass parameters to benchmarks.

In C++, use the mitata::runner class to manage benchmarks and summaries.

import { run, bench, boxplot, summary } from 'mitata';

function fibonacci(n) {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}

bench('fibonacci(40)', () => fibonacci(40));

boxplot(() => {
  summary(() => {
    bench('Array.from($size)', function* (state) {
      const size = state.get('size');
      yield () => Array.from({ length: size });
    }).range('size', 1, 1024);
  });
});

await run();

#include "src/mitata.hpp"

int fibonacci(int n) {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}

int main() {
  mitata::runner runner;
  runner.bench("noop", []() { });

  runner.summary([&]() {
    runner.bench("empty fn", []() { });
    runner.bench("fibonacci", []() { fibonacci(20); });
  });

  auto stats = runner.run();
}

Mitata provides built-in ASCII rendering for terminal-based visualizations. You can wrap your bench() calls in visualization scopes to generate barplots, boxplots, lineplots, and histograms. These scopes can be synchronous or asynchronous.

Available visualization functions:

• barplot(() => { ... }): Displays bar-style comparisons.
• boxplot(async () => { ... }): Displays box-and-whisker plots (supports async).
• lineplot(() => { ... }): Displays line plots.
• summary(() => { ... }): Displays a text-based summary of results.

You can nest visualizations, such as placing a summary inside a lineplot. Note that bench() calls made inside a nested scope (like summary) will not be included in the parent scope's visualization.

import { summary, barplot, boxplot, lineplot } from 'mitata';

// Wrap bench() calls in visualization scope
barplot(() => {
  bench('task', () => {
    // ...
  });
});

// Scopes can be async
await boxplot(async () => {
  // ...
});

// Combine multiple visualizations
lineplot(() => {
  summary(() => {
    // ...
  });

  // bench() calls here wont be part of summary
});

JavaScript engines may optimize away repeated computations by hoisting them out of loops or caching results (Loop Invariant Code Motion). To prevent the JIT from optimizing away computations that depend on parameters, use mitata's computed parameters feature. This moves the parameter computation outside the benchmark loop, ensuring the engine cannot treat the values as constants or loop-invariant.

bench(function* (ctx) {
  const str = 'abc';

  // ❌ Bad: JIT sees that both str and 'c' search value are constants/comptime-known
  yield () => str.includes('c');
  // will get optimized to:
  /*
    yield () => true;
  */

  // ❌ Bad: JIT sees that computation doesn't depend on anything inside loop
  const substr = ctx.get('substr');
  yield () => str.includes(substr);
  // will get optimized to:
  /*
    const $0 = str.includes(substr);
    yield () => $0;
  */

  // ✅ Good: using computed parameters prevents jit from performing any loop optimizations
  yield {
    [0]() {
      return str;
    },

    [1]() {
      return substr;
    },

    bench(str, substr) {
      return do_not_optimize(str.includes(substr));
    },
  };
}).args('substr', ['c']);

When calling run(), you can pass an options object to customize the output and execution behavior.

JavaScript options:

• format: Set the output format (e.g., 'json').
• filter: A regex to only run benchmarks matching the pattern.
• throw: If true, mitata will throw errors immediately instead of handling them quietly.
• format.mitata.name: Set a fixed length for the benchmark name column.

C++ options:

• .colors: Boolean to enable/disable colors.
• .format: String for the output format (e.g., "json").
• .filter: A std::regex to filter benchmarks.

import { run } from 'mitata';

await run({ format: 'json' }) // output json
await run({ filter: /new Array.*/ }) // only run benchmarks that match regex filter
await run({ throw: true }); // will immediately throw instead of handling error quietly
await run({ format: { mitata: { name: 'fixed' } } }); // benchmarks name column is fixed length

auto stats = runner.run({ .colors = true, .format = "json", .filter = std::regex(".*") });