📅 DateTime Helpers for Flutter

DateFormatters.formatDateShort(date);         // "12/1/2025"
DateFormatters.formatDateMedium(date);        // "Dec 1, 2025"
DateFormatters.formatDateLong(date);          // "December 1, 2025"
DateFormatters.formatDateFull(date);          // "Monday, December 1, 2025"
DateFormatters.formatYear(date);              // "2025"
DateFormatters.formatMonthYear(date);         // "December 2025"
DateFormatters.formatDayMonth(date);          // "December 1"
DateFormatters.formatDayName(date);           // "Monday"
DateFormatters.formatMonthName(date);         // "December"
DateFormatters.formatCustom(date, 'yyyy-MM-dd'); // "2025-12-01"
DateFormatters.formatIso8601(date);           // ISO 8601 format
DateFormatters.formatForFileName(date);       // File-safe format
DateFormatters.formatDateRange(start, end);   // Date range

TimeFormatters.formatTime12Hour(date);              // "2:30 PM"
TimeFormatters.formatTime24Hour(date);              // "14:30"
TimeFormatters.formatTime12HourWithSeconds(date);   // "2:30:45 PM"
TimeFormatters.formatTime24HourWithSeconds(date);   // "14:30:45"
TimeFormatters.formatTimeWithMilliseconds(date);    // "14:30:45.123"
TimeFormatters.formatDateTimeShort(date);           // "12/1/2025 2:30 PM"
TimeFormatters.formatDateTimeMedium(date);          // "Dec 1, 2025 2:30 PM"
TimeFormatters.formatDateTimeLong(date);            // "December 1, 2025 at 2:30 PM"

DateComparisons.isSameDay(date1, date2);      // Same day?
DateComparisons.isSameWeek(date1, date2);     // Same week?
DateComparisons.isSameMonth(date1, date2);    // Same month?
DateComparisons.isSameYear(date1, date2);     // Same year?
DateComparisons.isToday(date);                // Is today?
DateComparisons.isYesterday(date);            // Is yesterday?
DateComparisons.isTomorrow(date);             // Is tomorrow?
DateComparisons.isThisWeek(date);             // In current week?
DateComparisons.isThisMonth(date);            // In current month?
DateComparisons.isThisYear(date);             // In current year?
DateComparisons.isPast(date);                 // In the past?
DateComparisons.isFuture(date);               // In the future?
DateComparisons.isWeekend(date);              // Saturday/Sunday?
DateComparisons.isWeekday(date);              // Monday-Friday?
DateComparisons.isBetween(date, start, end);  // In date range?

// Period boundaries
DateCalculations.startOfDay(date);            // 00:00:00
DateCalculations.endOfDay(date);              // 23:59:59.999
DateCalculations.startOfWeek(date);           // Monday 00:00
DateCalculations.endOfWeek(date);             // Sunday 23:59
DateCalculations.startOfMonth(date);          // 1st day of month
DateCalculations.endOfMonth(date);            // Last day of month
DateCalculations.startOfYear(date);           // Jan 1st
DateCalculations.endOfYear(date);             // Dec 31st
DateCalculations.startOfQuarter(date);        // Quarter start
DateCalculations.endOfQuarter(date);          // Quarter end

// Business days
DateCalculations.addBusinessDays(date, 5);    // +5 weekdays
DateCalculations.subtractBusinessDays(date, 5); // -5 weekdays
DateCalculations.countBusinessDays(start, end); // Count weekdays

// Calculations
DateCalculations.calculateAge(birthDate);     // Age in years
DateCalculations.getDaysInMonth(year, month); // Days in month
DateCalculations.isLeapYear(year);            // Leap year?
DateCalculations.getQuarter(date);            // Quarter number (1-4)
DateCalculations.getWeekNumber(date);         // Week number in year
DateCalculations.addMonths(date, 3);          // +3 months (smart)
DateCalculations.subtractMonths(date, 3);     // -3 months
DateCalculations.getDifference(start, end);   // Detailed difference

// Timezone
DateCalculations.toUTC(date);                 // Convert to UTC
DateCalculations.toLocal(date);               // Convert to local
DateCalculations.formatTimezoneOffset(date);  // "+05:30"
DateCalculations.getTimezoneName(date);       // "PST"

RelativeTime.getRelativeTime(date);           // "2 hours ago"
RelativeTime.getRelativeTime(date, 'es_ES');  // "hace 2 horas"
RelativeTime.getRelativeTimeShort(date);      // "2h"
RelativeTime.formatDuration(duration);        // "2h 30m"
RelativeTime.formatTimeRemaining(targetDate); // Countdown

// Smart formatting
SmartFormatters.formatSmart(date);            // Context-aware

// Parsing
DateParsers.parseDate(dateString);            // Parse date
DateParsers.parseFlexible(dateString);        // Try multiple formats
DateParsers.isValidDate(dateString);          // Validate date string

import 'package:save_points_intl/datetime.dart';

String formatMessageTimestamp(DateTime messageTime) {
  if (DateComparisons.isToday(messageTime)) {
    return TimeFormatters.formatTime12Hour(messageTime); // "2:30 PM"
  } else if (DateComparisons.isYesterday(messageTime)) {
    return 'Yesterday';
  } else if (DateComparisons.isThisWeek(messageTime)) {
    return DateFormatters.formatDayName(messageTime); // "Monday"
  } else if (DateComparisons.isThisYear(messageTime)) {
    return DateFormatters.formatDayMonth(messageTime); // "Nov 30"
  } else {
    return DateFormatters.formatDateShort(messageTime); // "11/30/2024"
  }
}

// Usage
final timestamp = formatMessageTimestamp(messageDate);
print('Message sent: $timestamp');

import 'package:save_points_intl/datetime.dart';

class Event {
  final String title;
  final DateTime startTime;
  
  Event(this.title, this.startTime);
  
  String getDisplayTime() {
    if (DateComparisons.isToday(startTime)) {
      return 'Today at ${TimeFormatters.formatTime12Hour(startTime)}';
    } else if (DateComparisons.isTomorrow(startTime)) {
      return 'Tomorrow at ${TimeFormatters.formatTime12Hour(startTime)}';
    } else if (DateComparisons.isThisWeek(startTime)) {
      return '${DateFormatters.formatDayName(startTime)} at ${TimeFormatters.formatTime12Hour(startTime)}';
    } else {
      return TimeFormatters.formatDateTimeMedium(startTime);
    }
  }
  
  String getCountdown() {
    return RelativeTime.getRelativeTime(startTime);
  }
}

// Usage
final meeting = Event('Team Meeting', DateTime.now().add(Duration(hours: 3)));
print(meeting.getDisplayTime());  // "Today at 5:30 PM"
print(meeting.getCountdown());    // "in 3 hours"

import 'package:save_points_intl/datetime.dart';

class Post {
  final String content;
  final DateTime publishedAt;
  
  Post(this.content, this.publishedAt);
  
  String getTimestamp() {
    final diff = DateTime.now().difference(publishedAt);
    
    if (diff.inMinutes < 1) return 'Just now';
    if (diff.inHours < 1) return '${diff.inMinutes}m';
    if (diff.inHours < 24) return '${diff.inHours}h';
    if (diff.inDays < 7) return '${diff.inDays}d';
    
    return DateFormatters.formatDateMedium(publishedAt);
  }
}

// Usage
final post = Post('Hello World!', DateTime.now().subtract(Duration(hours: 2)));
print(post.getTimestamp()); // "2h"

import 'package:save_points_intl/datetime.dart';

class Reservation {
  final DateTime checkIn;
  final DateTime checkOut;
  
  Reservation(this.checkIn, this.checkOut);
  
  int get numberOfNights => checkOut.difference(checkIn).inDays;
  
  int get businessDays => 
      DateCalculations.countBusinessDays(checkIn, checkOut);
  
  String getStayPeriod() => 
      DateFormatters.formatDateRange(checkIn, checkOut);
  
  String getStatus() {
    if (DateComparisons.isToday(checkIn)) {
      return 'Checking in today';
    } else if (DateComparisons.isPast(checkIn) && 
               DateComparisons.isFuture(checkOut)) {
      return 'Currently staying';
    } else if (DateComparisons.isPast(checkOut)) {
      return 'Checked out';
    } else {
      return 'Checking in ${RelativeTime.getRelativeTime(checkIn)}';
    }
  }
}

// Usage
final reservation = Reservation(
  DateTime.now().add(Duration(days: 3)),
  DateTime.now().add(Duration(days: 8)),
);
print('Period: ${reservation.getStayPeriod()}');
print('Nights: ${reservation.numberOfNights}');
print('Status: ${reservation.getStatus()}');

import 'package:save_points_intl/datetime.dart';

class Task {
  final String name;
  final DateTime dueDate;
  DateTime? completedDate;
  
  Task(this.name, this.dueDate);
  
  bool get isOverdue => 
      completedDate == null && DateComparisons.isPast(dueDate);
  
  bool get isDueToday => 
      completedDate == null && DateComparisons.isToday(dueDate);
  
  String getStatus() {
    if (completedDate != null) {
      return 'Completed ${RelativeTime.getRelativeTime(completedDate!)}';
    }
    
    if (isOverdue) {
      final days = DateTime.now().difference(dueDate).inDays;
      return '⚠️ Overdue by $days day${days == 1 ? '' : 's'}';
    }
    
    if (isDueToday) {
      return '📅 Due today at ${TimeFormatters.formatTime12Hour(dueDate)}';
    }
    
    return '⏰ Due ${RelativeTime.getRelativeTime(dueDate)}';
  }
}

// Usage
final task = Task('Submit report', DateTime.now().add(Duration(hours: 5)));
print(task.getStatus()); // "⏰ Due in 5 hours"

import 'package:save_points_intl/datetime.dart';

class LocalizedDateService {
  final String locale;
  
  LocalizedDateService(this.locale);
  
  String formatDate(DateTime date) {
    return DateFormatters.formatDateLong(date, locale);
  }
  
  String formatTime(DateTime date) {
    return TimeFormatters.formatTime12Hour(date, locale);
  }
  
  String formatRelative(DateTime date) {
    return RelativeTime.getRelativeTime(date, locale);
  }
}

// Usage
final english = LocalizedDateService('en_US');
final spanish = LocalizedDateService('es_ES');
final arabic = LocalizedDateService('ar_SA');

final now = DateTime.now();
print(english.formatDate(now));  // "December 1, 2025"
print(spanish.formatDate(now));  // "1 de Diciembre de 2025"
print(arabic.formatDate(now));   // "1 ديسمبر 2025"

While intl is great, this library offers:

• ✅ No external dependencies = no version conflicts
• ✅ Lighter weight = faster builds
• ✅ Fully customizable = modify for your needs
• ✅ More business logic = calculations, comparisons, etc.
• ✅ Simpler API = easier to use

Use intl if you need comprehensive i18n. Use this if you want lightweight date/time helpers.

✅ Yes! This library is:

• Fully tested and verified
• Zero dependencies (no breaking changes risk)
• Type-safe with null safety
• Well documented
• Production-ready

Edit lib/constants.dart and add your language to:

1. monthNames map
2. monthNamesShort map
3. dayNames map
4. dayNamesShort map
5. getRelativeTimeTranslations() method

See Extending the Library for details.

✅ Yes! Arabic is included with proper translations. The library returns formatted strings; your UI framework handles RTL display.

✅ Absolutely! Import only what you need:

import 'package:save_points_intl/date_formatters.dart';
import 'package:save_points_intl/date_comparisons.dart';

The library is fully modular and tree-shakable.

Use the timezone utilities in DateCalculations:

// Convert to UTC
final utc = DateCalculations.toUTC(localDate);

// Convert to local
final local = DateCalculations.toLocal(utcDate);

// Get offset
final offset = DateCalculations.formatTimezoneOffset(date); // "+05:30"