Add opt-in timing instrumentation

[peachbits]

CHANGELOG

Does this branch warrant an entry to the CHANGELOG?

• Yes
• No

Dependencies

#23

Description

Adds opt-in timing instrumentation on top of #23.

biggyTimer('start' | 'stop') toggles collection. getBiggyStats() returns the totals and printBiggyStats() logs them. While running, it tracks total wall-clock time spent inside the public API (re-entrancy guarded, so nested calls count once) and the share spent in the native BigInt math. Disabled by default, so it adds no measurable cost to normal use.

It prefers performance.now() when present (always in a WebView, and in modern Hermes) and falls back to Date.now(), so it works in both the React Native and plugin-WebView environments.

Useful for measuring where biggystring spends time across implementations and engines. Depends on #23 and targets the bigint branch, so it should land after #23.

---

Note

Low Risk
Instrumentation is off by default and does not change numeric results; risk is limited to optional profiling overhead and console logging when explicitly started.

Overview
Adds opt-in wall-clock profiling so callers can compare biggystring cost across engines and implementations without affecting normal use when it is off.

Public math helpers (add, mul, toBns, comparisons, etc.) run through a re-entrancy-aware time() wrapper that only records when biggyTimer('start') is active; when disabled, time() returns immediately with no timing work. parseBigInt additionally splits out time spent in native BigInt parsing when profiling is on.

New surface: biggyTimer('start' | 'stop') (periodic console stats every 5s while running), getBiggyStats(), printBiggyStats(), resetBiggyStats(), and the BiggyStats type. Clock source prefers performance.now() with Date.now() fallback. CHANGELOG documents the feature under 5.0.0.

^{Reviewed by Cursor Bugbot for commit ec17080. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8585b4e. Configure here.}

[cursor]

Repeated start leaks intervals

Medium Severity

Calling biggyTimer('start') again without an intervening stop assigns a new setInterval without clearing the previous one. Earlier timers keep firing printBiggyStats every five seconds, so logs duplicate and intervals leak for the process lifetime.

 

^{Reviewed by Cursor Bugbot for commit 8585b4e. Configure here.}

[cursor]

Running time grows after stop

Low Severity

After biggyTimer('stop'), getBiggyStats() still computes totalRunningMs as now() - biggyStartTime because biggyStartTime is never cleared or frozen on stop. The accumulated biggystringMs and bigintMs stop changing, but the reported session duration and percentage ratios keep increasing on later reads.

Additional Locations (1)

• src/index.ts#L360-L366

 

^{Reviewed by Cursor Bugbot for commit 8585b4e. Configure here.}