Improvements

Author: corrideat

esbuild.ts

@@ -23,6 +23,7 @@ const buildOptionsBase: esbuild.BuildOptions = {
 	entryPoints: [
 		'./src/index.ts',
 		'./src/stats.ts',
+		'./src/types.ts',
 		'./src/reporters/advanced.ts',
 		'./src/reporters/simple.ts',
 		'./src/reporters/xunit.ts',

package-lock.json

@@ -1,6 +1,6 @@
 {
 	"name": "@apeleghq/benchmark",
-	"version": "1.0.2",
+	"version": "1.0.3",
 	"description": "A statistically rigorous benchmarking library with paired t-tests, baseline correction, and confidence intervals",
 	"type": "module",
 	"main": "./dist/index.cjs",
@@ -27,6 +27,16 @@
 				"default": "./dist/stats.cjs"
 			}
 		},
+		"./types": {
+			"import": {
+				"types": "./dist/types.d.ts",
+				"default": "./dist/types.mjs"
+			},
+			"require": {
+				"types": "./dist/types.d.cts",
+				"default": "./dist/types.cjs"
+			}
+		},
 		"./reporters/advanced": {
 			"import": {
 				"types": "./dist/reporters/advanced.d.ts",

package.json

@@ -0,0 +1,39 @@
+/* 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.
+ */
+
+export class BenchmarkError extends Error {}
+
+export class BenchmarkAbortedError extends BenchmarkError {}
+
+export class BenchmarkDuplicateNameError extends BenchmarkError {}
+
+export class BenchmarkEmptyError extends BenchmarkError {}
+
+export class BenchmarkRunnerError extends BenchmarkError {
+	benchName: string;
+	trial: number;
+
+	constructor(
+		message: string,
+		cause: unknown,
+		benchName: string,
+		trial: number,
+	) {
+		super(message, { cause: cause });
+
+		this.benchName = benchName;
+		this.trial = trial;
+	}
+}

src/errors.ts

@@ -22,13 +22,17 @@ export { generateReport } from './report.js';
 // Stats utilities (for custom consumer-side analysis)
 export * as stats from './stats.js';
 
+// Error types
+export * from './errors.js';
+
 // Types
 export { NULL_FUNCTION_NAME } from './types.js';
 export type {
 	ContextFn,
 	IBenchmarkFn,
 	IFunctionStatistics,
 	IPairedComparison,
+	IRunProgress,
 	ISuiteConfig,
 	ISuiteReport,
 	ITrialMeasurement,

src/index.ts

@@ -48,7 +48,7 @@ function computeFunctionStats(
 	const n = samples.length;
 	const sd = stats.stdDev(samples);
 	const se = stats.sem(samples);
-	const tCrit = stats.tCritical005TwoTailed(Math.max(n - 1, 1));
+	const tCrit = stats.tQuantile975(Math.max(n - 1, 1));
 
 	return {
 		name,
@@ -97,7 +97,7 @@ function computePairedComparison(
 
 	const tStat = seD > 0 ? meanD / seD : 0;
 	const pValue = seD > 0 ? stats.tDistPValue(tStat, df) : 1;
-	const tCrit = stats.tCritical005TwoTailed(df);
+	const tCrit = stats.tQuantile975(df);
 
 	const meanBadj = stats.mean(adjB);
 

src/report.ts

@@ -13,6 +13,12 @@
  * limitations under the License.
  */
 
+import {
+	BenchmarkAbortedError,
+	BenchmarkDuplicateNameError,
+	BenchmarkEmptyError,
+	BenchmarkRunnerError,
+} from './errors.js';
 import { generateReport } from './report.js';
 import type {
 	IBenchmarkFn,
@@ -21,20 +27,11 @@ import type {
 	ITrialMeasurement,
 	ITrialResult,
 } from './types.js';
-import { NULL_FUNCTION_NAME } from './types.js';
+import { IRunProgress, NULL_FUNCTION_NAME } from './types.js';
+import { shuffled } from './utils.js';
 
 // ── Helpers ─────────────────────────────────────────────────────────────
 
-/** Fisher-Yates shuffle (returns a new array). */
-function shuffled<T>(array: readonly T[]): T[] {
-	const out = [...array];
-	for (let i = out.length - 1; i > 0; i--) {
-		const j = Math.floor(Math.random() * (i + 1));
-		[out[i], out[j]] = [out[j], out[i]];
-	}
-	return out;
-}
-
 /** Invoke an optional sync-or-async callback with a `this` context. */
 async function invoke<TC extends object, TA extends unknown[] = never[]>(
 	fn: ((this: TC, ...args: TA) => unknown | PromiseLike<unknown>) | undefined,
@@ -86,7 +83,9 @@ async function measureTime<TC extends object>(
 		)
 			await r;
 	}
-	return performance.now() - start;
+	const end = performance.now();
+
+	return end - start;
 }
 
 // ── Suite ───────────────────────────────────────────────────────────────
@@ -142,20 +141,28 @@ export class Suite<TC extends object = Record<string, unknown>, TR = unknown> {
 	/** Register a benchmark function.  Returns `this` for chaining. */
 	add(fn: IBenchmarkFn<TC, TR>): this {
 		if (this._fns.some((f) => f.name === fn.name)) {
-			throw new Error(`Duplicate benchmark name: "${fn.name}"`);
+			throw new BenchmarkDuplicateNameError(
+				`Duplicate benchmark name: "${fn.name}"`,
+			);
 		}
 		this._fns.push(fn);
 		return this;
 	}
 
 	/** Execute all trials and return a {@link ISuiteReport}. */
-	async run(): Promise<ISuiteReport> {
+	async run(opts?: {
+		eventTarget?: EventTarget;
+		signal?: AbortSignal;
+	}): Promise<ISuiteReport> {
 		if (this._fns.length === 0) {
-			throw new Error(
+			throw new BenchmarkEmptyError(
 				'Suite has no benchmark functions — call .add() before .run()',
 			);
 		}
 
+		const eventTarget = opts?.eventTarget;
+		const signal = opts?.signal;
+
 		// Inject the null baseline — an empty function that captures the
 		// overhead of the measurement loop (call dispatch, thenable check,
 		// loop counter).  It participates in shuffling like every other
@@ -176,44 +183,70 @@ export class Suite<TC extends object = Record<string, unknown>, TR = unknown> {
 			const measurements: Record<string, ITrialMeasurement> = {};
 
 			for (const bench of order) {
-				if (
-					bench.name !== NULL_FUNCTION_NAME &&
-					(this._suiteValidate || bench.setup)
-				) {
-					const validateCtx = {} as TC;
-					await invoke(
-						this._suiteValidate,
-						validateCtx,
-						bench.fn as IBenchmarkFn<TC, TR>['fn'],
+				try {
+					if (signal?.aborted) {
+						throw new BenchmarkAbortedError('Aborted');
+					}
+					if (eventTarget) {
+						eventTarget.dispatchEvent(
+							new CustomEvent<IRunProgress>('progress', {
+								detail: {
+									trial: t + 1,
+									totalTrials: this._trials,
+									currentFunction: bench.name,
+								},
+							}),
+						);
+						// Allow event to propagate
+						await new Promise((resolve) => setTimeout(resolve, 0));
+					}
+
+					if (
+						bench.name !== NULL_FUNCTION_NAME &&
+						(this._suiteValidate || bench.setup)
+					) {
+						const validateCtx = {} as TC;
+						await invoke(
+							this._suiteValidate,
+							validateCtx,
+							bench.fn as IBenchmarkFn<TC, TR>['fn'],
+						);
+						await invoke(
+							bench.validate,
+							validateCtx,
+							bench.fn as IBenchmarkFn<TC, TR>['fn'],
+						);
+					}
+
+					const ctx = {} as TC;
+					await invoke(this._suiteSetup, ctx);
+					await invoke(bench.setup, ctx);
+
+					const totalMs = await measureTime(
+						bench.fn,
+						ctx,
+						this._warmup,
+						this._iterations,
 					);
-					await invoke(
-						bench.validate,
-						validateCtx,
-						bench.fn as IBenchmarkFn<TC, TR>['fn'],
+
+					await invoke(bench.teardown, ctx);
+					await invoke(this._suiteTeardown, ctx);
+
+					executionOrder.push(bench.name);
+					measurements[bench.name] = {
+						name: bench.name,
+						totalMs,
+						iterations: this._iterations,
+						perIterationMs: totalMs / this._iterations,
+					};
+				} catch (e) {
+					throw new BenchmarkRunnerError(
+						`Error in ${bench.name}`,
+						e,
+						bench.name,
+						t,
 					);
 				}
-
-				const ctx = {} as TC;
-				await invoke(this._suiteSetup, ctx);
-				await invoke(bench.setup, ctx);
-
-				const totalMs = await measureTime(
-					bench.fn,
-					ctx,
-					this._warmup,
-					this._iterations,
-				);
-
-				await invoke(bench.teardown, ctx);
-				await invoke(this._suiteTeardown, ctx);
-
-				executionOrder.push(bench.name);
-				measurements[bench.name] = {
-					name: bench.name,
-					totalMs,
-					iterations: this._iterations,
-					perIterationMs: totalMs / this._iterations,
-				};
 			}
 
 			trials.push({ trialIndex: t, executionOrder, measurements });
@@ -243,10 +276,14 @@ export async function runSuite<
 	TC extends object = Record<string, unknown>,
 	TR = unknown,
 >(
-	config: ISuiteConfig<TC, TR> & { functions: IBenchmarkFn<TC, TR>[] },
+	config: ISuiteConfig<TC, TR> & {
+		functions: IBenchmarkFn<TC, TR>[];
+		eventTarget?: EventTarget;
+		signal?: AbortSignal;
+	},
 ): Promise<ISuiteReport> {
-	const { functions, ...suiteConfig } = config;
+	const { functions, eventTarget, signal, ...suiteConfig } = config;
 	const suite = new Suite<TC, TR>(suiteConfig);
 	for (const fn of functions) suite.add(fn);
-	return suite.run();
+	return suite.run({ eventTarget, signal });
 }