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.

Timezone Utils

A lightweight, zero-dependency utility package for Dart and Flutter applications that simplifies timezone and date calculations.

This package performs all operations in UTC by default. This approach prevents common bugs and confusion caused by local device or server timezones. It has no external dependencies.

Features

• UTC-First Approach: All background operations use UTC to prevent errors.
• Duration & Expiry: Easily handle expiration checks (isExpired, hasTimePassedSince).
• Time Differences: Calculate the difference between two dates in days, hours, or minutes.
• Day Boundaries: Get the exact start (startOfDayUtc) and end (endOfDayUtc) of any given day.
• Time Ranges: Verify if a specific time falls within a given start and end period.
• Zero Dependencies: Built entirely with core Dart code, making it lightweight and universally compatible.
• High Performance: Optimized for frequently repeated operations.

Installation

Add the following line to your pubspec.yaml file:

dependencies:
  timezone_utils: ^<latest_version>

Usage Examples

Get Current Time (UTC)

import 'package:timezone_utils/timezone_utils.dart';

final now = TimezoneUtils.nowUtc();
print(now); // Output example: 2024-01-15 14:30:00.000Z

Expiration Check

final expiresAt = DateTime.utc(2024, 1, 15, 18, 0);

if (TimezoneUtils.isExpired(expiresAt)) {
  print('Time has expired!');
}

Create Future Time

// 24 hours from now
final expiry = TimezoneUtils.createExpiryFromNow(Duration(hours: 24));

// 7 days from now
final weekExpiry = TimezoneUtils.createExpiryFromNow(Duration(days: 7));

Calculate Time Passed

final createdAt = DateTime.utc(2024, 1, 10);

print(TimezoneUtils.daysSince(createdAt));    // e.g., 5
print(TimezoneUtils.hoursSince(createdAt));   // e.g., 120
print(TimezoneUtils.minutesSince(createdAt)); // e.g., 7200

Check if Specific Duration Has Passed

final lastSync = DateTime.utc(2024, 1, 15, 10, 0);

if (TimezoneUtils.hasTimePassedSince(lastSync, Duration(hours: 1))) {
  print('Time for a new synchronization!');
}

Start and End of the Day

final date = DateTime.utc(2024, 1, 15, 14, 30);

final start = TimezoneUtils.startOfDayUtc(date);
// Result: 2024-01-15 00:00:00.000Z

final end = TimezoneUtils.endOfDayUtc(date);
// Result: 2024-01-15 23:59:59.999Z

Verify Time Range

final now = TimezoneUtils.nowUtc();
final start = DateTime.utc(2024, 1, 1);
final end = DateTime.utc(2024, 12, 31);

if (TimezoneUtils.isWithinTimeRange(now, start, end)) {
  print('You are within the specified time period!');
}

Display Local Time to User

final utcTime = TimezoneUtils.nowUtc();

// Converts to local time ONLY for UI display purposes
final localTime = TimezoneUtils.utcToLocal(utcTime);
print('Local Time: $localTime');

API Reference

Method	Return Type	Description
nowUtc()	DateTime	Returns the current time in UTC
toUtc(dateTime)	DateTime	Converts any given time to UTC
timeDifference(from, to)	Duration	Calculates the exact duration between two times
timeDifferenceFromNow(dateTime)	Duration	Calculates the duration from a specific time to now
addDurationUtc(dateTime, duration)	DateTime	Safely adds a duration
subtractDurationUtc(dateTime, duration)	DateTime	Safely subtracts a duration
isExpired(expiresAt)	bool	Checks if the specified time has passed
hasTimePassedSince(dateTime, duration)	bool	Verifies if a specific duration has elapsed
createExpiryFromNow(duration)	DateTime	Creates a future expiration time from now
startOfDayUtc(dateTime)	DateTime	Returns the very beginning of the day (00:00:00.000)
endOfDayUtc(dateTime)	DateTime	Returns the very end of the day (23:59:59.999)
daysDifference(from, to)	int	Calculates calendar days between two dates
daysSince(dateTime)	int	Calculates calendar days passed since a specific date
hoursSince(dateTime)	int	Calculates hours passed
minutesSince(dateTime)	int	Calculates minutes passed
utcToLocal(dateTime)	DateTime	Converts UTC to the device's local time (for display only)
isWithinTimeRange(check, start, end)	bool	Tests if a time falls within two given periods
migrateToUtc(dateTime)	DateTime	A helper function for transitioning existing local times to UTC
nowUtcOptimized()	DateTime	A high-performance, fast current time function

Requirements

• Dart SDK 3.0 or higher

License

Protected under the MIT License. See the LICENSE file for more details.