Boa v0.21 is now available! After 9 months of development we are very happy to present you the latest release of the Boa JavaScript engine. Boa makes it easy to embed a JS engine in your projects, and you can even use it from WebAssembly. See the about page for more info.

In this release, our conformance has grown from 89.92% to 94.12% in the official ECMAScript Test Suite (Test262). Our growth in conformance is driven by increased conformance for Temporal (discussed further below) with the rest of the development effort being focused on performance, internal improvements, and runtime features. We will continue to implement more of the specification; however, as of the current moment, Boa's conformance aligns with the major browser engine's conformance, so future increases in conformance will be minor or bound to the feature size going forward.

You can check the full list of changes here, and the full information on conformance here.

Feature Highlights​

Temporal​

There has been a lot of progress made on Temporal, the new Stage 3 date/time proposal. With this release, Boa's conformance on Temporal grew from 40.67% to ~97%. This implementation is backed by the temporal_rs date/time Rust library, which we went over in our announcement blog post. Give the post a read if you are interested in temporal_rs and its development history.

Span nodes and error backtraces​

We added support for storing spans in our AST nodes, which allows determining the exact location of an AST node on its original file. We already kind of supported this feature in our lexer, but we did not store the spans after parsing.

Why is this important? Well, as a direct result from this, Boa now supports error backtraces when an exception is thrown!

As an additional plus, you can enable the native-backtrace feature to include "native" functions on a backtrace.

This feature has been one of the most requested ones for years, and we hope it will greatly help with debugging errors when using Boa.

Utility macros​

We introduced a new set of proc macros that make it much easier to create JsValues, JsObjects, Classes and even Modules. Let's see them in action!

js_value​

// Simple values can be created without passing the `Context`.
assert_eq!(js_value!( 1 ), JsValue::from(1));
assert_eq!(js_value!( false ), JsValue::from(false));

// To create arrays and objects, the context needs to be passed in.
assert_eq!(js_value!([ 1, 2, 3 ], context).display().to_string(), "[ 1, 2, 3 ]");
assert_eq!(
  js_value!({
    // Comments are allowed inside.
    "key": (js_string!("value"))
  }, context).display().to_string(),
  "{\n    key: \"value\"\n}",
);

js_object​

let object = js_object!({
  // Comments are allowed inside. String literals will always be transformed to `JsString`.
  "key": "value",
  // Identifiers will be used as keys, like in JavaScript.
  alsoKey: 1,
  // Expressions surrounded by brackets will be expressed, like in JavaScript.
  // Note that in this case, the unit value is represented by `null`.
  [1 + 2]: (),
}, context);

assert_eq!(
    JsValue::from(object).display().to_string(),
    "{\n    3: null,\n    key: \"value\",\n    alsoKey: 1\n}"
);

boa_class​

// All types that will be part of a class instance need to derive the
// `Trace` and `Finalize` traits.
#[derive(Clone, Trace, Finalize, JsData)]
enum AnimalType {
    Cat,
    Dog,
    Other,
}

#[derive(Clone, Trace, Finalize, JsData)]
struct Animal {
    ty: AnimalType,
    age: i32,
}

#[boa_class]
impl Animal {

    // Sets this method as the constructor of the ECMAScript class.
    #[boa(constructor)]
    fn new(name: String, age: i32) -> Self {
        let ty = match name.as_str() {
            "cat" => AnimalType::Cat,
            "dog" => AnimalType::Dog,
            _ => AnimalType::Other,
        };

        Self { ty, age }
    }

    // Any method that takes `&self` will be exposed as an instance method.
    fn speak(#[boa(error = "`this` was not an animal")] &self) -> JsString {
        match self.ty {
            AnimalType::Cat => js_string!("meow"),
            AnimalType::Dog => js_string!("woof"),
            AnimalType::Other => js_string!(r"¯\_(ツ)_/¯"),
        }
    }

    // Force this being a method (instead of a static function) by declaring it
    // as a method.
    #[boa(method)]
    #[boa(length = 11)]
    fn method(context: &mut Context) -> JsObject {
        let obj = JsObject::with_null_proto();
        obj.set(js_string!("key"), 43, false, context).unwrap();
        obj
    }

    // You can define getter methods; `animal.age` will automatically call this
    // on read.
    #[boa(getter)]
    fn age(&self) -> i32 {
        self.age
    }

    // You can also define setter methods; `animal.age = 5` will automatically call
    // this on write.
    #[boa(setter)]
    #[boa(method)]
    #[boa(rename = "age")]
    fn set_age(&mut self, age: i32) {
        self.age = age;
    }

    // This static method will be callable using the constructor function
    // (`Animal.marked_static_method()`).
    #[boa(static)]
    fn marked_static_method() -> i32 {
        123
    }

    // Methods without `&self` are considered static methods.
    fn static_method() -> i32 {
        42
    }
}

let mut context = Context::default();

// This registers the newly created class into the `Realm`.
context.register_global_class::<Animal>().unwrap();

context
    .eval(Source::from_bytes(
        r#"
        let pet = new Animal("dog", 3);
        console.log(pet.age) // 3
        console.log(Animal.staticMethod()) // 42
        console.log(Animal.markedStaticMethod()) // 123

        v = pet.method();
        console.log(v.key) // 43

        pet.age = 4;
        console.log(pet.age) // 4
    "#,
    )).unwrap();

boa_module​

#[boa_module]
mod hello {
    use boa_engine::{JsString, js_string};

    // Exports a function.
    fn world() -> JsString {
        js_string!("hello world")
    }

    // Exports the `Animal` class. This is the class that we defined in the
    // previous section.
    type Animal = super::Animal;

    // Exports a const variable.
    const SOME_LITERAL_NUMBER: i32 = 1234;

    // You can also rename exports.
    #[boa(rename = "this_is_different")]
    const SOME_OTHER_LITERAL: i32 = 5678;
}

// Creates a new `MapModuleLoader` to load our created module into the
// engine.
let module_loader = Rc::new(MapModuleLoader::new());
let mut context = Context::builder()
    .module_loader(module_loader.clone())
    .build()
    .unwrap();

// The module will be exposed as `/hello.js`.
module_loader.insert("/hello.js", hello::boa_module(None, &mut context));

let module = Module::parse(
    Source::from_bytes(
        r#"
            import * as m from '/hello.js';

            console.log(m.someLiteralNumber) // 1234
            console.log(m.this_is_different) // 5678

            console.log(m.world()) // "hello world"

            let pet = new m.Animal("dog", 8);
            console.log(pet.age) // 8
            console.log(pet.speak()) // "woof"
        "#,
    ),
    None,
    &mut context,
).unwrap();

let result = module
    .load_link_evaluate(&mut context)
    .await_blocking(&mut context)
    .unwrap();

Async APIs enhancements​

Historically, hooking functions returning a Future into Boa has been one of the biggest pain points of our API. This was mostly caused by how we defined FutureJob:

pub struct NativeJob {
    f: Box<dyn FnOnce(&mut Context) -> JsResult<JsValue>>,
    realm: Option<Realm>,
}

pub type FutureJob = Pin<Box<dyn Future<Output = NativeJob> + 'static>>;

With this definition, it was pretty much impossible to capture the Context inside the Future, and functions that needed to interweave engine operations with awaiting Futures needed to be split into multiple parts:

let fetch = async move {
    let body: Result<_, isahc::Error> = async {
        let mut response = Request::get(&url)
            .body(())?
            .send_async()
            .await?;

        Ok(response.text().await?)
    }
    .await;

    // Since the async context cannot take the `context` by ref, we have to continue
    // parsing inside a new `NativeJob` that will be enqueued into the promise job queue.
    NativeJob::new(move |context| -> JsResult<JsValue> {
        parse(body).await;

        // Also needed to match `NativeJob::new`.
        Ok(JsValue::undefined())
    })
};

// Just enqueue the future for now. We'll advance all the enqueued futures inside our custom
// `JobQueue`.
context
    .job_queue()
    .enqueue_future_job(Box::pin(fetch), context);

We wanted to improve this API, and the solution we thought about was to make Context shareable by wrapping it using RefCell. However, this proved to be very difficult for two reasons:

1. We needed to change all definitions to take &RefCell<Context> instead of &mut Context, which meant changing pretty much the whole codebase.
2. Some of our VM code was reentrant, and that would cause panics in the reentrant parts of the code when calling RefCell::borrow_mut; we would need to patch up the engine to remove the reentrancy.

After putting a lot of thought on this, we came up with a really nice solution; instead of wrapping Context with RefCell, we would wrap &mut Context with RefCell, and only on the async-related APIs. This would allow not only capturing the context on Future-related functions, but also doing this without having to refactor big parts of the code. Thus, we ditched FutureJob and introduced a new type of job: NativeAsyncJob.

/// An ECMAScript [Job] that can be run asynchronously.
///
/// This is an additional type of job that is not defined by the specification, enabling running `Future` tasks
/// created by ECMAScript code in an easier way.
#[allow(clippy::type_complexity)]
pub struct NativeAsyncJob {
    f: Box<dyn for<'a> FnOnce(&'a RefCell<&mut Context>) -> BoxedFuture<'a>>,
    realm: Option<Realm>,
}

With this change, any API that integrates with Future can additionally capture the &RefCell<&mut Context> to run engine-related operations after awaiting on a Future.

Revamped JobQueue​

After introducing the new job type, changes had to be made on JobQueue to better support new types of jobs. Thus, JobQueue was revamped and renamed to be the new JobExecutor:

/// An executor of `ECMAscript` [Jobs].
///
/// This is the main API that allows creating custom event loops.
///
/// [Jobs]: https://tc39.es/ecma262/#sec-jobs
pub trait JobExecutor: Any {
    /// Enqueues a `Job` on the executor.
    ///
    /// This method combines all the host-defined job enqueueing operations into a single method.
    /// See the [spec] for more information on the requirements that each operation must follow.
    ///
    /// [spec]: https://tc39.es/ecma262/#sec-jobs
    fn enqueue_job(self: Rc<Self>, job: Job, context: &mut Context);

    /// Runs all jobs in the executor.
    fn run_jobs(self: Rc<Self>, context: &mut Context) -> JsResult<()>;

    /// Asynchronously runs all jobs in the executor.
    ///
    /// By default forwards to [`JobExecutor::run_jobs`]. Implementors using async should override this
    /// with a proper algorithm to run jobs asynchronously.
    async fn run_jobs_async(self: Rc<Self>, context: &RefCell<&mut Context>) -> JsResult<()>
    where
        Self: Sized,
    {
        self.run_jobs(&mut context.borrow_mut())
    }
}

As you can probably tell, we made a lot of changes on JobExecutor:

• All methods now take Rc<Self> as their receiver, making it consistent with how the Context itself stores the JobExecutor.
• enqueue_promise_job and enqueue_future_job now are unified in a single enqueue_job, where Job is an enum containing the type of job that needs to be scheduled. This makes it much simpler to extend the engine with newer job types in the future, such as the newly introduced TimeoutJob and GenericJob types.
• run_jobs_async was converted to a proper async function, and excluded from JobExecutor's VTable. Additionally, this method now takes a &RefCell<&mut Context> as its context, which is the missing piece that enables sharing the Context between multiple Futures at the same time. This, however, means that we cannot provide a convenient wrapper such as Context::run_jobs for it anymore, which is one of the reasons why we decided to exclude that method from JobExecutor's VTable.

These changes not only made JobExecutor much simpler, but it also expanded the places where we could use its async capabilities to handle "special" features of ECMAScript that are more suited to an async way of doing things. ModuleLoader is one of those places.

Asyncified ModuleLoader​

Looking at the previous definition of ModuleLoader:

pub trait ModuleLoader {
    // Required method
    fn load_imported_module(
        &self,
        referrer: Referrer,
        specifier: JsString,
        finish_load: Box<dyn FnOnce(JsResult<Module>, &mut Context)>,
        context: &mut Context,
    );

    // Provided methods
    fn register_module(&self, _specifier: JsString, _module: Module) { ... }
    fn get_module(&self, _specifier: JsString) -> Option<Module> { ... }
    fn init_import_meta(
        &self,
        _import_meta: &JsObject,
        _module: &Module,
        _context: &mut Context,
    ) { ... }
}

... the weird finish_load on load_imported_module immediately pops up as an anomaly. In this case, finish_load is Boa's equivalent to HostLoadImportedModule ( referrer, moduleRequest, hostDefined, payload ), which is an abstract operation that is primarily used to define how an application will load and resolve a "module request"; think of it as a function that takes the "module-name" from import * as name from "module-name", then does "things" to load the module that corresponds to "module_name".

The peculiarity about this abstract operation is that it doesn't return anything! Instead, it just has a special requirement:

The host environment must perform FinishLoadingImportedModule(referrer, moduleRequest, payload, result), where result is either a normal completion containing the loaded Module Record or a throw completion, either synchronously or asynchronously.

Why expose the hook this way? Well, there is a clue in the previous requirement:

... either synchronously or asynchronously.

Aha! Directly returning from the hook makes it very hard to enable use cases where an application wants to load multiple modules asynchronously. Thus, the specification instead exposes a hook to pass the name of the module that needs to be loaded, and delegates the task of running the "post-load" phase to the host, which enables fetching modules synchronously or asynchronously, depending on the specific requirements of each application.

One downside of this definition, however, is that any data that is required by the engine to properly process the returned module would need to be transparently passed to the FinishLoadingImportedModule abstract operation, which is why the hook also has an additional requirement:

The operation must treat payload as an opaque value to be passed through to FinishLoadingImportedModule.

payload is precisely that data, and it may change depending on how the module is imported in the code; import "module" and import("module") are two examples of this.

We could expose this as an opaque *const () pointer argument and call it a day, but we're using Rust, dang it! and we like statically guaranteed safety! So, instead, we exposed FinishLoadingImportedModule as finish_load, which is a "closure" that captures payload on its stack, and can be called anywhere (like inside a Future) on the application with a proper Module and Context to further continue processing the module loaded by the ModuleLoader.

...
finish_load: Box<dyn FnOnce(JsResult<Module>, &mut Context)>,
...

Unfortunately, this API has downsides:

• It's possible to forget to call finish_load, which is safer than a dangling *const() pointer, but still prone to bugs.
• It is also really painful to work with, because you cannot capture the Context to further process the module after loading it. ... Sounds familiar? The async code snippet we showed before has this exact problem! And that snippet is directly taken from one of our ModuleLoader implementation examples.

Fast forward a couple of years and we're now changing big parts of JobExecutor: adding new job types, tinkering with JobExecutor, changing API signatures, etc. Then, while looking at the definition of ModuleLoader, we thought...

Huh, can't we make load_imported_module async now?

And that's exactly what we did. Behold, the new ModuleLoader!

pub trait ModuleLoader: Any {
    async fn load_imported_module(
        self: Rc<Self>,
        referrer: Referrer,
        specifier: JsString,
        context: &RefCell<&mut Context>,
    ) -> JsResult<Module>;

    fn init_import_meta(
        self: Rc<Self>,
        _import_meta: &JsObject,
        _module: &Module,
        _context: &mut Context,
    ) {
    }
}

Then, the code snippet we mentioned before nicely simplifies to:

async fn load_imported_module(
    self: Rc<Self>,
    _referrer: boa_engine::module::Referrer,
    specifier: JsString,
    context: &RefCell<&mut Context>,
) -> JsResult<Module> {
    let url = specifier.to_std_string_escaped();

    let response = async {
        let request = Request::get(&url)
            .redirect_policy(RedirectPolicy::Limit(5))
            .body(())?;
        let response = request.send_async().await?.text().await?;
        Ok(response)
    }
    .await
    .map_err(|err: isahc::Error| JsNativeError::typ().with_message(err.to_string()))?;

    let source = Source::from_bytes(&response);

    Module::parse(source, None, &mut context.borrow_mut())
}

What about synchronous applications?

The advantage of having JobExecutor be the main entry point for any Rust Futures that are enqueued by the engine is that an application can decide how to handle all Futures received by the implementation of JobExecutor. Thus, an application that doesn't want to deal with async Rust executors can implement a completely synchronous ModuleLoader and poll on all futures received by JobExecutor using something like futures_lite::poll_once.

Why not just block on each Future one by one instead?

Well, there is one new built-in that was introduced on this release which heavily depends on "properly" running Futures, and by "properly" we mean "not blocking the whole thread waiting on a future to finish". More on that in a bit.

Built-ins updates​

Atomics.waitAsync​

This release adds support for the Atomics.waitAsync method introduced in ECMAScript's 2024 specification. This method allows doing thread synchronization just like Atomics.wait, but with the big difference that it will return a Promise that will resolve when the thread gets notified with the Atomics.notify method, instead of blocking until that happens.

// Given an `Int32Array` shared between two threads:

const sab = new SharedArrayBuffer(1024);
const int32 = new Int32Array(sab);

// Thread 1 runs the following:
// { async: true, value: Promise {<pending>} }
const result = Atomics.waitAsync(int32, 0, 0, 1000);
result.value.then(() => console.log("waited!"));

// And thread 2 runs the following after Thread 1:
Atomics.notify(int32, 0);

// Then, in thread 1 we will (eventually) see "waited!" printed.

Note that this built-in requires having a "proper" implementation of a JobExecutor; again, "proper" in the sense of "not blocking the whole thread waiting on a future to finish", which can be accomplished with FutureGroup and futures_lite::poll_once if an async executor is not required (see SimpleJobExecutor's implementation). This is because it heavily relies on TimeoutJob to timeout if a notification doesn't arrive, and in NativeAsyncJob to communicate with the notifier threads using an async channel. This is the reason why we don't recommend just blocking on each received Future; that could cause TimeoutJobs to run much later than required, or even make it so that they don't run at all!

Set methods​

This release adds support for the new set methods added in ECMAScript's 2025 specification.

The new methods are:

• Set.prototype.intersection(other)
• Set.prototype.union(other)
• Set.prototype.difference(other)
• Set.prototype.symmetricDifference(other)
• Set.prototype.isSubsetOf(other)
• Set.prototype.isSupersetOf(other)
• Set.prototype.isDisjointFrom(other)

Thanks to @Hemenguelbindi for their work on this feature.

Float16 support for TypedArrays, Dataview and Math built-ins​

This release adds support for f16 types for the TypedArray, Dataview, and Math built-ins.

const x = new Float16Array([37, 42.123456]);
console.log(x[1]); // 42.125

Error.isError​

This release adds support for Error.isError, which will be introduced in ECMAScript's 2026 specification.

console.log(Error.isError(new Error())); // true
console.log(Error.isError({ __proto__: Error.prototype })); // false

Math.sumPrecise​

This release adds support for Math.sumPrecise, which will be introduced in ECMAScript's 2026 specification.

We've opted for using the new xsum summation algorithm for the underlying implementation.

let sum = Math.sumPrecise([1e20, 0.1, -1e20]);
console.log(sum); // 0.1

Array.fromAsync​

This release adds support for Array.fromAsync, which will be introduced in ECMAScript's 2026 specification.

Array.fromAsync allows to conveniently create a array from an async iterable by awaiting all of the items consecutively.

// Array.fromAsync is roughly equivalent to:
async function toArray(asyncIterator) {
  const arr = [];
  for await (const i of asyncIterator) arr.push(i);
  return arr;
}

async function* asyncIterable() {
  for (let i = 0; i < 5; i++) {
    await new Promise((resolve) => setTimeout(resolve, 10 * i));
    yield i;
  }
}

Array.fromAsync(asyncIterable()).then((array) => console.log(array));
// [0, 1, 2, 3, 4]
toArray(asyncIterable()).then((array) => console.log(array));
// [0, 1, 2, 3, 4]

Boa Runtime​

Work on Boa's runtime crate has continued with additional APIs added.

Additional APIs​

Additional APIs added the the Runtime crate include:

• fetch
• setTimeout
• setInterval
• clearInterval
• queueMicrotask

Conformance testing​

We've added some support for conformance testing runtime features against the Web Platform Tests (WPT).

Performance​

NaN Boxing​

With this release, Boa's JsValue will use nan-boxing by default. The NaN boxing of JsValue increased memory and runtime performance over the older enum.

As a note, the current implementation is not compatible with all platforms. While we hope to address this in the future, the legacy enum JsValue will be available via the jsvalue-enum feature flag.

Unfamiliar with NaN Boxing? We won't go over it in depth here, but we recommend this article to learn more.

Register VM​

Boa's virtual machine (VM) moved from a stack based VM to a register based VM in PR #3798.

New Contributors​

• @zzzdong made their first contribution in https://github.com/boa-dev/boa/pull/4058
• @albertleigh made their first contribution in https://github.com/boa-dev/boa/pull/4097
• @heygsc made their first contribution in https://github.com/boa-dev/boa/pull/4124
• @jamesthurley made their first contribution in https://github.com/boa-dev/boa/pull/4155
• @lockels made their first contribution in https://github.com/boa-dev/boa/pull/4189
• @changhc made their first contribution in https://github.com/boa-dev/boa/pull/4176
• @created-by-varun made their first contribution in https://github.com/boa-dev/boa/pull/4198
• @tomoverlund made their first contribution in https://github.com/boa-dev/boa/pull/4254
• @Hemenguelbindi made their first contribution in https://github.com/boa-dev/boa/pull/4145
• @Timkarx made their first contribution in https://github.com/boa-dev/boa/pull/4276
• @Rafferty97 made their first contribution in https://github.com/boa-dev/boa/pull/4303
• @cijiugechu made their first contribution in https://github.com/boa-dev/boa/pull/4307
• @countradooku made their first contribution in https://github.com/boa-dev/boa/pull/4214
• @xubaiwang made their first contribution in https://github.com/boa-dev/boa/pull/4381
• @hamflx made their first contribution in https://github.com/boa-dev/boa/pull/4405
• @BDeuDev made their first contribution in https://github.com/boa-dev/boa/pull/4419
• @jasonmilad made their first contribution in https://github.com/boa-dev/boa/pull/4430
• @hpp2334 made their first contribution in https://github.com/boa-dev/boa/pull/4453
• @Gumichocopengin8 made their first contribution in https://github.com/boa-dev/boa/pull/4462
• @mdrokz made their first contribution in https://github.com/boa-dev/boa/pull/4466
• @rrogerc made their first contribution in https://github.com/boa-dev/boa/pull/4459

Looking Forward​

Garbage collector rewrite​

This has been long overdue. Boa's garbage collector is a forked and modified version of rust-gc, and we have long been pushing our forked gc to its limits.

We have seen some evidence from previous pull requests that simply swapping allocators from Rust's global allocator can increase Boa's performance, and work on this will hopefully resume soon. If you're interested in garbage collectors and/or would be interested in helping out, feel free to join our GC room on Matrix.

Runtime functionality​

The boa_runtime crate was initially meant to contain functionality that was not meant to exist in the core ECMAScript implementation, for instance the console implementation. Noticeably, we have since added more runtime features to the crate with even more features expected in the next release.

Our current plan is if there is enough interest and the crate becomes too large, we will split boa_runtime into it's own repository. If you are interested in implementing any runtime features or contributing to a runtime, feel free to reach out.

Continuing performance improvements​

As mentioned on previous release posts, we will continue to further work on improving Boa's overall performance.

Intl and ECMA402 conformance​

We currently have some general support for the ECMA402 and ECMAScript's Intl object. We will continue to some general work on ECMA402 conformance to allow Boa to be fully usable for internationalization use cases.

How can you support Boa?​

Boa is an independent JavaScript engine implementing the ECMAScript specification, and we rely on the support of the community to keep it going. If you want to support us, you can do so by donating to our open collective. Proceeeds here go towards this very website, the domain name, and remunerating members of the team who have worked on the features released.

If financial contribution is not your strength, you can contribute by asking to be assigned to one of our open issues, and asking for mentoring if you don't know your way around the engine. Our contribution guide should help you here. If you are more used to working with JavaScript or frontend web development, we also welcome help to improve our web presence, either in our website, or in our testing representation page or benchmarks page. You can also contribute to our Criterion benchmark comparison GitHub action.

We are also looking to improve the documentation of the engine, both for developers of the engine itself and for users of the engine. Feel free to contact us in Matrix.

Thank You​

Once again, big thanks to all the contributors of this release!!!

After 2 years of development, we're pleased to announce the release of temporal_rs. A calendar and time zone aware Rust date/time library based on ECMAScript's Temporal API.

temporal_rs is a highly conformant implementation of the Temporal API in Rust that can be used in native Rust code or embedded into ECMAScript engines / interpreters to support their implementations, which we first announced in our Temporal blog post, if you're interested in learning more about small implementation details.

Currently, temporal_rs v0.1 is being used by Boa, Kiesel, V8, and Yavashark for their Temporal implementations (more on that later) and is estimated to land unflagged in Chromium v144.

Why v0.1? Why not v1.0?​

Right now the Temporal proposal is at Stage 3 (4 being the final stage) in the standards process. Although unlikely, we want to remain on a minor version to catch any changes which come in (mostly bug fixes) before the proposal reaches stage 4 and thus complete. We expect that to happen in Q1 2026.

Fear not! temporal_rs passes over 4000 specification tests, is stable and ready to use.

To celebrate the release of temporal_rs, we'll cover a short background of the Temporal implementation in Boa and why temporal_rs was split into its own crate, we'll go over the library's general design, and then we'll walk through a couple brief examples of using temporal_rs before finally talking about the FFI and engine adoption.

Some background and history​

"Temporal is the single biggest addition to ECMAScript since ES6"

Jason Williams, TC39 Delegate

In this section, we'll reflect on the overall implementation, some general difficulties we had along with lessons learned.

The temporal implementation in Boa began over two years ago and culminated in an absolutely massive PR, #3277.

The PR itself stubbed out a lot of the methods, implemented some Duration and Instant functionality, and started the support for custom calendars. There were, however, 2 major takeaways from this PR:

• Temporal is a massive specification update, it's the single biggest addition to ECMAScript since ES6.
• There is a lot of room to potentially optimize Temporal if we do not deal with JsValue directly.

After a couple weeks, the question came up amongst maintainers of not just Boa, but also other engines: "could we separate the datetime logic and implementation off into a completely separate library?" Sure.

The first commit of then boa_temporal occurred in PR #3461, which moved the majority of the existing functionality into a separate crate with the primary concern at the time of being able to support custom calendars, which was then ported into its own repository later a couple months later.

These early versions of temporal_rs were vastly different than the 0.1 release version, and it can be easily seen with a short glance through the first PR. temporal_rs needed to support custom calendars and time zones. In order to do this, each calendar was generic on a CalendarProtocol trait.

So to create a new date in the early versions of temporal_rs, you would have something like the following code:

use temporal_rs::{Date, Calendar, options::ArithmeticOverflow};
let date = Date::new_with_overflow(
    2025,
    9,
    21,
    Calendar::<()>::from_str("iso8601").unwrap(),
    ArithmeticOverflow::Reject
).unwrap();

Luckily, custom calendars and time zones were removed from the specification in the first half of 2024, so temporal_rs was able to remove that support, which greatly benefited the entire API. For instance, here's the same code in the 0.1 version of temporal_rs:

use temporal_rs::PlainDate;
let date = PlainDate::try_new_iso(2025, 9, 21).unwrap();

That was 2024 though, we're in September of 2025, so what's happened since the crate was initially split off from Boa over a year and a half ago? Well, plenty!

• In early 2024 the internal algorithm for Duration was overhauled in the specification, so temporal_rs had a complete rewrite of Duration.
• Duration moved from using f64 internally to FiniteF64, and then to non-floating-point integers.
• We moved from a large TemporalFields type to "Partial" objects, which better represent JavaScript property bags.
• A good portion of missing method implementations were added as well.
• Internal utility methods were moved to the Neri-Schneider algorithms.

In general, the implementation was moving along at a pretty decent pace, and would continue to do so well into roughly April of 2025 (mostly helped along by a group of students from the University of Bergen who began helping with the implementation in January 2025), but there were two final hurdles: time zone data and ZonedDateTime.

Time zones and time zone data are a topic for a completely different blog post in the future. But suffice to say, it took a little bit of time, and ZonedDateTime was developed alongside the time zone data.

This work began in November 2024, by stubbing out the general support of time zone data sourcing and ZonedDateTime. Then, after almost 10 months of general work, the last major updates to time zone data sourcing were merged at the beginning of September in PR #537 and #538. As a result, we were finally able to stabilize temporal_rs's API for a 0.1 release.

That's it for our brief background on temporal_rs.

Date and time is hard, and there is a lot that goes into it, especially when it comes to calendars and time zones. But that's what makes it interesting!

Temporal API overview​

The Temporal API focuses on a group of 8 date and time types, each of which corresponds to a different aspect of date and time with varying support for calendars and time zones, which are, unsurprisingly, represented in temporal_rs by the Calendar and TimeZone types.

There is also Now, which provides access to the current host system time. This can then be used to map the current Instant to any of the above Temporal types.

The types in the same categories will share similar APIs that are related to that category. For instance, all types that support a calendar date will have a with_calendar method as well as calendar date accessors. The exception being PlainYearMonth and PlainMonthDay which are missing their day and year, respectively ... for all intents and purposes.

For a full view of the API, we recommend checking our documentation.

temporal_rs design overview​

temporal_rs in general implements large portions of the specification directly in the codebase. However, it does still have some dependencies, which can be broken down into 4 main groups.

1. Time zone data, for sourcing time zone data
2. Calendrical calculations, for handling non-ISO calendar calculations
3. RFC9557 parsing, for parsing of RFC9557's internet extended date/time format (IXDTF)
4. Utilities

Notably, the dependencies that are highlighted in purple come from ICU4X. ICU4X is a phenomenal Rust project that takes a new approach to Unicode's ICU in order to make a new, more modular version of ICU.

While ICU4X provides the majority of the internationalization (i18n), Unicode, and formatting focused functionality, temporal_rs builds on top of ICU4X to provide an ECMAScript compliant date/time API for both native Rust and ECMAScript implementers.

Time zone data​

While we plan to go into time zones in a completely separate post, one of temporal_rs's primary design decisions was to offer a way to customize the source of time zone data, while also having an optional default source for convenience. The time zone data sourcing functionality is provided by timezone_provider, a sister crate of temporal_rs that provides a project agnostic crate alongside default trait implementations for sourcing time zone data.

We currently expose three types of provider implementations:

• CompiledTzdbProvider (current default), a provider that parses time zone data at runtime using data compiled into the binary.
• FsTzdbProvider, a provider that parses time zone data at runtime using the file system time zone database (if it exists for that OS).
• ZoneInfo64TzdbProvider, a provider using ICU's zoneinfo64 resource bundle.

We hope to have a zero copy compiled timezone provider available in the near future.

Using temporal_rs​

Let's dive into using temporal_rs from Rust.

Setup​

First, add temporal_rs as a dependency to your project using cargo:

cargo add temporal_rs

Or include the below in your project's Cargo.toml.

temporal_rs = "0.1.0"

By default, temporal_rs will use a compiled time zone data provider that compiles the time zone data into the binary. If you prefer to use the file system time zone database or a zoneinfo64 resource bundle, you can disable the compiled time zone data by setting default-features = false; you can import your preferred provider from the timezone_provider crate, then provide it to any API that requires a time zone provider.

For instance, to use the FsTzdbProvider, your Cargo.toml would look like the following.

timezone_provider = { version = "0.0.17", features = ["tzif"] }
temporal_rs = { version = "0.1.0", default-features = false, features = ["sys"]}

The sys feature for temporal_rs enables the default implementation for Now, and the tzif feature for timezone_provider enables the FsTzdbProvider.

Please note: timezone_provider is still considered unstable for the near future.

Some examples​

The below examples will be using temporal_rs with the default features.

Retrieve today's date​

use temporal_rs::Temporal;

// We can easily retrieve today's date using `Temporal::now()`
let today = Temporal::now().plain_date_iso(None).unwrap()

Date operations available​

Temporal provides a nice API for working with date and date/time via PlainDate and PlainDateTime.

use std::convert::TryFrom;
use temporal_rs::{Calendar, Temporal, options::DifferenceSettings, partial::PartialDuration};

// We can get today's date
let today = Temporal::now().plain_date_iso(None).unwrap();

// We can also add a Duration.
let partial = PartialDuration::empty().with_days(1);
let tomorrow = today.add(&partial.try_into().unwrap(), None).unwrap();

// We can get the difference between two dates
let diff = today
    .since(&tomorrow, DifferenceSettings::default())
    .unwrap();

// We can change the calendar
let tomorrow_japanese = tomorrow.with_calendar(Calendar::JAPANESE);

// We can retrieve the calendar's RFC9557 string
println!("{tomorrow_japanese}"); // 2025-09-24[u-ca=japanese]

Working with dates and time zones​

You can also easily work with dates and time zones with the ZonedDateTime type.

use temporal_rs::options::{DifferenceSettings, Disambiguation, OffsetDisambiguation, Unit};
use temporal_rs::{Calendar, Temporal, TimeZone, ZonedDateTime};

// We can parse a ZonedDateTime from utf8 bytes.
let zdt = ZonedDateTime::from_utf8(
    b"2025-03-01T11:16:10Z[America/Chicago][u-ca=iso8601]",
    Disambiguation::Compatible,
    OffsetDisambiguation::Reject,
)
.unwrap();

// We can get the current ZonedDateTime
let today = Temporal::now().zoned_date_time_iso(None).unwrap();

// And we can easily get the difference between two `ZonedDateTime`s
let mut options = DifferenceSettings::default();
options.largest_unit = Some(Unit::Year);
let diff = today.since(&zdt, options).unwrap();
println!("{diff}"); // P6M23D

// We can change the calendar for the `ZonedDateTime`
let today_coptic = today.with_calendar(Calendar::COPTIC);
println!("{today_coptic}"); // 2025-09-24T10:36:56.914365368-05:00[America/Chicago][u-ca=coptic]

// We can also easily convert it into just the date.
let today_plain_date_coptic = today_coptic.to_plain_date();
println!("{today_coptic}"); // 2025-09-24[u-ca=coptic]

While we can extend these examples further, a more fun exercise for the reader would be to take a look at the Temporal cookbook, as it displays the utility of the Temporal API using JavaScript and all of these examples are now usable from Rust as well.

FFI and engine adoption​

As previously stated, temporal_rs is used in Boa, Kiesel, and V8. There's just one thing, the latter of the two are ECMAScript implementations written in Zig and C++, respectively, not Rust. This was made possible through temporal_rs's FFI crate temporal_capi, which provides C and C++ bindings to temporal_rs.

The bindings are autogenerated via Diplomat, which is a project for generating FFI definitions for Rust libraries. In general, it's a really cool project and we would definitely recommend checking it out if you're looking to generate FFI bindings for other languages for your Rust library.

"Diplomat made the FFI code extremely easy: I basically wrote the entire temporal_capi FFI layer over the course of a couple PRs, each of which probably took me ~15 minutes each of relatively mindless "tab through docs, add API" work. Diplomat is really good at this type of thing."

Manishearth Rust Reddit Q&A:

There is some added benefits to offering C and C++ bindings beyond the classic: oh, let's (re)write it in Rust.

First, this approach allows other languages and engines to benefit from Rust's type system and memory safety guarantees without having to rewrite everything in Rust. It's a more modular and incremental approach that provides some level of flexibility.

Secondly, with how large the API is, temporal_rs streamlines the ability to adopt the Temporal API for any current and future implementations, since any future updates can be done primarily in one place and then released downstream. temporal_rs plus the engine specific integration code, while not a small amount of code, is a relatively trivial amount of work in comparison to a from scratch implementation.

Third, with adoption from multiple engines, temporal_rs benefits via external test coverage beyond the native Rust unit tests. For instance, looking at the engines that offer conformance numbers (Boa, Kiesel, and V8), each implementation is currently north of 95% conformance with V8 reaching the highest at around 99% conformance. There is still a small disparity in conformance, but this can be explained by the absence of some related features, i.e. Boa still hasn't completed its Intl.DateTimeFormat implementation yet, so it fails all ECMA402 toLocaleString tests. Nonetheless, we can still be fairly confident in the general correctness of temporal_rs, and any potential bugs will ideally be found and addressed fairly quickly.

In general, temporal_rs is a pretty good reference case for setting up a Rust library over FFI, being used in both a C++ and Zig codebase.

Conclusion​

The 0.1 release of temporal_rs is out. We expect the general API to remain fairly stable moving forward, with any non-patch bumps being for added features. Feel free to try it out, and provide feedback / file any issues you come across. Although, we will make changes and semantic versioning bumps based on feedback or the Temporal specification.

Our current plan is to have any remaining issues addressed and the API fully stable, in preparation for the "stabilization" of Temporal and its subsequent introduction to the ECMAScript specification. Once Temporal is "stabilized", we will move forward with a 1.0 release.

temporal_rs started as an interesting experiment in creating an engine agnostic library of the Temporal API that could also be usable as a date/time library in native Rust code, but seeing the wide adoption we've been getting from other engines, we can say that this project has been a great success! And with any luck, we hope this library will find its place in the Rust ecosystem as well.

Special thanks​

We'd like to thank all the contributors to temporal_rs for helping it get to v0.1.

Thanks to the University of Bergen students who helped drive some of the major conformance push earlier this year.

Also, a huge thanks to all the Temporal champions for all their work on the specification, as well as the ICU4X project for their incredible ongoing work on calendars and all things i18n related.

Discussion​

• Hackernews: https://news.ycombinator.com/item?id=45361826
• Reddit: https://www.reddit.com/r/rust/comments/1npffdx/temporal_rs_is_here_the_datetime_library_powering/

How can you support Boa?​

Boa is an independent JavaScript engine implementing the ECMAScript specification, and we rely on the support of the community to keep it going. If you want to support us, you can do so by donating to our open collective. Proceeeds here go towards this very website, the domain name, and remunerating members of the team who have worked on the features released.

If financial contribution is not your strength, you can contribute by asking to be assigned to one of our open issues, and asking for mentoring if you don't know your way around the engine. Our contribution guide should help you here. If you are more used to working with JavaScript or frontend web development, we also welcome help to improve our web presence, either in our website, or in our testing representation page or benchmarks page. You can also contribute to our Criterion benchmark comparison GitHub action.

We are also looking to improve the documentation of the engine, both for developers of the engine itself and for users of the engine. Feel free to contact us in Matrix.

More specifically, this will be the first in a series of posts primarily about implementing the new date/time built-in: Temporal. We'll be going over general lessons and interesting design choices we've stumbled upon, as well as the crates supporting that implementation.

Why should you care? Well, we are not only implementing Temporal for JavaScript, but for Rust as well ... more on that in a bit.

First, an aside!

What even is Temporal?​

Temporal is a modern API for handling date/time in a calendar and time zone aware manner that includes nine objects with over 200+ methods.

In JavaScript, Temporal is a global built-in namespace object that includes each of these nine built-ins:

• Temporal.Now
• Temporal.PlainDate
• Temporal.PlainTime
• Temporal.PlainDateTime
• Temporal.ZonedDateTime
• Temporal.Duration
• Temporal.Instant
• Temporal.PlainYearMonth
• Temporal.PlainMonthDay

But to be honest, this post isn't meant to give an overview of Temporal and its general API. If Temporal is news to you and you are interested in learning more, feel free to check out the phenomenal MDN documentation.

Back on track​

Being Boa a JavaScript engine / interpreter, developing a correct implementation of the ECMAScript specification is our raison d'être. This, in consequence, makes implementing Temporal one of our most important goals, since it represents roughly 7-8% of the current conformance test suite (~4000 of the ~50,000 tests).

When the PR of the first prototype of Temporal for Boa was submitted, a few things became evident:

1. Date/Time is a complicated beast (duh)
2. There's room for optimization and improvement
3. This would be handy to have in Rust

So after the prototype was merged, we pulled it out of Boa's internal builtins and externalized it into its own crate, temporal_rs, which landed behind an experimental flag in Boa v0.18.

After over a year and a half of development, Boa now sits at a conformance of about 90% for Temporal (and growing), with the entire implementation being backed by temporal_rs.

For its part, temporal_rs is shaping up to be a proper Rust date/time library that can be used to implement Temporal in a JavaScript engine, and even support general date/time use cases.

Let's take a look at Temporal: it's JavaScript API, it's Rust API in temporal_rs, and how temporal_rs supports implementing the specification.

Important core differences​

First, we need to talk about JavaScript values (JsValue) for a bit. This is functionally the core any value type of JavaScript. A JsValue could be a number represented as a 64 bit floating point, a string, a boolean, or an object. Not only is it an any, but JsValue is ultimately engine defined, with various implementations existing across engines.

While this is handy for a dynamically typed language like JavaScript, it is not ideal for implementing deep language specifications where an object or string may need to be cloned. Furthermore, it's just not great for an API in a typed language like Rust.

To work around this, we routinely use FromStr and a FiniteF64 custom primitive to handle casting and constraining, respectively, which glues dynamic types like JsValue with a typed API.

For instance, in Boa, we heavily lean into using the below patterns:

// (Note: this is abridged for readability)

// FiniteF64 usage
let number: f64 = js_value.to_number(context)?;
let finite_f64: FiniteF64 = FiniteF64::try_from(number)?;
let year: i32 = finite_f64.as_integer_with_truncation::<i32>();

// FromStr usage with `get_option`
let options_obj: &JsObject = get_options_object(&js_value)?;
let overflow: Option<ArithmeticOverflow> = get_option::<ArithmeticOverflow>(
    &options_obj,
    js_string!("overflow"),
    context
)?;

This is the core glue between Boa and the temporal_rs API that we will be going over below.

Implementing constructors​

There are a variety of ways to construct a core component like PlainDate, and that stems from the core constructor for each of the core components: new_with_overflow.

impl PlainDate {
    pub fn new_with_overflow(year: i32, month: u8, day: u8, calendar: Calendar, overflow: ArithmeticOverflow) -> Result<Self> {
        // Create PlainDate
    }
}

This function supports the baseline construction of Temporal builtins, which takes the usual year, month, day, alongside a calendar and also an overflow option to constrain or reject based on whether the provided values are in an expected range.

However, we can better express this in Rust with common try_ prefix notation.

impl PlainDate {
    pub fn new(year: i32, month: u8, day: u8, calendar: Calendar) -> Result<Self> {
        Self::new_with_overflow(year, month, day, calendar, ArithmeticOverflow::Constrain)
    }

    pub fn try_new(year: i32, month: u8, day: u8, calendar: Calendar) -> Result<Self> {
        Self::new_with_overflow(year, month, day, calendar, ArithmeticOverflow::Reject)
    }
}

These three constructors, new_with_overflow, try_new, and new, are fairly flexible and provide full coverage of the Temporal specification.

For instance, take the below snippet:

const plainDate = new Temporal.PlainDate(2025, 6, 9);

This code can easily be translated to Rust as:

use temporal_rs::PlainDate;
let plain_date = PlainDate::try_new(2025, 6, 9, Calendar::default())?;

Furthermore, we actually learn some interesting things about the JavaScript API from looking at the temporal_rs API:

1. The Temporal.PlainDate constructor can throw.
2. When the calendar is omitted, the default calendar is used (this will default to the iso8601 calendar)

Of course, if you somewhat prefer the brevity of the JavaScript API and don't want to list the default Calendar, temporal_rs provides the additional constructors new_iso and try_new_iso.

use temporal_rs::PlainDate;
let plain_date = PlainDate::try_new_iso(2025, 6, 9)?;

Interestingly enough, the _iso constructors are mostly expressing a part of the JavaScript API, just in native Rust. This is because in JavaScript the _iso constructors are assumed to exist due to resolving an undefined calendar to the default ISO calendar.

Let's discuss Now​

Colonel Sandurz: Now. You're looking at now, sir. Everything that happens now, is happening now.
Dark Helmet: What happened to then?
Colonel Sandurz: We passed then.
Dark Helmet: When?
Colonel Sandurz: Just now. We're at now now.
Dark Helmet: Go back to then.
Colonel Sandurz: When?
Dark Helmet: Now.
Colonel Sandurz: Now?
Dark Helmet: Now.
Colonel Sandurz: I can't.
Dark Helmet: Why?
Colonel Sandurz: We missed it.
Dark Helmet: When?
Colonel Sandurz: Just now.
Dark Helmet: When will then be now?
-- Spaceballs, 1987

Temporal.Now is an incredibly strange type, yet nevertheless important. It is the object from which the current instant can be measured and mapped into any of the Temporal components.

In JavaScript, this type has no [[Construct]] or [[Call]] internal method, which is a fancy way to say that Now has no constructor and cannot be called directly.

Instead, Now is used primarily as a namespace for its methods.

And this was reflected in early adaptions of Now, which looked more or less like the below:

struct Now;

impl Now {
    pub fn instant() -> Instant;

    pub fn zoned_date_time_iso() -> ZonedDateTime;
}

Interestingly enough, the above implementation is incorrect, or at the very least not ideal.

Hidden in the specification steps for Now are some very tricky steps invoking the abstract operations: SystemTimeZoneIdentifier and SystemUtcEpochNanoseconds. That's great, let's just use the usual suspects SystemTime and iana-time-zone, merge it, and call it a day on the implementation, right?

Except the core purpose of temporal_rs is that it can be used in any engine implementation, and accessing a system clock and system time zone is sometimes difficult for engines that support targets like embedded systems. Thus, this functionality must be delegated to the engine or runtime ... somehow.

How did we end up implementing Now if we have no access to the system clock or time zone? Well ... a builder pattern of course!

#[derive(Default)]
pub struct NowBuilder {
    clock: Option<EpochNanoseconds>,
    zone: Option<TimeZone>,
}

impl NowBuilder {
    pub fn with_system_nanoseconds(mut self, nanoseconds: EpochNanoseconds) -> Self {
        self.clock = Some(nanoseconds);
        self
    }

    pub fn with_system_zone(mut self, zone: TimeZone) -> Self {
        self.zone = Some(zone);
        self
    }

    pub fn build(self) -> Now {
        Now {
            clock: self.clock,
            zone: self.zone.unwrap_or_default(),
        }
    }
}

pub struct Now {
    clock: Option<EpochNanoseconds>,
    zone: TimeZone,
}

Once we've constructed Now, then we are off to the races!

To show the NowBuilder in action, in Boa, the implementation for Temporal.Now.plainDateISO() with the builder API is shown below:

impl Now {
    // The `Temporal.Now.plainDateISO` used when building `Temporal.Now`.
    fn plain_date_iso(_: &JsValue, args: &[JsValue], context: &mut Context) -> JsResult<JsValue> {
        let time_zone = args
            .get_or_undefined(0)
            .map(|v| to_temporal_timezone_identifier(v, context))
            .transpose()?;

        let now = build_now(context)?;

        let pd = now.plain_date_iso_with_provider(time_zone, context.tz_provider())?;
        create_temporal_date(pd, None, context).map(Into::into)
    }
}

// A helper for building Now
fn build_now(context: &mut Context) -> JsResult<NowInner> {
    Ok(NowBuilder::default()
        .with_system_zone(system_time_zone()?)
        .with_system_nanoseconds(system_nanoseconds(context)?)
        .build())
}

The nice part about this approach is that it also allows a std implementation that can be feature gated for general users that are not concerned with no_std.

    // Available with the `sys` feature flag
    use temporal_rs::Temporal;
    let now = Temporal::now().instant();

Partial API​

There's an interesting method on each of the Temporal built-ins that I'd assume most people who have used Rust would be familiar with: from. But this isn't Rust's friendly From trait. No, this from is a behemoth method that takes a JsValue and automagically gives you back the built-in that you'd like or throws. That's right! Give it a string, give it a property bag, give it an instance of another Temporal built-in; from will figure it out for you!

Simple, right?

Folks, we're pleased to announce that temporal_rs won't be supporting that! ... or at least not in that shape.

Again, the goal of temporal_rs is to implement the specification to the highest possible degree of conformance, so when we couldn't provide a direct translation of the specification's API, we made sure to provide APIs that (hopefully) made the glue code between engines and temporal_rs much shorter.

To exemplify this, let's take a look at some valid uses of from in JavaScript to construct a PlainDate.

// Create a `PlainDateTime`
const pdt = new Temporal.PlainDateTime(2025, 1, 1);
// We can use the `PlainDateTime` (`ZonedDateTime` / `PlainDate` are also options).
const pd_from_pdt = Temporal.PlainDate.from(pdt);
// We can use a string.
const pd_from_string = Temporal.PlainDate.from("2025-01-01");
// We can use a property bag.
const pd_from_property_bag = Temporal.PlainDate.from({
  year: 2025,
  month: 1,
  day: 1,
});

If we look closely to the common usage of the method, it seems like all that needs to be implemented by temporal_rs is:

• From<PlainDateTime>: Easy.
• From<ZonedDateTime>: Simple.
• FromStr: Tricky but can be done.
• From<JsObject>: ... ... oh. Did I mention JsObject, like JsValue, is engine defined as well?

Fortunately, this is where temporal_rs's Partial API comes in.

It turns out that, while property bags in JavaScript can have various fields set, there is still a general shape for the fields that can be provided and validated in Temporal.

To support this in temporal_rs, a "partial" component exists for each of the components that can then be provided to that component's from_partial method.

With this, we have fully implemented support for the from method in temporal_rs:

use core::str::FromStr;
use temporal_rs::{PlainDate, PlainDateTime, partial::PartialDate};
let pdt = PlainDateTime::try_new_iso(2025, 1, 1)?;
// We can use the `PlainDateTime` (`ZonedDateTime` / `PlainDate` are also options).
let pd_from_pdt = PlainDate::from(pdt);
// We can use a `str`.
let pd_from_string = PlainDate::from_str("2025-01-01")?;
// We can use a `PartialDate`.
let pd_from_partial = PlainDate::from_partial(
    PartialDate::new()
        .with_year(Some(2025))
        .with_month(Some(1))
        .with_day(Some(1))
);

NOTE: there may be updates to PartialDate in the future (see boa-dev/temporal #349 for more information).

Elephant in the room: time zones​

So far we have not discussed time zones, and -- surprise! -- we aren't going to ... yet. It's not because they aren't super cool and interesting and everyone totally 100% loves them. No, time zones aren't in this post because they are still being polished and deserve an entire post of their own.

So stay tuned for our next post on implementing Temporal! The one where we'll hopefully go over everyone's favorite subject, time zones; and answer the question that some of you may have if you happen to take a glance at temporal_rs's docs or try out our no_std support: what in the world is a provider API?

Conclusion​

In conclusion, we're implementing Temporal in Rust to support engine implementors as well as to have the API available in native Rust in general.

If you're interested in trying Temporal using Boa, you can use it in Boa's CLI or enable it in boa_engine with the experimental flag.

Outside of Boa's implementation, temporal_rs has implemented or supports the implementation for a large portion of the Temporal's API in native Rust. Furthermore, an overwhelming amount of the API can be considered stable¹ and is currently available in Boa with only a few outstanding issues that may be considered breaking changes.

If you're interested in trying out temporal_rs, feel free to add it to your dependencies with the command:

cargo add temporal_rs

or by adding the below in the [dependencies] section of your Cargo.toml:

temporal_rs = "0.0.9"

A FFI version of temporal is also available for C and C++ via temporal_capi.

Before we start, let's get some disclaimers out of the way:

• This post is written about optimizations in the Boa ECMAScript engine. Other engines might do things different, so take everything with a grain of salt.
• This post omits some implementation details to focus on the most relevant parts.
• This post contains data structures written in pseudo Rust that are only for visualization, so you should not need to understand Rust.

Scopes and Variables​

To start us off, let's refresh our understanding of variables and scopes in ECMAScript. Variables are identifiers in our code that we can use to store and retrieve values. Scopes describe the areas of code in which variables are visible. You might associate scopes with curly braces.

Let's look at an example to visualize scopes:

const a = 1;
console.log(a); // 1

{
  // <- start of a block scope
  const a = 2;
  console.log(a); // 2
} // <- end of a block scope

We declare and initialize two variables with the identifier a. Even though both have the same identifier, they are different variables. The variable with the value 1 is declared in the global scope. The variable with the value 2 is declared in a block scope.

In this example, we always find the variable that we want to access in the current scope. But what when the variable we access in not declared in the current scope?

Let's modify our example to see what happens in that case:

const a = 1;

{
  const b = 2;
  console.log(a); // 1
  console.log(b); // 2
}

In this example, our two variables have different identifiers. Notice that when we access the variable a from the block scope, its value is resolved as expected. This is because scopes are nested. When we cannot find a variable in the current scope, we look for the same identifier in the outer scope. In this case, we have to look for a in the block scope and then in the global scope.

Let's look at a more complex example:

const a = 1;
console.log(a); // 1

function f() {
  // <- start of a function scope
  var a = 2;
  console.log(a); // 2

  {
    // <- start of a block scope
    let a = 3;
    console.log(a); // 3
  } // <- end of a block scope

  console.log(a); // 2
} // <- end of a function scope

f();

console.log(a); // 1

You can see that variables are tied to their scopes. All three variables a never change their values. The variables just exist in their respective scopes, and as soon as the scope has ended, they are no longer accessible. Instead, the previous outer scope returns to being the current scope and its variables are accessible.

You can see that in addition to blocks, functions also have scopes. There are some more details to function scopes and how let, const and var differ. For our proposes we will only work with let and const and skip those details for now.

Storing Variables​

The Naive Approach​

When developing an ECMAScript engine we have to think about how we store and access scopes and variables. Take a look at the requirements we have for that storage data structure:

• A variable maps an identifier to a value.
• A scope can have multiple variables with unique identifiers.
• A scope may have an outer scope.

The variables in a scope fit a typical key-value store, like a hashmap. The hashmap stores our variable identifiers as keys and the variable values as corresponding values:

struct Scope {
    variables: HashMap<Identifier, Value>,
}

This is a nice and easy data structure for our variables. And because most languages come with a hashmap built-in, we do not have implement much!

Let's add the ability to nest our scopes. Since all scopes are the same, we can just build a self-referential data structure:

struct Scope {
    variables: HashMap<Identifier, Value>,
    outer: Scope,
}

This solution works and is easy to reason about. The data structures map very well on our mental model of variables and scopes. This was the approach we used in Boa before we switched to a different implementation over two years ago (https://github.com/boa-dev/boa/pull/1829).

Fixed Locations​

You may already have spotted some performance issues with this data structure. Consider that accessing variables is one of the things happening all the time in most languages. Therefore, the runtime performance of variable access operations should be highly optimized. With this current data structure we have to perform at least one hashmap lookup per variable access. Most hashmap implementations will incur significant cost compared to accessing a fixed location in memory. This problem gets worse when the variable we want to access is not in our current scope. In the worst case, we have to traverse all the scopes until we arrived at the global scope.

How would you optimize this data structure for runtime performance? Can you find a way to locate each variable without accessing multiple hashmaps?

When we read code, we can use our mental model of variables and scopes to see how each variable is unique. We just have to apply that knowledge to our data structure. In practice, we can assign each variable two indices that make it unique and give it a defined location in memory:

• scope index: The index of the scope that the variable is declared in.
• variable index: The index of the variable in its scope.

Let's visualize this in an example:

const a = 1; // scope index: 0; variable index: 0
{
  const b = 2; // scope index: 1; variable index: 0
  const c = 3; // scope index: 1; variable index: 1
}

You can see how each variable has a set of two unique indices. The scope index increases with each nested scope. The variable index increases with each variable in one specific scope.

Let's explore how unique these indices have to be:

{
  const a = 1; // scope index: 1; variable index: 0
}
{
  const b = 2; // scope index: 1; variable index: 0
}

As you can see, both a and b have a scope index of 1 and a variable index of 0. This works for us, because variables do not have to be unique for the whole program. They just have to be unique in their current nested tree of scopes.

With all of this in mind, we can build a data structure that allows us to access variables just based on these two indices. It might look something like this:

struct Scopes {
    scopes: Array<Scope>,
}

struct Scope {
    variables: Array<Value>,
}

Instead of having a self-referential data structure, we now have a two-dimensional array.

While this is our runtime data structure, we still have to calculate the variable indices before running the code. For that we can use our previous approach with some slight modifications. Instead of storing the value of the variable, we just store its index. Additionally, we store an index in every scope to easily access our scope indices:

struct Scope {
    index: u32,
    variables: HashMap<Identifier, Variable>,
    outer: Scope,
}

struct Variable {
    index: u32,
}

While this data structure still works based on self-referential hashmaps, we only need it before running code. Instead of doing a lookup on every variable access at runtime, we just have to do it once.

Local Variables​

Our previous optimization changed the data structure for our variables and scopes. But we can come up with further optimizations if we look at the usage of variables in the code.

Let's take a look at this example:

function addOne(a) {
  const one = 1;
  return one + a;
}
addOne(2);

Currently, we store a and one in our scopes and access them when performing the addition. But why do we need the special data structure for variables and scopes at all? What if we could just store the variables directly where we need them?

A typical ECMAScript engine uses a virtual machine (VM) to execute your code. VMs use dedicated memory for values they operate on; a stack or registers. For the purpose of this post, we use registers, but the stack would work in the same way. Let's try to use registers to store variables. While compiling the ECMAScript code into operations for our VM, we assign each variable to a register. Then we modify our variable operations to use registers instead of scopes to access variables.

When we test our example from above, it works fine with these changes. Let's write down what exactly happens:

1. The function addOne is called. Registers for a and one are allocated.
2. The first function argument with the value 2 is written to the register for a.
3. The value 1 is written to the register for one.
4. The values from the registers a and one are read and added together.

Nested Functions​

When testing some more complex code we will quickly see that something does not work as expected.

Let's look at this example:

function addOneBuilder() {
  const one = 1;
  return (a) => {
    return one + a;
  };
}
const addOne = addOneBuilder();
addOne(2);

While running the code, depending on the implementation, we might get a panic, a wrong result or even an unsafe memory access. Let's try to understand what is going on here:

1. The function addOneBuilder is called. A register for one is allocated.
2. The value 1 is written to the register for one.
3. The function addOneBuilder returns the arrow function bound to addOne.
4. The function addOne is called. A register for a is allocated.
5. The first function argument with the value 2 is written to the register for a.
6. The VM tries to access the register for one. This is the point where our things go wrong.

Registers in a VM are local to a specific function. In our example this means that the variable one can only be accessed successfully in the function addOneBuilder. As soon as we try to access it from addOne, the register we assigned during compilation does not hold the correct value anymore. This is why this optimization can be referred to as local variables or function local variables.

We now know that variables that are used in nested functions cannot be used as local variables. But this should not stop us from using the optimization. We just have to find all the variables that cannot be optimized. Then we can use our existing scopes to store those, while optimizing all the other ones.

Scope Analysis​

Finding Variables accessed by other Functions​

To determine which variables can be stored in registers, we analyze them prior to code execution. We can reuse our previously established scope structure based on hashmaps. It just needs some additional information to make our analysis work. Each scope needs to be flagged to indicate if it is a function scope. This is important, because we have to track if a variable is ever accessed from a nested function. Additionally, each variable needs a flag to indicate if it can be a local variable.

Our adjusted scope structure looks like this:

struct Scope {
    index: u32,
    function: bool, // <- This field is new
    variables: HashMap<Identifier, Variable>,
    outer: Scope,
}

struct Variable {
    index: u32,
    local: bool, // <- This field is new
}

We set the function flag on each scope when it is created. The local flag on the variables is true by default. After creating all the scopes and filling them with their variables, we traverse the ECMAScript code. Every time we find a variable access, we check which variable in which scope is being accessed. If a variable is not in the current scope, we go to the outer scope. If any of the scopes we see until we find the variable is a function scope, we set the local flag to false.

Let's visualize the scope analysis by writing out the scopes for this example:

function addOneBuilder() {
  const one = 1;
  return (a) => {
    return one + a;
  };
}

These are our scopes before the scope analysis. Notice that we start from the scope of the arrow function, since we work our way out from the most nested scope:

Scope {
    function: true
    variables: [
        "a": {
            index: 0,
            local: true,
        }
    ]
    outer: Scope {
        function: true
        variables: [
            "one": {
                index: 0,
                local: true,
            }
        ]
    }
}

Now we apply our scope analysis. During the access to variable one in the arrow function, we pass the function scope of the arrow function. This indicates that this variable cannot be local:

Scope {
    function: true
    variables: [
        "a": {
            index: 0,
            local: true, // <- Still `true`
        }
    ]
    outer: Scope {
        function: true
        variables: [
            "one": {
                index: 0,
                local: false, // <- Set to `false`
            }
        ]
    }
}

After the scope analysis is finished, we compile our code for the VM. When we encounter a variable that can be local, we assign it a register. When we encounter a variable that cannot be local, we use the old VM operations for our scopes storage.

Other Exceptions​

There are some more situations that prevent us from using local variables. We have to account for every case where a variable might be accessed from outside its function. Without going into detail on each of these cases, we can find all of them via scope analysis.

Here is a quick overview:

• Non strict functions create a mapped arguments object. The mapped arguments object can be used to read and write function arguments without using their identifiers. The reads and writes are kept in sync with the values of the argument variables. This means that we cannot determine if the argument variables are accessed from outside the function.

  An example of such a situation would be this code:

  function f(a) {
    console.log(a); // initial
    (() => {
      arguments[0] = "modified";
    })();
    console.log(a); // modified
  }
  f("initial");
  

  The solution here is to mark every argument variable that might be accessed through a mapped arguments object as non-local.

• Direct calls to eval allow potential variable access. Direct calls to eval have access to the current variables. Since any code could be executed in eval we cannot do proper scope analysis on any variables in such cases.

  An example of direct eval usage would be this:

  function f() {
    const a = 1;
    eval("function nested() {console.log(a)}; nested();");
  }
  f();
  

  Our solution is this case is to mark every variable in the scopes where the direct eval call is as non-local.

• Usage of the with statement. Variable identifiers inside a with statement are not static. A variable identifier could be the access to a variable, but it also could be the access to an object property.

  See this example:

  function f() {
    const a1 = 1;
    for (let i = 0; i < 2; i++) {
      with ({ [`a${i}`]: 2 }) {
        console.log(a1);
      }
    }
  }
  f();
  

  In the first loop execution a1 is the variable. In the second loop execution a1 is the object property. As a result of this behavior, every variable accessed inside a with statement cannot be local.

Conclusion​

After implementing local variables in Boa, we saw significant performance improvements in our benchmarks. Our overall benchmark scope improved by more than 25%. In one specific benchmark the scope increased by over 70%. Notice that Boa is not the most performant engine yet. There are probably other optimizations relating to variable storage that we have not implemented yet.

Hopefully, you might have already picked up some practical tips to potentially improve to performance of your ECMAScript code. Here are our observations that might help performance:

• Avoid accessing variables across functions. This might just help the ECMAScript engine to optimize your code better.
• Always use strict mode.
• Never use direct eval!
• Never use the with statement.

Boa v0.20 is now available! After 5 months of development we are very happy to present you the latest release of the Boa JavaScript engine. Boa makes it easy to embed a JS engine in your projects, and you can even use it from WebAssembly. See the about page for more info.

In this release, our conformance has grown from 87.3% to 89.92% in the official ECMAScript Test Suite (Test262). This small jump is expected as we're shifting most of our focus to performance as the majority of the engine is now conformant. We will continue to implement more of the specification as we go along but we expect these changes to be much smaller than we've been used to.

You can check the full list of changes here, and the full information on conformance here.

Feature Highlights​

Temporal​

Boa is continuing to progress on Temporal. The Temporal API is a new set of built-in objects and functions that is designed to be a more modern replacement for the Date object, providing a more feature-rich and flexible API for working with dates and times.

It is currently a stage 3 proposal and we are working alongside the TC39 champions to put together a solid Rust implementation. Since Temporal is such an extensive specification, we have done most of the work outside of Boa so that it can be used in other projects. This work can be found in the temporal_rs repository.

We hope to release a full blog post on Temporal in the future, but for now you can see the previous release notes for some examples on how to use it. You can also look at the Temporal Cook Book for some examples too!

If you're interested in learning more or want to contribute to the native Rust implementation of Temporal, feel free to check out temporal_rs's issues!

Boa's conformance on the Temporal test suite has grown from 24.61% to 40.67% in this release.

Nightlies​

Boa now supports nightly releases, this was originally created to aid with the testing of conformance for test262.fyi. This is a great way to see the latest changes and help offer feedback on new features or just to see the latest changes in the engine. You can find the nightly releases here

Atomics.pause​

Boa has added support for the stage 3 proposal Atomics.pause. This function is used to pause the execution of a thread for a specified amount of time. This function is useful for implementing spinlocks and other synchronization primitives in JavaScript.

Getters and Setters in the js_class! macro​

You can now add getters and setters to the js_class! macro. This allows you to define getters and setters on your JavaScript classes in Rust. This is a feature that has been requested by many users of Boa, and thanks to @hansl we now have it!

#[derive(Clone, Default, Trace, Finalize, JsData)]
pub struct Game {
    score: u32,
}

js_class! {
    class Game {
        property score {
            get(this: JsClass<Game>) -> u32 {
                this.borrow().score
            }

            set(this: JsClass<Game>, new_value: u32) {
                this.borrow_mut().score = new_value;
            }
        }

        constructor() {
            Ok(Game::default())
        }
    }
}