Temporal in Rust

Temporal is a calendar and timezone aware date/time builtin currently proposed for addition to the ECMAScript specification.

temporal_rs is an implementation of Temporal in Rust that aims to be 100% test compliant. While initially developed for Boa, the crate has been externalized and is being used in other engines such as V8 and Kiesel.

For more information on temporal_rs's general position in the Rust date/time library ecoystem, see our FAQ.

Example usage

Below are a few examples to give an overview of temporal_rs's current API.

Convert from an ISO8601 PlainDate into a Japanese PlainDate.

use temporal_rs::{PlainDate, Calendar};
use tinystr::tinystr;
use core::str::FromStr;
// Create a date with an ISO calendar
let iso8601_date = PlainDate::try_new_iso(2025, 3, 3).unwrap();
// Create a new date with the japanese calendar
let japanese_date = iso8601_date.with_calendar(Calendar::from_str("japanese").unwrap()).unwrap();
assert_eq!(japanese_date.era(), Some(tinystr!(16, "reiwa")));
assert_eq!(japanese_date.era_year(), Some(7));
assert_eq!(japanese_date.month(), 3)

Create a PlainDateTime from a RFC9557 IXDTF string.

For more information on the Internet Extended DateTime Format (IXDTF), see RFC9557.

use temporal_rs::PlainDateTime;
use core::str::FromStr;

let pdt = PlainDateTime::from_str("2025-03-01T11:16:10[u-ca=gregory]").unwrap();
assert_eq!(pdt.calendar().identifier(), "gregory");
assert_eq!(pdt.year(), 2025);
assert_eq!(pdt.month(), 3);
assert_eq!(pdt.day(), 1);
assert_eq!(pdt.hour(), 11);
assert_eq!(pdt.minute(), 16);
assert_eq!(pdt.second(), 10);

Create a ZonedDateTime for a RFC9557 IXDTF string.

Important Note: The below API is enabled with the compiled_data feature flag.

use temporal_rs::{ZonedDateTime, TimeZone};
use temporal_rs::options::{Disambiguation, OffsetDisambiguation};

let zdt = ZonedDateTime::from_str("2025-03-01T11:16:10Z[America/Chicago][u-ca=iso8601]", Disambiguation::Compatible, OffsetDisambiguation::Reject).unwrap();
assert_eq!(zdt.year().unwrap(), 2025);
assert_eq!(zdt.month().unwrap(), 3);
assert_eq!(zdt.day().unwrap(), 1);
assert_eq!(zdt.hour().unwrap(), 11);
assert_eq!(zdt.minute().unwrap(), 16);
assert_eq!(zdt.second().unwrap(), 10);

let zurich_zone = TimeZone::try_from_str("Europe/Zurich").unwrap();
let zdt_zurich = zdt.with_timezone(zurich_zone).unwrap();
assert_eq!(zdt_zurich.year().unwrap(), 2025);
assert_eq!(zdt_zurich.month().unwrap(), 3);
assert_eq!(zdt_zurich.day().unwrap(), 1);
assert_eq!(zdt_zurich.hour().unwrap(), 18);
assert_eq!(zdt_zurich.minute().unwrap(), 16);
assert_eq!(zdt_zurich.second().unwrap(), 10);

Temporal proposal

Relevant links and information regarding Temporal can be found below.

• Temporal MDN
• Temporal Documentation
• Temporal Proposal Specification
• Temporal Proposal Repository

Core maintainers

• Kevin Ness
• Manish Goregaokar
• José Julián Espina
• Jason Williams
• Haled Odat
• Boa Developers

Contributing

This project is open source and welcomes anyone interested to participate. Please see CONTRIBUTING.md for more information.

Test262 Conformance

The temporal_rs's current conformance results can be viewed on Boa's test262 conformance page.

FFI

temporal_rs currently has bindings for C++, available via the temporal_capi crate.

Communication

Feel free to contact us on Matrix.

License

This project is licensed under the Apache or MIT licenses, at your option.