Timezone correctness, by region

ChronoShield is a correctness engine, not a wrapper around a date library. This page lists the specific edge cases the API is tested against — the exact bugs that catch most timezone code, the unusual zones that get forgotten, and the parity work that keeps the bundled tzdata aligned with the Luxon reference implementation.

All examples below correspond to actual tests in the public test suite. Run them yourself: git clone → npm test.

US spring-forward gap

On the second Sunday of March, US clocks jump from 02:00 to 03:00. Anything in [02:00, 03:00) simply doesn't exist that day. ChronoShield returns DST_GAP instead of silently shifting.

// 2026-03-08 02:30 in America/New_York — the gap
validateDateTime("2026-03-08T02:30:00", "America/New_York")
// → { status: "invalid", reason_code: "DST_GAP" }

// 2026-03-08 02:00 — the exact gap boundary
validateDateTime("2026-03-08T02:00:00", "America/New_York")
// → DST_GAP (start of skipped hour)

// 2026-03-08 01:59:59 — just before, valid
// 2026-03-08 03:00:00 — just after, valid

US fall-back overlap

On the first Sunday of November, US clocks fall back from 02:00 to 01:00. Anything in [01:00, 02:00) happens twice. ChronoShield returns DST_OVERLAP with both candidate UTC instants — the caller decides which one the user meant.

// 2026-11-01 01:30 in America/New_York — the overlap
validateDateTime("2026-11-01T01:30:00", "America/New_York")
// → {
//     status: "ambiguous",
//     reason_code: "DST_OVERLAP",
//     possible_instants: [
//       { offset: "-04:00", instant_utc: "2026-11-01T05:30:00.000Z" },
//       { offset: "-05:00", instant_utc: "2026-11-01T06:30:00.000Z" }
//     ]
//   }

// Same time, but resolve with explicit policy:
resolveDateTime(..., { ambiguous: "earlier" })  // first occurrence
resolveDateTime(..., { ambiguous: "later" })    // second occurrence
resolveDateTime(..., { ambiguous: "reject" })   // 400 with code DST_OVERLAP

EU transitions (last Sunday of March / October)

Europe shifts on different dates from the US, which is exactly the trap distributed teams hit when they assume "DST is universal." ChronoShield tests Europe/London (last Sunday in March) explicitly, plus Europe/Berlin scenarios via the parity sweep.

// 2026-03-29 01:30 in Europe/London — spring-forward gap
validateDateTime("2026-03-29T01:30:00", "Europe/London")
// → DST_GAP (London goes 01:00 → 02:00, skipping the 01:00–02:00 hour)

Australia/Lord_Howe — 30-minute DST shift

Lord Howe Island is the only timezone in the world that shifts by 30 minutes for DST instead of an hour: UTC+10:30 standard, UTC+11:00 DST. Most "shift by an hour" assumptions in scheduling code are silently wrong here.

// 2026-10-04 02:15 (first Sunday in October) — clocks jump 02:00 → 02:30
validateDateTime("2026-10-04T02:15:00", "Australia/Lord_Howe")
// → DST_GAP (the skipped slot is 30 minutes wide, not 60)

// 2026-04-05 01:45 — fall-back, clocks go 02:00 → 01:30
validateDateTime("2026-04-05T01:45:00", "Australia/Lord_Howe")
// → DST_OVERLAP (1:45 happens twice, 30-minute overlap window)

Pacific/Chatham — UTC+12:45 with DST

The Chatham Islands sit at UTC+12:45 (standard) / UTC+13:45 (DST) — the most extreme non-hour offset on the planet. Date math that assumes hour-aligned offsets breaks here.

convertTime("2026-06-15T00:00:00Z", "Pacific/Chatham")
// Standard time (June, southern winter):
// → { local_datetime: "2026-06-15T12:45:00", offset: "+12:45" }

convertTime("2026-12-15T00:00:00Z", "Pacific/Chatham")
// DST (December, southern summer):
// → { local_datetime: "2026-12-15T13:45:00", offset: "+13:45" }

Asia/Kathmandu — UTC+5:45 (no DST, unusual offset)

Nepal's offset is 45 minutes off the nearest hour boundary — year-round, no DST. ChronoShield's resolve converts local Nepal time to UTC with the correct fractional offset.

resolveDateTime("2026-06-15T12:00:00", "Asia/Kathmandu", ...)
// → { instant_utc: "2026-06-15T06:15:00.000Z", offset: "+05:45" }
// (Note the :15 minute offset, not :00)

Asia/Tehran — Iran (irregular DST policy)

Tehran sits at UTC+3:30, with DST rules that have changed multiple times by political decree. Most date libraries lag the Iranian government's announcements; ChronoShield refreshes monthly from the IANA tzdb.

convertTime("2026-01-15T00:00:00Z", "Asia/Tehran")
// → { local_datetime: "2026-01-15T03:30:00", offset: "+03:30" }

Africa/Casablanca — Morocco's Ramadan-linked DST

Morocco uses UTC+1 year-round since 2018 but temporarily switches to UTC+0 during Ramadan, a religious-calendar-driven transition that doesn't fit any spring/fall pattern. ChronoShield validates both states correctly.

validateDateTime("2026-07-15T12:00:00", "Africa/Casablanca")  // standard period
// → valid

// During Ramadan, the offset shifts. Tests verify both regimes hold.

Southern hemisphere DST (Fiji, Santiago)

DST in the southern hemisphere happens on opposite dates from the north. Fiji and Santiago are tested explicitly because they're common business destinations where naive "DST starts in March" assumptions fail.

// Fiji: UTC+12, southern hemisphere
convertTime("2026-06-15T00:00:00Z", "Pacific/Fiji")  // southern winter, no DST
// → offset +12:00

// Santiago: tested for the unique transition dates Chile uses
resolveDateTime("2026-06-15T12:00:00", "America/Santiago", ...)
// → correct UTC instant for southern winter

The international date line & extreme zones

Pacific/Apia (Samoa) famously skipped December 30, 2011 entirely when it jumped from UTC−11 to UTC+13. Etc/GMT+12 is the most negative fixed offset. UTC itself is the no-op baseline that should always validate. All three are explicit tests.

// Samoa — one of the most forward-shifted timezones
convertTime("2026-06-15T00:00:00Z", "Pacific/Apia")
// → { local_datetime: "2026-06-15T13:00:00", offset: "+13:00" }

// Crossing the date line via Etc/GMT+12 (UTC−12)
convertTime("2026-06-15T00:00:00Z", "Etc/GMT+12")
// → { local_datetime: "2026-06-14T12:00:00", offset: "-12:00" }
// (Note: yesterday's date in local time)

Bundled-tzdata parity sweep vs. Luxon

ChronoShield ships its own bundled IANA-zone implementation (decoupled from system ICU and from a fixed Luxon version) so deploys aren't gated on the host's tzdata. To prove the bundle stays correct, every CI run sweeps the offset for every zone moment-timezone knows about at six representative timestamps and asserts byte-equality with Luxon's IANAZone.

• Sample timestamps include 2026 NY spring-forward and fall-back windows, summer 1985, end-of-2000, and 2035.
• ~600+ zones × 6 timestamps = ~3,500+ comparisons per run.
• Any divergence fails the build with the exact zone, instant, and the two offsets that disagreed.

Transition-boundary fuzz testing

Beyond the regular grid, a fuzz suite seeds random zone × timestamp pairs and probes around DST transitions specifically — the moments where bundled and reference implementations are most likely to drift on a tzdb update. Combined with the parity sweep, this catches subtle regressions before they reach the API.

tzdb update cadence

ChronoShield tracks IANA tzdb releases monthly — the same schedule as the upstream tzdb release schedule. The currently-served version is exposed at /v1/datetime/version in JSON, and a scheduled GitHub Action checks for new tzdb releases and opens a PR automatically.

GET /v1/datetime/version
→ {
    "tzdb_version": "2026b",
    "tzdb_source": "moment-timezone",
    "tzdb_source_version": "0.6.2",
    "api_version": "1.3.0"
  }