pub package

Flutter Date Kit

A comprehensive Flutter package that provides easy-to-use date formatting and manipulation utilities using the intl package. This package offers a complete toolkit of date formatting methods, extension methods, and utility functions for DateTime objects.

โœจ Features

  • ๐Ÿ—“๏ธ Multiple Date Formats: Support for various date formats including dd/MM/yyyy, yyyy-MM-dd, ISO formats, and more
  • โฐ Time Formatting: Format time in 12-hour and 24-hour formats
  • ๐Ÿ”ง Extension Methods: Convenient extension methods for DateTime objects
  • ๐Ÿ“ฑ Flutter Ready: Built specifically for Flutter applications
  • ๐Ÿงช Well Tested: Comprehensive test coverage
  • ๐Ÿ“š Well Documented: Clear documentation and examples
  • โšก Performance Optimized: Singleton pattern for better performance
  • ๐Ÿ›ก๏ธ Error Handling: Proper error handling for date parsing operations
  • ๐Ÿ› ๏ธ Utility Functions: Date manipulation and validation utilities

๐Ÿš€ Getting started

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_date_kit: ^latest

๐Ÿ“ File Structure

The package is organized into a modular structure for better maintainability:

lib/
โ”œโ”€โ”€ flutter_date_kit.dart              # Main entry point (exports all components)
โ””โ”€โ”€ src/
    โ”œโ”€โ”€ date_format_service.dart    # DateFormatService class with singleton pattern
    โ”œโ”€โ”€ date_time_extensions.dart   # DateTime extension methods
    โ”œโ”€โ”€ string_date_extensions.dart # String extension methods for date parsing
    โ”œโ”€โ”€ date_formats.dart          # DateFormat instances and patterns
    โ””โ”€โ”€ date_utils.dart            # Utility functions for date operations

This structure provides:

  • Better Organization: Each file has a specific responsibility
  • Easier Maintenance: Changes to specific functionality are isolated
  • Improved Readability: Smaller, focused files are easier to understand
  • Better Testing: Individual components can be tested separately

๐Ÿ“– Usage

๐Ÿ’ก Tip: Check out the example app for a comprehensive demonstration of all features with a beautiful UI!

๐Ÿš€ Quick Start: Run ./run_example.sh to launch the example app directly!

import 'package:flutter_date_kit/flutter_date_kit.dart';

void main() {
  // Using the singleton instance (recommended for better performance)
  final formatted = DateFormatService.instance.formatToDdMmYyyy(DateTime.now());
  print(formatted); // "25/12/2023"
  
  // Or create a new instance (backward compatibility)
  final formatter = DateFormatService();
  final date = DateTime(2023, 12, 25, 14, 30, 45);
  
  // Basic date formatting
  print(formatter.formatToDdMmYyyy(date)); // "25/12/2023"
  print(formatter.formatToYyyyMmDd(date)); // "2023-12-25"
  print(formatter.formatToShortDate(date)); // "25 Dec 2023"
  
  // Date with time
  print(formatter.formatToDateWithTime(date)); // "25 Dec 2023, 2:30 PM"
  print(formatter.formatToFullDateTime(date)); // "2023-12-25 14:30:45"
  
  // Time formatting
  print(formatter.formatToTime12Hour(date)); // "2:30 PM"
  print(formatter.formatToTime24Hour(date)); // "14:30"
  
  // Other formats
  print(formatter.formatToDayOfWeek(date)); // "Mon"
  print(formatter.formatToMonthYear(date)); // "December 2023"
}

Using Extension Methods (Most Convenient)

import 'package:flutter_date_kit/flutter_date_kit.dart';

void main() {
  final date = DateTime(2023, 12, 25, 14, 30, 45);
  
  // Extension methods make formatting even easier
  print(date.toDdMmYyyy()); // "25/12/2023"
  print(date.toYyyyMmDd()); // "2023-12-25"
  print(date.toShortDate()); // "25 Dec 2023"
  print(date.toDateWithTime()); // "25 Dec 2023, 2:30 PM"
  print(date.toTime12Hour()); // "2:30 PM"
  print(date.toTime24Hour()); // "14:30"
  print(date.toMonthYear()); // "December 2023"
  
  // Date utility extensions
  print(date.isToday); // false
  print(date.isYesterday); // false
  print(date.isTomorrow); // false
  print(date.age); // 0 (if date is today)
  print(date.quarter); // 4
  print(date.weekOfYear); // 52
  
  // Date manipulation
  final tomorrow = date.addDays(1);
  final yesterday = date.subtractDays(1);
  final daysDiff = date.differenceInDays(DateTime.now());
  
  // Date boundaries
  print(date.startOfDay); // 2023-12-25 00:00:00.000
  print(date.endOfDay); // 2023-12-25 23:59:59.000
  print(date.startOfWeek); // 2023-12-25 00:00:00.000 (Monday)
  print(date.endOfWeek); // 2023-12-31 00:00:00.000 (Sunday)
  print(date.startOfMonth); // 2023-12-01 00:00:00.000
  print(date.endOfMonth); // 2023-12-31 00:00:00.000
}

Using String Date Parsing and Formatting

import 'package:flutter_date_kit/flutter_date_kit.dart';

void main() {
  final formatter = DateFormatService.instance;
  
  // Parse yyyy-MM-dd strings and format them
  print(formatter.parseAndFormatDdMmYyyy('2023-12-25')); // "25/12/2023"
  print(formatter.parseAndFormatShortDate('2023-12-25')); // "25 Dec 2023"
  print(formatter.parseAndFormatMonthAbbr('2023-12-25')); // "Dec"
  print(formatter.parseAndFormatDayOfWeek('2023-12-25')); // "Mon"
  print(formatter.parseAndFormatYear('2023-12-25')); // "2023"
  print(formatter.parseAndFormatMonthYear('2023-12-25')); // "December 2023"
  
  // Parse dd/MM/yyyy strings and format them
  print(formatter.parseDdMmYyyyAndFormatYyyyMmDd('25/12/2023')); // "2023-12-25"
  print(formatter.parseDdMmYyyyAndFormatShortDate('25/12/2023')); // "25 Dec 2023"
  print(formatter.parseDdMmYyyyAndFormatMonthAbbr('25/12/2023')); // "Dec"
  
  // Using string extension methods
  print('2023-12-25'.parseYyyyMmDdToDdMmYyyy()); // "25/12/2023"
  print('2023-12-25'.parseYyyyMmDdToShortDate()); // "25 Dec 2023"
  print('2023-12-25'.parseYyyyMmDdToMonthAbbr()); // "Dec"
  print('25/12/2023'.parseDdMmYyyyToYyyyMmDd()); // "2023-12-25"
  print('25/12/2023'.parseDdMmYyyyToShortDate()); // "25 Dec 2023"
  
  // String validation
  print('2023-12-25'.isValidYyyyMmDd); // true
  print('25/12/2023'.isValidDdMmYyyy); // true
  print('12/25/2023'.isValidMmDdYyyy); // true
  print('invalid-date'.isValidYyyyMmDd); // false
}

Using DateUtils for Advanced Operations

import 'package:flutter_date_kit/flutter_date_kit.dart';

void main() {
  // Current date and time utilities
  print(DateUtils.getCurrentDateDdMmYyyy()); // "25/12/2023"
  print(DateUtils.getCurrentDateYyyyMmDd()); // "2023-12-25"
  print(DateUtils.getCurrentTime24Hour()); // "14:30"
  print(DateUtils.getCurrentTime12Hour()); // "2:30 PM"
  
  // Date validation
  print(DateUtils.isValidYyyyMmDd('2023-12-25')); // true
  print(DateUtils.isValidDdMmYyyy('25/12/2023')); // true
  print(DateUtils.isValidMmDdYyyy('12/25/2023')); // true
  
  // Date manipulation
  final date = DateTime(2023, 12, 25);
  print(DateUtils.addDays(date, 7)); // 2024-01-01
  print(DateUtils.subtractDays(date, 7)); // 2023-12-18
  
  // Date boundaries
  print(DateUtils.startOfDay(date)); // 2023-12-25 00:00:00.000
  print(DateUtils.endOfDay(date)); // 2023-12-25 23:59:59.000
  print(DateUtils.startOfWeek(date)); // 2023-12-25 00:00:00.000 (Monday)
  print(DateUtils.endOfWeek(date)); // 2023-12-31 00:00:00.000 (Sunday)
  print(DateUtils.startOfMonth(date)); // 2023-12-01 00:00:00.000
  print(DateUtils.endOfMonth(date)); // 2023-12-31 00:00:00.000
  
  // Date comparisons
  print(DateUtils.isToday(date)); // false
  print(DateUtils.isYesterday(date)); // false
  print(DateUtils.isTomorrow(date)); // false
  
  // Date differences
  final otherDate = DateTime(2023, 12, 30);
  print(DateUtils.differenceInDays(otherDate, date)); // 5
  print(DateUtils.differenceInHours(otherDate, date)); // 120
  print(DateUtils.differenceInMinutes(otherDate, date)); // 7200
  
  // Age calculation
  final birthDate = DateTime(1990, 6, 15);
  print(DateUtils.getAge(birthDate)); // 33
  
  // Calendar utilities
  print(DateUtils.isLeapYear(2024)); // true
  print(DateUtils.daysInMonth(2023, 2)); // 28
  print(DateUtils.getQuarter(date)); // 4
  print(DateUtils.getWeekOfYear(date)); // 52
}

Error Handling

import 'package:flutter_date_kit/flutter_date_kit.dart';

void main() {
  try {
    // This will throw a FormatException
    final result = DateFormatService.instance.parseAndFormatDdMmYyyy('invalid-date');
  } catch (e) {
    print('Error: $e'); // Error: FormatException: Invalid date format. Expected yyyy-MM-dd, got: invalid-date
  }
  
  // Safe validation
  if ('2023-12-25'.isValidYyyyMmDd) {
    final result = DateFormatService.instance.parseAndFormatDdMmYyyy('2023-12-25');
    print(result); // "25/12/2023"
  }
}

๐Ÿ“‹ Available Format Methods

DateFormatService Methods

Method Format Example Output
formatToDdMmYyyy() dd/MM/yyyy "25/12/2023"
formatToYyyyMmDd() yyyy-MM-dd "2023-12-25"
formatToShortDate() dd MMM yyyy "25 Dec 2023"
formatToDateWithTime() dd MMM yyyy, h:mm a "25 Dec 2023, 2:30 PM"
formatToFullDateTime() yyyy-MM-dd HH:mm:ss "2023-12-25 14:30:45"
formatToIsoWithTimezone() yyyy-MM-dd'T'HH:mm:ssZ "2023-12-25T14:30:00+00:00"
formatToTime12Hour() h:mm a "2:30 PM"
formatToTime24Hour() HH:mm "14:30"
formatToFullTime() HH:mm:ss "14:30:45"
formatToDayOfWeek() E "Mon"
formatToMonthAbbr() MMM "Dec"
formatToMonthFull() MMMM "December"
formatToYear() y "2023"
formatToMonthYear() MMMM yyyy "December 2023"
formatToMmDdYyyy() MM/dd/yyyy "12/25/2023"
formatToFullDayDate() EEEE, MMMM d, yyyy "Monday, December 25, 2023"
formatToYyyyMmDdHhMm() yyyy-MM-dd HH:mm "2023-12-25 14:30"

String Parsing Methods (DateFormatService)

Method Input Format Output Format Example
parseAndFormatDdMmYyyy() yyyy-MM-dd dd/MM/yyyy "2023-12-25" โ†’ "25/12/2023"
parseAndFormatShortDate() yyyy-MM-dd dd MMM yyyy "2023-12-25" โ†’ "25 Dec 2023"
parseAndFormatMonthAbbr() yyyy-MM-dd MMM "2023-12-25" โ†’ "Dec"
parseAndFormatDayOfWeek() yyyy-MM-dd E "2023-12-25" โ†’ "Mon"
parseAndFormatYear() yyyy-MM-dd y "2023-12-25" โ†’ "2023"
parseAndFormatMonthYear() yyyy-MM-dd MMMM yyyy "2023-12-25" โ†’ "December 2023"
parseDdMmYyyyAndFormatYyyyMmDd() dd/MM/yyyy yyyy-MM-dd "25/12/2023" โ†’ "2023-12-25"
parseDdMmYyyyAndFormatShortDate() dd/MM/yyyy dd MMM yyyy "25/12/2023" โ†’ "25 Dec 2023"
parseDdMmYyyyAndFormatMonthAbbr() dd/MM/yyyy MMM "25/12/2023" โ†’ "Dec"

Extension Methods

Method Format Example Output
toDdMmYyyy() dd/MM/yyyy "25/12/2023"
toYyyyMmDd() yyyy-MM-dd "2023-12-25"
toShortDate() dd MMM yyyy "25 Dec 2023"
toDateWithTime() dd MMM yyyy, h:mm a "25 Dec 2023, 2:30 PM"
toFullDateTime() yyyy-MM-dd HH:mm:ss "2023-12-25 14:30:45"
toIsoWithTimezone() yyyy-MM-dd'T'HH:mm:ssZ "2023-12-25T14:30:00+00:00"
toTime12Hour() h:mm a "2:30 PM"
toTime24Hour() HH:mm "14:30"
toFullTime() HH:mm:ss "14:30:45"
toDayOfWeek() E "Mon"
toMonthAbbr() MMM "Dec"
toMonthFull() MMMM "December"
toYear() y "2023"
toMonthYear() MMMM yyyy "December 2023"
toMmDdYyyy() MM/dd/yyyy "12/25/2023"
toFullDayDate() EEEE, MMMM d, yyyy "Monday, December 25, 2023"
toYyyyMmDdHhMm() yyyy-MM-dd HH:mm "2023-12-25 14:30"

String Extension Methods

Method Input Format Output Format Example
parseYyyyMmDdToDdMmYyyy() yyyy-MM-dd dd/MM/yyyy "2023-12-25" โ†’ "25/12/2023"
parseYyyyMmDdToShortDate() yyyy-MM-dd dd MMM yyyy "2023-12-25" โ†’ "25 Dec 2023"
parseYyyyMmDdToMonthAbbr() yyyy-MM-dd MMM "2023-12-25" โ†’ "Dec"
parseYyyyMmDdToDayOfWeek() yyyy-MM-dd E "2023-12-25" โ†’ "Mon"
parseYyyyMmDdToYear() yyyy-MM-dd y "2023-12-25" โ†’ "2023"
parseYyyyMmDdToMonthYear() yyyy-MM-dd MMMM yyyy "2023-12-25" โ†’ "December 2023"
parseDdMmYyyyToYyyyMmDd() dd/MM/yyyy yyyy-MM-dd "25/12/2023" โ†’ "2023-12-25"
parseDdMmYyyyToShortDate() dd/MM/yyyy dd MMM yyyy "25/12/2023" โ†’ "25 Dec 2023"
parseDdMmYyyyToMonthAbbr() dd/MM/yyyy MMM "25/12/2023" โ†’ "Dec"
isValidYyyyMmDd - bool "2023-12-25" โ†’ true
isValidDdMmYyyy - bool "25/12/2023" โ†’ true
isValidMmDdYyyy - bool "12/25/2023" โ†’ true

DateTime Extension Properties

Property Type Description Example
isToday bool Checks if date is today date.isToday
isYesterday bool Checks if date is yesterday date.isYesterday
isTomorrow bool Checks if date is tomorrow date.isTomorrow
age int Gets age from birth date birthDate.age
quarter int Gets quarter of year date.quarter
weekOfYear int Gets week of year date.weekOfYear
startOfDay DateTime Start of day (00:00:00) date.startOfDay
endOfDay DateTime End of day (23:59:59) date.endOfDay
startOfWeek DateTime Start of week (Monday) date.startOfWeek
endOfWeek DateTime End of week (Sunday) date.endOfWeek
startOfMonth DateTime Start of month date.startOfMonth
endOfMonth DateTime End of month date.endOfMonth
startOfYear DateTime Start of year date.startOfYear
endOfYear DateTime End of year date.endOfYear

DateTime Extension Methods

Method Description Example
addDays(int days) Adds days to date date.addDays(7)
subtractDays(int days) Subtracts days from date date.subtractDays(7)
differenceInDays(DateTime other) Days difference date.differenceInDays(other)
differenceInHours(DateTime other) Hours difference date.differenceInHours(other)
differenceInMinutes(DateTime other) Minutes difference date.differenceInMinutes(other)

๐Ÿ—๏ธ Architecture

The package is organized into several modules for better maintainability:

  • flutter_date_kit.dart: Main entry point with DateFormatService and extensions
  • src/date_formats.dart: Date format patterns and pre-configured DateFormat instances
  • src/date_utils.dart: Utility functions for date manipulation and validation

๐Ÿ”ง Performance Optimizations

  • Singleton Pattern: DateFormatService uses a singleton pattern to avoid creating multiple instances
  • Pre-configured Formats: DateFormat instances are pre-configured for better performance
  • Extension Methods: Use the singleton instance internally for optimal performance

๐Ÿ›ก๏ธ Error Handling

The package provides comprehensive error handling:

  • FormatException: Thrown when parsing invalid date strings
  • Validation Methods: Safe validation methods to check date format validity
  • Try-Catch Support: All parsing methods support try-catch error handling

๐Ÿ“š Additional information

This package is built on top of the intl package, which provides internationalization and localization facilities for Dart and Flutter applications.

Dependencies

  • intl: ^0.20.2 - For date formatting functionality
  • flutter: ">=1.17.0" - Flutter framework

Contributing

Feel free to contribute to this package by:

  1. Forking the repository
  2. Creating a feature branch
  3. Making your changes
  4. Adding tests
  5. Submitting a pull request

License

This package is licensed under the BSD-3-Clause license.

Libraries

flutter_date_kit