overtake 1.3.2 → 2.0.0

package/README.md

@@ -98,8 +98,7 @@ benchmark('data', getData)
 
 ### Importing Local Files
 
-- **CLI mode (`npx overtake`)**: `baseUrl` is set to the benchmark file, so `await import('./helper.js')` works.
-- **Programmatic mode (`suite.execute`)**: pass `baseUrl: import.meta.url` (the benchmark’s file URL) so relative imports resolve correctly. If you omit it, Overtake falls back to `process.cwd()` and relative imports may fail.
+- **CLI mode (`npx overtake`)**: relative imports resolve from the benchmark file automatically.
 
 ```typescript
 // CLI usage – relative path is fine
@@ -109,16 +108,6 @@ benchmark('local', () => 1)
     return { helper };
   })
   .measure('use helper', ({ helper }) => helper());
-
-// Programmatic usage – provide baseUrl
-const suite = new Benchmark('local');
-suite
-  .target('helper', async () => {
-    const { helper } = await import('./helpers.js');
-    return { helper };
-  })
-  .measure('use helper', ({ helper }) => helper());
-await suite.execute({ baseUrl: import.meta.url });
 ```
 
 ## Usage
@@ -285,7 +274,7 @@ npx overtake <pattern> [options]
 | Option               | Short | Description                                           | Default   |
 | -------------------- | ----- | ----------------------------------------------------- | --------- |
 | `--format`           | `-f`  | Output format (see [Output Formats](#output-formats)) | `simple`  |
-| `--report-types`     | `-r`  | Stats to show (see [Metrics](#available-metrics))     | `['ops']` |
+| `--report-types`     | `-r`  | Stats to show, repeat for multiple (`-r ops -r p99`)  | `['ops']` |
 | `--workers`          | `-w`  | Concurrent workers                                    | CPU count |
 | `--min-cycles`       |       | Minimum measurement iterations                        | 50        |
 | `--max-cycles`       |       | Maximum measurement iterations                        | 1000      |
@@ -304,7 +293,7 @@ npx overtake <pattern> [options]
 npx overtake "**/*.bench.ts" -f table
 
 # Show detailed statistics
-npx overtake bench.ts -r ops mean p95 p99
+npx overtake bench.ts -r ops -r mean -r p95 -r p99
 
 # Output JSON for CI
 npx overtake bench.ts -f json > results.json
@@ -400,7 +389,7 @@ Specify with `--report-types` or `reportTypes` option.
 **Example:**
 
 ```bash
-npx overtake bench.ts -r ops mean sd rme p50 p95 p99
+npx overtake bench.ts -r ops -r mean -r sd -r rme -r p50 -r p95 -r p99
 ```
 
 ## Baseline Comparison
@@ -503,6 +492,14 @@ CLI mode enforces one benchmark per file. Calling `benchmark()` twice throws an
 
 **Solution**: In CLI mode, don't import Benchmark or call `.execute()`. Use the global `benchmark` function.
 
+### Worker out of memory
+
+Benchmarks that retain objects across iterations (e.g. pushing to an array to prevent GC) can exhaust the worker heap. Increase the heap limit via `NODE_OPTIONS`:
+
+```bash
+NODE_OPTIONS='--max-old-space-size=8192' npx overtake bench.ts
+```
+
 ### Results vary between runs
 
 **Solution**: Increase `--min-cycles` for more samples, or use the `gcBlock` pattern to prevent garbage collection.

package/bin/overtake.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env -S node --experimental-vm-modules --no-warnings --expose-gc
-import '../build/cli.js';
+import '../src/cli.ts';

package/build/executor.d.ts

@@ -1,9 +1,10 @@
-import { Report } from './reporter.js';
-import { ExecutorRunOptions, ReportOptions, BenchmarkOptions, ReportTypeList, ProgressCallback } from './types.js';
+import { Report } from './reporter.ts';
+import { type ExecutorRunOptions, type ReportOptions, type BenchmarkOptions, type ReportTypeList, type ProgressCallback } from './types.ts';
 export type ExecutorReport<R extends ReportTypeList> = Record<R[number], Report> & {
     count: number;
     heapUsedKB: number;
     dceWarning: boolean;
+    error?: string;
 };
 export interface ExecutorOptions<R extends ReportTypeList> extends BenchmarkOptions, ReportOptions<R> {
     workers?: number;
@@ -11,4 +12,8 @@ export interface ExecutorOptions<R extends ReportTypeList> extends BenchmarkOpti
     onProgress?: ProgressCallback;
     progressInterval?: number;
 }
-export declare const createExecutor: <TContext, TInput, R extends ReportTypeList>(options: Required<ExecutorOptions<R>>) => import("async").QueueObject<ExecutorRunOptions<TContext, TInput>>;
+export interface Executor<TContext, TInput> {
+    pushAsync<T>(task: ExecutorRunOptions<TContext, TInput>): Promise<T>;
+    kill(): void;
+}
+export declare const createExecutor: <TContext, TInput, R extends ReportTypeList>(options: Required<ExecutorOptions<R>>) => Executor<TContext, TInput>;

package/build/index.d.ts

@@ -1,10 +1,9 @@
-import { ExecutorOptions, ExecutorReport } from './executor.js';
-import { MaybePromise, StepFn, SetupFn, TeardownFn, FeedFn, ReportType, ReportTypeList } from './types.js';
+import { type ExecutorOptions, type ExecutorReport } from './executor.ts';
+import { type MaybePromise, type StepFn, type SetupFn, type TeardownFn, type FeedFn, type ReportType, type ReportTypeList } from './types.ts';
 declare global {
     const benchmark: typeof Benchmark.create;
 }
 export declare const DEFAULT_WORKERS: number;
-export declare const AsyncFunction: Function;
 export interface TargetReport<R extends ReportTypeList> {
     target: string;
     measures: MeasureReport<R>[];
@@ -20,10 +19,10 @@ export interface FeedReport<R extends ReportTypeList> {
 export declare const DEFAULT_REPORT_TYPES: readonly ["ops"];
 export type DefaultReportTypes = (typeof DEFAULT_REPORT_TYPES)[number];
 export declare class MeasureContext<TContext, TInput> {
-    title: string;
-    run: StepFn<TContext, TInput>;
     pre?: StepFn<TContext, TInput>;
     post?: StepFn<TContext, TInput>;
+    title: string;
+    run: StepFn<TContext, TInput>;
     constructor(title: string, run: StepFn<TContext, TInput>);
 }
 export declare class Measure<TContext, TInput> {
@@ -33,11 +32,11 @@ export declare class Measure<TContext, TInput> {
     post(fn: StepFn<TContext, TInput>): Measure<TContext, TInput>;
 }
 export declare class TargetContext<TContext, TInput> {
-    readonly title: string;
-    readonly setup?: SetupFn<MaybePromise<TContext>> | undefined;
     teardown?: TeardownFn<TContext>;
     measures: MeasureContext<TContext, TInput>[];
-    constructor(title: string, setup?: SetupFn<MaybePromise<TContext>> | undefined);
+    readonly title: string;
+    readonly setup?: SetupFn<MaybePromise<TContext>>;
+    constructor(title: string, setup?: SetupFn<MaybePromise<TContext>>);
 }
 export declare class Target<TContext, TInput> {
     #private;
@@ -47,8 +46,8 @@ export declare class Target<TContext, TInput> {
 }
 export declare class FeedContext<TInput> {
     readonly title: string;
-    readonly fn?: FeedFn<TInput> | undefined;
-    constructor(title: string, fn?: FeedFn<TInput> | undefined);
+    readonly fn?: FeedFn<TInput>;
+    constructor(title: string, fn?: FeedFn<TInput>);
 }
 export declare class Benchmark<TInput> {
     #private;
@@ -60,7 +59,7 @@ export declare class Benchmark<TInput> {
     feed<I>(title: string, fn: FeedFn<I>): Benchmark<TInput | I>;
     target<TContext>(title: string): Target<void, TInput>;
     target<TContext>(title: string, setup: SetupFn<Awaited<TContext>>): Target<TContext, TInput>;
-    execute<R extends readonly ReportType[] = typeof DEFAULT_REPORT_TYPES>(options: ExecutorOptions<R> & {
+    execute<R extends readonly ReportType[] = typeof DEFAULT_REPORT_TYPES>(options?: Partial<ExecutorOptions<R>> & {
         progress?: boolean;
     }): Promise<TargetReport<R>[]>;
 }

package/build/reporter.d.ts

@@ -1,4 +1,4 @@
-import { ReportType } from './types.js';
+import { type ReportType } from './types.ts';
 export declare class Report {
     readonly type: ReportType;
     readonly value: bigint;
@@ -8,4 +8,12 @@ export declare class Report {
     valueOf(): number;
     toString(): string;
 }
-export declare const createReport: (durations: BigUint64Array, type: ReportType) => Report;
+type Stats = {
+    sum: bigint;
+    mean: bigint;
+    ssd: bigint;
+    n: bigint;
+};
+export declare const computeStats: (durations: BigUint64Array) => Stats;
+export declare const createReport: (durations: BigUint64Array, type: ReportType, stats?: Stats) => Report;
+export {};

package/build/runner.d.ts

@@ -1,2 +1,2 @@
-import { Options } from './types.js';
+import { type Options } from './types.ts';
 export declare const benchmark: <TContext, TInput>({ setup, teardown, pre, run: runRaw, post, data, warmupCycles, minCycles, absThreshold, relThreshold, gcObserver, durationsSAB, controlSAB, }: Required<Options<TContext, TInput>>) => Promise<number>;

package/build/types.d.ts

@@ -53,14 +53,14 @@ export interface Options<TContext, TInput> extends RunOptions<TContext, TInput>,
     durationsSAB: SharedArrayBuffer;
     controlSAB: SharedArrayBuffer;
 }
-export declare enum Control {
-    INDEX = 0,
-    PROGRESS = 1,
-    COMPLETE = 2,
-    HEAP_USED = 3
-}
+export declare const Control: {
+    readonly INDEX: 0;
+    readonly PROGRESS: 1;
+    readonly COMPLETE: 2;
+    readonly HEAP_USED: 3;
+};
 export declare const CONTROL_SLOTS: number;
-export declare const DEFAULT_CYCLES = 1000;
+export declare const DEFAULT_CYCLES = 10000;
 export declare const Z95 = 1.96;
 export declare const DURATION_SCALE = 1000n;
 export declare const COMPLETE_VALUE = 10000;

package/build/utils.d.ts

@@ -1,21 +1,7 @@
-export declare const abs: (value: bigint) => bigint;
+export declare const resolveHookUrl: string;
+export declare const isqrt: (n: bigint) => bigint;
 export declare const cmp: (a: bigint | number, b: bigint | number) => number;
 export declare const max: (a: bigint, b: bigint) => bigint;
-export declare const divMod: (a: bigint, b: bigint) => {
-    quotient: bigint;
-    remainder: bigint;
-};
 export declare function div(a: bigint, b: bigint, decimals?: number): string;
 export declare function divs(a: bigint, b: bigint, scale: bigint): bigint;
-export declare class ScaledBigInt {
-    value: bigint;
-    scale: bigint;
-    constructor(value: bigint, scale: bigint);
-    add(value: bigint): void;
-    sub(value: bigint): void;
-    div(value: bigint): void;
-    mul(value: bigint): void;
-    unscale(): bigint;
-    number(): number;
-}
-export declare const transpile: (code: string) => Promise<string>;
+export declare function assertNoClosure(code: string, name: string): void;

package/package.json

@@ -1,28 +1,18 @@
 {
   "name": "overtake",
-  "version": "1.3.2",
+  "version": "2.0.0",
   "description": "NodeJS performance benchmark",
   "type": "module",
   "types": "build/index.d.ts",
-  "main": "build/index.cjs",
-  "module": "build/index.js",
   "exports": {
     "types": "./build/index.d.ts",
-    "require": "./build/index.cjs",
-    "import": "./build/index.js"
-  },
-  "typesVersions": {
-    "*": {
-      "*": [
-        "build/index.d.ts"
-      ]
-    }
+    "import": "./src/index.ts"
   },
   "bin": {
     "overtake": "bin/overtake.js"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "repository": {
     "type": "git",
@@ -41,30 +31,22 @@
   },
   "homepage": "https://github.com/3axap4eHko/overtake#readme",
   "devDependencies": {
-    "@jest/globals": "^30.2.0",
-    "@swc/jest": "^0.2.39",
-    "@types/async": "^3.2.25",
-    "@types/jest": "^30.0.0",
     "@types/node": "^25.3.0",
     "@types/progress": "^2.0.7",
     "husky": "^9.1.7",
-    "inop": "^0.9.0",
-    "jest": "^30.2.0",
     "overtake": "^1.3.1",
     "prettier": "^3.8.1",
     "pretty-quick": "^4.2.2",
-    "typescript": "^5.9.3"
+    "typescript": "5.9.3"
   },
   "dependencies": {
-    "@swc/core": "^1.15.11",
-    "async": "^3.2.6",
-    "commander": "^14.0.3",
-    "glob": "^13.0.6",
+    "@swc/core": "^1.15.18",
     "progress": "^2.0.3"
   },
   "scripts": {
-    "build": "rm -rf build && inop src build -i __tests__ -i *.tmp.ts && tsc --declaration --emitDeclarationOnly",
+    "build": "rm -rf build && tsc --declaration --emitDeclarationOnly",
     "start": "./bin/overtake.js",
-    "test": "jest --detectOpenHandles --passWithNoTests"
+    "test": "node --experimental-test-module-mocks --test src/__tests__/*.ts",
+    "test:cov": "node --experimental-test-module-mocks --experimental-test-coverage --test src/__tests__/*.ts"
   }
 }

package/src/__tests__/assert-no-closure.ts

@@ -0,0 +1,135 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { assertNoClosure } from '../utils.ts';
+
+describe('assertNoClosure', () => {
+  describe('allows functions without closures', () => {
+    it('arrow with params only', () => {
+      assert.doesNotThrow(() => assertNoClosure('(x) => x * 2', 'run'));
+    });
+
+    it('arrow with local variables', () => {
+      assert.doesNotThrow(() => assertNoClosure('(ctx, input) => { const y = ctx.value + input; return y; }', 'run'));
+    });
+
+    it('function expression', () => {
+      assert.doesNotThrow(() => assertNoClosure('function(x) { return x + 1; }', 'run'));
+    });
+
+    it('named function expression', () => {
+      assert.doesNotThrow(() => assertNoClosure('function run(x) { return x + 1; }', 'run'));
+    });
+
+    it('async arrow', () => {
+      assert.doesNotThrow(() => assertNoClosure('async (ctx) => { const r = await fetch("url"); return r; }', 'run'));
+    });
+
+    it('destructured params', () => {
+      assert.doesNotThrow(() => assertNoClosure('({a, b: c}, [d, ...e]) => a + c + d + e.length', 'run'));
+    });
+
+    it('nested function declaration', () => {
+      assert.doesNotThrow(() => assertNoClosure('(arr) => { function helper(x) { return x * 2; } return arr.map(helper); }', 'run'));
+    });
+
+    it('for-of loop variable', () => {
+      assert.doesNotThrow(() => assertNoClosure('(arr) => { let sum = 0; for (const x of arr) sum += x; return sum; }', 'run'));
+    });
+
+    it('member access on params', () => {
+      assert.doesNotThrow(() => assertNoClosure('(ctx) => ctx.data.map(x => x.value)', 'run'));
+    });
+
+    it('globals like console, Buffer, Math, Array', () => {
+      assert.doesNotThrow(() => assertNoClosure('(ctx) => { console.log(Math.max(...ctx)); return Buffer.from(Array.of(1)); }', 'run'));
+    });
+
+    it('try-catch with error binding', () => {
+      assert.doesNotThrow(() => assertNoClosure('(ctx) => { try { return ctx(); } catch (e) { return e; } }', 'run'));
+    });
+
+    it('class expression', () => {
+      assert.doesNotThrow(() => assertNoClosure('() => { class Foo { bar() { return 1; } } return new Foo(); }', 'run'));
+    });
+
+    it('label statements', () => {
+      assert.doesNotThrow(() => assertNoClosure('() => { outer: for (let i = 0; i < 10; i++) { break outer; } }', 'run'));
+    });
+  });
+
+  describe('detects closures', () => {
+    it('single closed-over variable', () => {
+      assert.throws(() => assertNoClosure('(x) => x + closedOver', 'run'), /closedOver/);
+    });
+
+    it('multiple closed-over variables', () => {
+      assert.throws(() => assertNoClosure('(ctx) => sharedData.filter(x => x > threshold)', 'run'), /sharedData/);
+    });
+
+    it('closed-over function call', () => {
+      assert.throws(() => assertNoClosure('(ctx) => helper(ctx)', 'run'), /helper/);
+    });
+
+    it('closed-over array', () => {
+      assert.throws(() => assertNoClosure('() => myArray.map(x => x * 2)', 'run'), /myArray/);
+    });
+
+    it('computed member access with outer variable', () => {
+      assert.throws(() => assertNoClosure('(obj) => obj[key]', 'run'), /key/);
+    });
+
+    it('variable used as argument', () => {
+      assert.throws(() => assertNoClosure('() => JSON.stringify(config)', 'run'), /config/);
+    });
+
+    it('variable in template literal', () => {
+      assert.throws(() => assertNoClosure('() => `${prefix}-value`', 'run'), /prefix/);
+    });
+  });
+
+  describe('error message', () => {
+    it('includes the function name', () => {
+      assert.throws(() => assertNoClosure('() => x', 'setup'), /"setup"/);
+      assert.throws(() => assertNoClosure('() => x', 'run'), /"run"/);
+      assert.throws(() => assertNoClosure('() => x', 'teardown'), /"teardown"/);
+    });
+
+    it('lists all closed-over variables', () => {
+      try {
+        assertNoClosure('() => a + b + c', 'run');
+        assert.fail('should have thrown');
+      } catch (e) {
+        assert.match((e as Error).message, /\ba\b/);
+        assert.match((e as Error).message, /\bb\b/);
+        assert.match((e as Error).message, /\bc\b/);
+      }
+    });
+
+    it('explains the problem and suggests fix', () => {
+      try {
+        assertNoClosure('() => x', 'run');
+        assert.fail('should have thrown');
+      } catch (e) {
+        const msg = (e as Error).message;
+        assert.ok(msg.includes('.toString()'));
+        assert.ok(msg.includes('worker'));
+        assert.ok(msg.includes('setup'));
+        assert.ok(msg.includes('data'));
+      }
+    });
+  });
+
+  describe('edge cases', () => {
+    it('silently passes on unparseable code', () => {
+      assert.doesNotThrow(() => assertNoClosure('not valid js {{{', 'run'));
+    });
+
+    it('empty arrow function', () => {
+      assert.doesNotThrow(() => assertNoClosure('() => {}', 'run'));
+    });
+
+    it('undefined return', () => {
+      assert.doesNotThrow(() => assertNoClosure('() => undefined', 'run'));
+    });
+  });
+});

package/src/__tests__/benchmark-execute.ts

@@ -0,0 +1,48 @@
+import { describe, it, mock } from 'node:test';
+import assert from 'node:assert/strict';
+
+describe('Benchmark.execute', () => {
+  it('returns an error report when executor task setup fails', async () => {
+    const pushAsync = mock.fn(() => Promise.reject(new Error('Benchmark "run" function references outer-scope variables: port')));
+    const kill = mock.fn();
+
+    mock.module('../executor.ts', {
+      namedExports: {
+        createExecutor: () => ({ pushAsync, kill }),
+      },
+    });
+
+    const { Benchmark } = await import('../index.ts');
+
+    const bench = Benchmark.create('feed');
+    bench.target('target').measure('run', () => 1);
+
+    const reports = await bench.execute();
+
+    assert.deepStrictEqual(reports, [
+      {
+        target: 'target',
+        measures: [
+          {
+            measure: 'run',
+            feeds: [
+              {
+                feed: 'feed',
+                data: {
+                  count: 0,
+                  heapUsedKB: 0,
+                  dceWarning: false,
+                  error: 'Benchmark "run" function references outer-scope variables: port',
+                },
+              },
+            ],
+          },
+        ],
+      },
+    ]);
+    assert.strictEqual(pushAsync.mock.callCount(), 1);
+    assert.strictEqual(kill.mock.callCount(), 1);
+
+    mock.restoreAll();
+  });
+});