jaytwo.LocalTime 0.1.0-beta-20251008230428

jaytwo.LocalTime

jaytwo.LocalTime is a tiny, focused library for handling local times without surprises.

View source on GitHub

Features

• Convert between local time and UTC with a known time zone
• Translate times from one time zone to another
• Handle DST transitions with configurable strict/lenient rules
• Perform clock-aware arithmetic (add/subtract across DST changes correctly)
• Deterministic "now" injection for testing
• Simple ASP.NET Core DI integration (ILocalTimeService, ILocalTimeTranslator)
• Based on IANA TZDB identifiers (via NodaTime) for reliable cross-platform behavior
• Verbose DST Resolution API (detect ambiguous/skipped times, see alternatives)
• Optional truncation of "now" to a specified precision (e.g., seconds) for database compatibility

Installation

Add the NuGet package:

PM> Install-Package jaytwo.LocalTime

Usage

• Use ILocalTimeService to work between a known local time zone and UTC.
• Use ILocalTimeTranslator to convert a local time from one zone to another.

Examples

Basic Usage

1. Local time ↔ UTC

using jaytwo.LocalTime;

var localTimeService = new LocalTimeService("America/Denver"); // throws if TZ ID is invalid
var nowLocal = localTimeService.LocalNow;                      // DateTimeOffset (local zone)
var nowUtc   = localTimeService.UtcNow;                        // DateTimeOffset (UTC)

// Conversions
var timestamp = localTimeService.GetDateTimeOffset(someLocalDateTime); // local -> DateTimeOffset
var utc = localTimeService.GetUtcDateTime(someLocalDateTime);          // local -> UTC DateTime
var local = localTimeService.GetLocalDateTimeFromUtc(someUtcDateTime); // UTC -> local DateTime (Unspecified)

Need deterministic now (e.g., for tests)? LocalTimeService.Create("America/Denver", utcNowFactory: () => fixedUtcNow)

DST Handling

Pass throwOnAmbiguousOrSkipped: true to throw on DST gaps/ambiguities (or set it in the constructor). Default is lenient resolution.

2. Clock-aware arithmetic (handles DST correctly)

// Add across DST transitions
var plus1h = localTimeService.AddHours(DateTime.Parse("2025-03-09T01:00:00"), 1); // returns 2025-03-09T03:00:00-06:00

// Subtract two local wall-clock times (real elapsed time)
var elapsed = localTimeService.Subtract(
    DateTime.Parse("2025-11-02T03:00:00"),
    DateTime.Parse("2025-11-02T00:00:00")); // returns 4 hours

3. Zone → zone translation

var localTimeTranslator = new LocalTimeTranslator("America/Denver", "America/Los_Angeles");

// Local DateTime in input zone → local DateTimeOffset in output zone
var losAngelesDateTimeOffset = localTimeTranslator.ToOutputDateTimeOffset(someDenverDateTime);

// Or get a local DateTime in the output zone
var losAngelesDateTime = localTimeTranslator.ToOutputDateTime(someDenverDateTime);

Note: Using nowPrecision only affects LocalNow and UtcNow; it does not truncate time values passed to other methods.

4. Verbose DST Resolution

// In the US, for a 'fall back' DST transition, the 1 AM hour repeats
var ambiguousLocalTime = DateTime.Parse("2025-11-02T01:30:00");

// resolve with details
var resolved = localTimeService.Resolve(ambiguousLocalTime);

// resolved.IsAmbiguous()        → true
// resolved.IsSkipped()          → false
// resolved.Matches[0]           → 2025-11-02T01:30:00-06:00
// resolved.Matches[1]           → 2025-11-02T01:30:00-07:00
// resolved.ForwardShifted       → null
// resolved.StartOfIntervalAfter → null

// In the US, for a 'spring forward' DST transition, the 2 AM hour is skipped
var skippedLocalTime = DateTime.Parse("2025-03-09T02:30:00");

// resolve with details
var resolved = localTimeService.Resolve(skippedLocalTime);

// resolved.IsAmbiguous()        → false
// resolved.IsSkipped()          → true
// resolved.Matches              → (empty)
// resolved.ForwardShifted       → 2025-03-09T03:30:00-07:00
// resolved.StartOfIntervalAfter → 2025-03-09T03:00:00-07:00

Quantized Now

Optionally truncate "now" to a specified precision (e.g., seconds, milliseconds) for database compatibility. Though the DateTime type can represent time with sub-microsecond precision, sometimes other systems (e.g., databases) do not.

var service = new LocalTimeService("America/Denver", nowPrecision: TimePrecision.Second);

// DateTimeOffset.Now   → 2025-01-01T12:34:56.78987654-07:00 (full sub-microsecond precision)
// service.LocalNow     → 2025-01-01T12:34:56.00000000-07:00 (truncated to second precision)

Injecting with DI (typical ASP.NET Core)

services.AddSingleton<ILocalTimeService>(sp => new LocalTimeService("America/Denver"));

Note: "Local" refers to the time zone configured on the service (TimeZoneId).

Notes

Made with ♥ by Jake — Licensed under the MIT License