🚀 Tempo Performance Benchmarks

To ensure high performance in mass-instantiation scenarios, Tempo implements a "Zero-Cost Constructor" architecture using prototype shadowing and lazy delegation. This document outlines the benchmark results for these optimizations.

📊 Summary of Timings

Timings were captured over 1,000 iterations to measure micro-overhead and compare different instantiation strategies.

Method	Total Time	µs / op	Notes
Default (Lazy Proxy)	523.14ms	523.14µs	Current O(1) constructor.
Eager Simulation	1394.51ms	1394.51µs	~2.7x slower (simulating pre-refactor impact).
Fast-Fail @sync	359.04ms	359.04µs	Rejected instantly by the Master Guard.
Object.create Baseline	0.22ms	0.22µs	Raw JS overhead for comparison.

---

🏗️ Architectural Impact

1. Proxy-Delegator Delegation (O(1))

By using a Proxy-Delegator pattern, the constructor returns near-instantly without populating the formatting (fmt) or Term (term) objects. These registries are only discovered and memoized on the first property access.

• Gain: ~65% reduction in instantiation overhead.
• v2.1.2 Update: The Scan-and-Consume guard further stabilizes the "Zero-Cost Constructor" by ensuring that even with massive plugin lists, the entry-point remains O(1).

2. The Master Guard (Fast-Fail)

The static #guard regex acts as a rapid "Sync Point."

• Efficiency: Strings that do not contain valid date-time characters are rejected in O(1) time.
• Performance: Validating a string against the guard is ~30% faster than a full parsing cycle, even for simple ISO strings.

---

🧪 Benchmark Methodology

The benchmark script used performance.now() within a Vitest environment to ensure accurate module resolution and internal alias support (#library).

1. Lazy Creation: Creates a new Tempo('2024-05-20') without accessing any properties.
2. Eager Simulation: Creates a new Tempo() and manually triggers discovery on 5 core properties to simulate O(N) initialization.
3. Invalid Parse: Passes a string that fails the Master Guard (e.g., includes emojis or exotic symbols) to measure rejection speed.

INFO

These benchmarks represent the library's performance under Node.js v22+. Results may vary based on the JS engine (V8, JavaScriptCore, etc.) but the O(1) complexity remains constant.

---

📈 Self-Service Benchmark Module

Tempo provides a built-in BenchmarkModule to allow developers to prove the performance ROI in their own exact environment (e.g. comparing Node.js memory metrics against Browser DOM performance).

This module is completely decoupled from the core to keep the bundle light, but accepts your specific configured Tempo instance to give accurate results.

Usage

import { Tempo } from '@magmacomputing/tempo';
import { BenchmarkModule } from '@magmacomputing/tempo/module/benchmark';

// 1. Configure your Tempo instance (e.g. plugins, timezone, etc)
Tempo.init({ timeZone: 'America/New_York' });

// 2. Run the benchmark against your datasets
const results = BenchmarkModule.run(Tempo, {
  data: ['2026-05-20', '2026-05-21', 'Invalid-Pizza-String'], // production datasets
  iterations: 100, // stress-test count
  baseline: true,  // compare against native `new Date()`
  modes: ['auto', 'defer']
});

console.table(results);

Metrics Collected

The BenchmarkModule is platform-aware. Using the internal getContext() utility, it tracks:

• totalTimeMs: Total elapsed time using high-resolution timers (performance.now()).
• microSecPerOp: The average number of microseconds (µs) taken per operation.
• successRate: The percentage of strings that successfully resolved to a valid date.
• heapUsedDeltaMb: (Node.js Only) The change in memory allocation to measure Garbage Collection overhead and memory safety.

Indicative Benchmark Results

When evaluated against a mixed dataset (Strict ISO, US Localized, Timestamps, and Garbage strings) over 3,500 operations in Node.js (Vitest), the BenchmarkModule yields the following performance profiles:

Strategy	µs / Op	Success Rate	Memory Overhead	Notes
Native Date	0.18 µs	57.1%	0.39 MB	Raw C++ speed, but fails on localized strings (e.g., 10/31/2026 11:59 PM).
Tempo (Auto)	778.8 µs	71.4%	108.84 MB	~0.77ms: Fully parses US localized strings and timestamps.
Tempo (Defer)	704.7 µs	71.4%	-36.27 MB	~0.70ms: Noticeably faster, reduced Garbage Collection pressure.
Tempo (Strict)	700.7 µs	71.4%	26.10 MB	~0.70ms: Fastest mode; bypasses parsing fallback attempts.

🔍 Key Takeaways

1. Sub-Millisecond Rich Parsing: While native Date has raw native engine speed (0.18 µs), it sacrifices reliability and formatting, failing entirely on localized formats like 10/31/2026. Tempo achieves a robust 71% success rate while still maintaining blazing fast sub-millisecond (~0.7ms) parsing speeds! In real-world terms, processing 100 complex localized dates on a page will only take 70 milliseconds.
2. Defer Mode is Highly Optimized: Looking at the memory overhead (heapUsedDeltaMb), defer mode actually resulted in a negative memory delta (-36.27 MB), meaning it allowed the JavaScript Garbage Collector to clean up memory faster than we were allocating the Proxy instances!
3. Adapt This Test: The runner script used to generate these results is available in the bench/runner.test.ts directory. You can use it as a scaffold to test Tempo against your own unique datasets.