@monstermann/tinybench-pretty-printer/README.md

Customizable pretty-printer for tinybench benchmarks

<div align="center">

<h1>tinybench-pretty-printer</h1>

**🔎 Customizable pretty-printer for [tinybench](https://github.com/tinylibs/tinybench) benchmarks**

![Minified](https://img.shields.io/badge/Minified-30.73_KB-blue)
![Minzipped](https://img.shields.io/badge/Minzipped-10.53_KB-blue)

</div>

![Example](./docs/screenshots/example.png)

# Features

- Output for CLIs and markdown
- Build your own columns
- Change column order
- Handles unicode & truncation
- Customizable count formatting:
    - `none`
    - `shortest`
    - `highest`
    - `lowest`
    - `mean`
    - `thousands`
    - `millions`
    - `billions`
- Customizable duration formatting:
    - `shortest`
    - `highest`
    - `lowest`
    - `mean`
    - `nanoseconds`
    - `microseconds`
    - `milliseconds`
    - `seconds`
- Sorting:
    - `false`
    - `asc`
    - `desc`
    - `Function`
- Uses `Intl.NumberFormat` for localization and removing insignificant fractions
- Customizable header titles, styles and alignments
- Customizable row styles and alignments
- Customizable borders and border styles
- …

# Installation

```sh
npm install @monstermann/tinybench-pretty-printer
yarn add @monstermann/tinybench-pretty-printer
pnpm add @monstermann/tinybench-pretty-printer
```

# Getting Started

```ts
import { Bench } from 'tinybench'

const bench = new Bench()

bench.add(Function)
bench.add(Function)
bench.add(Function)

await bench.run()
```

**Using Defaults**

```ts
import { tinybenchPrinter } from '@monstermann/tinybench-pretty-printer'

const cli = tinybenchPrinter.toCli(bench)
console.log(cli)
```

```ts
import { writeFile } from 'node:fs/promises'

const markdown = tinybenchPrinter.toMarkdown(bench)
await writeFile('results.md', markdown)
```

**Using Options**

```ts
import { tinybenchPrinter } from '@monstermann/tinybench-pretty-printer'

const myCustomPrinter = tinybenchPrinter

    // Display ops/sec in millions exclusively:
    .ops({ method: 'millions' })

    // Pick a time formatting method based on the mean duration of all benchmarks,
    // and tweak some styling for that column:
    .time({
        method: 'mean',
        rowAlignment: ['center'],
        rowStyle: ['bold'],
    })

    // Sort ascending instead of descending:
    .sort('asc')

    // Decrease the default padding:
    .padding(1)

    // Remove some borders to make it more compact:
    .useBorderTop(false)
    .useBorderLeft(false)
    .useBorderRight(false)
    .useBorderBottom(false)

console.log(myCustomPrinter.toCli(bench))
```

## Configuring Default Columns

```ts
import { tinybenchPrinter } from '@monstermann/tinybench-pretty-printer'

tinybenchPrinter

    .name({
        // Change the header title:
        header: 'name',
        // Change the header style:
        // (see https://github.com/alexeyraspopov/picocolors/blob/main/types.ts)
        headerStyle: ['bold'],
        // Change the header alignment: (left | center | right)
        headerAlignment: 'center',

        // Change the row alignment: (left | center | right)
        rowAlignment: 'left',
        // Change the row style:
        // (see https://github.com/alexeyraspopov/picocolors/blob/main/types.ts)
        rowStyle: [],
    })

    .summary({
        // Change the column text of the fastest result:
        fastestTitle: '🥇',

        // Display as "10x slower":
        method: 'x',
        // Display as "-90%":
        method: '%',

        // Change the header title:
        header: 'summary',
        // Change the header style:
        // (see https://github.com/alexeyraspopov/picocolors/blob/main/types.ts)
        headerStyle: ['bold'],
        // Change the header alignment: (left | center | right)
        headerAlignment: 'center',

        // Change the row alignment: (left | center | right)
        rowAlignment: 'center',
        // Change the row style:
        // (see https://github.com/alexeyraspopov/picocolors/blob/main/types.ts)
        rowStyle: [],

    })

    .ops({
        // Display value as-is:
        method: 'none',
        // Display all rows in thousands, eg. "10K":
        method: 'thousands',
        // Display all rows in millions, eg. "10M":
        method: 'millions',
        // Display all rows in billions, eg. "10B"
        method: 'billions',

        // Choose from the above, favoring the shortest possible option for each row:
        method: 'shortest',
        // Chose from the above, based on the highest ops/sec of all benchmarks:
        method: 'highest',
        // Chose from the above, based on the lowest ops/sec of all benchmarks:
        method: 'lowest',
        // Chose from the above, based on the mean ops/sec of all benchmarks:
        method: 'mean',

        // Change the header title:
        header: 'ops/sec',
        // Change the header style:
        // (see https://github.com/alexeyraspopov/picocolors/blob/main/types.ts)
        headerStyle: ['bold'],
        // Change the header alignment: (left | center | right)
        headerAlignment: 'center',

        // Change the row alignment: (left | center | right)
        rowAlignment: 'right',
        // Change the row style:
        // (see https://github.com/alexeyraspopov/picocolors/blob/main/types.ts)
        rowStyle: ['blue'],

    })

    .time({
        // Display all rows in nanoseconds, eg. "10ns":
        method: 'nanoseconds',
        // Display all rows in microseconds, eg. "10µs":
        method: 'microseconds',
        // Display all rows in milliseconds, eg. "10ms":
        method: 'milliseconds',
        // Display all rows in seconds, eg. "10s":
        method: 'seconds',

        // Choose from the above, favoring the shortest possible option for each row:
        method: 'shortest',
        // Chose from the above, based on the highest time/op of all benchmarks:
        method: 'highest',
        // Chose from the above, based on the lowest time/op of all benchmarks:
        method: 'lowest',
        // Chose from the above, based on the mean time/op of all benchmarks:
        method: 'mean',

        // Change the header title:
        header: 'time/op',
        // Change the header style:
        // (see https://github.com/alexeyraspopov/picocolors/blob/main/types.ts)
        headerStyle: ['bold'],
        // Change the header alignment: (left | center | right)
        headerAlignment: 'center',

        // Change the row alignment: (left | center | right)
        rowAlignment: 'right',
        // Change the row style:
        // (see https://github.com/alexeyraspopov/picocolors/blob/main/types.ts)
        rowStyle: ['yellow'],
    })

    .margin({
        // Change the header title:
        header: 'margin',
        // Change the header style:
        // (see https://github.com/alexeyraspopov/picocolors/blob/main/types.ts)
        headerStyle: ['bold'],
        // Change the header alignment: (left | center | right)
        headerAlignment: 'center',

        // Change the row alignment: (left | center | right)
        rowAlignment: 'center',
        // Change the row style:
        // (see https://github.com/alexeyraspopov/picocolors/blob/main/types.ts)
        rowStyle: ['magenta'],
    })

    .samples({
        // Display value as-is:
        method: 'none',
        // Display all rows in thousands, eg. "10K":
        method: 'thousands',
        // Display all rows in millions, eg. "10M":
        method: 'millions',
        // Display all rows in billions, eg. "10B"
        method: 'billions',

        // Choose from the above, favoring the shortest possible option for each row:
        method: 'shortest',
        // Chose from the above, based on the highest ops/sec of all benchmarks:
        method: 'highest',
        // Chose from the above, based on the lowest ops/sec of all benchmarks:
        method: 'lowest',
        // Chose from the above, based on the mean ops/sec of all benchmarks:
        method: 'mean',

        // Change the header title:
        header: 'samples',
        // Change the header style:
        // (see https://github.com/alexeyraspopov/picocolors/blob/main/types.ts)
        headerStyle: ['bold'],
        // Change the header alignment: (left | center | right)
        headerAlignment: 'center',

        // Change the row alignment: (left | center | right)
        rowAlignment: 'right',
        // Change the row style:
        // (see https://github.com/alexeyraspopov/picocolors/blob/main/types.ts)
        rowStyle: ['magenta'],
    })
```

## Adding Custom Columns

> [!NOTE]
> You can also use this to overwrite the default columns!

```ts
import { tinybenchPrinter } from '@monstermann/tinybench-pretty-printer'

tinybenchPrinter

    .column('my-custom-column', {
        // Return the string that should be displayed in each row:
        content({
            task,
            tasks,
            fastestTask,
            slowestTask,
            locales,
            formatNumber,
            formatDuration,
            formatCount,
        }) {
            return String(task.result.hz)
        },

        // Set the header title:
        header: 'ops/sec',
        // Set the header style:
        // (see https://github.com/alexeyraspopov/picocolors/blob/main/types.ts)
        headerStyle: ['bold'],
        // Set the header alignment: (left | center | right)
        headerAlignment: 'center',
        // Set the row alignment: (left | center | right)
        rowAlignment: 'right',
        // Set the row style:
        // (see https://github.com/alexeyraspopov/picocolors/blob/main/types.ts)
        rowStyle: ['blue'],
    })

    // After you set up your columns, you need to define which columns to display,
    // in what order:
    .order(['name', 'summary', 'my-custom-column'])
```

## Rendering Options

```ts
import { tinybenchPrinter } from '@monstermann/tinybench-pretty-printer'

tinybenchPrinter

    // Change the order of the columns and/or drop unwanted ones:
    .order(['name', 'ops'])

    // Change the sorting method used:
    .sort(false)
    .sort('asc')
    .sort('desc')
    .sort(tasks => tasks)

    // Change the locales passed to Number.toLocaleString:
    .locales('en-US')

    // Change the NodeJS.WriteStream that is used to detect the maximum available width:
    .stdout(process.stdout)
    // Force a custom max-width:
    .maxWidth(undefined)

    // Change the padding between columns:
    .padding(2)

    // Customize which borders should be used:
    .useHeader(true)
    .useTopBorder(true)
    .useBottomBorder(true)
    .useLeftBorder(true)
    .useRightBorder(true)
    .useDividerBorder(true)
    .useHeaderSeparator(true)
    .useRowSeparator(false)

    // Change the style of all borders:
    // (see https://github.com/alexeyraspopov/picocolors/blob/main/types.ts)
    .borderStyle(['dim'])

    // Customize the borders:
    .borders({
        top: '─',
        topLeft: '┌',
        topRight: '┐',
        topDivider: '┬',

        bottom: '─',
        bottomLeft: '└',
        bottomRight: '┘',
        bottomDivider: '┴',

        left: '│',
        right: '│',
        divider: '│',

        separator: '─',
        separatorLeft: '├',
        separatorRight: '┤',
        separatorDivider: '┼',
    })
```