diff --git a/src/benchmark.js b/src/benchmark.js index 4e1525f..00e5cfe 100644 --- a/src/benchmark.js +++ b/src/benchmark.js @@ -10,20 +10,31 @@ import { AsyncFunction, checkBenchmarkArgs, colors, - convertReportToBmf, cpuModel, gc, - isObject, measure, overrideBenchmarkOptions, version, writeFileSync, } from './lib.js' import { logger } from './logger.js' -import * as clr from './reporter/clr.js' -import * as table from './reporter/table.js' +import { bmf } from './reporter/json/index.js' +import { + benchmarkError, + benchmarkReport, + bold, + br, + dim, + header, + size, + summary, + units, + warning, + white, +} from './reporter/terminal/index.js' import { runtime } from './runtime.js' import { now } from './time.js' +import { isObject } from './utils.js' let groupName = null const groups = new Map() @@ -247,18 +258,18 @@ const executeBenchmarks = async ( after: benchmark.after, }) if (!opts.json) - logFn(table.benchmark(benchmark.name, benchmark.stats, opts)) + logFn(benchmarkReport(benchmark.name, benchmark.stats, opts)) } catch (err) { benchmark.error = err if (!opts.json) - logFn(table.benchmarkError(benchmark.name, benchmark.error, opts)) + logFn(benchmarkError(benchmark.name, benchmark.error, opts)) } } // biome-ignore lint/style/noParameterAssign: benchmarks = benchmarks.filter(benchmark => benchmark.error == null) - if (!opts.json && table.warning(benchmarks, opts)) { + if (!opts.json && warning(benchmarks, opts)) { logFn('') - logFn(table.warning(benchmarks, opts)) + logFn(warning(benchmarks, opts)) } if ( (Object.keys(groupOpts).length === 0 || groupOpts.summary === true) && @@ -266,7 +277,7 @@ const executeBenchmarks = async ( benchmarks.length > 1 ) { logFn('') - logFn(table.summary(benchmarks, opts)) + logFn(summary(benchmarks, opts)) } return once } @@ -341,7 +352,7 @@ export async function run(opts = {}) { opts.silent = opts.silent ?? false opts.units = opts.units ?? false opts.colors = opts.colors ?? colors - opts.size = table.size(benchmarks.map(benchmark => benchmark.name)) + opts.size = size(benchmarks.map(benchmark => benchmark.name)) const log = opts.silent === true ? emptyFunction : logger @@ -352,14 +363,12 @@ export async function run(opts = {}) { } if (!opts.json && benchmarks.length > 0) { - log(clr.dim(opts.colors, clr.white(opts.colors, `cpu: ${report.cpu}`))) - log( - clr.dim(opts.colors, clr.white(opts.colors, `runtime: ${report.runtime}`)) - ) + log(dim(opts.colors, white(opts.colors, `cpu: ${report.cpu}`))) + log(dim(opts.colors, white(opts.colors, `runtime: ${report.runtime}`))) log('') - log(table.header(opts)) - log(table.br(opts)) + log(header(opts)) + log(br(opts)) } let once = await executeBenchmarks( @@ -371,10 +380,9 @@ export async function run(opts = {}) { for (const [group, groupOpts] of groups) { if (!opts.json) { if (once) log('') - if (!group.startsWith(tatamiNgGroup)) - log(`• ${clr.bold(opts.colors, group)}`) + if (!group.startsWith(tatamiNgGroup)) log(`• ${bold(opts.colors, group)}`) if (once || !group.startsWith(tatamiNgGroup)) - log(clr.dim(opts.colors, clr.white(opts.colors, table.br(opts)))) + log(dim(opts.colors, white(opts.colors, br(opts)))) } AsyncFunction === groupOpts.before.constructor @@ -393,12 +401,12 @@ export async function run(opts = {}) { : groupOpts.after() } - if (!opts.json && opts.units) log(table.units(opts)) + if (!opts.json && opts.units) log(units(opts)) if (opts.json || opts.file) { let jsonReport switch (opts.json) { case jsonOutputFormat.bmf: - jsonReport = JSON.stringify(convertReportToBmf(report)) + jsonReport = JSON.stringify(bmf(report)) break default: jsonReport = JSON.stringify( diff --git a/src/index.d.ts b/src/index.d.ts index 59e0497..cf27318 100644 --- a/src/index.d.ts +++ b/src/index.d.ts @@ -62,7 +62,7 @@ export function run(options?: { units?: boolean }): Promise -export interface Report { +export type BenchmarkReport = { cpu: string runtime: string @@ -97,5 +97,7 @@ export interface Report { mad: number // median time absolute deviation ss: boolean // statistical significance } - }[] + } } + +export type Report = BenchmarkReport[] diff --git a/src/index.js b/src/index.js index 2d47fea..6bc4db4 100644 --- a/src/index.js +++ b/src/index.js @@ -1 +1,2 @@ -export { group, bench, baseline, run } from './benchmark.js' +export { baseline, bench, group, run } from './benchmark.js' +export { bmf } from './reporter/json/index.js' diff --git a/src/lib.js b/src/lib.js index 1f24e06..a5f3771 100644 --- a/src/lib.js +++ b/src/lib.js @@ -1,3 +1,6 @@ +import { spawnSync as nodeSpawnSync } from 'node:child_process' +import { setFlagsFromString } from 'node:v8' +import { runInNewContext } from 'node:vm' import { defaultSamples, defaultTime, @@ -7,11 +10,15 @@ import { tTable, } from './constants.js' import { runtime } from './runtime.js' +import { + absoluteDeviation, + average, + medianSorted, + quantileSorted, + variance, +} from './stats-utils.js' import { now } from './time.js' - -import { spawnSync as nodeSpawnSync } from 'node:child_process' -import { setFlagsFromString } from 'node:v8' -import { runInNewContext } from 'node:vm' +import { checkDividend, isObject } from './utils.js' export const AsyncFunction = (async () => {}).constructor @@ -133,28 +140,6 @@ export const gc = (() => { }[runtime]() })() -export const convertReportToBmf = report => { - return report.benchmarks - .map(({ name, stats }) => { - const throughputSd = ratioStandardDeviation(1e9, 0, stats.avg, stats.sd) - return { - [name]: { - latency: { - value: stats?.avg, - lower_value: stats?.avg - stats?.sd, - upper_value: stats?.avg + stats?.sd, - }, - throughput: { - value: stats?.iters, - lower_value: stats?.iters - throughputSd, - upper_value: stats?.iters + throughputSd, - }, - }, - } - }) - .reduce((obj, item) => Object.assign(obj, item), {}) -} - export const checkBenchmarkArgs = (fn, opts = {}) => { if (![Function, AsyncFunction].includes(fn.constructor)) throw new TypeError(`expected function, got ${fn.constructor.name}`) @@ -203,18 +188,6 @@ export const overrideBenchmarkOptions = (benchmark, opts) => { benchmark.warmup = opts.warmup ?? benchmark.warmup } -export const isObject = value => { - return Object.prototype.toString.call(value).slice(8, -1) === 'Object' -} - -export const checkDividend = n => { - if (n == null) throw new TypeError(`Invalid dividend: ${n}`) - if ('number' !== typeof n) - throw new TypeError(`expected number, got ${n.constructor.name}`) - if (n === 0 || Number.isNaN(n)) throw new RangeError(`Invalid dividend: ${n}`) - return n -} - /** * Measure a function runtime. * @@ -297,68 +270,10 @@ export async function measure(fn, opts = {}) { ? await benchmark(fn, opts.before, opts.after, opts.now) : benchmark(fn, opts.before, opts.after, opts.now) - return buildStats(samples) -} - -const variance = (samples, avg = average(samples)) => { - return ( - samples.reduce((a, b) => a + (b - avg) ** 2, 0) / - checkDividend(samples.length - 1) // Bessel's correction - ) -} - -const quantileSorted = (samples, q) => { - if (!Array.isArray(samples)) { - throw new TypeError(`expected array, got ${samples.constructor.name}`) - } - if (samples.length === 0) { - throw new Error('expected non-empty array, got empty array') - } - if (q < 0 || q > 1) { - throw new Error('q must be between 0 and 1') - } - if (q === 0) { - return samples[0] - } - if (q === 1) { - return samples[samples.length - 1] - } - const base = (samples.length - 1) * q - const baseIndex = Math.floor(base) - if (samples[baseIndex + 1] != null) { - return ( - samples[baseIndex] + - (base - baseIndex) * (samples[baseIndex + 1] - samples[baseIndex]) - ) - } - return samples[baseIndex] -} - -const medianSorted = samples => quantileSorted(samples, 0.5) - -const average = samples => { - if (!Array.isArray(samples)) { - throw new TypeError(`expected array, got ${samples.constructor.name}`) - } - if (samples.length === 0) { - throw new Error('expected non-empty array, got empty array') - } - - return samples.reduce((a, b) => a + b, 0) / samples.length + return buildMeasurementStats(samples) } -const absoluteDeviation = (samples, aggFn) => { - const value = aggFn(samples) - const absoluteDeviations = [] - - for (const sample of samples) { - absoluteDeviations.push(Math.abs(sample - value)) - } - - return aggFn(absoluteDeviations) -} - -const buildStats = samples => { +const buildMeasurementStats = samples => { if (!Array.isArray(samples)) throw new TypeError(`expected array, got ${samples.constructor.name}`) if (samples.length === 0) @@ -394,13 +309,3 @@ const buildStats = samples => { ss: samples.length >= minimumSamples, } } - -// https://en.wikipedia.org/wiki/Propagation_of_uncertainty#Example_formulae -export const ratioStandardDeviation = (avgA, sdA, avgB, sdB) => { - return ( - (avgA / checkDividend(avgB)) * - Math.sqrt( - (sdA / checkDividend(avgA)) ** 2 + (sdB / checkDividend(avgB)) ** 2 - ) - ) -} diff --git a/src/reporter/json/bmf.js b/src/reporter/json/bmf.js new file mode 100644 index 0000000..b03eac7 --- /dev/null +++ b/src/reporter/json/bmf.js @@ -0,0 +1,24 @@ +import { ratioStandardDeviation } from '../../stats-utils.js' + +export const bmf = report => { + return report.benchmarks + .filter(benchmark => benchmark.error == null) + .map(({ name, stats }) => { + const throughputSd = ratioStandardDeviation(1e9, 0, stats?.avg, stats?.sd) + return { + [name]: { + latency: { + value: stats?.avg, + lower_value: stats?.avg - stats?.sd, + upper_value: stats?.avg + stats?.sd, + }, + throughput: { + value: stats?.iters, + lower_value: stats?.iters - throughputSd, + upper_value: stats?.iters + throughputSd, + }, + }, + } + }) + .reduce((obj, item) => Object.assign(obj, item), {}) +} diff --git a/src/reporter/json/index.js b/src/reporter/json/index.js new file mode 100644 index 0000000..4ae2ebd --- /dev/null +++ b/src/reporter/json/index.js @@ -0,0 +1 @@ +export { bmf } from './bmf.js' diff --git a/src/reporter/clr.js b/src/reporter/terminal/clr.js similarity index 100% rename from src/reporter/clr.js rename to src/reporter/terminal/clr.js diff --git a/src/reporter/fmt.js b/src/reporter/terminal/fmt.js similarity index 100% rename from src/reporter/fmt.js rename to src/reporter/terminal/fmt.js diff --git a/src/reporter/terminal/index.js b/src/reporter/terminal/index.js new file mode 100644 index 0000000..ccb544b --- /dev/null +++ b/src/reporter/terminal/index.js @@ -0,0 +1,15 @@ +export { + bold, + dim, + white, +} from './clr.js' +export { + benchmarkError, + benchmarkReport, + br, + header, + size, + summary, + units, + warning, +} from './table.js' diff --git a/src/reporter/table.js b/src/reporter/terminal/table.js similarity index 65% rename from src/reporter/table.js rename to src/reporter/terminal/table.js index ea796c0..a73db69 100644 --- a/src/reporter/table.js +++ b/src/reporter/terminal/table.js @@ -2,9 +2,21 @@ import { highRelativeMarginOfError, tTable, tatamiNgGroup, -} from '../constants.js' -import { checkDividend, ratioStandardDeviation } from '../lib.js' -import * as clr from './clr.js' +} from '../../constants.js' +import { ratioStandardDeviation } from '../../stats-utils.js' +import { checkDividend } from '../../utils.js' +import { + blue, + bold, + cyan, + dim, + gray, + green, + magenta, + red, + white, + yellow, +} from './clr.js' import { duration, errorMargin, itersPerSecond, speedRatio } from './fmt.js' export function size(names) { @@ -28,15 +40,15 @@ export function br({ } export function benchmarkError(name, error, { size, colors = true }) { - return `${name.padEnd(size, ' ')}${clr.red(colors, 'error')}: ${ + return `${name.padEnd(size, ' ')}${red(colors, 'error')}: ${ error.message - }${error.stack ? `\n${clr.gray(colors, error.stack)}` : ''}` + }${error.stack ? `\n${gray(colors, error.stack)}` : ''}` } export function units({ colors = true } = {}) { - return clr.dim( + return dim( colors, - clr.white( + white( colors, ` 1 ps = 1 picosecond = 1e-12s @@ -67,7 +79,7 @@ export function header({ }` } -export function benchmark( +export function benchmarkReport( name, stats, { @@ -83,28 +95,25 @@ export function benchmark( return `${name.padEnd(size, ' ')}${ !avg ? '' - : `${clr.yellow(colors, duration(stats.avg))}`.padStart( - 14 + 10 * colors, - ' ' - ) + : `${yellow(colors, duration(stats.avg))}`.padStart(14 + 10 * colors, ' ') }${ !iters ? '' - : `${clr.yellow(colors, itersPerSecond(stats.iters))}`.padStart( + : `${yellow(colors, itersPerSecond(stats.iters))}`.padStart( 14 + 10 * colors, ' ' ) }${ !rmoe ? '' - : `± ${clr[stats.rmoe > highRelativeMarginOfError ? 'red' : 'blue'](colors, errorMargin(stats.rmoe))}`.padStart( + : `± ${(stats.rmoe > highRelativeMarginOfError ? red : blue)(colors, errorMargin(stats.rmoe))}`.padStart( 14 + 10 * colors, ' ' ) }${ !min_max ? '' - : `(${clr.cyan(colors, duration(stats.min))} … ${clr.magenta( + : `(${cyan(colors, duration(stats.min))} … ${magenta( colors, duration(stats.max) )})`.padStart(24 + 2 * 10 * colors, ' ') @@ -113,14 +122,12 @@ export function benchmark( ? '' : ` ${ stats.mad > 0 - ? `${clr.green(colors, duration(stats.p50))} ± ${clr.red(colors, duration(stats.mad))}`.padStart( + ? `${green(colors, duration(stats.p50))} ± ${red(colors, duration(stats.mad))}`.padStart( 20 + 2 * 10 * colors, ' ' ) - : clr - .green(colors, duration(stats.p50)) - .padStart(20 + 10 * colors, ' ') - } ${clr.green(colors, duration(stats.p75)).padStart(9 + 10 * colors, ' ')} ${clr.green(colors, duration(stats.p99)).padStart(9 + 10 * colors, ' ')} ${clr.green(colors, duration(stats.p995)).padStart(9 + 10 * colors, ' ')}` + : green(colors, duration(stats.p50)).padStart(20 + 10 * colors, ' ') + } ${green(colors, duration(stats.p75)).padStart(9 + 10 * colors, ' ')} ${green(colors, duration(stats.p99)).padStart(9 + 10 * colors, ' ')} ${green(colors, duration(stats.p995)).padStart(9 + 10 * colors, ' ')}` }` } @@ -132,17 +139,17 @@ export function warning(benchmarks, { colors = true }) { for (const benchmark of benchmarks) { if (benchmark.stats.ss === false) { warnings.push( - `${clr.bold(colors, clr.yellow(colors, 'Warning'))}: ${clr.bold(colors, clr.cyan(colors, benchmark.name))} has a sample size below statistical significance: ${clr.red(colors, benchmark.samples)}` + `${bold(colors, yellow(colors, 'Warning'))}: ${bold(colors, cyan(colors, benchmark.name))} has a sample size below statistical significance: ${red(colors, benchmark.samples)}` ) } if (benchmark.stats.rmoe > highRelativeMarginOfError) { warnings.push( - `${clr.bold(colors, clr.yellow(colors, 'Warning'))}: ${clr.bold(colors, clr.cyan(colors, benchmark.name))} has a high relative margin of error: ${clr.red(colors, errorMargin(benchmark.stats.rmoe))}` + `${bold(colors, yellow(colors, 'Warning'))}: ${bold(colors, cyan(colors, benchmark.name))} has a high relative margin of error: ${red(colors, errorMargin(benchmark.stats.rmoe))}` ) } if (benchmark.stats.mad > 0) { warnings.push( - `${clr.bold(colors, clr.yellow(colors, 'Warning'))}: ${clr.bold(colors, clr.cyan(colors, benchmark.name))} has a non zero median absolute deviation: ${clr.red(colors, duration(benchmark.stats.mad))}` + `${bold(colors, yellow(colors, 'Warning'))}: ${bold(colors, cyan(colors, benchmark.name))} has a non zero median absolute deviation: ${red(colors, duration(benchmark.stats.mad))}` ) } } @@ -170,8 +177,8 @@ export function summary(benchmarks, { colors = true }) { return `${`${ baseline.group == null || baseline.group.startsWith(tatamiNgGroup) ? '' - : `${clr.bold(colors, clr.white(colors, baseline.group.trim().split(/\s+/).length > 1 ? `'${baseline.group}'` : `${baseline.group}`))} ` - }${clr.bold(colors, clr.white(colors, 'summary'))}`}\n ${clr.bold(colors, clr.cyan(colors, baseline.name))}${benchmarks + : `${bold(colors, white(colors, baseline.group.trim().split(/\s+/).length > 1 ? `'${baseline.group}'` : `${baseline.group}`))} ` + }${bold(colors, white(colors, 'summary'))}`}\n ${bold(colors, cyan(colors, baseline.name))}${benchmarks .filter(benchmark => benchmark !== baseline) .map(benchmark => { const ratio = benchmark.stats.avg / checkDividend(baseline.stats.avg) @@ -192,12 +199,12 @@ export function summary(benchmarks, { colors = true }) { ] || tTable.infinity const ratioMoe = ratioSem * critical const ratioRmoe = (ratioMoe / checkDividend(ratio)) * 100 - return `\n ${clr[1 > ratio ? 'red' : 'green']( + return `\n ${(1 > ratio ? red : green)( colors, 1 > ratio ? speedRatio(1 / checkDividend(ratio)) : speedRatio(ratio) - )} ± ${clr.blue(colors, errorMargin(ratioRmoe))} times ${ + )} ± ${blue(colors, errorMargin(ratioRmoe))} times ${ 1 > ratio ? 'slower' : 'faster' - } than ${clr.bold(colors, clr.cyan(colors, benchmark.name))}` + } than ${bold(colors, cyan(colors, benchmark.name))}` }) .join('')}` } diff --git a/src/stats-utils.js b/src/stats-utils.js new file mode 100644 index 0000000..22fe0c5 --- /dev/null +++ b/src/stats-utils.js @@ -0,0 +1,69 @@ +import { checkDividend } from './utils.js' + +export const variance = (samples, avg = average(samples)) => { + return ( + samples.reduce((a, b) => a + (b - avg) ** 2, 0) / + checkDividend(samples.length - 1) // Bessel's correction + ) +} + +export const quantileSorted = (samples, q) => { + if (!Array.isArray(samples)) { + throw new TypeError(`expected array, got ${samples.constructor.name}`) + } + if (samples.length === 0) { + throw new Error('expected non-empty array, got empty array') + } + if (q < 0 || q > 1) { + throw new Error('q must be between 0 and 1') + } + if (q === 0) { + return samples[0] + } + if (q === 1) { + return samples[samples.length - 1] + } + const base = (samples.length - 1) * q + const baseIndex = Math.floor(base) + if (samples[baseIndex + 1] != null) { + return ( + samples[baseIndex] + + (base - baseIndex) * (samples[baseIndex + 1] - samples[baseIndex]) + ) + } + return samples[baseIndex] +} + +export const medianSorted = samples => quantileSorted(samples, 0.5) + +export const average = samples => { + if (!Array.isArray(samples)) { + throw new TypeError(`expected array, got ${samples.constructor.name}`) + } + if (samples.length === 0) { + throw new Error('expected non-empty array, got empty array') + } + + return samples.reduce((a, b) => a + b, 0) / samples.length +} + +export const absoluteDeviation = (samples, aggFn) => { + const value = aggFn(samples) + const absoluteDeviations = [] + + for (const sample of samples) { + absoluteDeviations.push(Math.abs(sample - value)) + } + + return aggFn(absoluteDeviations) +} + +// https://en.wikipedia.org/wiki/Propagation_of_uncertainty#Example_formulae +export const ratioStandardDeviation = (avgA, sdA, avgB, sdB) => { + return ( + (avgA / checkDividend(avgB)) * + Math.sqrt( + (sdA / checkDividend(avgA)) ** 2 + (sdB / checkDividend(avgB)) ** 2 + ) + ) +} diff --git a/src/utils.js b/src/utils.js new file mode 100644 index 0000000..2f4e726 --- /dev/null +++ b/src/utils.js @@ -0,0 +1,11 @@ +export const isObject = value => { + return Object.prototype.toString.call(value).slice(8, -1) === 'Object' +} + +export const checkDividend = n => { + if (n == null) throw new TypeError(`Invalid dividend: ${n}`) + if ('number' !== typeof n) + throw new TypeError(`expected number, got ${n.constructor.name}`) + if (n === 0 || Number.isNaN(n)) throw new RangeError(`Invalid dividend: ${n}`) + return n +}