@holoscript/benchmark

Performance benchmarking suite for HoloScript parser, type checker, formatter, and LSP.

Installation

npm install @holoscript/benchmark

Running Benchmarks

# All suites
npm run bench:all

# Individual suites
npm run bench:parser
npm run bench:compiler
npm run bench:typechecker
npm run bench:formatter

# CI mode (JSON output)
npm run bench:ci

Benchmark Suites

Parser

Measures full and incremental parse performance across fixture sizes:

import { runParserBench } from '@holoscript/benchmark';

const bench = await runParserBench();
// Benchmarks: parse-small, parse-medium, parse-large
// Benchmarks: incremental-small-single-edit, incremental-medium-single-edit, incremental-large-single-edit

Compiler

Measures compilation, incremental recompilation, trait diffing, and cache serialization:

import { runCompilerBench } from '@holoscript/benchmark';

const bench = await runCompilerBench();
// Benchmarks: compile-full-*, compile-incremental-*, diff-trait-config-*
// Benchmarks: recompilation-set-*, cache-serialize, cache-deserialize

Formatter

Measures full-file and range formatting:

import { runFormatterBench } from '@holoscript/benchmark';

const bench = await runFormatterBench();
// Benchmarks: format-small, format-medium, format-large
// Benchmarks: format-range-small, format-range-medium

Type Checker

Measures type checking with and without trait validation:

import { runTypeCheckerBench } from '@holoscript/benchmark';

const bench = await runTypeCheckerBench();
// Benchmarks: typecheck-small, typecheck-medium, typecheck-with-trait-validation-small

Sync & Network

Measures high-frequency synchronization primitive performance:

import { runSyncBench } from '@holoscript/benchmark';

const bench = await runSyncBench();
// Benchmarks: quantize-position, dequantize-position, compress-quaternion, measure-compression-ratio

Note on Network Exclusions: The JitterBuffer and PriorityScheduler components were migrated to the @holoscript/mesh package in v4.3+. Their benchmarking has been explicitly excluded from the core @holoscript/benchmark suite to unblock D.011 validation. Network load, buffering, and priority-queue scenarios are now measured exclusively in packages/mesh/__tests__/perf/ via Playwright network throttling environments.

Regression Detection

Compare results against a baseline to catch performance regressions:

# Save baseline
npm run bench:ci > baseline.json

# Compare against baseline
npm run bench -- --compare=baseline.json

import { extractResults, detectRegressions } from '@holoscript/benchmark';

const current = extractResults(bench, 'parser');
const report = detectRegressions(current, baseline, 0.1); // 10% threshold

Metrics Analysis

import { calculateMetrics, compareMetrics, formatMetrics } from '@holoscript/benchmark';

const metrics = calculateMetrics(task);
console.log(formatMetrics(metrics));
// "parse-small: 12,345 ops/sec (0.081ms/op)"

const regression = compareMetrics(baseline, current, 0.05);
if (regression.isRegression) {
  console.warn(`${regression.metric} regressed by ${regression.percentChange}%`);
}

Fixtures

Test fixtures in fixtures/:

| File | Description | | --------------- | ------------------------------------------------ | | small.hsplus | Small scene (1 template, 2 objects) | | medium.hsplus | Medium scene (2 templates, grid layout) | | large.hsplus | Large scene (multiple templates, complex traits) |

Exported Types

• BenchmarkResult - Individual benchmark result
• SuiteResults - Results for a suite
• AllResults - Complete benchmark run
• BenchmarkMetrics - Calculated metrics (hz, period, samples, stdDev)
• PerformanceRegression - Regression analysis result

License

MIT