Various improvements

* Support for parameters
* Better types
* Re-designed validation to run once

Author: corrideat

example/params.ts

@@ -0,0 +1,47 @@
+/* Copyright © 2026 Apeleg Limited. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License") with LLVM
+ * exceptions; you may not use this file except in compliance with the
+ * License. You may obtain a copy of the License at
+ *
+ * http://llvm.org/foundation/relicensing/LICENSE.txt
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { deepEqual, notEqual } from 'node:assert/strict';
+import { runSuite } from '../src/index.js';
+
+type Ctx = {
+	array: unknown[];
+};
+
+const result = await runSuite<Ctx, Ctx['array'], [dep1: number, dep2: string]>({
+	name: 'Array shallow copying',
+	args: [1, 'a'],
+	setup() {
+		this.array = [1, 2, 3];
+	},
+	validate(fn) {
+		this.array = [6, 7, 8];
+		const result = fn.call(this, 1, 'a');
+		notEqual(result, this.array);
+		deepEqual(result, this.array);
+	},
+	functions: [
+		{
+			name: 'Array.from',
+			fn(dep1, dep2) {
+				dep1.toExponential(1);
+				dep2.toLowerCase();
+				return Array.from(this.array);
+			},
+		},
+	],
+});
+
+console.log(result);

package-lock.json

@@ -1,6 +1,6 @@
 {
 	"name": "@apeleghq/benchmark",
-	"version": "1.0.4",
+	"version": "1.0.5",
 	"description": "A statistically rigorous benchmarking library with paired t-tests, baseline correction, and confidence intervals",
 	"type": "module",
 	"main": "./dist/index.cjs",

package.json

@@ -37,6 +37,7 @@ export type {
 	ISuiteReport,
 	ITrialMeasurement,
 	ITrialResult,
+	SuiteConfig,
 } from './types.js';
 
 export * from './reporters/index.js';

src/index.ts

@@ -29,7 +29,7 @@ import type {
  */
 function getBaselineSamples(
 	baselineName: string,
-	trials: ITrialResult[],
+	trials: readonly Readonly<ITrialResult>[],
 ): number[] {
 	return trials.map((t) => t.measurements[baselineName].perIterationMs);
 }
@@ -38,8 +38,8 @@ function getBaselineSamples(
 
 function computeFunctionStats(
 	name: string,
-	trials: ITrialResult[],
-	baselineSamples: number[],
+	trials: readonly Readonly<ITrialResult>[],
+	baselineSamples: readonly number[],
 ): IFunctionStatistics {
 	const rawSamples = trials.map((t) => t.measurements[name].perIterationMs);
 	// Subtract the null-function time measured in the *same* trial
@@ -74,8 +74,8 @@ function computeFunctionStats(
 function computePairedComparison(
 	nameA: string,
 	nameB: string,
-	trials: ITrialResult[],
-	baselineSamples: number[],
+	trials: readonly Readonly<ITrialResult>[],
+	baselineSamples: readonly number[],
 ): IPairedComparison {
 	// Use baseline-corrected values so that relativeDifference reflects
 	// actual computation time, not measurement overhead.
@@ -121,7 +121,7 @@ export function generateReport(
 	name: string,
 	config: ISuiteReport['config'],
 	trials: ITrialResult[],
-	functionNames: string[],
+	functionNames: readonly string[],
 	baselineName: string,
 ): ISuiteReport {
 	const baselineSamples = getBaselineSamples(baselineName, trials);

src/report.ts

@@ -121,7 +121,7 @@ function csig(p: number): string {
 }
 
 /** Coefficient of variation as a percentage. */
-function cvPct(f: IFunctionStatistics): number {
+function cvPct(f: Readonly<IFunctionStatistics>): number {
 	return f.mean > 0 ? (f.stdDev / f.mean) * 100 : 0;
 }
 
@@ -157,7 +157,7 @@ function tpBar(ratio: number, w: number, rank: number): string {
  * Mini sparkline histogram of the sample distribution.
  * Bins are rendered with Unicode block elements ▁–█.
  */
-function sparkline(samples: number[], w: number = 18): string {
+function sparkline(samples: readonly number[], w: number = 18): string {
 	if (samples.length < 2) return '';
 	const sorted = [...samples].sort((a, b) => a - b);
 	const min = sorted[0];
@@ -193,7 +193,7 @@ function sparkline(samples: number[], w: number = 18): string {
  * - Median: bold white `│`
  */
 function miniBox(
-	f: IFunctionStatistics,
+	f: Readonly<IFunctionStatistics>,
 	lo: number,
 	hi: number,
 	w: number = 32,
@@ -255,7 +255,7 @@ function secLine(label: string, totalW: number = 76): string {
 //  Sections
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-function renderHeader(suite: ISuiteReport): string[] {
+function renderHeader(suite: Readonly<ISuiteReport>): string[] {
 	const L: string[] = [];
 	const { config } = suite;
 
@@ -296,8 +296,8 @@ function renderHeader(suite: ISuiteReport): string[] {
 // ─── Winner announcement ─────────────────────────────────────────────────────
 
 function renderWinner(
-	fns: IFunctionStatistics[],
-	comps: IPairedComparison[],
+	fns: readonly Readonly<IFunctionStatistics>[],
+	comps: readonly Readonly<IPairedComparison>[],
 ): string[] {
 	if (fns.length < 2) return [];
 
@@ -353,7 +353,9 @@ function renderWinner(
 
 // ─── Leaderboard ─────────────────────────────────────────────────────────────
 
-function renderLeaderboard(fns: IFunctionStatistics[]): string[] {
+function renderLeaderboard(
+	fns: readonly Readonly<IFunctionStatistics>[],
+): string[] {
 	const L: string[] = [];
 	const fastest = fns[0];
 
@@ -440,7 +442,9 @@ function renderLeaderboard(fns: IFunctionStatistics[]): string[] {
 
 // ─── Distribution (box plots + sparklines) ───────────────────────────────────
 
-function renderDistribution(fns: IFunctionStatistics[]): string[] {
+function renderDistribution(
+	fns: readonly Readonly<IFunctionStatistics>[],
+): string[] {
 	const L: string[] = [];
 
 	L.push(secLine('Distribution'));
@@ -498,7 +502,9 @@ function renderDistribution(fns: IFunctionStatistics[]): string[] {
 
 // ─── Detailed statistics table ───────────────────────────────────────────────
 
-function renderDetailedStats(fns: IFunctionStatistics[]): string[] {
+function renderDetailedStats(
+	fns: readonly Readonly<IFunctionStatistics>[],
+): string[] {
 	const L: string[] = [];
 
 	L.push(secLine('Detailed Statistics'));
@@ -552,13 +558,13 @@ function renderDetailedStats(fns: IFunctionStatistics[]): string[] {
 // ─── Pairwise comparisons ────────────────────────────────────────────────────
 
 function renderComparisons(
-	fns: IFunctionStatistics[],
-	comps: IPairedComparison[],
+	fns: readonly Readonly<IFunctionStatistics>[],
+	comps: readonly Readonly<IPairedComparison>[],
 ): string[] {
 	if (comps.length === 0) return [];
 
 	const L: string[] = [];
-	const byName: Record<string, IFunctionStatistics> = {};
+	const byName: Record<string, Readonly<IFunctionStatistics>> = {};
 	for (const f of fns) byName[f.name] = f;
 
 	L.push(secLine('Pairwise Comparisons (paired t-test)'));
@@ -630,8 +636,8 @@ function renderComparisons(
 // ─── Speed matrix ────────────────────────────────────────────────────────────
 
 function renderMatrix(
-	fns: IFunctionStatistics[],
-	comps: IPairedComparison[],
+	fns: readonly Readonly<IFunctionStatistics>[],
+	comps: readonly Readonly<IPairedComparison>[],
 ): string[] {
 	// Only render for a reasonable number of functions
 	if (fns.length < 3 || fns.length > 8) return [];
@@ -713,8 +719,8 @@ function renderMatrix(
 // ─── Measurement overhead / baseline ─────────────────────────────────────────
 
 function renderBaseline(
-	baseline: IFunctionStatistics | undefined,
-	fastest: IFunctionStatistics,
+	baseline: Readonly<IFunctionStatistics> | undefined,
+	fastest: Readonly<IFunctionStatistics>,
 ): string[] {
 	if (!baseline) return [];
 
@@ -812,7 +818,7 @@ function renderFooter(): string[] {
  * | Speed matrix         | Developers (3-8 fns)  |
  * | Measurement overhead | Advanced users        |
  */
-export function formatReport(suite: ISuiteReport): string {
+export function formatReport(suite: Readonly<ISuiteReport>): string {
 	// ── Separate baseline from benchmarks, sort fastest → slowest ──────
 	const baseline = suite.functions.find((f) => f.name === suite.baselineName);
 	const fns = suite.functions
@@ -851,7 +857,10 @@ export interface IReporterOptions {
 	output?: (s: string) => void;
 }
 
-function printReport(suite: ISuiteReport, opts?: IReporterOptions): void {
+function printReport(
+	suite: Readonly<ISuiteReport>,
+	opts?: Readonly<IReporterOptions>,
+): void {
 	const out =
 		opts?.output ??
 		(console.log as Exclude<IReporterOptions['output'], undefined>);

src/reporters/advanced.ts

@@ -15,3 +15,4 @@
 
 export { default as advanced } from './advanced.js';
 export { default as simple } from './simple.js';
+export { default as xunit } from './xunit.js';

src/reporters/index.ts

@@ -58,7 +58,10 @@ export interface IReporterOptions {
  * - A bar chart and paired-comparison table are shown when there
  *   are two or more user functions.
  */
-function report(suite: ISuiteReport, opts?: IReporterOptions): void {
+function report(
+	suite: Readonly<ISuiteReport>,
+	opts?: Readonly<IReporterOptions>,
+): void {
 	const out =
 		opts?.output ??
 		(console.log as Exclude<IReporterOptions['output'], undefined>);
@@ -145,7 +148,10 @@ function report(suite: ISuiteReport, opts?: IReporterOptions): void {
 /*  Section renderers                                                  */
 /* ================================================================== */
 
-function emitHeader(ln: (s?: string) => void, suite: ISuiteReport): void {
+function emitHeader(
+	ln: (s?: string) => void,
+	suite: Readonly<ISuiteReport>,
+): void {
 	const { config: c } = suite;
 	ln(`  ${pc.bold(pc.cyan(suite.name))}`);
 	ln(
@@ -162,9 +168,9 @@ function emitHeader(ln: (s?: string) => void, suite: ISuiteReport): void {
 
 function emitTable(
 	ln: (s?: string) => void,
-	fns: IFunctionStatistics[],
-	fastest: IFunctionStatistics,
-	unit: Unit,
+	fns: readonly Readonly<IFunctionStatistics>[],
+	fastest: Readonly<IFunctionStatistics>,
+	unit: Readonly<Unit>,
 	showRel: boolean,
 ): void {
 	const nameW = Math.max(...fns.map((f) => f.name.length));
@@ -213,9 +219,9 @@ function emitTable(
 
 function emitChart(
 	ln: (s?: string) => void,
-	fns: IFunctionStatistics[],
-	fastest: IFunctionStatistics,
-	unit: Unit,
+	fns: readonly Readonly<IFunctionStatistics>[],
+	fastest: Readonly<IFunctionStatistics>,
+	unit: Readonly<Unit>,
 	W: number,
 ): void {
 	const nameW = Math.max(...fns.map((f) => f.name.length));
@@ -245,9 +251,9 @@ function emitChart(
 
 function emitComparisons(
 	ln: (s?: string) => void,
-	comps: IPairedComparison[],
-	fastest: IFunctionStatistics,
-	unit: Unit,
+	comps: readonly Readonly<IPairedComparison>[],
+	fastest: Readonly<IFunctionStatistics>,
+	unit: Readonly<Unit>,
 	W: number,
 ): void {
 	ln(`  ${pc.bold('Comparisons')} ${pc.dim('(paired t-test, α = 0.05)')}`);
@@ -296,8 +302,8 @@ function emitComparisons(
 
 function emitBaseline(
 	ln: (s?: string) => void,
-	baseline: IFunctionStatistics,
-	unit: Unit,
+	baseline: Readonly<IFunctionStatistics>,
+	unit: Readonly<Unit>,
 ): void {
 	const raw = baseline.rawSamples;
 	const avg = mean(raw);

src/reporters/simple.ts

@@ -34,7 +34,7 @@ const escapeXml = (s: string) => {
 };
 
 const safeXml = (
-	template: TemplateStringsArray,
+	template: Readonly<TemplateStringsArray>,
 	...substitutions: unknown[]
 ): string => {
 	const escapedSubstitutions = substitutions.map((substitution) =>
@@ -71,7 +71,7 @@ const sign = (n: number): string => (n >= 0 ? '+' : '');
 
 // ── <system-out> plain-text summaries ───────────────────────────────────
 
-function fnSummaryText(f: IFunctionStatistics): string {
+function fnSummaryText(f: Readonly<IFunctionStatistics>): string {
 	return [
 		safeXml`Benchmark: ${f.name}`,
 		safeXml``,
@@ -88,7 +88,7 @@ function fnSummaryText(f: IFunctionStatistics): string {
 	].join('\n');
 }
 
-function cmpSummaryText(c: IPairedComparison): string {
+function cmpSummaryText(c: Readonly<IPairedComparison>): string {
 	const dir =
 		c.meanDifference > 0
 			? 'slower than'
@@ -125,7 +125,7 @@ function cmpSummaryText(c: IPairedComparison): string {
  */
 function buildFnCase(
 	suite: string,
-	f: IFunctionStatistics,
+	f: Readonly<IFunctionStatistics>,
 	wallClockMs: number,
 ): string {
 	return [
@@ -166,7 +166,7 @@ function buildFnCase(
  *
  * All t-test fields land in `vendor:benchmark.*` with full precision.
  */
-function buildCmpCase(suite: string, c: IPairedComparison): string {
+function buildCmpCase(suite: string, c: Readonly<IPairedComparison>): string {
 	return [
 		safeXml`    <testcase name="${c.a + ' vs ' + c.b}" classname="${suite + '.comparisons'}" time="0">`,
 		safeXml`      <properties>`,
@@ -214,7 +214,7 @@ function buildCmpCase(suite: string, c: IPairedComparison): string {
  * `vendor:benchmark.*` `<property>` elements with full JS numeric
  * precision (lossless IEEE-754 round-trip via default `toString`).
  */
-function formatJUnitXml(report: ISuiteReport): string {
+function formatJUnitXml(report: Readonly<ISuiteReport>): string {
 	const timestamp = new Date().toISOString();
 
 	// ── Pre-compute per-function wall-clock totals from trial data ──