easy_date_time library

A timezone-aware DateTime library for Dart.

This library provides EasyDateTime, a drop-in replacement for Dart's DateTime that supports timezone-aware operations.

Quick Start

import 'package:easy_date_time/easy_date_time.dart';

void main() {
  EasyDateTime.initializeTimeZone();  // Required - call once at startup

  final now = EasyDateTime.now();  // Local time
  final tokyo = EasyDateTime.now(location: TimeZones.tokyo);

  // Parse with timezone preserved
  final dt = EasyDateTime.parse('2025-12-07T10:30:00+08:00');
  print(dt.hour);  // 10 (not converted!)
}

Features

  • Timezone Support: Any IANA timezone (Asia/Tokyo, America/New_York, etc.)
  • Time Preservation: parse() preserves original time values
  • Operators: +, -, <, >, == for intuitive operations
  • JSON Serialization: ISO 8601 format, works with json_serializable
  • Immutable: Thread-safe, works with riverpod/bloc/freezed

Classes

DateTimeFormats
Predefined date/time format patterns.
EasyDateTime
A timezone-aware DateTime implementation.
EasyDateTimeFormatter
A pre-compiled date formatter for high-performance scenarios.
Location
A Location maps time instants to the zone in use at that time. Typically, the Location represents the collection of time offsets in use in a geographical area, such as CEST and CET for central Europe.
TimeZones
Convenient access to common timezone locations.

Extensions

DateTimeExtension on DateTime
Extension on DateTime to convert to EasyDateTime.
DurationExtension on int
Extension on int to create Duration more easily.
EasyDateTimeFormatting on EasyDateTime
Extension providing date/time formatting methods for EasyDateTime.
EasyDateTimeUtilities on EasyDateTime
Extension providing date utility methods for EasyDateTime.

Properties

effectiveDefaultLocation → Location
Gets the effective default location for EasyDateTime operations.
no setter
internalIsTimeZoneInitialized → bool
Internal: Checks if the timezone database has been initialized.
no setter

Functions

getLocation(String locationName) → Location
Find Location by its name.
internalClearDefaultLocation() → void
Internal: Clears the global default location.
internalGetDefaultLocation() → Location?
Internal: Gets the current global default location.
internalInitializeTimeZone() → void
Internal: Initializes the IANA timezone database.
internalSetDefaultLocation(Location? location) → void
Internal: Sets the global default location.

Exceptions / Errors

InvalidDateFormatException
Exception thrown when an invalid date string is provided for parsing.
InvalidTimeZoneException
Exception thrown when an invalid timezone location is provided.
TimeZoneNotInitializedException
Exception thrown when timezone initialization is required but hasn't been performed.