benchmark_types.ts

Target measurement duration per task in milliseconds. The loop runs at least min_iterations iterations *and* at least this long, with max_iterations and on_iteration abort() as hard ceilings. Default: 1000ms

Number of warmup iterations before actual measurements. Warmup helps stabilize JIT compilation and caches. Default: 10

Cooldown time between tasks in milliseconds. Lets the runtime settle GC and (partially) thermal state between tasks. Fixed regardless of the previous task's duration or allocation footprint — if a suite mixes heavy and light tasks, raise this so light tasks downstream don't run in the prior task's GC shadow. Default: 100ms

Minimum number of iterations to run. The loop continues past duration_ms if needed to reach this floor, so raising it in a slow suite extends wall-clock past duration_ms.

The default (30) is sized so the Welch's-t DOF approximation used by benchmark_stats_compare stays stable on the floor case. Lowering it below ~15 produces statistically unreliable significance calls on slow tasks that hit the floor exactly — the math still runs but comparison.significant becomes a coin flip on noisy outliers.

Default: 30

Maximum number of iterations to run. Prevents infinite loops on extremely fast functions, and also sizes the pre-allocated timings array — set this only as high as you expect to fill, since oversized caps waste memory and add GC pressure during measurement. Default: 100000

Custom timer to use for measurements. Default: timer_default (auto-detects environment)

Callback invoked after each iteration completes. Useful for triggering garbage collection, logging progress, early termination, or custom instrumentation.

Note: The callback time is NOT included in iteration measurements - it runs after the timing capture. However, frequent GC calls will slow overall benchmark execution time.

Callback invoked after each task completes. Useful for logging progress during long benchmark runs.

Group results by category using filter functions.

Display name for the group

Optional description shown below the group name

Filter function to determine which results belong to this group

Task name to use as baseline for the "vs" column. When specified, ratios are computed against this task instead of the fastest. If the baseline task is not found in the group, falls back to "vs Best" with a warning.

Task name

Statistical analysis of the benchmark

Number of iterations executed

Total wall-clock time for the task (setup + warmup + measurement + teardown) in milliseconds

Raw timing data for each iteration in nanoseconds. Length equals iterations (the array is right-sized after measurement). Useful for custom statistical analysis, histogram generation, or exporting to external tools.

Effective per-task time budget after applying overrides to suite defaults. Persisted into baselines so benchmark_baseline_compare can detect methodology drift — a min_iterations bump between baseline and current shifts Welch's DOF and produces "regressions" that are sample-size artifacts, not real drift.

Name of the task (for display)

Function to benchmark (sync or async). Return values are ignored.

Optional setup function run before benchmarking this task. Not included in timing measurements.

Mutations to fn and name made here are honored by the measurement loop — useful for dynamic configuration that depends on async state resolved during setup.

Optional teardown function run after benchmarking this task. Not included in timing measurements.

If true, skip this task during benchmark runs. Useful for temporarily disabling tasks during development.

If true, run only this task (and other tasks marked only). Useful for focusing on specific tasks during development.

Hint for whether the function is sync or async. Auto-detected during warmup if not set; async: false skips per-iteration promise checking for sync functions, while async: true forces an await on every measurement iteration.

Setting async: true on a function that returns sync forces an unnecessary microtask per iteration — for sub-microsecond functions this adds measurable bias. Prefer leaving async undefined (auto- detected during warmup) unless the conditional-async hazard below applies.

Required for conditional-async fns — without async: true, a first call that happens to return synchronously locks in the sync code path and any later Promise returns leak as unhandled rejections.

Override the suite's duration_ms for this task only. Useful when one task is much slower than others and needs a longer (or shorter) measurement window than the suite default.

Override the suite's warmup_iterations for this task only. Slow tasks may want fewer warmup iterations to keep wall-clock reasonable; tight/complex functions may want more so TurboFan reaches steady state.

Override the suite's min_iterations for this task only. Raise this on slow tasks so percentile and CI math have enough samples. Wins over duration_ms (see the suite field) — a slow task with a raised floor extends wall-clock until the count is reached.

Prefer raising this over duration_ms when you need more samples: per-iteration noise (GC, scheduler, thermal) is a time-rate process, so a longer wall-clock window proportionally inflates exposure to rare tail events. Raising the sample floor fixes the statistical-power problem without that inflation.

Override the suite's max_iterations for this task only. Cap a fast task to a fixed sample count, or raise the ceiling on a slow task that would otherwise be limited by the suite default. Also sizes the per-task pre-allocation — avoid extreme caps that won't actually be filled. When this differs sharply across tasks in the same suite, the larger allocation can leak GC pressure into subsequent tasks (cooldown_ms is fixed regardless of prior task footprint).