Micron Runner

Benchmark tool that shows how performance scales with input size. Run sweep benchmarks across a range of N values and visualize the results.

micron-runner --sweep 100:5000:500

  array-sort.bench.js
  ┌───────┬──────┬──────┬──────┬──────┐
  │   N   │  min │  avg │  max │  p95 │
  ├───────┼──────┼──────┼──────┼──────┤
  │   100 │   0ms│   0ms│   1ms│   0ms│
  │   600 │   1ms│   1ms│   2ms│   1ms│
  │  1100 │   3ms│   3ms│   4ms│   4ms│
  └───────┴──────┴──────┴──────┴──────┘

Installation

npm install --save-dev micron-runner

or globally:

npm install -g micron-runner

Quick Start

1. Create a benchmarks/ folder in your project
2. Add .bench.js files
3. Run micron-runner

project/
└── benchmarks/
    ├── array-sort.bench.js
    └── db-insert.bench.js

Benchmark File Format

// benchmarks/my-benchmark.bench.js

export const name = 'My benchmark';       // optional label

export async function setup() {
    // runs once before the sweep starts
}

export async function teardown() {
    // runs once after the sweep ends
}

export async function bench(n) {
    // measured code — called n times per step
}

Only bench is required. setup, teardown, and name are optional.

Examples

Pure JS (no dependencies):

// benchmarks/array-sort.bench.js
export async function bench(n) {
    const arr = Array.from({ length: n }, () => Math.random());
    arr.sort((a, b) => a - b);
}

With database setup:

// benchmarks/db-insert.bench.js
import mongoose from 'mongoose';
import User from '../models/user.js';

export async function setup() {
    await mongoose.connect('mongodb://localhost:27017/mydb');
}

export async function teardown() {
    await mongoose.connection.close();
}

export async function bench() {
    await User.create({ name: 'test', email: `test-${Date.now()}@x.com` });
}

CLI Usage

micron-runner                              # auto-detect ./benchmarks
micron-runner ./my-folder                  # custom folder
micron-runner --sweep 100:5000:500         # start:end:step shorthand
micron-runner --start 100 --end 5000 --step 500
micron-runner --repeats 5
micron-runner --json > results.json        # CI-friendly JSON output
micron-runner --quiet                      # errors only
micron-runner --help

Options

| Flag | Alias | Description | Default | |------|-------|-------------|---------| | --sweep start:end:step | | Shorthand for start/end/step | | | --start | -s | Initial N | 100 | | --end | -e | Final N | 2100 | | --step | -i | Step between N values | 500 | | --repeats | -r | Repeats per step | 3 | | --outdir | -o | Output folder | ./results | | --json | -j | Output JSON to stdout, skip HTML | | | --quiet | -q | Suppress all output except errors | |

Programmatic API

import Micron from 'micron-runner';

const runner = new Micron({
    folder: './benchmarks',
    start: 100,
    end: 5000,
    step: 500,
    repeats: 3,
    writeResults: true,   // write HTML chart to outdir
    json: false,          // print JSON to stdout
    quiet: false
});

const results = await runner.run();

Output

After each benchmark file, a table is printed to stdout:

  db-insert.bench.js
  ┌───────┬──────┬──────┬──────┬──────┐
  │   N   │  min │  avg │  max │  p95 │
  ├───────┼──────┼──────┼──────┼──────┤
  │   100 │  12ms│  14ms│  18ms│  17ms│
  │   600 │  61ms│  65ms│  72ms│  70ms│
  └───────┴──────┴──────┴──────┴──────┘

An HTML chart with avg, p95, min/max lines is written to ./results/index.html.

Use --json to get structured output for CI pipelines:

micron-runner --json > results.json

TypeScript

Types are included:

import Micron, { MicronConfig, BenchModule, BenchResults } from 'micron-runner';

License

MIT