lots of moving things around and need to do test stuff

Author: devries

examples/time_now/src/time_now.gleam

@@ -17,12 +17,12 @@ pub fn main() {
 
 fn print_all_times(
   now: timestamp.Timestamp,
-) -> Result(Nil, timezone.TimeZoneError) {
+) -> Result(Nil, database.TzDatabaseError) {
   let db = database.load_from_os()
 
   database.get_available_timezones(db)
   |> list.map(fn(zone_name) {
-    case timezone.get_time_in_zone_tzdb(now, zone_name, db) {
+    case timezone.get_time_in_zone(now, zone_name, db) {
       Ok(tiz) ->
         io.println(
           string.pad_end(zone_name <> ":", 40, " ") <> format_time(tiz),

gleam.toml

@@ -1,5 +1,5 @@
 name = "timezone"
-version = "0.1.0"
+version = "0.2.0"
 
 # Fill out these fields if you intend to generate HTML documentation or publish
 # your project to the Hex package manager.
@@ -17,7 +17,6 @@ gleam_stdlib = ">= 0.44.0 and < 2.0.0"
 gleam_time = ">= 1.4.0 and < 2.0.0"
 simplifile = ">= 2.3.0 and < 3.0.0"
 filepath = ">= 1.1.2 and < 2.0.0"
-envoy = ">= 1.0.2 and < 2.0.0"
 
 [dev-dependencies]
 gleeunit = ">= 1.0.0 and < 2.0.0"

manifest.toml

@@ -2,7 +2,6 @@
 # You typically do not need to edit this file
 
 packages = [
-  { name = "envoy", version = "1.0.2", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "envoy", source = "hex", outer_checksum = "95FD059345AA982E89A0B6E2A3BF1CF43E17A7048DCD85B5B65D3B9E4E39D359" },
   { name = "filepath", version = "1.1.2", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "filepath", source = "hex", outer_checksum = "B06A9AF0BF10E51401D64B98E4B627F1D2E48C154967DA7AF4D0914780A6D40A" },
   { name = "gleam_stdlib", version = "0.63.2", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "962B25C667DA07F4CAB32001F44D3C41C1A89E58E3BBA54F183B482CF6122150" },
   { name = "gleam_time", version = "1.4.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_time", source = "hex", outer_checksum = "DCDDC040CE97DA3D2A925CDBBA08D8A78681139745754A83998641C8A3F6587E" },
@@ -11,7 +10,6 @@ packages = [
 ]
 
 [requirements]
-envoy = { version = ">= 1.0.2 and < 2.0.0" }
 filepath = { version = ">= 1.1.2 and < 2.0.0" }
 gleam_stdlib = { version = ">= 0.44.0 and < 2.0.0" }
 gleam_time = { version = ">= 1.4.0 and < 2.0.0" }

src/timezone.gleam

@@ -20,20 +20,7 @@ import gleam/result
 import gleam/time/calendar.{type Date, type TimeOfDay}
 import gleam/time/duration.{type Duration}
 import gleam/time/timestamp.{type Timestamp}
-import timezone/database
-
-/// Time Zone error type
-/// This needs review and change as we split things up
-pub type TimeZoneError {
-  /// Error parsing timezone data
-  ParseError
-
-  /// Error constructing time zone transition table.
-  TimeSliceError
-
-  /// Other error in the Zone file
-  ZoneFileError
-}
+import timezone/database.{type TzDatabase, type TzDatabaseError}
 
 /// Representation of time in a time zone
 pub type TimeInZone {
@@ -46,16 +33,39 @@ pub type TimeInZone {
   )
 }
 
-/// Potentially new API for time_in_zone
-pub fn get_time_in_zone_tzdb(
+/// Given a timestamp, IANA time zone name, and a `TzDatabase` record,
+/// get the data and time of the timestamp along with information about
+/// the timezone, such as its offset from UTC, designation, and if it
+/// is daylight savings time in that zone.
+///
+/// # Example
+///
+/// ```gleam
+/// import gleam/time/timestamp
+/// import timezone/database
+///
+/// let ts = timestamp.from_unix_seconds(1_758_223_300)
+/// let db = database.load_from_os()
+/// 
+/// get_time_in_zone(ts, "America/New_York", db)
+/// // Ok(TimeInZone(
+/// //   Date(2025, September, 18),
+/// //   TimeOfDay(15, 21, 40, 0),
+/// //   Duration(-14_400, 0),
+/// //   "EDT",
+/// //   True,
+/// // ))
+/// ```
+pub fn get_time_in_zone(
   ts: Timestamp,
   zone_name: String,
-  db: database.TzDatabase,
-) -> Result(TimeInZone, TimeZoneError) {
-  use zone_parameters <- result.map(
-    database.get_zone_parameters(ts, zone_name, db)
-    |> result.replace_error(ParseError),
-  )
+  db: TzDatabase,
+) -> Result(TimeInZone, TzDatabaseError) {
+  use zone_parameters <- result.map(database.get_zone_parameters(
+    ts,
+    zone_name,
+    db,
+  ))
 
   let #(dt, tm) = timestamp.to_calendar(ts, zone_parameters.offset)
 

src/timezone/database.gleam

@@ -11,11 +11,21 @@ import timezone/tzparser
 pub opaque type TzDatabase {
   TzDatabase(
     zone_names: List(String),
-    zone_data: dict.Dict(String, tzparser.TZFile),
+    zone_data: dict.Dict(String, tzparser.TzFile),
   )
 }
 
+/// TzDatabase error types
+pub type TzDatabaseError {
+  /// There is no information available for this zone.
+  ZoneNotFound
+  /// Unable to provide zone information due to missing or
+  /// incomplete data.
+  ProcessingError
+}
+
 /// Load timezone database from default operating system location
+/// which is typically "/usr/share/zoneinfo".
 pub fn load_from_os() {
   load_from_path("/usr/share/zoneinfo")
 }
@@ -37,10 +47,28 @@ pub fn load_from_path(path: String) {
   )
 }
 
+/// Create new empty TzDatabase.
+pub fn new() -> TzDatabase {
+  TzDatabase([], dict.new())
+}
+
+/// Add new timezone definition to TzDatabase.
+pub fn add_tzfile(
+  db: TzDatabase,
+  zone_name: String,
+  tzfile: tzparser.TzFile,
+) -> TzDatabase {
+  let namelist = case dict.has_key(db.zone_data, zone_name) {
+    True -> db.zone_names
+    False -> [zone_name, ..db.zone_names] |> list.sort(string.compare)
+  }
+  TzDatabase(namelist, dict.insert(db.zone_data, zone_name, tzfile))
+}
+
 fn process_tzfile(
   filename: String,
   components_to_drop: Int,
-) -> Result(#(String, tzparser.TZFile), Nil) {
+) -> Result(#(String, tzparser.TzFile), Nil) {
   let zone_name =
     filepath.split(filename)
     |> list.drop(components_to_drop)
@@ -49,7 +77,6 @@ fn process_tzfile(
   use tzdata <- result.try(
     simplifile.read_bits(filename) |> result.replace_error(Nil),
   )
-
   use timeinfo <- result.try(
     tzparser.parse(tzdata) |> result.replace_error(Nil),
   )
@@ -70,30 +97,58 @@ pub type ZoneParameters {
   ZoneParameters(offset: Duration, is_dst: Bool, designation: String)
 }
 
+/// Retrieve the time zone parameters for a zone at a particular time.
+/// The time is given as a `gleam/time/timestamp.Timestamp`, the zone name
+/// and a time zone database. Because of
+/// daylight savings time as well as other historical shifts in how time
+/// has been measured, time zone information for a location shifts over time,
+/// therefore the offset or designation you get from the database is time
+/// dependant. Do not assume that the time zone parameters will be the same
+/// at any other time.
+///
+/// # Example
+///
+/// ```gleam
+/// import gleam/time/timestamp
+/// 
+/// let ts = timestamp.from_unix_seconds(1_758_223_300)
+/// let db = database.load_from_os()
+/// 
+/// get_zone_parameters(ts, "America/New_York", db)
+/// // Ok(ZoneParameters(
+/// //   Duration(-144_40, 0),
+/// //   True,
+/// //   "EDT",
+/// // ))
+/// ```
 pub fn get_zone_parameters(
   ts: timestamp.Timestamp,
   zone_name: String,
   db: TzDatabase,
-) -> Result(ZoneParameters, Nil) {
-  use tzdata <- result.try(dict.get(db.zone_data, zone_name))
+) -> Result(ZoneParameters, TzDatabaseError) {
+  use tzdata <- result.try(
+    dict.get(db.zone_data, zone_name) |> result.replace_error(ZoneNotFound),
+  )
   let default = default_slice(tzdata.fields)
 
   let slices = create_slices(tzdata.fields)
 
-  use slice <- result.try(get_slice(ts, slices, default))
+  use slice <- result.try(
+    get_slice(ts, slices, default) |> result.replace_error(ProcessingError),
+  )
 
   Ok(ZoneParameters(slice.utoff, slice.isdst, slice.designation))
 }
 
 // Below are some things I previously had elsewhere
 
 /// Timezone definition slice
-type TTSlice {
-  TTSlice(start_time: Int, utoff: Duration, isdst: Bool, designation: String)
+type TtSlice {
+  TtSlice(start_time: Int, utoff: Duration, isdst: Bool, designation: String)
 }
 
 // Turn time zone fields into a list of timezone information slices
-fn create_slices(fields: tzparser.TZFileFields) -> List(TTSlice) {
+fn create_slices(fields: tzparser.TzFileFields) -> List(TtSlice) {
   let infos =
     list.zip(fields.ttinfos, fields.designations)
     |> list.index_map(fn(tup, idx) { #(idx, tup) })
@@ -108,30 +163,30 @@ fn create_slices(fields: tzparser.TZFileFields) -> List(TTSlice) {
           0 -> False
           _ -> True
         }
-        Ok(TTSlice(tup.0, duration.seconds(ttinfo.utoff), isdst, designation))
+        Ok(TtSlice(tup.0, duration.seconds(ttinfo.utoff), isdst, designation))
       }
       _ -> Error(Nil)
     }
   })
   |> result.values
 }
 
-fn default_slice(fields: tzparser.TZFileFields) -> Result(TTSlice, Nil) {
+fn default_slice(fields: tzparser.TzFileFields) -> Result(TtSlice, Nil) {
   use ttinfo <- result.try(list.first(fields.ttinfos))
   use designation <- result.try(list.first(fields.designations))
   let isdst = case ttinfo.isdst {
     0 -> False
     _ -> True
   }
 
-  Ok(TTSlice(0, duration.seconds(ttinfo.utoff), isdst, designation))
+  Ok(TtSlice(0, duration.seconds(ttinfo.utoff), isdst, designation))
 }
 
 fn get_slice(
   ts: timestamp.Timestamp,
-  slices: List(TTSlice),
-  default: Result(TTSlice, Nil),
-) -> Result(TTSlice, Nil) {
+  slices: List(TtSlice),
+  default: Result(TtSlice, Nil),
+) -> Result(TtSlice, Nil) {
   let #(seconds, _) = timestamp.to_unix_seconds_and_nanoseconds(ts)
 
   slices