easy_date_time library

A timezone-aware DateTime library for Dart.

This library provides EasyDateTime, an enhanced DateTime implementation with explicit IANA timezone support.

Quick Start

import 'package:easy_date_time/easy_date_time.dart';

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

  final now = EasyDateTime.now();  // Configured local location
  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: Suitable for value-oriented application state

Classes

DateTimeFormats
Predefined date/time format patterns.
EasyDateTime
A timezone-aware DateTime implementation.
EasyDateTimeFormatter
A pre-compiled date formatter for high-performance scenarios.
EasyParseOptions
Configures how EasyDateTime parsing should behave.
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.
ParseDiagnostics
Structured metadata attached to parse failures.
TimeZones
Convenient access to common timezone locations.

Enums

DateTimeUnit
Units of time for EasyDateTime.startOf and EasyDateTime.endOf.
EasyParseMode
Parsing behavior modes for EasyDateTime string parsing.
OffsetResolution
How timezone offsets should be resolved during parsing.
ParseFailureStage
Identifies where parsing failed.

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

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.
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.