easy_date_time

An enhanced DateTime implementation 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

EasyDateTime implements DateTime, so its values can be supplied to APIs that accept DateTime, while timezone behavior remains explicit.

Documentation

Installation

Stable release on pub.dev:

dependencies:
  easy_date_time: ^0.12.3

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