feat: add sections for JobExecutor, ModuleLoader and async changes

Author: jedel1043

blog/boa-release-21/img/backtrace.gif

@@ -14,7 +14,7 @@ Boa makes it easy to embed a JS engine in your projects, and you can
 even use it from WebAssembly. See the [about](/about) page for more
 info.
 
-In this release, our conformance has grown from 89.92% to 93.94% in the
+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,
@@ -34,47 +34,159 @@ information on conformance [here][conformance].
 
 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%.
+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](../2025-09-24-temporal-release). Give the post a read if you are
+interested in `temporal_rs` and its development history.
 
-The implementation is backed by the `temporal_rs` date/time Rust
-library, which we went over briefly in our June
-[blog post](../2025-06-15-temporal-impl-1.md) with hopefully another post
-in the not too distant future. So far, `temporal_rs` has also been used in
-both V8 and Keisel to implement Temporal.
+### Span nodes and error backtraces
 
-Temporal can be used from `boa_cli` or enabled in `boa_engine` with the
-`experimental` or `temporal` feature.
+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.
 
-You can also try out Temporal directly in Rust using `temporal_rs`:
+Why is this important? Well, as a direct result from this, Boa now supports error backtraces
+when an exception is thrown!
 
-```
-cargo add temporal_rs
+![backtrace-example](./img/backtrace.gif)
+
+As an additional plus, you can enable the `native-backtrace` feature to include
+"native" functions on a backtrace.
+
+![native-backtrace-example](./img/native-backtrace.gif)
+
+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.
+
+### 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`:
+
+```rust
+pub type FutureJob = Pin<Box<dyn Future<Output = NativeJob> + 'static>>;
 ```
 
-#### Special thanks
+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 `Future`s would have to be split into multiple parts:
+
+```rust
+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)
+}
+```
 
-Special thanks to all the student's from University of Bergen who helped contribute to
-`temporal_rs` and Boa, as well as Shane Carr ([@sffc](https://github.com/@sffc)) and
-Manish Goregaokar ([@manishearth](https://github.com/@manishearth)) for their contributions
-and help with `temporal_rs`.
+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, which meant calling `RefCell::borrow_mut`
+   would cause panics in the reentrant parts of the code; we would need to
+   redesign some parts of 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 to `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`.
+
+```Rust
+/// 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>,
+}
+```
 
-### Span nodes and error backtraces
+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`](https://docs.rs/boa_engine/0.20.0/boa_engine/job/trait.JobQueue.html)
+to better support new job types. Thus, `JobQueue` was revamped and renamed to be the
+new `JobExecutor`:
+
+```rust
+/// 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())
+    }
+}
+```
 
-We also add support for span nodes in our parser and AST. Span nodes mark the start and
-end index in the source code for a specific token.
+As you can probably tell, we made a lot of changes on the `JobExecutor`:
 
-As a result, this release of Boa supports error backtraces when an exception is thrown
-as seen below.
+TODO
 
-![backtrace-example](./img/backtrace.gif)
+### Revamped `ModuleLoader`
 
-This feature will greatly help with debugging errors when using Boa.
+TODO
 
-### Specification updates
+### Built-ins updates
 
 #### Set methods
 
-This release adds support for the new set methods added in ES2025.
+This release adds support for the new set methods added in ECMAScript's 2025
+specification.
 
 The new methods are:
 
@@ -101,15 +213,18 @@ console.log(x[1]); // 42.125
 
 #### Error.isError
 
-This release adds support for `Error.isError`, which is accepted for ES2026.
+This release adds support for `Error.isError`, which will be introduced in
+ECMAScript's 2026 specification.
 
 ```javascript
-let check = Error.isError(new Error()); // returns true
+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 is accepted for ES2026.
+This release adds support for `Math.sumPrecise`, which will be introduced in
+ECMAScript's 2026 specification.
 
 We've opted for using the new [`xsum`](https://crates.io/crates/xsum) summation algorithm
 for the underlying implementation.
@@ -119,6 +234,13 @@ let sum = Math.sumPrecise([1e20, 0.1, -1e20]);
 console.log(sum); // 0.1
 ```
 
+#### Atomics.waitAsync
+
+TODO
+
+
+#### Array.fromAsync
+
 ## Boa Runtime
 
 Work on Boa's runtime crate has continued with additional APIs added.
@@ -146,7 +268,7 @@ With this release, Boa's `JsValue` will use nan-boxing by default. The NaN boxin
 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`
+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

blog/boa-release-21/img/native-backtrace.gif

@@ -27,4 +27,3 @@ Hide
 Type "rm yikes.js"
 
 Enter
-

blog/boa-release-21/index.md

@@ -0,0 +1,35 @@
+Output native-backtrace.gif
+
+# Setup env
+Hide
+
+Set TypingSpeed 50ms
+Set Theme "GruvboxDark"
+
+# boa_cli needs to be installed for the tape to run.
+Require boa
+
+Show
+
+Type@100ms `cat <<EOF > native.js`
+Enter
+Type@100ms `Array.prototype.every.call([[10]], arr => arr.forEach(`
+Enter
+Type@100ms `  e => { throw value; }`
+Enter
+Type@100ms `));`
+Enter
+Type@100ms `EOF`
+Enter
+
+Type@100ms "boa native.js"
+
+Enter
+
+Sleep 10s
+
+Hide
+
+Type "rm native.js"
+
+Enter