perf(time): cache the IANA UTC offset instead of re-formatting per call

[vinay-veerappa]

The problem

Pine time functions run once per bar, and a script with per-bar day-key logic makes several calls per bar. timestamp(TZ, ...) and year()/month()/dayofmonth()/hour()/dayofweek() with an IANA timezone each resolve that timezone through Intl.DateTimeFormat on every call.

Profiled on a real 10k-bar chart execute (an HTF-EMA-style script making ~15 IANA time calls per bar at global scope; Node ICU):

	self time
_timestampFromIANA	58.6%
getDatePartsInTimezone	20.5%
	79% of a 33s execute

Why memoizing the formatter is only half of it

Two costs are stacked, and fixing one leaves most of the time on the table:

	cost
new Intl.DateTimeFormat(...)	~41 µs
formatter.formatToParts(date)	~3.9 µs
parts read off a cached offset	~0.12 µs

Memoizing the formatter instance (they're pure functions of (locale, options) per ECMA-402) removes the 41 µs and takes the execute 33s → 26s — but timezone math is still 40% of the profile, because formatToParts remains per call.

Caching the resolved offset removes that too: 26s → 15s, with timezone functions dropping to 2% of the profile. Overall 33s → 15s.

src/namespaces/tzOffset.ts is the shared primitive both hot paths reduce to.

How the cache stays exact

An IANA offset is piecewise constant in UTC and the pieces are months long. The cache stores the offset at UTC-midnight boundaries:

• a UTC day whose two boundaries agree carries that offset throughout, so calendar parts are read arithmetically;
• a UTC day whose boundaries disagree contains a transition, and every instant in it falls through to the original formatToParts path.

So the cache never approximates across a transition. Adjacent days share a boundary probe, which means one formatToParts per calendar day regardless of bar interval — strictly cheaper than uncached even on a daily chart (one probe per bar versus one per call).

One assumption, stated in the module header: no zone transitions twice within a single UTC day and returns to the same offset. No entry in the IANA database does this.

An hour-bucketed cache would be simpler and is wrong — Australia/Lord_Howe shifts 30 minutes at an instant that isn't on a UTC hour boundary. It's in the test matrix for exactly that reason.

Behaviour

• _timestampFromIANA keeps its single-pass semantics exactly (a wall-clock time inside a DST gap or fold is genuinely ambiguous, and Pine resolves it this way) — only the offset lookup changed.
• getDatePartsInTimezone now derives dayOfWeek arithmetically instead of parsing a localized weekday string. Same result, one less locale dependency.

Tests

tests/namespaces/timezone-offset.test.ts uses Intl itself as the oracle and sweeps every hour of eight transition days across six zones — America/New_York, Europe/London, Australia/Sydney, Asia/Kolkata, Asia/Kathmandu, Australia/Lord_Howe — plus minute resolution across the US spring-forward instant, fixed-offset spellings, and the unknown-zone fallback. One case asserts the cached offset equals the uncached offset on a transition day and that the day genuinely straddles a change, so it can't pass vacuously.

tests/namespaces/timezone-perf.test.ts is a regression guard: 35k bars × 5 IANA calls per bar, bounded at 2000ms. ~2890ms unfixed, ~440ms fixed.

Negative control: replacing the boundary comparison with an unconditional day-start offset fails 3 of the 6 correctness cases.

Suite status

main and this branch have the same 139 pre-existing failures:

	failed	passed
main (beacd58)	139	1744
this branch	139	1752

The +8 are the tests added here. I haven't touched the pre-existing failures — happy to look at them separately if useful.

Notes for review

• No public API change; no new dependency.
• src/namespaces/Core.ts already fails prettier --check on main, so I deliberately did not run --write over it — that would have buried this diff in unrelated reformatting. The new files are prettier-clean and my edits add no new violations.
• CONTRIBUTING asks for a Discussion before architectural changes. I read this as a perf fix to existing functions rather than an architectural one (it doesn't touch the transpiler, Series, or Context), but say the word and I'll move it to a Discussion.

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[vinay-veerappa]

I have read the CLA Document and I hereby sign the CLA