#temporal

///|
test "the core types" {
  // A calendar date: no time, no time zone.
  let date = @temporal.PlainDate::try_new(2025, 3, 1)
  inspect(date, content="2025-03-01")

  // A wall-clock time: no date, no time zone.
  let time = @temporal.PlainTime::try_new(hour=11, minute=16, second=10)
  inspect(time, content="11:16:10")

  // The two combined.
  inspect(date.to_plain_date_time(time~), content="2025-03-01T11:16:10")

  // An exact point on the timeline.
  inspect(
    @temporal.Instant::of_string("2025-03-01T11:16:10Z"),
    content="2025-03-01T11:16:10Z",
  )

  // A span of time, with no anchor.
  inspect(@temporal.Duration::of(hours=2, minutes=30), content="PT2H30M")
}

#Installation

moon add marianoguerra/temporal

import {
  "marianoguerra/temporal",
}

#What it covers

#Calendar arithmetic is not day counting

///|
test "month arithmetic is calendar-aware" {
  let one_month = @temporal.Duration::of(months=1)

  // February has no 31st, so the day is constrained to the end of the month —
  // and how far depends on whether it is a leap year.
  inspect(
    @temporal.PlainDate::try_new(2023, 1, 31).add(one_month),
    content="2023-02-28",
  )
  inspect(
    @temporal.PlainDate::try_new(2024, 1, 31).add(one_month),
    content="2024-02-29",
  )

  // `reject` turns the constraint into an error instead.
  let jan31 = @temporal.PlainDate::try_new(2023, 1, 31)
  try jan31.add(one_month, overflow=Reject) |> ignore catch {
    _ => ()
  } noraise {
    _ => fail("expected the constrained day to be rejected")
  }
}

///|
test "a difference is expressed in the units you ask for" {
  let start = @temporal.PlainDate::try_new(2019, 1, 1)
  let end = @temporal.PlainDate::try_new(2023, 9, 15)
  let with_unit = (unit : @temporal.DateTimeUnit) => {
    start.until(
      end,
      settings=@temporal.DifferenceSettings::new(largest_unit=unit),
    )
  }
  inspect(with_unit(Year), content="P4Y8M14D")
  inspect(with_unit(Month), content="P56M14D")
  inspect(with_unit(Day), content="P1718D")
}

#Durations

///|
test "durations round and total against a reference point" {
  let duration = @temporal.Duration::of_string("P1Y2M3DT4H5M6.789S")
  inspect(duration.years(), content="1")
  inspect(duration.months(), content="2")

  // Time-only durations need no reference.
  inspect(
    @temporal.Duration::of(minutes=45).add(@temporal.Duration::of(hours=1)),
    content="PT1H45M",
  )
  inspect(
    @temporal.Duration::of(hours=1, minutes=30).total(
      Minute,
      @temporal.utc_only_provider,
    ),
    content="90",
  )

  // Calendar units need one, because their length depends on where they start.
  // From 2020-01-01, 45 days is one month and 14 days, and 14 is less than
  // half of February's 29, so it rounds down.
  let relative = @temporal.PlainDate::try_new(2020, 1, 1)
  inspect(
    @temporal.Duration::of(days=45).round(
      @temporal.RoundingOptions::new(smallest_unit=Month),
      @temporal.utc_only_provider,
      relative_to=DateRelative(relative),
    ),
    content="P1M",
  )
}

#Rounding

///|
test "rounding" {
  let time = @temporal.PlainTime::try_new(hour=12, minute=34, second=56)
  inspect(
    time.round(@temporal.RoundingOptions::new(smallest_unit=Minute)),
    content="12:35:00",
  )
  inspect(
    time.round(
      @temporal.RoundingOptions::new(smallest_unit=Minute, rounding_mode=Floor),
    ),
    content="12:34:00",
  )
  // The increment must divide its unit evenly.
  inspect(
    time.round(
      @temporal.RoundingOptions::new(
        smallest_unit=Minute,
        increment=@temporal.RoundingIncrement::try_new(15),
      ),
    ),
    content="12:30:00",
  )
}

#Parsing and formatting

///|
test "RFC 9557 strings" {
  inspect(
    @temporal.PlainDateTime::of_string("2025-03-01T11:16:10.5[u-ca=iso8601]"),
    content="2025-03-01T11:16:10.5",
  )
  // A `Z` designator asserts an exact instant, so a plain type rejects it.
  try
    @temporal.PlainDateTime::of_string("2025-03-01T11:16:10Z") |> ignore
  catch {
    err => assert_true(err is @temporal.RangeError(_))
  } noraise {
    _ => fail("expected the UTC designator to be rejected")
  }
}

#Time zones

///|
test "zoned date-times over a fixed offset" {
  let zdt = @temporal.ZonedDateTime::of_string(
    "2025-03-01T11:16:10Z[UTC]", @temporal.utc_only_provider,
  )
  inspect(zdt.hour(), content="11")

  // Moving to another zone keeps the instant and changes the wall clock.
  let chicago_offset = @temporal.TimeZone::OffsetZone(
    @temporal.UtcOffset::from_minutes(-360),
  )
  let shifted = zdt.with_time_zone(chicago_offset, @temporal.utc_only_provider)
  inspect(shifted.hour(), content="5")
  assert_eq(shifted.epoch_nanoseconds(), zdt.epoch_nanoseconds())
}

#Errors

///|
test "errors carry an ECMAScript error kind" {
  try @temporal.PlainDate::try_new(2023, 2, 30) |> ignore catch {
    err => {
      assert_true(err is @temporal.RangeError(_))
      inspect(err.kind_name(), content="RangeError")
    }
  } noraise {
    _ => fail("expected February 30th to be rejected")
  }
}

#Scope and known differences from temporal_rs

• Only the ISO 8601 calendar is implemented. The Calendar type exists and round-trips through parsing and toString annotations, but a non-ISO identifier such as gregory or japanese raises a RangeError explaining that it is recognized but unimplemented. temporal_rs supports these through ICU4X.
• No time zone database is embedded. Fixed offsets and UTC work directly; named IANA zones need a TimeZoneProvider implementation. temporal_rs ships compiled TZif data behind a feature flag.
• No access to the host clock. There is no Now; construct an Instant from epoch nanoseconds supplied by the caller.

#Testing

• Unit tests (temporal_test.mbt) cover the named edge cases: range limits, month-length interactions, and the regressions temporal_rs carries tests for.
• Property tests (property_test.mbt, int128/int128_test.mbt) assert laws rather than values — round trips, symmetries, idempotence — using the seeded generator in internal/prop. The 128-bit integer type is checked against BigInt as an oracle, including that its Double conversion is correctly rounded.
• Conformance tests (conformance_cases_test.mbt) replay several thousand operations whose expected results were produced by temporal_rs itself. The file is generated, so moon test re-checks this port against the reference implementation without needing Rust installed.
• Differential fuzzing (tools/fuzz.py) generates fresh random cases on every run and compares them against the Rust oracle live.

cargo build --release --manifest-path tools/oracle/Cargo.toml

# Refresh the frozen corpus.
python3 tools/gen_conformance.py

# Fuzz against the oracle; each round uses a fresh seed.
python3 tools/fuzz.py --rounds 20 --count 3000

#References

• Temporal proposal and its documentation
• MDN: Temporal
• temporal_rs, the Rust implementation this port follows

#License