Temporal vs Date: JavaScript Time Architecture Lab

Base ISO Datetime

Target IANA Timezone

Duration to Add (Days)

DST Disambiguation Mode

LEGACY HAZARD JavaScript `Date` API

1995 Netscape Spec

            // ⚠️ Traps: 0-indexed months & in-place mutation

            const d = new Date(2026, 2, 15); // Month 2 is March!

            d.setDate(d.getDate() + 16); // Silent mutation!

Month Index Interpretation 2 (March, 0-indexed)

Memory Mutation Hazard Mutates in-place (original modified)

ISO String Output 2026-03-31T06:30:00.000Z

Timezone & DST Safety Skips or duplicates hour across 2026-03-08 DST transition without zone metadata

Parsing Reliability Implementation-dependent local vs UTC shift

Heap Memory Pointer State

Reference 'originalDate'

2026-03-31 (OVERWRITTEN)

Reference 'updatedDate'

Same Pointer (d === result)

TEMPORAL GUARANTEE TC39 Stage 4 `Temporal` API

Pure & Immutable

            // ✅ Guarantee: 1-12 months & pure immutability

            const pDate = Temporal.PlainDate.from('2026-03-15');

            const next = pDate.add({ days: 16 }); // New object returned

Month Index Interpretation 3 (March, 1-12 standard)

Immutability Guarantee Pure returns new Temporal.PlainDate(2026, 3, 31)

Temporal Result String 2026-03-31

Timezone & DST Resolution 2026-03-08T03:00:00-04:00[America/New_York]

Strict Parsing Engine Explicit ISO 8601 strict validation (2026-03-15)

Heap Memory Pointer State

Reference 'originalPlainDate'

2026-03-15 (PRESERVED)

Reference 'nextPlainDate'

2026-03-31 (NEW INSTANCE)

Daylight Saving Time (DST) Gap & Overlap Visualizer

Transition Day Hour Scrubber (00:00 to 06:00 wall-clock) 02:30:00 (Invalid Gap Time)

00:00 EST 01:00 EST 02:00 [SKIPPED] 03:00 EDT 04:00 EDT 05:00 EDT 06:00 EDT

⚠️ Spring-Forward Gap Analysis: Wall-clock time 02:30:00 does not exist on March 8, 2026 in America/New_York. Legacy new Date('2026-03-08T02:30:00') produces platform-dependent erratic offsets. Temporal.ZonedDateTime.from() with disambiguation: 'compatible' cleanly and deterministically advances to 2026-03-08T03:30:00-04:00[America/New_York].

        // Migration snippet generated for Month 0-Index & Immutability

        // Before:

        const legacyDate = new Date(2026, 2, 15);

        legacyDate.setDate(legacyDate.getDate() + 16);

        // After (TC39 Stage 4 Temporal):

        const plainDate = Temporal.PlainDate.from({ year: 2026, month: 3, day: 15 });

        const result = plainDate.add({ days: 16 }); // => 2026-03-31

Production Ready: TC39 Stage 4 specifications & ISO 8601 calendar standard.