timezone_utils 0.0.1

A lightweight, zero-dependency UTC-first utility class for safe timezone operations. Provides expiry checks, time differences, day/hour calculations, and migration helpers.

example/lib/main.dart

import 'package:timezone_utils/timezone_utils.dart';

void main() {
  // Get current UTC time
  final now = TimezoneUtils.nowUtc();
  print('Current UTC: $now');

  // Create an expiry 24 hours from now
  final expiry = TimezoneUtils.createExpiryFromNow(Duration(hours: 24));
  print('Expires at: $expiry');

  // Check if something expired
  final pastDate = DateTime.utc(2020, 1, 1);
  print('Past date expired: ${TimezoneUtils.isExpired(pastDate)}'); // true

  final futureDate = TimezoneUtils.createExpiryFromNow(Duration(days: 30));
  print('Future date expired: ${TimezoneUtils.isExpired(futureDate)}'); // false

  // Days since a date
  final createdAt = DateTime.utc(2024, 1, 1);
  print('Days since Jan 1, 2024: ${TimezoneUtils.daysSince(createdAt)}');

  // Hours and minutes since
  final lastSync = now.subtract(Duration(hours: 3, minutes: 45));
  print('Hours since last sync: ${TimezoneUtils.hoursSince(lastSync)}');
  print('Minutes since last sync: ${TimezoneUtils.minutesSince(lastSync)}');

  // Check if enough time has passed
  final cooldownPassed = TimezoneUtils.hasTimePassedSince(
    lastSync,
    Duration(hours: 1),
  );
  print('Cooldown passed (1h): $cooldownPassed'); // true

  // Day boundaries
  final startOfDay = TimezoneUtils.startOfDayUtc(now);
  final endOfDay = TimezoneUtils.endOfDayUtc(now);
  print('Start of day: $startOfDay');
  print('End of day: $endOfDay');

  // Time range check
  final inRange = TimezoneUtils.isWithinTimeRange(
    now,
    DateTime.utc(2020, 1, 1),
    DateTime.utc(2030, 12, 31),
  );
  print('In range 2020-2030: $inRange'); // true

  // Convert UTC to local for display
  final localTime = TimezoneUtils.utcToLocal(now);
  print('Local time: $localTime');

  // Duration arithmetic
  final twoHoursLater = TimezoneUtils.addDurationUtc(now, Duration(hours: 2));
  final oneDayAgo = TimezoneUtils.subtractDurationUtc(now, Duration(days: 1));
  print('Two hours later: $twoHoursLater');
  print('One day ago: $oneDayAgo');

  // High-performance UTC now
  final optimized = TimezoneUtils.nowUtcOptimized();
  print('Optimized UTC: $optimized');

  // Migration helper
  final localDateTime = DateTime(2024, 6, 15, 10, 30); // local time
  final migrated = TimezoneUtils.migrateToUtc(localDateTime);
  print('Migrated to UTC: $migrated');
}