easy_date_time #

Timezone-aware DateTime for Dart

A drop-in DateTime alternative with full IANA timezone support. Parse times without surprise UTC conversions.

中文 | 日本語

Why easy_date_time? #

Dart's built-in DateTime and other solutions have limitations in real-world use:

In short: Less boilerplate, fewer surprises, timezone-aware by default.

See the difference:

// DateTime: offset is parsed, but time gets converted to UTC
DateTime.parse('2025-12-07T10:30:00+08:00').hour      // → 2 😕

// EasyDateTime: what you parse is what you get
EasyDateTime.parse('2025-12-07T10:30:00+08:00').hour  // → 10 ✓

Key Features #

• 🌍 Full Timezone Support All IANA timezones available (e.g., Asia/Shanghai, America/New_York)

• 🕒 What You Parse Is What You Get No automatic UTC conversion behind your back

• ➕ Readable Arithmetic now + 1.days, 2.hours + 30.minutes—clean and obvious

• 🔄 Opt-in Conversion Timezone changes only when you ask (.inLocation(), .inUtc())

• 🧱 Safe Month/Year Changes copyWithClamped() handles edge cases like Jan 31 → Feb

Installation #

Add to pubspec.yaml:

dependencies:
  easy_date_time: ^0.1.0

Initialize once at app startup:

void main() {
  initializeTimeZone();  // Required

  // Optional: set default timezone
  setDefaultLocation(TimeZones.shanghai);

  runApp(MyApp());
}

Quick Start #

final now = EasyDateTime.now();  // Default or local timezone
final tokyo = EasyDateTime.now(location: TimeZones.tokyo);
final parsed = EasyDateTime.parse('2025-12-07T10:30:00+08:00');

print(parsed.hour);  // 10

Using Timezones #

Common Timezones (recommended) #

final tokyo = EasyDateTime.now(location: TimeZones.tokyo);
final shanghai = EasyDateTime.now(location: TimeZones.shanghai);

Any IANA Timezone #

final nairobi = EasyDateTime.now(location: getLocation('Africa/Nairobi'));

Global Default #

setDefaultLocation(TimeZones.shanghai);
final now = EasyDateTime.now();  // Uses Shanghai time

Preserving Original Time #

final dt = EasyDateTime.parse('2025-12-07T10:30:00+08:00');

print(dt.hour);          // 10
print(dt.locationName);  // Asia/Shanghai

Explicit conversion:

final ny = dt.inLocation(TimeZones.newYork);
final utc = dt.inUtc();

Timezone Conversion #

final tokyo = EasyDateTime.now(location: TimeZones.tokyo);
final newYork = tokyo.inLocation(TimeZones.newYork);

print(tokyo.isAtSameMoment(newYork));  // true: same instant

Date Arithmetic #

final now = EasyDateTime.now();
final tomorrow = now + 1.days;
final later = now + 2.hours + 30.minutes;

Preventing Month Overflow #

final jan31 = EasyDateTime.utc(2025, 1, 31);

jan31.copyWith(month: 2);        // March 3rd (overflow)
jan31.copyWithClamped(month: 2); // Feb 28

JSON & Serialization #

Works with json_serializable / freezed via custom converter:

class EasyDateTimeConverter implements JsonConverter<EasyDateTime, String> {
  const EasyDateTimeConverter();

  @override
  EasyDateTime fromJson(String json) => EasyDateTime.fromJson(json);

  @override
  String toJson(EasyDateTime object) => object.toJson();
}

Important Notes #

• == compares whether two times represent the same instant
• Non-IANA timezone offsets will throw an error
• Must call initializeTimeZone() first

Safe User Input Parsing #

final dt = EasyDateTime.tryParse(userInput);
if (dt == null) {
  print('Invalid date format');
}

Contributing #

Issues and PRs welcome. See CONTRIBUTING.md for guidelines.

License #

BSD 2-Clause