DateTime ↔️ timezone package: Interoperability of UTC, Local, and IANA Zones

Answer

Core DateTime has no IANA identifier. Preserve zone information by never relying on DateTime.isUtc / toLocal() alone. Store the IANA ID alongside the instant and reconstruct with timezone after loadTimeZones().

1. Pattern that preserves original zone information

Confirmed fact: DateTime only knows UTC or the OS local offset. Once a DateTime is created, its original IANA zone is lost.

Likely explanation: The safe mapping is:

• Keep the instant in UTC for storage/transport.
• Keep the IANA zone ID as a separate string field.
• Rehydrate with timezone only when you need zone-aware arithmetic.

Steps for this case:

1. Load tzdata once at app start: await timezone.initializeTimeZones();
2. If you have a UTC instant: final loc = timezone.getLocation('America/New_York'); final tz = timezone.TZDateTime.from(dateTimeUtc, loc);
3. If you have a local DateTime and you know its source zone: final tz = timezone.TZDateTime.from(dateTimeLocal, loc); Do not use loc = timezone.getLocation(timezone.getLocalLocation().name) for business logic.
4. Never do dateTime.toLocal() after a timezone conversion; it re-applies the OS local zone and discards the IANA ID.

If the source IANA zone is unknown for a local DateTime, zone information cannot be recovered. That is a data-model limitation, not a library bug.

2. Deterministic offsets across platforms during DST transitions

Confirmed fact: Offsets depend on the tzdata version loaded and the platform’s ICU/glibc resolution.

Deterministic steps:

1. Bundle a specific tzdata asset with the app and load it explicitly. Do not rely on the OS database.
2. Call loadTimeZones() before any conversion and never call findLocal() for server-side logic.
3. Always convert from UTC to the target IANA location: TZDateTime.from(utcInstant, location). This yields the same offset on Android, iOS, macOS and Linux when the same tzdata version is used.
4. Pin the tzdata version in dependencies and test known DST transition instants, e.g., spring forward and fall back for the zones you support.

Uncertainty: Platform differences in system local zone resolution remain if you mix toLocal() with timezone objects. Avoid that mix.

3. Mitigate runtime failures from missing or outdated tzdata

Confirmed fact: Using timezone without loading tzdata throws at runtime.

Production best practices:

• Initialize at startup with error handling: try load, catch, fall back to UTC and log.
• Ship a recent tzdata payload in the app bundle and verify it loads. Do not depend on host tzdata.
• Version-pin timezone and tzdata packages and schedule updates for tz database releases.
• Add a startup self-check that constructs TZDateTime for a known zone and asserts expected offsets for a fixed UTC instant.
• Avoid using getLocalLocation() for persistent data; use it only for UI display.

Missing diagnostic detail that changes recommendation: Are your incoming core DateTime values always UTC from the backend, or are some created locally without a known IANA ID? If local without ID, you need to change ingestion to capture the zone ID; otherwise zone cannot be preserved.