easy_date_time 0.12.2

A drop-in replacement for Dart's `DateTime` with IANA timezone support.

easy_date_time

A DateTime-compatible API for Dart and Flutter with explicit IANA timezone handling and deterministic parse policies.

Why this package

Dart DateTime.parse() normalizes offset inputs to UTC. In timezone-heavy applications, this often changes the wall-clock value that users entered.

DateTime.parse('2026-01-18T10:30:00+08:00').hour;    // 2
EasyDateTime.parse('2026-01-18T10:30:00+08:00').hour; // 10

easy_date_time keeps DateTime API compatibility while making timezone behavior explicit.

Documentation

• Migration guide
• Project documentation guide
• API reference
• Contribution guide

Installation

Stable release on pub.dev:

dependencies:
  easy_date_time: ^0.12.2

Requirements

• Dart SDK: >=3.10.0 <4.0.0
• Initialize timezone data once before timezone-aware operations

import 'package:easy_date_time/easy_date_time.dart';

void main() {
  EasyDateTime.initializeTimeZone();
}

Quick start

final source = EasyDateTime.parse(
  '2026-01-18T10:30:00+08:00',
  options: const EasyParseOptions(),
);
final ny = source.inLocation(TimeZones.newYork);

print(source.hour);          // 10
print(source.locationName);  // UTC+08:00 in fixed mode
print(ny.locationName);      // America/New_York

If you omit options, parse() keeps the legacy region-inference path for migration compatibility.

Parse policy model

Parse mode

Mode	Purpose	Behavior
legacy	Preserve historical behavior	Region-based offset resolution
compatible	Default when explicit options are passed	Permissive parsing with normalization
isoStrict	Strict calendar validation	Rejects invalid calendar dates; it is not ISO-only parsing

Offset resolution

Strategy	Resulting location	Typical use
OffsetResolution.fixed	Synthetic UTC±HH:MM	Preserve exact offset identity
OffsetResolution.region	IANA location lookup result	Prefer regional timezone semantics

final dt = EasyDateTime.parse(
  '2026-01-18T10:30:00+08:00',
  options: const EasyParseOptions(
    mode: EasyParseMode.compatible,
    offsetResolution: OffsetResolution.fixed,
  ),
);

Common tasks

Create values with an explicit timezone

final tokyoNow = EasyDateTime.now(location: TimeZones.tokyo);
final meeting = EasyDateTime(
  2026,
  5,
  3,
  9,
  30,
  0,
  0,
  0,
  TimeZones.london,
);

Run calendar arithmetic across DST transitions

final ny = TimeZones.newYork;
final beforeDst = EasyDateTime(2025, 3, 9, 0, 0, 0, 0, 0, ny);

final wallClock = beforeDst.addCalendarDays(1);       // 2025-03-10 00:00
final physical = beforeDst.add(const Duration(days: 1)); // 2025-03-10 01:00

If a calculated local time falls in a DST gap or overlap, the timezone database applies its implicit, region-specific resolution.

Format output

final formatted = EasyDateTime.now(location: TimeZones.tokyo)
    .format('yyyy-MM-dd HH:mm:ss xxxxx');

Preserve a numeric offset when reading ISO 8601 / JSON data

final restored = EasyDateTime.fromIso8601String(
  storedValue,
  options: const EasyParseOptions(),
);

DateTime API mapping

Existing API	easy_date_time
DateTime.now()	EasyDateTime.now()
DateTime.utc(...)	EasyDateTime.utc(...)
DateTime.parse(String)	EasyDateTime.parse(String, options: ...)
DateTime.tryParse(String)	EasyDateTime.tryParse(String, options: ...)
DateTime.fromMillisecondsSinceEpoch(ms)	EasyDateTime.fromMillisecondsSinceEpoch(ms)
DateTime.toUtc()	EasyDateTime.toUtc()
DateTime.toLocal()	EasyDateTime.toLocal()
No IANA location model	inLocation(TimeZones.xxx)
No global location override	setDefaultLocation(...) / clearDefaultLocation()

Compatibility boundary

EasyDateTime can be passed to APIs that accept DateTime. Dart extension methods dispatch from the static receiver type: calling copyWith() through a DateTime reference returns a core DateTime, so use EasyDateTime APIs when an IANA location must remain available.

Migration notes for v0.12

• strict: false maps to EasyParseMode.compatible
• strict: true maps to EasyParseMode.isoStrict
• strict is deprecated in parse() and tryParse()

// Before
EasyDateTime.parse(input, strict: true);

// After
EasyDateTime.parse(
  input,
  options: const EasyParseOptions(mode: EasyParseMode.isoStrict),
);

For full migration details, see doc/migration/v0_12_migration_guide.md.

Support

• Issues: https://github.com/MasterHiei/easy_date_time/issues
• Pull requests are welcome. See CONTRIBUTING.md