@soroush.tech/bench 0.1.0

package/dist/index.cjs

@@ -0,0 +1,17 @@
+//#region src/index.ts
+/**
+* Validates and freezes a benchmark definition. Authored in a `*.bench.ts`
+* file and `export default`-ed; the `bench` CLI loads that default export
+* inside the pinned container.
+*/
+function defineBench(config) {
+	if (typeof config.name !== "string" || config.name.trim() === "") throw new TypeError("defineBench: `name` must be a non-empty string");
+	const caseEntries = Object.entries(config.cases ?? {});
+	if (caseEntries.length < 2) throw new TypeError("defineBench: `cases` must define at least two cases to compare");
+	for (const [key, fn] of caseEntries) if (typeof fn !== "function") throw new TypeError(`defineBench: case "${key}" must be a function`);
+	for (const [alias, spec] of Object.entries(config.packages ?? {})) if (typeof spec !== "string" || spec.trim() === "") throw new TypeError(`defineBench: package "${alias}" must map to a non-empty install spec`);
+	if (config.warmup !== void 0 && (!Number.isInteger(config.warmup) || config.warmup < 0)) throw new TypeError("defineBench: `warmup` must be a non-negative integer");
+	return Object.freeze({ ...config });
+}
+//#endregion
+module.exports = defineBench;

package/dist/index.d.cts

@@ -0,0 +1,37 @@
+//#region src/index.d.ts
+/**
+ * The context handed to every benchmark case at call time.
+ *
+ * `modules` maps each alias declared in {@link BenchConfig.packages} to its
+ * resolved module namespace. Comparing two versions of the same package is the
+ * reason cases receive their modules here rather than importing at the top
+ * level: Node cannot hold two versions of one bare specifier in a single graph,
+ * so the harness installs each under its alias and injects them.
+ */
+interface BenchContext {
+  modules: Record<string, unknown>;
+}
+/** A single function under test. Receives the {@link BenchContext}. */
+type BenchCase = (ctx: BenchContext) => unknown | Promise<unknown>;
+interface BenchConfig {
+  /** Human label for the comparison; prefixes every case in the report. */
+  name: string;
+  /**
+   * Optional `alias -> npm install spec` map (e.g. `{ v4: 'lodash@4.17.21' }`).
+   * The harness installs each under its alias and exposes it on
+   * `ctx.modules[alias]`, enabling two-or-more-versions-of-one-package runs.
+   */
+  packages?: Record<string, string>;
+  /** The named versions to compare. At least two are required. */
+  cases: Record<string, BenchCase>;
+  /** Warmup iterations before measuring. Defaults to the runner's default. */
+  warmup?: number;
+}
+/**
+ * Validates and freezes a benchmark definition. Authored in a `*.bench.ts`
+ * file and `export default`-ed; the `bench` CLI loads that default export
+ * inside the pinned container.
+ */
+declare function defineBench(config: BenchConfig): Readonly<BenchConfig>;
+//#endregion
+export { BenchCase, BenchConfig, BenchContext, defineBench as default };

package/dist/index.d.mts

@@ -0,0 +1,37 @@
+//#region src/index.d.ts
+/**
+ * The context handed to every benchmark case at call time.
+ *
+ * `modules` maps each alias declared in {@link BenchConfig.packages} to its
+ * resolved module namespace. Comparing two versions of the same package is the
+ * reason cases receive their modules here rather than importing at the top
+ * level: Node cannot hold two versions of one bare specifier in a single graph,
+ * so the harness installs each under its alias and injects them.
+ */
+interface BenchContext {
+  modules: Record<string, unknown>;
+}
+/** A single function under test. Receives the {@link BenchContext}. */
+type BenchCase = (ctx: BenchContext) => unknown | Promise<unknown>;
+interface BenchConfig {
+  /** Human label for the comparison; prefixes every case in the report. */
+  name: string;
+  /**
+   * Optional `alias -> npm install spec` map (e.g. `{ v4: 'lodash@4.17.21' }`).
+   * The harness installs each under its alias and exposes it on
+   * `ctx.modules[alias]`, enabling two-or-more-versions-of-one-package runs.
+   */
+  packages?: Record<string, string>;
+  /** The named versions to compare. At least two are required. */
+  cases: Record<string, BenchCase>;
+  /** Warmup iterations before measuring. Defaults to the runner's default. */
+  warmup?: number;
+}
+/**
+ * Validates and freezes a benchmark definition. Authored in a `*.bench.ts`
+ * file and `export default`-ed; the `bench` CLI loads that default export
+ * inside the pinned container.
+ */
+declare function defineBench(config: BenchConfig): Readonly<BenchConfig>;
+//#endregion
+export { BenchCase, BenchConfig, BenchContext, defineBench as default };

package/dist/index.mjs

@@ -0,0 +1,17 @@
+//#region src/index.ts
+/**
+* Validates and freezes a benchmark definition. Authored in a `*.bench.ts`
+* file and `export default`-ed; the `bench` CLI loads that default export
+* inside the pinned container.
+*/
+function defineBench(config) {
+	if (typeof config.name !== "string" || config.name.trim() === "") throw new TypeError("defineBench: `name` must be a non-empty string");
+	const caseEntries = Object.entries(config.cases ?? {});
+	if (caseEntries.length < 2) throw new TypeError("defineBench: `cases` must define at least two cases to compare");
+	for (const [key, fn] of caseEntries) if (typeof fn !== "function") throw new TypeError(`defineBench: case "${key}" must be a function`);
+	for (const [alias, spec] of Object.entries(config.packages ?? {})) if (typeof spec !== "string" || spec.trim() === "") throw new TypeError(`defineBench: package "${alias}" must map to a non-empty install spec`);
+	if (config.warmup !== void 0 && (!Number.isInteger(config.warmup) || config.warmup < 0)) throw new TypeError("defineBench: `warmup` must be a non-negative integer");
+	return Object.freeze({ ...config });
+}
+//#endregion
+export { defineBench as default };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@soroush.tech/bench",
+  "version": "0.1.0",
+  "description": "Run A/B function and package-version benchmarks inside a CPU/RAM-pinned Docker sandbox for stable, low-noise numbers. Built on mitata.",
+  "keywords": [
+    "benchmark",
+    "benchmarking",
+    "mitata",
+    "performance",
+    "docker",
+    "sandbox",
+    "cpu-pinning",
+    "typescript"
+  ],
+  "author": "Masoud Soroush <masoud@soroush.tech>",
+  "license": "MIT",
+  "homepage": "https://github.com/soroush-tech/soroush.tech/tree/main/packages/bench#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/soroush-tech/soroush.tech.git",
+    "directory": "packages/bench"
+  },
+  "bugs": {
+    "url": "https://github.com/soroush-tech/soroush.tech/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "bench": "./dist/bin.mjs"
+  },
+  "files": [
+    "dist",
+    "Dockerfile"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "types": "./src/index.ts",
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "import": {
+          "types": "./dist/index.d.mts",
+          "default": "./dist/index.mjs"
+        },
+        "require": {
+          "types": "./dist/index.d.cts",
+          "default": "./dist/index.cjs"
+        }
+      }
+    },
+    "main": "./dist/index.cjs",
+    "module": "./dist/index.mjs",
+    "types": "./dist/index.d.mts"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint . --max-warnings 0",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "pnpm build"
+  },
+  "devDependencies": {
+    "@soroush.tech/eslint-config": "workspace:*",
+    "@types/node": "^24.13.2",
+    "@vitest/coverage-v8": "^4.1.9",
+    "eslint": "^10.5.0",
+    "globals": "^17.7.0",
+    "mitata": "^1.0.34",
+    "tsdown": "^0.22.3",
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.9"
+  }
+}