From a8ba70f1a0eaff269c41d16ff1a5bd95945e02bf Mon Sep 17 00:00:00 2001 From: Aapo Alasuutari Date: Sun, 15 Mar 2026 22:39:42 +0200 Subject: [PATCH] fix: make nova_vm lib docs releasable --- README.md | 1 - nova_vm/src/ecmascript/execution/agent.rs | 1 - nova_vm/src/lib.rs | 81 ++++++++++++++++++++++- 3 files changed, 80 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 817014d3c..4bdff1904 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,6 @@ let realm = agent.create_default_realm(); let _ = agent.run_in_realm(&realm, |_agent, _gc| { // do work here }); -agent.gc(); ``` ## [Architecture] diff --git a/nova_vm/src/ecmascript/execution/agent.rs b/nova_vm/src/ecmascript/execution/agent.rs index 3cd0dad3e..1289c6be8 100644 --- a/nova_vm/src/ecmascript/execution/agent.rs +++ b/nova_vm/src/ecmascript/execution/agent.rs @@ -681,7 +681,6 @@ pub trait HostHooks: core::fmt::Debug { /// let _ = agent.run_in_realm(&realm, |_agent, _gc| { /// // do work here /// }); -/// agent.gc(); /// ``` pub struct GcAgent { agent: Agent, diff --git a/nova_vm/src/lib.rs b/nova_vm/src/lib.rs index 6ffa564b2..e30884fab 100644 --- a/nova_vm/src/lib.rs +++ b/nova_vm/src/lib.rs @@ -4,7 +4,86 @@ #![cfg_attr(feature = "proposal-float16array", feature(f16))] #![warn(missing_docs)] -#![doc = include_str!("../../README.md")] + +//! # Nova JavaScript engine +//! +//! Nova is a [JavaScript] engine focused on being lightweight, modular, and +//! easy to embed. The engine's architecture is built close to the ECMAScript +//! specification in structure with the implementation relying on idiomatic Rust +//! and data-oriented design over traditional JavaScript engine building +//! strategies. Interpreter performance is also a goal, but not yet a high +//! priority. +//! +//! The engine is exposed as a library with an API for implementation in Rust +//! projects which themselves must serve as a runtime for JavaScript code. The +//! execution model is greatly inspired by [Kiesel] and [LibJS]. +//! +//! ## Basic usage +//! +//! The engine has very little bells or whistles and is very easy to set up for +//! one-off script runs or simple call-and-return instances. The engine uses the +//! [WTF-8] encoding internally for [`String`] storage, making interfacing with +//! JavaScript look and act similar to normal Rust code. +//! +//! ```rust +//! use nova_vm::{ecmascript::{DefaultHostHooks, GcAgent}, engine::GcScope}; +//! let mut agent = GcAgent::new(Default::default(), &DefaultHostHooks); +//! let realm = agent.create_default_realm(); +//! let _ = agent.run_in_realm(&realm, |_agent, _gc| { +//! // do work here +//! }); +//! ``` +//! +//! ## Architecture +//! +//! The engine's public API relies on idiomatic Rust over traditional JavaScript +//! engine building wisdom. This is most apparent in the [`Value`] type and its +//! subvariants such as [`Object`]: instead of using NaN-boxing, NuN-boxing, or +//! other traditional and known efficient strategies for building a dynamically +//! typed language, Nova uses normal Rust enums carrying either on-stack data or +//! a 32-bit handle to heap-allocated data. The only pointer that gets +//! consistently passed through call stacks is the [`Agent`] reference, and +//! handles are merely ways to access heap-allocated JavaScript data held inside +//! the `Agent`. +//! +//! Internally, the architecture and structure of the engine follows the +//! ECMAScript specification but uses data-oriented design for the actual +//! implementation. Data on the heap is allocated in homogenous (containing data +//! of only one type) arenas with hot data split apart from cold data, and +//! optional data stored behind keyed indirections using the arena's associated +//! 32-bit handle as the key, thus using no memory to store the default null +//! case. The arenas are additionally compacted during garbage collection, +//! trading some extra collection time for better runtime cache locality for hot +//! data. +//! +//! ## Shortcomings and unexpected edge cases +//! +//! Nova JavaScript engine is not perfect and has many shortcomings. +//! +//! 1. The engine performance is acceptable, but it is not fast by any means. +//! 1. The [`Array`] implementation does not support sparse storage internally. +//! Calling `new Array(10 ** 9)` will request an allocation for 1 billion +//! JavaScript [`Value`]s. +//! 1. The [`RegExp`] implementation does not support lookaheads, lookbehinds, +//! or backreferences. It is always in UTF-8 / Unicode sets mode, does not +//! support RegExp patterns containing unpaired surrogates, and its groups +//! are slightly different from what the ECMAScript specification defines. In +//! short: it is not compliant. +//! 1. [`Promise`] subclassing is currently not supported. +//! 1. The engine does not support [WebAssembly] execution. +//! +//! [`Agent`]: crate::ecmascript::Agent +//! [`Array`]: crate::ecmascript::Array +//! [`RegExp`]: crate::ecmascript::RegExp +//! [`Promise`]: crate::ecmascript::Promise +//! [`Object`]: crate::ecmascript::Object +//! [`String`]: crate::ecmascript::String +//! [`Value`]: crate::ecmascript::Value +//! [WebAssembly]: https://webassembly.org +//! [WTF-8]: https://wtf-8.codeberg.page/ +//! [JavaScript]: https://tc39.es/ecma262 +//! [Kiesel]: https://codeberg.org/kiesel-js/kiesel +//! [LibJS]: https://github.com/LadybirdBrowser/ladybird/tree/master/Libraries/LibJS pub mod ecmascript; pub mod engine;