Chapters
English
github
DocsBlogBenchmarks
fontcolor_theme
package

API @deepkit/bench

npm install @deepkit/bench

A simple tool to benchmark code snippets.

import { benchmark, run } from '@deepkit/bench';

// ASCII binary parsing example
const binaryString = Buffer.from('Hello World', 'utf8');
const codes = [

benchmark('Buffer.toString', () => {
    const utf8String = binaryString.toString('utf8');
});

benchmark('String.fromCodePoint', () => {
    const utf8String = String.fromCodePoint()
});

void run();
 
$ node --import @deepkit/run benchmarks/ascii-parsing.ts
Node v22.13.1
 🏎 x  20,326,482.53 ops/sec Β± 4.95%   0.000049 ms/op 	β–†β–†β–‡β–…β–†β–†β–…β–…β–†β–…β–…β–…β–…β–…β–…β–…β–…β–…β–…β–…β–…β–… Buffer.toString 	19850001 samples
 🏎 x  36,012,545.69 ops/sec Β± 1.78%   0.000028 ms/op 	β–‡β–‡β–‡β–‡β–‡β–‡β–‡β–‡β–‡β–‡β–‡β–‡β–‡β–‡β–‡β–‡β–‡β–‡β–‡β–‡β–‡β–‡ String.fromCodePoint 	35800001 samples
done

Classes
Functions
Types

Classes

BenchSuite [source] 
export class BenchSuite {
    /**  Global callback when any suite completes */
    static onComplete?: (name: string, result: BenchSuiteResult) => void;
    /**  Name of the benchmark suite */
    constructor(public readonly name: string, private defaultMaxTime: number = , private showSummary: boolean = false);
    /**
     * Add a benchmark to the suite.
     *
     * @param name - Name of the benchmark
     * @param fn - Function to benchmark (can be sync or async)
     * @param options - Optional settings
     */
    add(name: string, fn: () => void | Promise<void>, options: BenchmarkOptions = {}): this;
    /**
     * Run all benchmarks synchronously and return results.
     * Only works with sync benchmark functions.
     * For async benchmarks, use runAsync().
     */
    run(options: {
        verbose?: boolean;
    } = {}): BenchSuiteResult;
    /**
     * Run all benchmarks asynchronously.
     *
     * @returns Promise resolving to suite results
     */
    async runAsync(options: {
        verbose?: boolean;
    } = {}): Promise<BenchSuiteResult>;
    /**
     * Get results as JSON-serializable object.
     */
    getResults(): BenchSuiteResult;
}

BenchSuite - A benchmark suite for organizing and running multiple benchmarks.

Features:

  • Automatic sync/async detection
  • Block bar visualization
  • Memory tracking
  • Relative comparison between benchmarks
  • Callback when suite completes

Functions

getBlockBar [source] 
(values: number[], width?: number): string

Creates a colored block bar visualization from sample data. Uses HSV color gradient (green -> yellow) based on value.

getBrailleBar [source] 
(values: number[]): string

Creates a Braille-based bar visualization (more compact).

formatHz [source] 
(v: number): string

Formats operations per second with K/M/B suffix.

formatHzFull [source] 
(v: number): string

Formats operations per second with full number and locale formatting.

formatMean [source] 
(ms: number): string

Formats mean time per operation with appropriate unit (ns, Β΅s, ms, s).

formatRme [source] 
(v: number): string

Formats relative margin of error as percentage.

formatBytes [source] 
(bytes: number): string

Formats bytes with appropriate unit (B, KB, MB).

benchmark [source] 
(name: string, fn: () => void | Promise<void>): void

Registers a benchmark with the given name and function. Function can be synchronous or asynchronous.

run [source] 
(seconds?: number): Promise<void>

Runs all registered benchmarks each for the given number of seconds.

forceGC [source] 
(): void

Forces garbage collection if --expose-gc flag was used.

getHeapUsage [source] 
(): number

Gets current heap memory usage in bytes.

warmup [source] 
(fn: () => unknown, times?: number): void

Warmup function for V8 optimization. Run a function multiple times to ensure V8 optimizes it before benchmarking.

warmupAsync [source] 
(fn: () => Promise<unknown>, times?: number): Promise<void>

Async warmup function for V8 optimization.

Types

BenchResult [source] 
// TYPES
// ══════════════════════════════════════════════════════════════════════════════

/**
 * Result of a single benchmark
 */
export interface BenchResult {
    /** Operations per second */
    hz: number;
    /** Total elapsed time in seconds */
    elapsed: number;
    /** Relative margin of error (as percentage) */
    rme: number;
    /** Mean time per operation in milliseconds */
    mean: number;
    /** Variance of samples */
    variance: number;
    /** Number of iterations run */
    iterations: number;
    /** Sample timings for visualization (up to 50 samples) */
    samples: number[];
    /** Heap memory difference in bytes */
    heapDiff: number;
    /** Whether this is an async benchmark */
    async: boolean;
    /** GC events during benchmark (pause times in ms) */
    gcEvents: number[];
}

Result of a single benchmark

BenchSuiteResult [source] 
type BenchSuiteResult = { [name: string]: BenchResult };

Results of a benchmark suite (name -> result)

BenchmarkOptions [source] 
interface BenchmarkOptions {
    /** Maximum time to run in seconds (default: 1) */
    maxTime?: number;
}

Options for individual benchmarks

EnglishδΈ­ζ–‡ (Chinese)ν•œκ΅­μ–΄ (Korean)ζ—₯本θͺž (Japanese)Deutsch (German)