fix(tinybench-plugin): support tinybench v5 and v6

tinybench v6 moved the benchmark function, its options, and the resolved
bench options behind ES private fields (and flattened the options onto the
bench instance), which broke the plugin's reliance on reaching those
internals through casts: analysis mode crashed with "fn is not a function"
and walltime mode crashed reading `bench.opts.setup`.

Capture the function and options ourselves when `bench.add` runs, normalize
option access across the v4/v5 `bench.opts` layout and the v6 flattened one,
bake the walltime root frame into the registered function instead of mutating
the (now private) task function, and opt back into sample retention that v6
disabled by default. Add dedicated example fixtures pinning tinybench v5 and
v6 so CI exercises every supported major, excluding them from the Node 18 leg
since tinybench v5+ requires Node >=20.

Closes COD-2929
Co-Authored-By: Claude <noreply@anthropic.com>

Generated with AI Agent (Claude Code)

Author: GuillaumeLagrange

.github/workflows/ci.yml

@@ -51,6 +51,12 @@ jobs:
       matrix:
         node-version: ["18", "20.5.1"]
         example: ${{ fromJson(needs.list-examples.outputs.examples) }}
+        # tinybench v5+ requires Node >=20, so its examples cannot run on Node 18
+        exclude:
+          - node-version: "18"
+            example: "with-tinybench-v5"
+          - node-version: "18"
+            example: "with-tinybench-v6"
       fail-fast: false
     steps:
       - uses: "actions/checkout@v4"

examples/with-tinybench-v5/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "with-tinybench-v5",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "bench-tinybench": "node --loader esbuild-register/loader -r esbuild-register tinybench.ts",
+    "typecheck": "tsc --noEmit --pretty"
+  },
+  "devDependencies": {
+    "@codspeed/tinybench-plugin": "workspace:*",
+    "esbuild-register": "^3.4.2",
+    "tinybench": "^5.1.0",
+    "typescript": "^5.1.3"
+  }
+}

examples/with-tinybench-v5/tinybench.ts

@@ -0,0 +1,39 @@
+import { withCodSpeed } from "@codspeed/tinybench-plugin";
+import { Bench } from "tinybench";
+
+function recursiveFibonacci(n: number): number {
+  if (n < 2) {
+    return n;
+  }
+  return recursiveFibonacci(n - 1) + recursiveFibonacci(n - 2);
+}
+
+// The plugin resolves tinybench's `Bench` type from the version hoisted at the
+// monorepo root, which differs from the major pinned in this example. A real
+// consumer has a single installed tinybench, so this mismatch is local to the
+// workspace; `@ts-expect-error` keeps the example typechecking and flags us if
+// the discrepancy ever resolves on its own.
+// @ts-expect-error cross-version Bench type mismatch within the monorepo
+const bench = withCodSpeed(new Bench({ time: 100, warmup: true }));
+
+bench
+  .add("recursive fibo 10", () => {
+    recursiveFibonacci(10);
+  })
+  // Register the per-task hooks so the plugin's handling of them is exercised.
+  .add(
+    "recursive fibo 15 with hooks",
+    () => {
+      recursiveFibonacci(15);
+    },
+    {
+      beforeAll() {},
+      beforeEach() {},
+      afterEach() {},
+      afterAll() {},
+    },
+  );
+
+bench.run().then(() => {
+  console.table(bench.table());
+});

examples/with-tinybench-v5/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "lib": ["es2023"],
+    "module": "ESNext",
+    "target": "es2022",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "Node"
+  }
+}

examples/with-tinybench-v6/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "with-tinybench-v6",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "bench-tinybench": "node --loader esbuild-register/loader -r esbuild-register tinybench.ts",
+    "typecheck": "tsc --noEmit --pretty"
+  },
+  "devDependencies": {
+    "@codspeed/tinybench-plugin": "workspace:*",
+    "esbuild-register": "^3.4.2",
+    "tinybench": "^6.0.2",
+    "typescript": "^5.1.3"
+  }
+}

examples/with-tinybench-v6/tinybench.ts

@@ -0,0 +1,39 @@
+import { withCodSpeed } from "@codspeed/tinybench-plugin";
+import { Bench } from "tinybench";
+
+function recursiveFibonacci(n: number): number {
+  if (n < 2) {
+    return n;
+  }
+  return recursiveFibonacci(n - 1) + recursiveFibonacci(n - 2);
+}
+
+// The plugin resolves tinybench's `Bench` type from the version hoisted at the
+// monorepo root, which differs from the major pinned in this example. A real
+// consumer has a single installed tinybench, so this mismatch is local to the
+// workspace; `@ts-expect-error` keeps the example typechecking and flags us if
+// the discrepancy ever resolves on its own.
+// @ts-expect-error cross-version Bench type mismatch within the monorepo
+const bench = withCodSpeed(new Bench({ time: 100, warmup: true }));
+
+bench
+  .add("recursive fibo 10", () => {
+    recursiveFibonacci(10);
+  })
+  // Register the per-task hooks so the plugin's handling of them is exercised.
+  .add(
+    "recursive fibo 15 with hooks",
+    () => {
+      recursiveFibonacci(15);
+    },
+    {
+      beforeAll() {},
+      beforeEach() {},
+      afterEach() {},
+      afterAll() {},
+    },
+  );
+
+bench.run().then(() => {
+  console.table(bench.table());
+});

examples/with-tinybench-v6/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "lib": ["es2023"],
+    "module": "ESNext",
+    "target": "es2022",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "Node"
+  }
+}

packages/tinybench-plugin/src/analysis.ts

@@ -6,7 +6,7 @@ import {
   wrapWithRootFrame,
   wrapWithRootFrameSync,
 } from "@codspeed/core";
-import { Bench, Fn, FnOptions, Task } from "tinybench";
+import { Bench, Task } from "tinybench";
 import { BaseBenchRunner } from "./shared";
 
 export function setupCodspeedAnalysisBench(
@@ -28,7 +28,7 @@ class AnalysisBenchRunner extends BaseBenchRunner {
   }
 
   protected async runTaskAsync(task: Task, uri: string): Promise<void> {
-    const { fnOpts, fn } = task as unknown as { fnOpts?: FnOptions; fn: Fn };
+    const { fnOpts, fn } = this.getTaskData(task);
 
     await fnOpts?.beforeAll?.call(task, "run");
     await optimizeFunction(async () => {
@@ -50,7 +50,7 @@ class AnalysisBenchRunner extends BaseBenchRunner {
   }
 
   protected runTaskSync(task: Task, uri: string): void {
-    const { fnOpts, fn } = task as unknown as { fnOpts?: FnOptions; fn: Fn };
+    const { fnOpts, fn } = this.getTaskData(task);
 
     fnOpts?.beforeAll?.call(task, "run");
     fnOpts?.beforeEach?.call(task, "run");

packages/tinybench-plugin/src/benchOptions.ts

@@ -0,0 +1,24 @@
+import { Bench, Hook } from "tinybench";
+
+// The benchmark options tinybench resolves: timing knobs plus the suite-level
+// setup/teardown hooks. tinybench guarantees `setup`/`teardown` are populated
+// (at least with no-op defaults), so they are non-optional here.
+export interface ResolvedBenchOptions {
+  setup: Hook;
+  teardown: Hook;
+  warmup?: boolean;
+  warmupIterations?: number;
+  warmupTime?: number;
+  iterations?: number;
+  time?: number;
+  retainSamples?: boolean;
+}
+
+// Up to tinybench v5 the resolved options lived under `bench.opts`; from v6 they
+// are flattened onto the bench instance itself. Returning the holder object
+// (rather than a copy) keeps in-place mutation of `setup`/`teardown` working,
+// which the walltime runner relies on to bracket its instrumentation window.
+export function getBenchOptions(bench: Bench): ResolvedBenchOptions {
+  const opts = (bench as unknown as { opts?: ResolvedBenchOptions }).opts;
+  return opts ?? (bench as unknown as ResolvedBenchOptions);
+}

packages/tinybench-plugin/src/index.ts

@@ -7,9 +7,11 @@ import {
   SetupInstrumentsRequestBody,
   SetupInstrumentsResponse,
   tryIntrospect,
+  wrapWithRootFrameSync,
 } from "@codspeed/core";
 import { Bench } from "tinybench";
 import { setupCodspeedAnalysisBench } from "./analysis";
+import { getOrCreateTaskDataMap } from "./taskData";
 import { getOrCreateUriMap } from "./uri";
 import { setupCodspeedWalltimeBench } from "./walltime";
 
@@ -22,9 +24,11 @@ export function withCodSpeed(bench: Bench): Bench {
   }
 
   const rootCallingFile = getCallingFile(1);
+  const instrumentMode = getInstrumentMode();
 
   // Compute and register URI for bench
   const uriMap = getOrCreateUriMap(bench);
+  const taskDataMap = getOrCreateTaskDataMap(bench);
   const rawAdd = bench.add;
   bench.add = (name, fn, opts?) => {
     const callingFile = getCallingFile(1);
@@ -34,10 +38,17 @@ export function withCodSpeed(bench: Bench): Bench {
     }
     uri += `::${name}`;
     uriMap.set(name, uri);
-    return rawAdd.bind(bench)(name, fn, opts);
+    taskDataMap.set(name, { fn, fnOpts: opts });
+    // In walltime mode the task is driven by tinybench's own measured loop, so
+    // the root frame must be baked into the function tinybench stores rather
+    // than injected later (the function is an inaccessible private field on the
+    // task from tinybench v6 onwards). The sync wrapper is transparent to the
+    // function's return value, so it preserves tinybench's sync/async handling.
+    const registeredFn =
+      instrumentMode === "walltime" ? wrapWithRootFrameSync(fn) : fn;
+    return rawAdd.bind(bench)(name, registeredFn, opts);
   };
 
-  const instrumentMode = getInstrumentMode();
   if (instrumentMode === "analysis") {
     setupCodspeedAnalysisBench(bench, rootCallingFile);
   } else if (instrumentMode === "walltime") {