Performance Benchmarks
Relevant source files
The following files were used as context for generating this wiki page:
Performance Benchmarks in the Better Tables project serve as a deterministic gate and trend-tracking system to ensure high-speed data handling and interaction latency. The system is categorized into four distinct tiers ranging from zero-wall-clock interaction cost gates to machine-dependent micro-benchmarks and E2E latency measurements.
The primary goal is to prevent regressions in runtime speed, type instantiation costs, and felt interaction latency (such as pagination clicks or filter commits). These benchmarks utilize tools like mitata for micro-benchmarks and Playwright for E2E interaction characterization.
Sources: plans/063-performance-test-harness.md:38-51, packages/core/bench/index.ts:1-12
Multi-Tier Benchmark Architecture
The performance testing strategy is structured into four tiers to balance machine independence with real-world latency measurement.
The diagram shows the hierarchy of performance testing, starting from deterministic unit-level counts to high-level E2E interaction timing.
Sources: plans/063-performance-test-harness.md:126-140
Tier 1 & 2: Deterministic Gates
These tiers focus on machine-independent metrics. Tier 1 asserts exact integers for operations such as the number of fetchData calls per pagination click or SQL statements per adapter operation. Tier 2 measures growth ratios (e.g., 1k vs 10k rows) to detect $O(n^2)$ regressions without failing due to environment-specific wall-clock variance.
Sources: plans/063-performance-test-harness.md:126-133, plans/063-performance-test-harness.md:213-228
Core Runtime Micro-benchmarks (Tier 3)
The project utilizes mitata to track trends in core manager operations, URL serialization, and filter node processing. Results are stored as JSON in bench-results/ to facilitate long-term trend analysis.
Benchmark Categories
| Feature | Benchmark Scope | Source File |
|---|---|---|
| Pagination | Page transitions on 100k rows | packages/core/bench/index.ts:140-150 |
| Sorting | State mutation via toggleSort | packages/core/bench/index.ts:152-158 |
| Filtering | Validation and state replacement for 50-leaf arrays | packages/core/bench/index.ts:160-166 |
| URL Serialization | LZ-string compression of complex filter trees | packages/core/bench/index.ts:171-186 |
| Data Transformation | Nested structure transformation (1k/10k rows) | packages/adapters/toolkit/bench/index.ts:121-137 |
Transformation Scaling Logic
The DataTransformer benchmark measures the cost of nested structure transformation across different dataset sizes and relationship cardinalities (flat vs. one-to-many fan-out).
Type Instantiation Performance
Better Tables enforces strict budgets on TypeScript instantiation costs to maintain developer experience (DX). High instantiation counts lead to slow IDE feedback and long build times.
- Hard Gate: Instantiations $\le 2,000,000$ per fixture.
- Loose Gate: Check time $\le 7.5$ seconds (Slack for slow CI runners).
- Fixtures: Measured using
tsc --extendedDiagnosticson specific projects liketsconfig.filter-perf.jsonandtsconfig.table-def-perf.json.
Sources: plans/063-performance-test-harness.md:248-257, plans/011-table-definition-dx-design.md:309-325, packages/core/bench/index.ts:192-225
E2E Interaction Latency (Tier 4)
Interaction benchmarks measure the "felt" lag in production-built applications using Playwright. These tests utilize a 4x CPU throttle to simulate average hardware and repeat interactions 15 times to generate stable p50/p75 metrics.
Measured Interactions
- Pagination:
Next page/Previous pageclick to first row data swap. - Sorting: Header click to row re-ordering.
- Facets: Toggle sidebar filter to counts/rows update.
Sources: apps/marketing/e2e/perf-interactions.e2e.ts:135-179
Implementation Details
Result Reporting
Benchmark results are aggregated into standardized JSON formats using a BenchEntry interface. This allows the github-action-benchmark tool to process different metrics (nanoseconds, milliseconds, or instantiation counts) under a unified customSmallerIsBetter strategy.
interface BenchEntry {
name: string;
unit: string; // "ns", "ms", or "instantiations"
value: number;
}
Sources: packages/core/bench/index.ts:40-44, plans/063-performance-test-harness.md:290-297
Summary
The Performance Benchmark suite ensures that Better Tables remains a high-performance library by pinning operation costs at the unit, adapter, and E2E levels. By separating deterministic gates (Tier 1/2) from environmental trends (Tier 3/4), the project maintains stable CI gates while continuously monitoring real-world latency and scalability.