Implement Foundation-based time zone support for Darwin systems with comprehensive DST handling (#539)

- Extract TimeZoneRules interface to abstract timezone operations
- Refactor existing tzdb logic into TimeZoneRulesCommon
- Add TimeZoneRulesFoundation using NSTimeZone for Darwin platforms
- Handle DST transitions (gaps/overlaps) with Foundation APIs
- Add comprehensive tests verifying Foundation/tzdb behavior parity

Fixes #485

Author: DmitryNekrasov

core/androidNative/src/internal/TzdbBionic.kt

@@ -10,13 +10,13 @@
 package kotlinx.datetime.internal
 
 private class TzdbBionic(private val rules: Map<String, Entry>) : TimeZoneDatabase {
-    override fun rulesForId(id: String): TimeZoneRules =
+    override fun rulesForId(id: String): TimeZoneRulesCommon =
         rules[id]?.readRules() ?: throw IllegalStateException("Unknown time zone $id")
 
     override fun availableTimeZoneIds(): Set<String> = rules.keys
 
     class Entry(val file: ByteArray, val offset: Int, val length: Int) {
-        fun readRules(): TimeZoneRules = readTzFile(file.copyOfRange(offset, offset + length)).toTimeZoneRules()
+        fun readRules(): TimeZoneRulesCommon = readTzFile(file.copyOfRange(offset, offset + length)).toTimeZoneRules()
     }
 }
 

core/commonJs/src/internal/Platform.kt

@@ -61,7 +61,7 @@ private val tzdb: Result<TimeZoneDatabase?> = runCatching {
         return (wholeMinutes * SECONDS_PER_MINUTE + seconds) * sign
     }
 
-    val zones = mutableMapOf<String, TimeZoneRules>()
+    val zones = mutableMapOf<String, TimeZoneRulesCommon>()
     val (zonesPacked, linksPacked) = readTzdb() ?: return@runCatching null
     for (zone in zonesPacked) {
         val components = zone.split('|')
@@ -70,7 +70,7 @@ private val tzdb: Result<TimeZoneDatabase?> = runCatching {
         }
         val indices = components[3].map { charCodeToInt(it) }
         val lengthsOfPeriodsWithOffsets = components[4].split(' ').map(::base60MinutesInSeconds)
-        zones[components[0]] = TimeZoneRules(
+        zones[components[0]] = TimeZoneRulesCommon(
             transitionEpochSeconds = lengthsOfPeriodsWithOffsets.runningReduce(Long::plus).let {
                 if (it.size == indices.size - 1) it else it.take<Long>(indices.size - 1)
             },
@@ -85,7 +85,7 @@ private val tzdb: Result<TimeZoneDatabase?> = runCatching {
         }
     }
     object : TimeZoneDatabase {
-        override fun rulesForId(id: String): TimeZoneRules =
+        override fun rulesForId(id: String): TimeZoneRulesCommon =
             zones[id] ?: throw IllegalTimeZoneException("Unknown time zone: $id")
 
         override fun availableTimeZoneIds(): Set<String> = zones.keys
@@ -135,7 +135,7 @@ internal actual fun timeZoneById(zoneId: String): TimeZone {
     throw IllegalTimeZoneException("js-joda timezone database is not available")
 }
 
-internal fun rulesForId(zoneId: String): TimeZoneRules? = tzdb.getOrThrow()?.rulesForId(zoneId)
+internal fun rulesForId(zoneId: String): TimeZoneRulesCommon? = tzdb.getOrThrow()?.rulesForId(zoneId)
 
 internal actual fun getAvailableZoneIds(): Set<String> =
     tzdb.getOrThrow()?.availableTimeZoneIds() ?: setOf("UTC")

core/commonKotlin/src/internal/TimeZoneDatabase.kt

@@ -6,6 +6,6 @@
 package kotlinx.datetime.internal
 
 internal interface TimeZoneDatabase {
-    fun rulesForId(id: String): TimeZoneRules
+    fun rulesForId(id: String): TimeZoneRulesCommon
     fun availableTimeZoneIds(): Set<String>
 }

core/commonKotlin/src/internal/TimeZoneRules.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2023 JetBrains s.r.o. and contributors.
+ * Copyright 2019-2025 JetBrains s.r.o. and contributors.
  * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
  */
 
@@ -11,7 +11,14 @@ import kotlinx.datetime.toLocalDateTime
 import kotlin.math.*
 import kotlin.time.Instant
 
-internal class TimeZoneRules(
+internal interface TimeZoneRules {
+
+    fun infoAtInstant(instant: Instant): UtcOffset
+
+    fun infoAtDatetime(localDateTime: LocalDateTime): OffsetInfo
+}
+
+internal class TimeZoneRulesCommon(
     /**
      * The list of [Instant.epochSeconds] parts of the instants when recorded transitions occur, in ascending order.
      */
@@ -31,15 +38,15 @@ internal class TimeZoneRules(
      * [recurringZoneRules].
      */
     val recurringZoneRules: RecurringZoneRules?,
-) {
+) : TimeZoneRules {
     init {
         require(offsets.size == transitionEpochSeconds.size + 1) {
             "offsets.size must be one more than transitionEpochSeconds.size"
         }
     }
 
     /**
-     * Constructs a [TimeZoneRules] without any historic data.
+     * Constructs a [TimeZoneRulesCommon] without any historic data.
      */
     constructor(initialOffset: UtcOffset, rules: RecurringZoneRules) : this(
         transitionEpochSeconds = emptyList(),
@@ -68,7 +75,7 @@ internal class TimeZoneRules(
         }
     }
 
-    fun infoAtInstant(instant: Instant): UtcOffset {
+    override fun infoAtInstant(instant: Instant): UtcOffset {
         val epochSeconds = instant.epochSeconds
         // good: no transitions, or instant is after the last transition
         if (recurringZoneRules != null && transitionEpochSeconds.lastOrNull()?.let { epochSeconds >= it } != false) {
@@ -84,7 +91,7 @@ internal class TimeZoneRules(
         return offsets[index]
     }
 
-    fun infoAtDatetime(localDateTime: LocalDateTime): OffsetInfo {
+    override fun infoAtDatetime(localDateTime: LocalDateTime): OffsetInfo {
         if (recurringZoneRules != null && transitionLocalDateTimes.lastOrNull()?.let { localDateTime > it } != false) {
             return recurringZoneRules.infoAtLocalDateTime(localDateTime, offsets.last())
         }
@@ -177,6 +184,12 @@ internal class RecurringZoneRules(
         }
     }
 
+    /**
+     * IMPORTANT: keep this implementation in sync with [TimeZoneRulesFoundation.infoAtDatetime].
+     * The algorithms and corner-case handling should stay identical so that Darwin (Foundation-based)
+     * and tzdb-based platforms compute the same results.  When you change logic here, reflect the
+     * same change in [TimeZoneRulesFoundation.infoAtDatetime].
+     */
     fun infoAtLocalDateTime(localDateTime: LocalDateTime, offsetAtYearStart: UtcOffset): OffsetInfo {
         val year = localDateTime.year
         var offset = offsetAtYearStart

core/commonKotlin/src/internal/Tzfile.kt

@@ -40,13 +40,13 @@ internal class TzFileData(
 }
 
 internal class TzFile(val data: TzFileData, val rules: PosixTzString?) {
-    fun toTimeZoneRules(): TimeZoneRules {
+    fun toTimeZoneRules(): TimeZoneRulesCommon {
         val tzOffsets = buildList {
             add(data.states[0].offset)
             data.transitions.forEach { add(data.states[it.stateIndex].offset) }
         }
         val offsets = tzOffsets.map { it.toUtcOffset() }
-        return TimeZoneRules(data.transitions.map { it.time }, offsets, rules?.toRecurringZoneRules())
+        return TimeZoneRulesCommon(data.transitions.map { it.time }, offsets, rules?.toRecurringZoneRules())
     }
 }
 

core/commonKotlin/test/TimeZoneRulesTest.kt

@@ -37,7 +37,7 @@ class TimeZoneRulesTest {
         val ruleString = "AST4ADT,M3.2.0,M11.1.0\n" // Atlantic/Bermuda
         val recurringRules =
             PosixTzString.readIfPresent(BinaryDataReader(ruleString.encodeToByteArray()))!!.toRecurringZoneRules()!!
-        val rules = TimeZoneRules(UtcOffset(hours = -4), recurringRules)
+        val rules = TimeZoneRulesCommon(UtcOffset(hours = -4), recurringRules)
         val dstStartTime = LocalDateTime(2020, 3, 8, 2, 1)
         val infoAtDstStart = rules.infoAtDatetime(dstStartTime)
         assertTrue(infoAtDstStart is OffsetInfo.Gap, "Expected Gap, got $infoAtDstStart")

core/darwin/src/internal/TimeZoneNative.kt

@@ -1,21 +1,33 @@
 /*
- * Copyright 2019-2020 JetBrains s.r.o.
+ * Copyright 2019-2025 JetBrains s.r.o.
  * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
  */
 
 @file:OptIn(ExperimentalForeignApi::class)
+
 package kotlinx.datetime.internal
 
 import kotlinx.cinterop.*
 import kotlinx.datetime.TimeZone
-import kotlinx.datetime.internal.*
 import platform.Foundation.*
 
 internal actual fun timeZoneById(zoneId: String): TimeZone =
-    RegionTimeZone(tzdb.getOrThrow().rulesForId(zoneId), zoneId)
+    if (tzdb.isSuccess)
+        RegionTimeZone(tzdb.getOrThrow().rulesForId(zoneId), zoneId)
+    else
+        timeZoneByIdFoundation(zoneId)
+
+internal fun timeZoneByIdFoundation(zoneId: String): TimeZone =
+    RegionTimeZone(TimeZoneRulesFoundation(zoneId), zoneId)
 
 internal actual fun getAvailableZoneIds(): Set<String> =
-    tzdb.getOrThrow().availableTimeZoneIds()
+    if (tzdb.isSuccess)
+        tzdb.getOrThrow().availableTimeZoneIds()
+    else
+        getAvailableZoneIdsFoundation()
+
+internal fun getAvailableZoneIdsFoundation(): Set<String> =
+    NSTimeZone.knownTimeZoneNames.mapTo(mutableSetOf("UTC")) { it.toString() }
 
 private val tzdb = runCatching { TzdbOnFilesystem(Path.fromString(defaultTzdbPath())) }
 

core/darwin/src/internal/TimeZoneRulesFoundation.kt

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2019-2025 JetBrains s.r.o. and contributors.
+ * Use of this source code is governed by the Apache 2.0 License that can be found in the LICENSE.txt file.
+ */
+
+package kotlinx.datetime.internal
+
+import kotlinx.cinterop.ExperimentalForeignApi
+import kotlinx.cinterop.UnsafeNumber
+import kotlinx.cinterop.convert
+import kotlinx.datetime.LocalDateTime
+import kotlinx.datetime.UtcOffset
+import kotlinx.datetime.toKotlinInstant
+import kotlinx.datetime.toLocalDateTime
+import kotlinx.datetime.toNSDate
+import kotlinx.datetime.toNSDateComponents
+import platform.Foundation.NSCalendar
+import platform.Foundation.NSCalendarIdentifierISO8601
+import platform.Foundation.NSCalendarUnitYear
+import platform.Foundation.NSDate
+import platform.Foundation.NSTimeZone
+import platform.Foundation.timeZoneWithName
+import kotlin.time.Instant
+
+internal class TimeZoneRulesFoundation(private val zoneId: String) : TimeZoneRules {
+    private val nsTimeZone: NSTimeZone = NSTimeZone.timeZoneWithName(zoneId)
+        ?: throw IllegalArgumentException("Unknown timezone: $zoneId")
+
+    override fun infoAtInstant(instant: Instant): UtcOffset =
+        infoAtNsDate(instant.toNSDate())
+
+    /**
+     * IMPORTANT: mirrors the logic in [RecurringZoneRules.infoAtLocalDateTime].
+     * Any update to offset calculations, transition handling, or edge cases
+     * must be duplicated there to maintain consistent behavior across
+     * all platforms.
+     */
+    @OptIn(UnsafeNumber::class, ExperimentalForeignApi::class)
+    override fun infoAtDatetime(localDateTime: LocalDateTime): OffsetInfo {
+        val calendar = NSCalendar.calendarWithIdentifier(NSCalendarIdentifierISO8601)
+            ?.apply { timeZone = nsTimeZone }
+
+        val year = localDateTime.year
+        val startOfTheYear = calendar?.dateFromComponents(LocalDateTime(year, 1, 1, 0, 0).toNSDateComponents())
+        check(startOfTheYear != null) { "Failed to get the start of the year for $localDateTime, timezone: $zoneId" }
+
+        var currentDate: NSDate = startOfTheYear
+        var offset = infoAtNsDate(startOfTheYear)
+        do {
+            val transitionDateTime = nsTimeZone.nextDaylightSavingTimeTransitionAfterDate(currentDate)
+            if (transitionDateTime == null) break
+
+            val yearOfNextDate = calendar.component(NSCalendarUnitYear.convert(), fromDate = transitionDateTime)
+            val transitionDateTimeInstant = transitionDateTime.toKotlinInstant()
+
+            val offsetBefore = infoAtNsDate(currentDate)
+            val ldtBefore = transitionDateTimeInstant.toLocalDateTime(offsetBefore)
+            val offsetAfter = infoAtNsDate(transitionDateTime)
+            val ldtAfter = transitionDateTimeInstant.toLocalDateTime(offsetAfter)
+
+            return if (localDateTime < ldtBefore && localDateTime < ldtAfter) {
+                OffsetInfo.Regular(offsetBefore)
+            } else if (localDateTime >= ldtBefore && localDateTime >= ldtAfter) {
+                offset = offsetAfter
+                currentDate = transitionDateTime
+                continue
+            } else if (ldtAfter < ldtBefore) {
+                OffsetInfo.Overlap(transitionDateTimeInstant, offsetBefore, offsetAfter)
+            } else {
+                OffsetInfo.Gap(transitionDateTimeInstant, offsetBefore, offsetAfter)
+            }
+        } while (yearOfNextDate <= year)
+
+        return OffsetInfo.Regular(offset)
+    }
+
+    @OptIn(UnsafeNumber::class, ExperimentalForeignApi::class)
+    private fun infoAtNsDate(nsDate: NSDate): UtcOffset {
+        val offsetSeconds = nsTimeZone.secondsFromGMTForDate(nsDate)
+        return UtcOffset(seconds = offsetSeconds.convert())
+    }
+}