TimeZoneKit 1.0.3

TimeZoneKit

A simple, intuitive timezone library for .NET that makes working with timezones actually enjoyable.

Why TimeZoneKit?

• 🎯 Simple API - Easier than NodaTime, more powerful than TimeZoneConverter
• 🌍 Geographic Lookup - Find timezones by city, coordinates, or country
• 💼 Business Hours - Built-in business hours and meeting time calculations
• 🔄 Smart Parsing - Parse timezones from abbreviations, names, or offsets
• 🌐 Localization - Display names in multiple languages
• ⚡ Fast - Cached lookups and optimized for performance
• 📦 Zero Dependencies - Only requires System.Text.Json
• 🎨 Cross-Platform - Works on Windows, Linux, and macOS

Installation

dotnet add package TimeZoneKit

Or via NuGet Package Manager:

Install-Package TimeZoneKit

Quick Start

using TimeZoneKit;
using TimeZoneKit.Extensions;

// Simple conversion
var nyTime = DateTime.UtcNow.ToTimeZone("America/New_York");

// Parse various formats
var tz = TimeZoneKit.Parse("EST");           // Abbreviation
var tz2 = TimeZoneKit.Parse("New York");     // City name
var tz3 = TimeZoneKit.Parse("GMT-5");        // Offset

// Check business hours
var isOpen = DateTime.Now.IsBusinessHour("America/New_York");

// Find meeting times across timezones
var slots = TimeZoneKit.FindMeetingTime(
    new[] { "America/New_York", "Europe/London", "Asia/Tokyo" },
    new TimeRange(9, 17),
    DateTime.Today
);

Features

1. Simple Timezone Conversion

// Extension methods for DateTime
var utcTime = DateTime.UtcNow;
var nyTime = utcTime.ToTimeZone("America/New_York");
var londonTime = utcTime.ToTimeZone("Europe/London");

// Static methods
var converted = TimeZoneKit.Convert(dateTime, "America/New_York");
var utc = TimeZoneKit.ToUtc(localTime, "EST");

// Convert between timezones
var tokyoTime = nyTime.ToTimeZone("America/New_York", "Asia/Tokyo");

2. Smart Timezone Parsing

TimeZoneKit can parse timezones from multiple formats:

// Abbreviations
var tz1 = TimeZoneKit.Parse("EST");
var tz2 = TimeZoneKit.Parse("PST");
var tz3 = TimeZoneKit.Parse("GMT");

// City names
var tz4 = TimeZoneKit.Parse("New York");
var tz5 = TimeZoneKit.Parse("London");
var tz6 = TimeZoneKit.Parse("Tokyo");

// Offset strings
var tz7 = TimeZoneKit.Parse("GMT-5");
var tz8 = TimeZoneKit.Parse("UTC+9");

// IANA timezone IDs
var tz9 = TimeZoneKit.Parse("America/New_York");

// Windows timezone IDs
var tz10 = TimeZoneKit.Parse("Eastern Standard Time");

// Safe parsing
if (TimeZoneKit.TryParse("EST", out var tzInfo))
{
    Console.WriteLine($"Parsed: {tzInfo.DisplayName}");
}

3. IANA ↔ Windows Mapping

// Convert between IANA and Windows timezone IDs
var windowsId = TimeZoneKit.IanaToWindows("America/New_York");
// Returns: "Eastern Standard Time"

var ianaId = TimeZoneKit.WindowsToIana("Eastern Standard Time");
// Returns: "America/New_York"

// Get TimeZoneInfo (works with both formats)
var tzInfo = TimeZoneKit.GetTimeZoneInfo("America/New_York");

4. Geographic Lookup

// Find timezone by city name
var londonTz = TimeZoneKit.FromCity("London");
var tokyoTz = TimeZoneKit.FromCity("Tokyo");

// Get all timezones for a country (ISO 3166-1 alpha-2 code)
var usTimezones = TimeZoneKit.GetByCountry("US");
// Returns: ["America/New_York", "America/Chicago", "America/Denver", ...]

var jpTimezones = TimeZoneKit.GetByCountry("JP");
// Returns: ["Asia/Tokyo"]

// Get timezones by UTC offset
var zones = TimeZoneKit.GetByOffset(TimeSpan.FromHours(-5));
// Returns all timezones with UTC-5 base offset

5. Search and Discovery

// Search for timezones
var results = TimeZoneKit.Search("eastern");
// Returns: ["America/New_York", "America/Detroit", ...]

// Get common timezones (for dropdown lists)
var common = TimeZoneKit.GetCommonTimezones();
// Returns: ["America/New_York", "America/Chicago", "Europe/London", ...]

// Get friendly display names
var displayName = TimeZoneKit.GetFriendlyName("America/New_York");
// Returns: "Eastern Time (US & Canada)"

6. DST Information

// Check if a timezone supports DST
var hasDst = TimeZoneKit.SupportsDst("America/New_York");
// Returns: true

// Check if a specific date/time is in DST
var isDst = TimeZoneKit.IsDaylightSavingTime("America/New_York", DateTime.Now);

// Get the UTC offset at a specific time
var offset = TimeZoneKit.GetOffsetAt("America/New_York", DateTime.Now);
Console.WriteLine($"Current offset: {offset.TotalHours} hours");

// Extension method
var isDst2 = DateTime.Now.IsDaylightSavingTime("America/New_York");

7. Business Hours Support

// Check if current time is during business hours (9 AM - 5 PM weekdays)
var isOpen = DateTime.UtcNow.IsBusinessHour("America/New_York");

// Custom business hours
var isOpen2 = DateTime.UtcNow.IsBusinessHour("America/New_York", startHour: 8, endHour: 18);

// Find next business hour
var nextOpen = DateTime.UtcNow.NextBusinessHour("America/New_York");
Console.WriteLine($"Next business hour: {nextOpen}");

// Advanced: Custom business hours per day
var businessHours = new BusinessHours("America/New_York", 9, 17)
{
    Saturday = new TimeRange(10, 14), // Open Saturdays 10 AM - 2 PM
    Sunday = null // Closed Sundays
};

var isNowOpen = businessHours.IsOpen(DateTime.Now);
var nextAvailable = businessHours.NextAvailableTime(DateTime.Now);

8. Meeting Time Finder

Find time slots when all participants are available across different timezones:

// Find meeting times across multiple timezones
var slots = TimeZoneKit.FindMeetingTime(
    timeZones: new[] { "America/New_York", "Europe/London", "Asia/Tokyo" },
    workingHours: new TimeRange(9, 17), // 9 AM - 5 PM
    date: DateTime.Today
);

foreach (var slot in slots)
{
    Console.WriteLine($"Meeting window: {slot.StartTime} - {slot.EndTime} UTC");
    Console.WriteLine($"Duration: {slot.Duration.TotalHours} hours");

    // See what time this is in each timezone
    Console.WriteLine($"  NY: {slot.GetStartTimeInZone("America/New_York")}");
    Console.WriteLine($"  London: {slot.GetStartTimeInZone("Europe/London")}");
    Console.WriteLine($"  Tokyo: {slot.GetStartTimeInZone("Asia/Tokyo")}");
}

// Advanced: Custom business hours per timezone
var customHours = new[]
{
    new BusinessHours("America/New_York", 9, 17),
    new BusinessHours("Europe/London", 8, 16),
    new BusinessHours("Asia/Tokyo", 10, 18)
};

var customSlots = TimeZoneKit.FindMeetingTime(customHours, DateTime.Today);

Supported Timezones

TimeZoneKit includes comprehensive timezone data for 350+ cities, 60+ countries, and 110+ timezone mappings worldwide:

North America (Complete Coverage)

• United States: All time zones including EST, CST, MST, PST, Arizona (no DST), Alaska, Hawaii
• Canada: All provinces from Newfoundland (NST) to Pacific, including unique half-hour zones
• Mexico: Mexico City, Cancun, Monterrey, Tijuana, and regional variations

Europe (Comprehensive)

• Western Europe: London, Dublin, Lisbon, and Atlantic islands
• Central Europe: Paris, Berlin, Rome, Madrid, Amsterdam, Brussels, Zurich, Vienna
• Northern Europe: Stockholm, Copenhagen, Oslo, Helsinki
• Eastern Europe: Athens, Istanbul, Moscow, Warsaw, Prague, Budapest, Bucharest
• Russia: All 11 time zones from Kaliningrad to Kamchatka

Asia (Full Coverage)

• Middle East: Dubai, Riyadh, Tel Aviv, Beirut, Cairo
• South Asia: India, Pakistan, Bangladesh, Sri Lanka, Nepal (including unique UTC+5:45)
• Southeast Asia: Singapore, Bangkok, Kuala Lumpur, Jakarta, Manila, Ho Chi Minh City
• East Asia: Tokyo, Seoul, Shanghai, Beijing, Hong Kong, Taipei

Pacific & Oceania

• Australia: All time zones including Perth, Darwin, Adelaide, Brisbane, Sydney, Melbourne, Hobart
• New Zealand: Auckland, Wellington, Christchurch, and Chatham Islands (UTC+12:45)
• Pacific Islands: Fiji, Guam, Tonga

Latin America

• South America: Brazil (4 zones), Argentina (12 zones), Chile, Peru, Colombia, Venezuela
• Central America: All countries from Panama to Guatemala

Africa

• Major Hubs: Johannesburg, Cairo, Lagos, Nairobi, Casablanca, Addis Ababa

Special Features

• ✅ Half-hour offsets (India, Newfoundland, Venezuela, etc.)
• ✅ Quarter-hour offsets (Nepal at UTC+5:45)
• ✅ DST and non-DST zones correctly handled
• ✅ Historical timezone changes supported
• ✅ Multi-timezone countries fully mapped

API Reference

Core Methods

Parsing & Discovery

Mappings & Display

DST Information

Business Hours

Extension Methods

All core methods are available as DateTime extension methods:

dateTime.ToTimeZone(timeZoneId)
dateTime.ToUtc(timeZoneId)
dateTime.GetOffset(timeZoneId)
dateTime.IsDaylightSavingTime(timeZoneId)
dateTime.IsBusinessHour(timeZoneId)
dateTime.NextBusinessHour(timeZoneId)

Target Frameworks

• .NET 8.0
• .NET 6.0
• .NET Standard 2.0 (supports .NET Framework 4.6.2+)

Performance

TimeZoneKit is optimized for performance:

• ✅ Lazy loading - Data files loaded only when needed
• ✅ Thread-safe caching - TimeZoneInfo instances cached using ConcurrentDictionary
• ✅ Embedded resources - No file I/O at runtime
• ✅ Zero allocations in hot paths where possible

Test Coverage

TimeZoneKit is extensively tested with 400+ unit tests covering:

• ✅ Parsing: 100+ tests for abbreviations, city names, IANA IDs, Windows IDs, and offset formats
• ✅ Geographic Lookup: 70+ tests for cities, countries, and offset-based searches
• ✅ Conversions: 20+ tests for timezone conversions, DST transitions, and round-trip accuracy
• ✅ DST Handling: 25+ tests for daylight saving time across multiple regions
• ✅ Business Hours: 30+ tests for business hour calculations and meeting time finding
• ✅ Mapping: 50+ tests for IANA ↔ Windows conversions and display names
• ✅ Search: 15+ tests for search functionality and discovery

All tests passing on .NET 8.0, .NET 6.0, and .NET Standard 2.0.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Acknowledgments

• IANA Timezone Database
• Unicode CLDR for localization data
• Inspired by TimeZoneConverter and NodaTime

Support

• GitHub Issues: https://github.com/ervistrupja/TimeZoneKit/issues
• Documentation: https://github.com/ervistrupja/TimeZoneKit

Made with ❤️ by Ervis Trupja