Consider introducing a separate RegionTimeZone class

[dkhalanskyjb]

Right now, we have an all-encompassing class TimeZone and its subclass, FixedOffsetTimeZone: TimeZone.

TimeZone can be an interface instead, with two separate implementations: FixedOffsetTimeZone and RegionTimeZone. We could split the time zones by what identifier they have:

• IANA tzdb identifiers, like Etc/UTC or Europe/Berlin,
• and generic identifiers like GMT+01:30.

An upside is that a RegionTimeZone would always have a valid IANA timezone database identifier, guaranteed to be recognized everywhere: see #222. A downside is that Etc/UTC is also semantically a fixed-offset time zone, but wouldn't be marked as such. Also, something like Etc/UTC is not even a region, so maybe another name is needed.

[kevincianfarini]

Do the names NamedTimeZone and AnonymousTimeZone fit here? The former would be an entry in tzdb, and the latter would essentially just wrap a UtcOffset.

Thanks for taking a look into this!

[straight-shoota]

The current model is pretty good and correlates with well defined terms in the time zone handling.
The general concept is called a time zone. A fixed-offset time zone is considered a specialization.

From a programmer's perspective, fixed-offset is simpler and has less features than a dynamic offset, which might suggest the inheritance should be inverted. But from a domain modeling perspective, this doesn't really make sense.
Every time zone has a name and maps an offset to any specific instance of time. That name can be an IANA identifier or not. The offset can be always the same or not.

[kevincianfarini]

An upside is that a RegionTimeZone would always have a valid IANA timezone database identifier, guaranteed to be recognized everywhere: see #222. A downside is that Etc/UTC is also semantically a fixed-offset time zone, but wouldn't be marked as such. Also, something like Etc/UTC is not even a region, so maybe another name is needed.

Based on the discussion in #222 might I recommend the names DatabaseEntryTimeZone and FixedOffsetTimeZone? I didn't realize that tzdb recognized entries like Etc/UTC+11 for example, so the prefix "region" definitely doesn't feel like a good fit. If we wanted to be really specific, maybe the name IANADatabaseTimeZone would be good, though I could see how that'd be considered overkill.

TimeZone can be an interface instead

Is it planned that such an interface would be sealed? It'd be helpful for ensuring that other libraries which depend on kotlinx-datetime don't offer their own implementations of TimeZone, though I know that sealed structures can often cause pain points in maintaining backwards compatibility for libraries. If it is planned, I imagine the three inheritors could be:

public sealed interface TimeZone { 
  
  public val id: String 

  public fun offsetAt(instant: Instant): UtcOffset

  // Acts like the canonical UTC time zone in tzdb, but doesn't require reading from the filesystem. 
  public object UTC : TimeZone { 
    override val id: String get() = "Etc/UTC"
    public fun offsetAt(instant: Instant) = UtcOffset(0)
  }
}

// One UTC offset. In memory only. 
public class FixedOffsetTimeZone(...) : TimeZone { /* implementation */ }

// Queries some local tzdb data file.
public class DatabaseEntryTimeZone(...) : TimeZone { /* implementation */ }

Do the maintainers agree?