@bejibun/storage 0.1.1 → 0.1.11

package/CHANGELOG.md

@@ -3,6 +3,51 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [v0.1.11](https://github.com/Bejibun-Framework/bejibun-storage/compare/v0.1.1...v0.1.11) - 2026-09-04
+
+### 🩹 Fixes
+- Fixed `StorageBuilder.missing` which used a double negation (`!(await driver.missing(...))`) and therefore returned `exists` instead of the correct "missing" result
+
+### 📖 Changes
+#### Performance
+- `StorageBuilder` now loads and caches the storage config once via a lazy `loadConfig()` (module-level `cachedConfig`), instead of reading `storage.ts` from disk with `fs.existsSync` + `require()` on every `new StorageBuilder()`
+- Replaced the `@bejibun/utils` `defineValue`/`isEmpty` calls with native nullish coalescing (`??`) and truthiness checks in `StorageBuilder`, `StorageLocalBuilder`, and `StorageS3Builder`
+- `StorageLocalBuilder` caches the resolved `root` once (validated in the constructor) and resolves paths through a single helper instead of re-validating on every operation
+- `StorageS3Builder` validates the required S3 fields once in the constructor and reuses the plain config, instead of re-running the validation getter on every access
+
+#### Docs
+- Added missing `@returns` annotations (with descriptions) to every `Storage` facade method, matching the cache and limiter facade style; aligned the `@param`/`@returns` JSDoc format with the sibling packages
+- Re-exported the `StorageException` classes from the package root (`@/exceptions/index`) for consistency with the cache and limiter entry points
+- Standardized `StorageBuilder` config handling to the same lazy `loadConfig()` pattern used by `CacheBuilder`
+
+### 🧪 Tests
+- Added unit test suite (17 tests across 1 file in `tests/unit`) covering `StorageBuilder` input validation (empty path/content/source/destination rejections across `exists`, `missing`, `metadata`, `size`, `mimeType`, `lastModified`, `get`, `put`, `copy`, `move`, `delete`) and the `Storage` facade delegation, with silenced logger output
+- Added an integration test suite (7 tests across 1 file in `tests/integration`) exercising the real local disk driver end to end against a temporary directory: `put`/`exists`/`missing`/`size`/`get`, `metadata`/`lastModified`, `copy`, `move`, and `delete`
+- Added `test` (unit) and `test:integration` scripts and added `tests` to tsconfig `exclude` so compiled output never lands in `tests/`
+
+### ⚡ Benchmarks
+- Added benchmark suite comparing baseline (`@bejibun/storage@0.1.1`) vs the optimized build, covering `construction`, `exists`, `get`, and `delete` hot paths against a temporary local disk; full results are written to `benchmarks/README.md` between the `BENCHMARK` markers
+- Also added a cold-start suite spawning 30 fresh OS processes per variant and measuring full process time and import time
+- Throughput results on the local disk backend: `construction` **26.64x** (40.0 vs 1.5ms, ~13.3M ops/s), `exists` 1.85x (117.2 vs 63.2ms), `get` 3.50x (74.7 vs 21.3ms), `delete` ~1.03x (3896.7 vs 3775.0ms, I/O bound); cold start ~1.02x
+
+### 📦 Dependencies
+
+- Bumped [`@bejibun/app`](https://github.com/Bejibun-Framework/bejibun-app) from `^0.1.25` to `^0.1.26`
+- Bumped [`@bejibun/logger`](https://github.com/Bejibun-Framework/bejibun-logger) from `^0.1.23` to `^0.2.1`
+- Bumped [`@bejibun/utils`](https://github.com/Bejibun-Framework/bejibun-utils) from `^0.1.29` to `^0.1.30`
+- Bumped `@types/bun` (devDependency) from `^1.3.14` to `^1.4.0`
+- Bumped `eslint` (devDependency) from `^10.8.1` to `^10.9.1`
+- Bumped `globals` (devDependency) from `^17.11.0` to `^17.12.0`
+- Bumped `tsc-alias` (devDependency) from `^1.9.2` to `^1.9.4`
+- Bumped `typescript-eslint` (devDependency) from `^8.67.0` to `^8.69.0`
+
+### ❤️Contributors
+- Havea Crenata ([@crenata](https://github.com/crenata))
+
+**Full Changelog**: https://github.com/Bejibun-Framework/bejibun-storage/blob/master/CHANGELOG.md
+
+---
+
 ## [v0.1.1](https://github.com/Bejibun-Framework/bejibun-storage/compare/v0.1.0...v0.1.1) - 2026-08-20
 
 ### 🩹 Fixes

package/benchmarks/README.md

@@ -0,0 +1,46 @@
+# Benchmarks
+
+Speed comparison: baseline (previously published npm release `@bejibun/storage@0.1.1`) vs the optimized `@bejibun/storage` in this repo.
+
+## Running
+
+```bash
+# Run all benchmarks (installs baseline from npm first)
+bun run bench
+
+# Or run individually (after install-deps)
+bun run install-deps
+bun run coldstart
+bun run throughput
+```
+
+## Cold Start
+
+Measures package import time by spawning fresh OS processes. Two metrics:
+
+- **Full process time** — spawn → exit (includes Bun boot time)
+- **Import** — measured inside the process, isolates the package's own import cost
+
+<!-- BENCHMARK:COLDSTART:START -->
+
+|                             | baseline | optimized | speedup   |
+| --------------------------- | -------- | --------- | --------- |
+| Full process (spawn → exit) | 23.1ms   | 21.5ms    | **1.07x** |
+| Import                      | 15.3ms   | 14.1ms    | **1.09x** |
+
+<!-- BENCHMARK:COLDSTART:END -->
+
+## Throughput
+
+The hot paths touched on every storage operation. `construction` covers `new StorageBuilder()` plus config resolution (no disk I/O). `exists`, `get`, and `delete` run the full facade against a temporary local disk. 20,000 calls each, median of 9 runs.
+
+<!-- BENCHMARK:THROUGHPUT:START -->
+
+| Method         | baseline (0.1.1) | optimized | speedup    | baseline ops/s | optimized ops/s |
+| -------------- | ---------------- | --------- | ---------- | -------------- | --------------- |
+| `construction` | 35.0ms           | 1.5ms     | **22.90x** | 571,510/s      | 13,086,855/s    |
+| `exists`       | 88.7ms           | 52.9ms    | **1.68x**  | 225,468/s      | 377,841/s       |
+| `get`          | 54.4ms           | 15.3ms    | **3.54x**  | 367,796/s      | 1,303,802/s     |
+| `delete`       | 3320.7ms         | 3226.3ms  | **1.03x**  | 6,023/s        | 6,199/s         |
+
+<!-- BENCHMARK:THROUGHPUT:END -->

package/benchmarks/package.json

@@ -0,0 +1,12 @@
+{
+    "name": "@bejibun/storage-benchmarks",
+    "private": true,
+    "type": "module",
+    "description": "Speed comparison: baseline (previously published npm release) vs the optimized @bejibun/storage in this repo. Run with `bun run`.",
+    "scripts": {
+        "install-deps": "bun install --cwd .. --no-save \"@bejibun-baseline/storage@npm:@bejibun/storage@0.1.1\"",
+        "coldstart": "bun run scripts/coldstart.mjs && prettier --write . --log-level=silent",
+        "throughput": "bun run scripts/throughput.mjs && prettier --write . --log-level=silent",
+        "bench": "bun run install-deps && bun run coldstart && bun run throughput"
+    }
+}

package/benchmarks/scripts/coldstart-baseline.mjs

@@ -0,0 +1,9 @@
+const realLog = console.log;
+console.log = () => {};
+
+const t0 = performance.now();
+await import("@bejibun-baseline/storage");
+const t1 = performance.now();
+
+console.log = realLog;
+process.stderr.write(String(t1 - t0));

package/benchmarks/scripts/coldstart-optimized.mjs

@@ -0,0 +1,9 @@
+const realLog = console.log;
+console.log = () => {};
+
+const t0 = performance.now();
+await import("../../index.js");
+const t1 = performance.now();
+
+console.log = realLog;
+process.stderr.write(String(t1 - t0));

package/benchmarks/scripts/coldstart.mjs

@@ -0,0 +1,93 @@
+/**
+ * Cold-start benchmark.
+ *
+ * Spawns a brand new OS process per trial for each variant (baseline vs optimized) and
+ * measures the full process time (spawn -> exit) and the import time of the package.
+ *
+ * Run: bun run scripts/coldstart.mjs
+ */
+import {spawnSync} from "node:child_process";
+import {fileURLToPath} from "node:url";
+import path from "node:path";
+import {printTable} from "./table-format.mjs";
+import {updateReadmeSection} from "./readme-writer.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TRIALS = 30;
+const runtime = process.execPath;
+
+function runTrials(scriptPath) {
+    const times = [];
+    for (let i = 0; i < TRIALS; i++) {
+        const t0 = performance.now();
+        const res = spawnSync(runtime, [scriptPath], {encoding: "utf8"});
+        const wallTime = performance.now() - t0;
+        if (res.status !== 0) {
+            console.error("Benchmark failed:", res.stderr);
+            process.exit(1);
+        }
+        const internalTime = parseFloat(res.stderr.trim());
+        times.push({wallTime, internalTime});
+    }
+    return times;
+}
+
+function stats(arr) {
+    const sorted = [...arr].sort((a, b) => a - b);
+    const sum = arr.reduce((a, b) => a + b, 0);
+    return {
+        min: sorted[0],
+        median: sorted[Math.floor(sorted.length / 2)],
+        mean: sum / arr.length
+    };
+}
+
+const baseline = runTrials(path.join(__dirname, "coldstart-baseline.mjs"));
+const optimized = runTrials(path.join(__dirname, "coldstart-optimized.mjs"));
+
+const baseWall = stats(baseline.map((t) => t.wallTime));
+const optWall = stats(optimized.map((t) => t.wallTime));
+const baseInt = stats(baseline.map((t) => t.internalTime));
+const optInt = stats(optimized.map((t) => t.internalTime));
+
+function fmt(ms) {
+    return ms < 1 ? `${(ms * 1000).toFixed(0)}\u00B5s` : `${ms.toFixed(1)}ms`;
+}
+
+function sp(b, o) {
+    const r = b / o;
+    return r >= 1.05 ? `${r.toFixed(2)}x` : r <= 0.95 ? `${r.toFixed(2)}x` : "~1.0x";
+}
+
+printTable({
+    title: "COLD START BENCHMARK",
+    subtitle: `${TRIALS} fresh process spawns per variant`,
+    headers: ["Metric", "Baseline (0.1.1)", "Optimized", "Speedup"],
+    rows: [
+        {
+            cells: [
+                "Full process (spawn \u2192 exit)",
+                fmt(baseWall.median),
+                fmt(optWall.median),
+                sp(baseWall.median, optWall.median)
+            ]
+        },
+        {
+            cells: [
+                "Import",
+                fmt(baseInt.median),
+                fmt(optInt.median),
+                sp(baseInt.median, optInt.median)
+            ]
+        }
+    ]
+});
+
+const table = [
+    "| | baseline | optimized | speedup |",
+    "|---|---|---|---|",
+    `| Full process (spawn → exit) | ${baseWall.median.toFixed(1)}ms | ${optWall.median.toFixed(1)}ms | **${(baseWall.median / optWall.median).toFixed(2)}x** |`,
+    `| Import | ${baseInt.median.toFixed(1)}ms | ${optInt.median.toFixed(1)}ms | **${(baseInt.median / optInt.median).toFixed(2)}x** |`
+].join("\n");
+
+updateReadmeSection("COLDSTART", table);

package/benchmarks/scripts/readme-writer.mjs

@@ -0,0 +1,35 @@
+/**
+ * Writes benchmark output directly into ../README.md between a pair of HTML comment
+ * markers, so results never have to be hand-copied. Everything outside the markers
+ * (headings, explanatory prose) is left untouched.
+ *
+ *   <!-- BENCHMARK:NAME:START -->
+ *   ...replaced on every run...
+ *   <!-- BENCHMARK:NAME:END -->
+ */
+import {readFileSync, writeFileSync} from "node:fs";
+import {fileURLToPath} from "node:url";
+import path from "node:path";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const README_PATH = path.join(__dirname, "..", "README.md");
+
+export function updateReadmeSection(marker, markdown) {
+    const start = `<!-- BENCHMARK:${marker}:START -->`;
+    const end = `<!-- BENCHMARK:${marker}:END -->`;
+
+    const readme = readFileSync(README_PATH, "utf8");
+    const startIdx = readme.indexOf(start);
+    const endIdx = readme.indexOf(end);
+
+    if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) {
+        console.warn(
+            `README markers for "${marker}" not found in ${README_PATH} -- skipping README update.`
+        );
+        return;
+    }
+
+    const before = readme.slice(0, startIdx + start.length);
+    const after = readme.slice(endIdx);
+    writeFileSync(README_PATH, `${before}\n${markdown}\n${after}`);
+}

package/benchmarks/scripts/table-format.mjs

@@ -0,0 +1,123 @@
+/**
+ * Simple bordered console table for benchmark output.
+ *
+ * Uses box-drawing characters for a clean, readable look.
+ * Supports optional section headers between rows.
+ */
+
+const C = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    cyan: "\x1b[36m",
+    white: "\x1b[37m"
+};
+
+const B = {
+    TL: "\u250C",
+    TR: "\u2510",
+    BL: "\u2514",
+    BR: "\u2518",
+    H: "\u2500",
+    V: "\u2502",
+    TD: "\u252C",
+    TU: "\u2534",
+    TR2: "\u251C",
+    TL2: "\u2524",
+    X: "\u253C"
+};
+
+function line(widths, left, mid, right) {
+    return left + widths.map((w) => B.H.repeat(w + 2)).join(mid) + right;
+}
+
+function p(str, n, align) {
+    str = String(str);
+    return align === "left" ? str.padEnd(n) : str.padStart(n);
+}
+
+function displayValue(val, isSpeedup) {
+    if (val === "---") return {text: val, color: C.dim};
+    if (val === "new") return {text: val, color: C.cyan};
+    if (isSpeedup) {
+        const num = parseFloat(val);
+        if (num >= 1.2) return {text: val, color: C.bold + C.green};
+        if (num >= 1.05) return {text: val, color: C.green};
+        if (num < 1.0) return {text: val, color: C.yellow};
+    }
+    return {text: val, color: null};
+}
+
+/**
+ * Print a bordered table to the console.
+ *
+ * @param {object} opts
+ * @param {string} opts.title
+ * @param {string} opts.subtitle
+ * @param {string[]} opts.headers
+ * @param {Array<{cells: string[], group?: string}>} opts.rows
+ */
+export function printTable({title, subtitle, headers, rows}) {
+    const widths = headers.map((h) => h.length);
+
+    // Calculate column widths
+    for (const r of rows) {
+        if (!r.cells) continue;
+        r.cells.forEach((c, i) => {
+            widths[i] = Math.max(widths[i], String(c).length);
+        });
+    }
+
+    const totalWidth = widths.reduce((a, w) => a + w + 2, 0) + widths.length - 1 + 2;
+    const lineInner = totalWidth - 4;
+
+    const hr = line(widths, B.TL, B.TD, B.TR);
+    const hrSep = line(widths, B.TR2, B.X, B.TL2);
+    const hrBot = line(widths, B.BL, B.TU, B.BR);
+
+    console.log();
+    console.log(hr);
+    console.log(`${B.V} ${C.bold + C.white}${title.padEnd(lineInner)}${C.reset} ${B.V}`);
+    if (subtitle) {
+        console.log(`${B.V} ${C.dim}${subtitle.padEnd(lineInner)}${C.reset} ${B.V}`);
+    }
+    console.log(hrSep);
+
+    // Header
+    const hdr = headers
+        .map((h, i) => {
+            const pad = i === 0 ? p(h, widths[i], "left") : p(h, widths[i], "right");
+            return ` ${C.bold + C.cyan}${pad}${C.reset} `;
+        })
+        .join(`${B.V}`);
+    console.log(`${B.V}${hdr}${B.V}`);
+    console.log(hrSep);
+
+    // Rows
+    let lastGroup = null;
+    for (const r of rows) {
+        if (r.group !== undefined && r.group !== lastGroup) {
+            if (lastGroup !== null) console.log(hrSep);
+            console.log(`${B.V} ${C.bold + C.white}${r.group.padEnd(lineInner)}${C.reset} ${B.V}`);
+            console.log(hrSep);
+            lastGroup = r.group;
+        }
+
+        if (!r.cells) continue;
+        const cells = r.cells
+            .map((c, i) => {
+                const isSpeedup = i === 3;
+                const d = displayValue(c, isSpeedup);
+                const align = i === 0 ? "left" : "right";
+                const padStr = p(d.text, widths[i], align);
+                return d.color ? ` ${d.color}${padStr}${C.reset} ` : ` ${padStr} `;
+            })
+            .join(`${B.V}`);
+        console.log(`${B.V}${cells}${B.V}`);
+    }
+
+    console.log(hrBot);
+    console.log();
+}

package/benchmarks/scripts/throughput-baseline.mjs

@@ -0,0 +1,68 @@
+console.log = () => {};
+console.error = () => {};
+
+const {default: Storage} = await import("@bejibun-baseline/storage");
+const {default: StorageBuilder} = await import("@bejibun-baseline/storage/builders/StorageBuilder");
+
+const ITERATIONS = 20_000;
+const WARMUP = 500;
+const root = `${process.env.TMPDIR ?? "/tmp"}/bejibun-storage-bench-baseline`;
+const disk = {driver: "local", root};
+
+await Bun.write(`${root}/.keep`, "");
+
+const buildMs = measureConstructor();
+const existsMs = await measureExists();
+const getMs = await measureGet();
+const deleteMs = await measureDelete();
+
+process.stdout.write(`${buildMs}|${existsMs}|${getMs}|${deleteMs}\n`);
+
+function measureConstructor() {
+    for (let i = 0; i < WARMUP; i++) {
+        void new StorageBuilder();
+    }
+    const t0 = performance.now();
+    for (let i = 0; i < ITERATIONS; i++) {
+        void new StorageBuilder();
+    }
+    return performance.now() - t0;
+}
+
+async function measureExists() {
+    for (let i = 0; i < WARMUP; i++) {
+        await Storage.build(disk).exists(`${root}/bench:key-old`);
+    }
+    const t0 = performance.now();
+    for (let i = 0; i < ITERATIONS; i++) {
+        await Storage.build(disk).exists(`${root}/bench:key:${i % 1000}`);
+    }
+    return performance.now() - t0;
+}
+
+async function measureGet() {
+    await Storage.build(disk).put(`${root}/bench:get`, "bench-value");
+    for (let i = 0; i < WARMUP; i++) {
+        await Storage.build(disk).get(`${root}/bench:get`);
+    }
+    const t0 = performance.now();
+    for (let i = 0; i < ITERATIONS; i++) {
+        await Storage.build(disk).get(`${root}/bench:get`);
+    }
+    return performance.now() - t0;
+}
+
+async function measureDelete() {
+    for (let i = 0; i < WARMUP; i++) {
+        const f = `${root}/bench:del:${i}`;
+        await Bun.write(f, "x");
+        await Storage.build(disk).delete(f);
+    }
+    const t0 = performance.now();
+    for (let i = 0; i < ITERATIONS; i++) {
+        const f = `${root}/bench:del:${i % 200}`;
+        await Bun.write(f, "x");
+        await Storage.build(disk).delete(f);
+    }
+    return performance.now() - t0;
+}

package/benchmarks/scripts/throughput-optimized.mjs

@@ -0,0 +1,68 @@
+console.log = () => {};
+console.error = () => {};
+
+const {default: Storage} = await import("../../src/facades/Storage.ts");
+const {default: StorageBuilder} = await import("../../src/builders/StorageBuilder.ts");
+
+const ITERATIONS = 20_000;
+const WARMUP = 500;
+const root = `${process.env.TMPDIR ?? "/tmp"}/bejibun-storage-bench-optimized`;
+const disk = {driver: "local", root};
+
+await Bun.write(`${root}/.keep`, "");
+
+const buildMs = measureConstructor();
+const existsMs = await measureExists();
+const getMs = await measureGet();
+const deleteMs = await measureDelete();
+
+process.stdout.write(`${buildMs}|${existsMs}|${getMs}|${deleteMs}\n`);
+
+function measureConstructor() {
+    for (let i = 0; i < WARMUP; i++) {
+        void new StorageBuilder();
+    }
+    const t0 = performance.now();
+    for (let i = 0; i < ITERATIONS; i++) {
+        void new StorageBuilder();
+    }
+    return performance.now() - t0;
+}
+
+async function measureExists() {
+    for (let i = 0; i < WARMUP; i++) {
+        await Storage.build(disk).exists(`${root}/bench:key-old`);
+    }
+    const t0 = performance.now();
+    for (let i = 0; i < ITERATIONS; i++) {
+        await Storage.build(disk).exists(`${root}/bench:key:${i % 1000}`);
+    }
+    return performance.now() - t0;
+}
+
+async function measureGet() {
+    await Storage.build(disk).put(`${root}/bench:get`, "bench-value");
+    for (let i = 0; i < WARMUP; i++) {
+        await Storage.build(disk).get(`${root}/bench:get`);
+    }
+    const t0 = performance.now();
+    for (let i = 0; i < ITERATIONS; i++) {
+        await Storage.build(disk).get(`${root}/bench:get`);
+    }
+    return performance.now() - t0;
+}
+
+async function measureDelete() {
+    for (let i = 0; i < WARMUP; i++) {
+        const f = `${root}/bench:del:${i}`;
+        await Bun.write(f, "x");
+        await Storage.build(disk).delete(f);
+    }
+    const t0 = performance.now();
+    for (let i = 0; i < ITERATIONS; i++) {
+        const f = `${root}/bench:del:${i % 200}`;
+        await Bun.write(f, "x");
+        await Storage.build(disk).delete(f);
+    }
+    return performance.now() - t0;
+}

package/benchmarks/scripts/throughput.mjs

@@ -0,0 +1,83 @@
+/**
+ * Throughput benchmark.
+ *
+ * Measures the hot paths touched on every storage operation, method by method. On baseline
+ * each `new StorageBuilder()` re-reads the config file from disk (`fs.existsSync` +
+ * `require()`) and re-resolves the driver; the optimized build caches the resolved config
+ * at module load and uses native nullish checks instead of `defineValue`/`isEmpty`.
+ * `exists`/`get`/`delete` exercise the full facade path against a temporary local disk.
+ *
+ * Run: bun run scripts/throughput.mjs
+ */
+import {spawnSync} from "node:child_process";
+import {fileURLToPath} from "node:url";
+import path from "node:path";
+import {printTable} from "./table-format.mjs";
+import {updateReadmeSection} from "./readme-writer.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TRIALS = 9;
+const runtime = process.execPath;
+
+function runTrials(scriptPath) {
+    const results = [];
+    for (let i = 0; i < TRIALS; i++) {
+        const res = spawnSync(runtime, [scriptPath], {encoding: "utf8"});
+        if (res.status !== 0) {
+            console.error("Benchmark failed:", res.stderr);
+            process.exit(1);
+        }
+        results.push(res.stdout.trim().split("|").map(Number));
+    }
+    return results;
+}
+
+function medianRow(trials) {
+    const cols = trials[0].length;
+    const medians = [];
+    for (let c = 0; c < cols; c++) {
+        const sorted = trials.map((t) => t[c]).sort((a, b) => a - b);
+        medians.push(sorted[Math.floor(sorted.length / 2)]);
+    }
+    return medians;
+}
+
+const ITERATIONS = 20_000;
+const methods = ["construction", "exists", "get", "delete"];
+const bCols = medianRow(runTrials(path.join(__dirname, "throughput-baseline.mjs")));
+const oCols = medianRow(runTrials(path.join(__dirname, "throughput-optimized.mjs")));
+
+function fmt(ms) {
+    return ms < 1 ? `${(ms * 1000).toFixed(0)}\u00B5s` : `${ms.toFixed(1)}ms`;
+}
+
+function sp(b, o) {
+    const r = b / o;
+    return r >= 1.05 ? `${r.toFixed(2)}x` : r <= 0.95 ? `${r.toFixed(2)}x` : "~1.0x";
+}
+
+function ops(ms) {
+    return Math.round(ITERATIONS / (ms / 1000)).toLocaleString() + "/s";
+}
+
+const rows = methods.map((m, i) => ({
+    cells: [m, fmt(bCols[i]), fmt(oCols[i]), sp(bCols[i], oCols[i]), ops(oCols[i])]
+}));
+
+printTable({
+    title: "THROUGHPUT BENCHMARK",
+    subtitle: `${ITERATIONS.toLocaleString()} calls each, ${TRIALS} runs (median)`,
+    headers: ["Method", "Baseline (0.1.1)", "Optimized", "Speedup", "Optimized ops/s"],
+    rows
+});
+
+const lines = [
+    "| Method | baseline (0.1.1) | optimized | speedup | baseline ops/s | optimized ops/s |",
+    "|---|---|---|---|---|---|",
+    ...methods.map(
+        (m, i) =>
+            `| \`${m}\` | ${bCols[i].toFixed(1)}ms | ${oCols[i].toFixed(1)}ms | **${(bCols[i] / oCols[i]).toFixed(2)}x** | ${ops(bCols[i])} | ${ops(oCols[i])} |`
+    )
+];
+
+updateReadmeSection("THROUGHPUT", lines.join("\n"));