A comprehensive calendar library for Gleam, providing robust date, time, and datetime operations with full ISO 8601 support. Ported from Elixir's Calendar modules.

sidereal /saɪˈdɪəriəl/ — of or relating to the stars. Sidereal time is the ancient astronomical method of measuring time by the apparent motion of the stars rather than the Sun. Just as astronomers rely on the stars for precise timekeeping, this library provides precise and complete date, time, and datetime operations for Gleam.

gleam add sidereal@1

import calendar/date
import calendar/time
import calendar/datetime
import calendar/duration

pub fn main() {
  // Create and validate dates
  let assert Ok(d) = date.new_simple(2024, 12, 25)

  // Work with time (microsecond precision)
  let assert Ok(t) = time.new_simple(14, 30, 0)

  // Combine into a UTC datetime
  let assert Ok(dt) = datetime.new_utc_simple(2024, 12, 25, 14, 30, 0)

  // Parse ISO 8601 strings
  let assert Ok(d2) = date.from_iso8601("2024-06-15")

  // Date arithmetic
  let assert Ok(tomorrow) = date.add_days(d, 1)
  let diff = date.diff(d, d2)

  // Durations with ISO 8601 support
  let assert Ok(dur) = duration.from_iso8601("P1Y2M3DT4H5M6S")
  let assert Ok(shifted) = date.shift(d, dur)
}

• Date Operations: Creation, validation, arithmetic, and formatting
• Time Handling: Precise time with microsecond support
• DateTime Management: Combined date and time with timezone awareness
• Naive DateTime: DateTime without timezone for local representations
• Duration Arithmetic: Add, subtract, multiply, and parse time durations
• ISO 8601 Support: Full parsing and formatting compliance
• Date Ranges: Iterate over date sequences with custom steps
• Type Safety: Comprehensive error handling with Result types
• Zero Dependencies: Only requires gleam_stdlib
• Cross-Platform: Works on both Erlang and JavaScript targets

• calendar/date - Date creation, validation, arithmetic, and formatting
• calendar/time - Time handling with microsecond precision
• calendar/datetime - Combined date and time with timezone support
• calendar/naive_datetime - DateTime without timezone awareness
• calendar/duration - Duration arithmetic with ISO 8601 parsing
• calendar/iso - ISO 8601 calendar system utilities
• calendar/date_range - Date range iteration and membership

This library provides optional interoperability with the gleam_time package for users who need it.

• All calendar functions work without any additional dependencies
• No compilation errors or runtime dependencies on gleam_time
• Self-contained — use sidereal with just gleam_stdlib

1. Add gleam_time to your project:

   [dependencies]
   gleam_time = ">= 1.0.0 and < 2.0.0"

2. Copy the interop module to your project:

   cp optional_modules/gleam_time_interop.gleam src/calendar/

3. Use the conversion functions:

   import calendar/date
   import calendar/gleam_time_interop as interop
   import gleam/time/timestamp
   
   let assert Ok(our_date) = date.new_simple(2024, 1, 15)
   let gleam_date = interop.date_to_gleam(our_date)
   
   let timestamp = timestamp.system_time()
   let our_datetime = interop.datetime_from_timestamp(timestamp)

• Date: date_to_gleam, date_from_gleam
• Time: time_to_gleam, time_from_gleam
• DateTime/Timestamp: datetime_to_timestamp, datetime_from_timestamp
• NaiveDateTime: naive_datetime_to_gleam, naive_datetime_from_gleam
• Duration: duration_to_gleam, duration_from_gleam

Further documentation can be found at https://hexdocs.pm/sidereal.

gleam test  # Run the tests
gleam build # Build the project

This library is a Gleam port of Elixir's Calendar modules. The date/time algorithms and API design are derived from the work of the Elixir Team and Plataformatec.

Apache License 2.0