overtake 1.0.4 → 1.1.0

package/src/utils.ts

@@ -1,3 +1,5 @@
+import { transform } from '@swc/core';
+
 export const abs = (value: bigint) => {
   if (value < 0n) {
     return -value;
@@ -63,3 +65,21 @@ export class ScaledBigInt {
     return Number(div(this.value, this.scale));
   }
 }
+
+export const transpile = async (code: string): Promise<string> => {
+  const output = await transform(code, {
+    filename: 'benchmark.ts',
+    jsc: {
+      parser: {
+        syntax: 'typescript',
+        tsx: false,
+        dynamicImport: true,
+      },
+      target: 'esnext',
+    },
+    module: {
+      type: 'es6',
+    },
+  });
+  return output.code;
+};

package/src/worker.ts

@@ -1,8 +1,12 @@
 import { workerData } from 'node:worker_threads';
+import { SourceTextModule, SyntheticModule, createContext } from 'node:vm';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
 import { benchmark } from './runner.js';
-import { SetupFn, TeardownFn, StepFn, WorkerOptions } from './types.js';
+import { WorkerOptions } from './types.js';
 
 const {
+  baseUrl,
   setupCode,
   teardownCode,
   preCode,
@@ -14,19 +18,66 @@ const {
   minCycles,
   absThreshold,
   relThreshold,
+  gcObserver = true,
 
   durationsSAB,
   controlSAB,
 }: WorkerOptions = workerData;
 
-const setup: SetupFn<unknown> = setupCode && Function(`return ${setupCode};`)();
-const teardown: TeardownFn<unknown> = teardownCode && Function(`return ${teardownCode};`)();
+const serialize = (code?: string) => (code ? code : '() => {}');
 
-const pre: StepFn<unknown, unknown> = preCode && Function(`return ${preCode};`)();
-const run: StepFn<unknown, unknown> = runCode && Function(`return ${runCode};`)();
-const post: StepFn<unknown, unknown> = postCode && Function(`return ${postCode};`)();
+const source = `
+export const setup = ${serialize(setupCode)};
+export const teardown = ${serialize(teardownCode)};
+export const pre = ${serialize(preCode)};
+export const run = ${serialize(runCode)};
+export const post = ${serialize(postCode)};
+  `;
 
-const exitCode = await benchmark({
+const context = createContext({ console, Buffer });
+const imports = new Map<string, SyntheticModule>();
+const mod = new SourceTextModule(source, {
+  identifier: baseUrl,
+  context,
+  initializeImportMeta(meta) {
+    meta.url = baseUrl;
+  },
+  importModuleDynamically(specifier, referencingModule) {
+    const base = referencingModule.identifier ?? baseUrl;
+    const resolveFrom = createRequire(fileURLToPath(base));
+    return import(resolveFrom.resolve(specifier));
+  },
+});
+
+await mod.link(async (specifier, referencingModule) => {
+  const base = referencingModule.identifier ?? baseUrl;
+  const resolveFrom = createRequire(fileURLToPath(base));
+  const target = resolveFrom.resolve(specifier);
+  const cached = imports.get(target);
+  if (cached) return cached;
+
+  const importedModule = await import(target);
+  const exportNames = Object.keys(importedModule);
+  const imported = new SyntheticModule(
+    exportNames,
+    () => {
+      exportNames.forEach((key) => imported.setExport(key, importedModule[key]));
+    },
+    { identifier: target, context: referencingModule.context },
+  );
+  imports.set(target, imported);
+  return imported;
+});
+
+await mod.evaluate();
+const { setup, teardown, pre, run, post } = mod.namespace as any;
+
+if (!run) {
+  throw new Error('Benchmark run function is required');
+}
+
+process.exitCode = await benchmark({
+  baseUrl,
   setup,
   teardown,
   pre,
@@ -38,9 +89,8 @@ const exitCode = await benchmark({
   minCycles,
   absThreshold,
   relThreshold,
+  gcObserver,
 
   durationsSAB,
   controlSAB,
 });
-
-process.exit(exitCode);

package/CLAUDE.md

@@ -1,145 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Overtake is a high-precision JavaScript/TypeScript benchmarking library that uses worker thread isolation and statistical convergence to provide accurate performance measurements. It solves common benchmarking problems like JIT optimization interference and cross-benchmark contamination.
-
-## Development Commands
-
-```bash
-# Build the project (uses inop for transpilation + tsc for declarations only)
-npm run build
-# or with pnpm
-pnpm build
-
-# Run tests (uses Jest with SWC transpilation - no test files currently exist)
-npm test
-
-# Execute benchmarks via CLI
-npx overtake "examples/*.ts" -f table -r ops mean p95
-
-# Run a single benchmark file
-npx overtake examples/quick-start.ts
-
-# Start the CLI directly (requires argument)
-npm start examples/quick-start.ts
-
-# Format code with Prettier (via pre-commit hook)
-npx prettier --write "src/**/*.ts" "examples/**/*.ts"
-
-# Note: Package manager is pnpm@10.14.0 (see packageManager field in package.json)
-```
-
-## Architecture
-
-### Core Components
-
-1. **Benchmark Class** (`src/index.ts`): Main API with fluent interface for defining benchmarks using feed → target → measure pattern
-2. **Executor** (`src/executor.ts`): Worker thread pool management using async queues and SharedArrayBuffer for zero-copy communication
-3. **Worker** (`src/worker.ts`): Isolated execution environment with fresh V8 context per benchmark
-4. **Runner** (`src/runner.ts`): Handles warmup cycles, statistical convergence detection, and timing collection
-5. **Reporter** (`src/reporter.ts`): Statistical analysis and result formatting (ops/sec, percentiles, mean/median/mode)
-
-### Key Design Patterns
-
-- **Worker Thread Isolation**: Each benchmark runs in separate thread to prevent contamination
-- **SharedArrayBuffer Communication**: Zero-copy data transfer for high-precision bigint timing
-- **Statistical Convergence**: Automatic cycle adjustment based on configurable confidence thresholds
-- **Dynamic Code Execution**: Function serialization across threads with VM module sandboxing
-
-### API Structure
-
-```typescript
-// Fluent API pattern
-benchmark('name', feedFunction)
-  .target('implementation')
-  .measure('operation', measureFunction)
-  .execute() // Returns Promise<Report[]>
-```
-
-## Technical Requirements
-
-- Node.js >=22 (uses modern features like VM modules)
-- ES modules only (no CommonJS)
-- TypeScript with ESNext target
-- Uses SWC for transpilation (not tsc for builds)
-
-## Important Implementation Notes
-
-- **CRITICAL**: All imports must be dynamic inside target callbacks since they run in worker threads:
-  ```typescript
-  // CORRECT - dynamic import inside target
-  .target('V8', async () => {
-    const { serialize } = await import('node:v8');
-    return { serialize };
-  })
-  
-  // WRONG - static import at top level
-  import { serialize } from 'node:v8';
-  .target('V8', () => ({ serialize }))
-  ```
-- Timing uses `process.hrtime.bigint()` for nanosecond precision
-- Worker threads communicate via SharedArrayBuffer to minimize overhead
-- Build process uses `inop` tool for transpilation followed by tsc for declarations only
-- Test files should match `*.spec.ts` or `*.test.ts` patterns (currently no tests exist)
-
-## API Usage Modes
-
-### CLI Mode (Global `benchmark` function)
-- Used when running via `npx overtake file.ts`
-- CLI provides global `benchmark` function automatically
-- No imports needed, no `.execute()` call required
-- Results printed based on CLI flags
-
-Example (examples/quick-start.ts):
-```typescript
-const suite = benchmark('name', () => data);
-suite.target('impl').measure('op', (ctx, input) => { /* ... */ });
-```
-
-### Programmatic Mode (Import Benchmark class)
-- Used for standalone scripts with custom execution
-- Must import Benchmark class and printer functions
-- Must call `.execute()` and handle results
-
-Example (examples/complete.ts):
-```typescript
-import { Benchmark, printJSONReports } from '../build/index.js';
-const suite = new Benchmark('name', () => data);
-// ... define targets and measures
-const reports = await suite.execute({ /* options */ });
-printJSONReports(reports, 2);
-```
-
-## Common Issues and Solutions
-
-### TypeScript Transpilation
-- CLI uses SWC's `transform` function to strip TypeScript types
-- If you see "Missing initializer in const declaration", it means TypeScript wasn't transpiled
-- The transpiler in `src/cli.ts` must use `transform`, not `parse`/`print`
-
-### Benchmarks Not Running
-- CLI mode: Ensure using global `benchmark` function (no import)
-- Programmatic mode: Must call `.execute()` and handle results
-- Check that worker count doesn't exceed CPU cores
-
-### Memory Management Patterns
-- Use `gcBlock` Set to prevent garbage collection during measurements:
-  ```typescript
-  .target('name', () => {
-    const gcBlock = new Set(); // Prevents GC
-    return { gcBlock };
-  })
-  .measure('op', ({ gcBlock }, input) => {
-    gcBlock.add(result); // Keep reference alive
-  })
-  ```
-
-## Code Quality Tools
-
-- **Formatter**: Prettier (config in `.prettierrc`) - runs automatically on commit via husky pre-commit hook
-- **Test Runner**: Jest with SWC transpilation (config in `jest.config.js`)
-- **TypeScript Config**: Strict mode enabled, targets ESNext with NodeNext modules
-- **No linter or type-check commands**: Add these if needed in the future

package/examples/array-copy.ts

@@ -1,17 +0,0 @@
-const copySuite = benchmark('1M array of strings', () => Array.from({ length: 1_000_000 }, (_, idx) => `${idx}`))
-  .feed('1M array of numbers', () => Array.from({ length: 1_000_000 }, (_, idx) => idx))
-  .feed('1M typed array', () => new Uint32Array(1_000_000).map((_, idx) => idx));
-
-copySuite.target('for loop').measure('copy half', (_, input) => {
-  const n = input?.length ?? 0;
-  const mid = n / 2;
-  for (let i = 0; i < mid; i++) {
-    input[i + mid] = input[i];
-  }
-});
-
-copySuite.target('copyWithin').measure('copy half', (_, input) => {
-  const n = input?.length ?? 0;
-  const mid = n / 2;
-  input.copyWithin(mid, 0, mid);
-});

package/examples/object-merge.ts

@@ -1,41 +0,0 @@
-import { Benchmark, printSimpleReports } from '../build/index.js';
-
-const objectMergeSuite = new Benchmark('1K array of objects', () => Array.from({ length: 1_000 }, (_, idx) => ({ [idx]: idx })));
-
-objectMergeSuite.target('reduce destructure').measure('data', (_, input) => {
-  input.reduce((acc, obj) => {
-    return { ...acc, ...obj };
-  }, {});
-});
-
-objectMergeSuite.target('reduce assign').measure('data', (_, input) => {
-  input.reduce((acc, obj) => {
-    Object.assign(acc, obj);
-    return acc;
-  }, {});
-});
-
-objectMergeSuite.target('forEach assign').measure('data', (_, input) => {
-  const result = {};
-  input.forEach((obj) => {
-    Object.assign(result, obj);
-  });
-});
-
-objectMergeSuite.target('for assign').measure('data', (_, input) => {
-  const result = {};
-  for (let i = 0; i < input.length; i++) {
-    Object.assign(result, input[i]);
-  }
-});
-
-objectMergeSuite.target('assign').measure('data', (_, input) => {
-  Object.assign({}, ...input);
-});
-
-const reports = await objectMergeSuite.execute({
-  reportTypes: ['ops'],
-  maxCycles: 10_000,
-});
-
-printSimpleReports(reports);

package/examples/serialization.ts

@@ -1,22 +0,0 @@
-import { randomUUID } from 'node:crypto';
-
-const serializeSuite = benchmark('1K strings', () => Array.from({ length: 10_000 }, () => randomUUID()));
-
-const v8Target = serializeSuite.target('V8', async () => {
-  const { serialize, deserialize } = await import('node:v8');
-  const gcBlock = new Set();
-  return { serialize, deserialize, gcBlock };
-});
-
-v8Target.measure('serialize', ({ serialize, gcBlock }, input) => {
-  gcBlock.add(serialize(input));
-});
-
-serializeSuite
-  .target('JSON', () => {
-    const gcBlock = new Set();
-    return { gcBlock };
-  })
-  .measure('serialize', ({ gcBlock }, input) => {
-    gcBlock.add(JSON.stringify(input));
-  });