rusteerio 0.1.0 → 1.0.0

package/dist/slim.mjs

@@ -3,7 +3,7 @@ import {
   dom,
   load,
   merge
-} from "./chunk-DKULX6VO.mjs";
+} from "./chunk-DMRD3FGC.mjs";
 import "./chunk-OHPGEY3E.mjs";
 
 // src/slim.ts

package/native/src/arena.rs

@@ -51,6 +51,15 @@ impl DomNode {
     pub(crate) fn is_element(&self) -> bool {
         matches!(self.kind.as_str(), "tag" | "script" | "style")
     }
+    pub(crate) fn content_bytes(&self) -> usize {
+        let attributes: usize = self
+            .attribs
+            .values()
+            .filter_map(Value::as_str)
+            .map(str::len)
+            .sum();
+        self.data.as_ref().map_or(0, String::len) + attributes
+    }
 }
 
 #[derive(Clone, Debug)]
@@ -353,20 +362,31 @@ impl DomArena {
                     let name = node.name.as_deref().unwrap_or("");
                     output.push('<');
                     output.push_str(name);
+                    // parse5 qualifies foreign attributes; XML and htmlparser2
+                    // rendering write the stored attribute names unchanged.
+                    let qualifiers = (!xml
+                        && options.get("_useHtmlParser2") != Some(&Value::Bool(true)))
+                    .then(|| {
+                        (
+                            node.extras.get("attribsNamespace"),
+                            node.extras.get("attribsPrefix"),
+                        )
+                    });
                     for (name, value) in &node.attribs {
                         output.push(' ');
-                        if !xml {
-                            if let Some(prefix) = node
-                                .extras
-                                .get("attribsPrefix")
-                                .and_then(|value| value.get(name))
-                                .and_then(Value::as_str)
-                            {
-                                output.push_str(prefix);
-                                output.push(':');
-                            }
+                        match qualifiers {
+                            Some((namespaces, prefixes)) => super::push_attribute_name(
+                                &mut output,
+                                name,
+                                namespaces
+                                    .and_then(|map| map.get(name))
+                                    .and_then(Value::as_str),
+                                prefixes
+                                    .and_then(|map| map.get(name))
+                                    .and_then(Value::as_str),
+                            ),
+                            None => output.push_str(name),
                         }
-                        output.push_str(name);
                         let value = value
                             .as_str()
                             .map(str::to_owned)
@@ -625,16 +645,25 @@ impl DomArena {
                         .filter(|id| self.node(*id).is_some_and(DomNode::is_element)),
                 ),
                 "parents" | "ancestors" => {
+                    // Like Cheerio, stop at the first document node. A template's
+                    // contents live in a fragment, so they never report the
+                    // template or its ancestors as their own.
                     let mut parent = node.parent;
                     let mut seen = HashSet::new();
                     while let Some(id) = parent {
                         if !seen.insert(id) {
                             break;
                         }
-                        if self.node(id).is_some_and(DomNode::is_element) {
+                        let Some(ancestor) = self.node(id) else {
+                            break;
+                        };
+                        if ancestor.kind == "root" {
+                            break;
+                        }
+                        if ancestor.is_element() {
                             result.push(id);
                         }
-                        parent = self.node(id).and_then(|node| node.parent);
+                        parent = ancestor.parent;
                     }
                 }
                 "next" | "prev" | "nextAll" | "prevAll" => {

package/native/src/lib.rs

@@ -35,8 +35,40 @@ pub use runtime::{configure_worker_pool, worker_pool_info, WorkerPoolInfo};
 pub use stream::NativeStream;
 
 const HTML_NS: &str = "http://www.w3.org/1999/xhtml";
+const XML_NS: &str = "http://www.w3.org/XML/1998/namespace";
+const XMLNS_NS: &str = "http://www.w3.org/2000/xmlns/";
+const XLINK_NS: &str = "http://www.w3.org/1999/xlink";
+
+/// Writes an attribute's serialized name. Like parse5, the namespace rather
+/// than the stored prefix selects the qualifier: HTML5 gives foreign `xmlns`
+/// attributes an empty prefix, which must not become `:xmlns`. Other namespaces
+/// keep a non-empty prefix; an empty or missing one writes the bare name.
+pub(crate) fn push_attribute_name(
+    output: &mut String,
+    local: &str,
+    namespace: Option<&str>,
+    prefix: Option<&str>,
+) {
+    match namespace.filter(|namespace| !namespace.is_empty()) {
+        None => {}
+        Some(XML_NS) => output.push_str("xml:"),
+        Some(XMLNS_NS) => {
+            if local != "xmlns" {
+                output.push_str("xmlns:");
+            }
+        }
+        Some(XLINK_NS) => output.push_str("xlink:"),
+        Some(_) => {
+            if let Some(prefix) = prefix.filter(|prefix| !prefix.is_empty()) {
+                output.push_str(prefix);
+                output.push(':');
+            }
+        }
+    }
+    output.push_str(local);
+}
 
-#[napi]
+#[napi(custom_finalize)]
 pub struct NativeDocument {
     html: RefCell<Option<Html>>,
     // Stable public IDs are preorder positions, rather than parser allocation
@@ -51,10 +83,43 @@ pub struct NativeDocument {
     managed: Cell<bool>,
     diagnostics: RefCell<Vec<Value>>,
     locations: RefCell<HashMap<u32, Value>>,
+    // V8 cannot see native allocations. Reporting them lets its GC collect
+    // unreachable documents under native memory pressure.
+    content_bytes: Cell<usize>,
+    reported_heap_bytes: Cell<i64>,
+}
+
+impl ObjectFinalize for NativeDocument {
+    fn finalize(self, mut env: Env) -> Result<()> {
+        let reported = self.reported_heap_bytes.get();
+        if reported != 0 {
+            // Accounting is advisory; a failure must not throw from a finalizer.
+            let _ = env.adjust_external_memory(-reported);
+        }
+        Ok(())
+    }
 }
 
+fn html_node_content_bytes(node: &Node) -> usize {
+    match node {
+        Node::Text(text) => text.len(),
+        Node::Comment(comment) => comment.len(),
+        Node::Element(element) => element.attrs.iter().map(|(_, value)| value.len()).sum(),
+        _ => 0,
+    }
+}
+
+/// Approximate retained bytes per node in each representation, excluding the
+/// text and attribute content counted separately. V8 treats the total only as
+/// allocation pressure, so these err on the high side.
+const IMMUTABLE_NODE_BYTES: usize = 256;
+const ARENA_NODE_BYTES: usize = 512;
+/// Smaller changes to an already reported size are skipped to keep operations cheap.
+const HEAP_REPORT_STEP: i64 = 64 * 1024;
+
 impl NativeDocument {
     pub(crate) fn from_arena(arena: arena::DomArena, options: Value) -> Self {
+        let content_bytes = arena.nodes.iter().map(arena::DomNode::content_bytes).sum();
         Self {
             html: RefCell::new(None),
             ids: RefCell::new(Vec::new()),
@@ -67,6 +132,8 @@ impl NativeDocument {
             managed: Cell::new(false),
             diagnostics: RefCell::new(Vec::new()),
             locations: RefCell::new(HashMap::new()),
+            content_bytes: Cell::new(content_bytes),
+            reported_heap_bytes: Cell::new(0),
         }
     }
     pub(crate) fn set_diagnostic_records(&self, records: Vec<Value>) {
@@ -82,6 +149,39 @@ impl NativeDocument {
         Self::parse_options(source, is_document, serde_json::json!({}), None)
     }
 
+    fn estimated_heap_bytes(&self) -> i64 {
+        let live_arena_nodes = self.arena.borrow().as_ref().map_or(0, |arena| {
+            arena.nodes.len().saturating_sub(arena.free.len())
+        });
+        let immutable_nodes = self.ids.borrow().len();
+        let retained_source = self.source.borrow().as_ref().map_or(0, String::capacity);
+        let content = if live_arena_nodes + immutable_nodes == 0 {
+            0
+        } else {
+            self.content_bytes.get()
+        };
+        let bytes = content
+            + retained_source
+            + immutable_nodes * IMMUTABLE_NODE_BYTES
+            + live_arena_nodes * ARENA_NODE_BYTES;
+        i64::try_from(bytes).unwrap_or(i64::MAX)
+    }
+
+    fn report_heap_bytes(&self, mut env: Env) {
+        let reported = self.reported_heap_bytes.get();
+        let estimated = self.estimated_heap_bytes();
+        let change = estimated - reported;
+        let is_small_update = reported != 0 && estimated != 0 && change.abs() < HEAP_REPORT_STEP;
+        if change != 0 && !is_small_update && env.adjust_external_memory(change).is_ok() {
+            self.reported_heap_bytes.set(estimated);
+        }
+    }
+
+    fn reported<T>(&self, env: Env, value: T) -> T {
+        self.report_heap_bytes(env);
+        value
+    }
+
     pub(crate) fn parse_options(
         source: &str,
         is_document: bool,
@@ -262,6 +362,7 @@ impl NativeDocument {
                     && value != &&serde_json::json!("")
             })
             .and(source);
+        let content_bytes = html.tree.values().map(html_node_content_bytes).sum();
         Self {
             html: RefCell::new(Some(html)),
             ids: RefCell::new(ids),
@@ -274,6 +375,8 @@ impl NativeDocument {
             managed: Cell::new(false),
             diagnostics: RefCell::new(diagnostics),
             locations: RefCell::new(locations),
+            content_bytes: Cell::new(content_bytes),
+            reported_heap_bytes: Cell::new(0),
         }
     }
 
@@ -583,7 +686,16 @@ impl NativeDocument {
             }
         }
     }
-    #[napi]
+    #[napi(js_name = "collectGarbage")]
+    pub fn collect_garbage_and_report(&self, env: Env) -> MemoryStats {
+        let stats = self.collect_garbage();
+        self.report_heap_bytes(env);
+        MemoryStats {
+            external_bytes: self.reported_heap_bytes.get(),
+            ..stats
+        }
+    }
+
     pub fn collect_garbage(&self) -> MemoryStats {
         self.needs_collect.set(false);
         if self.arena.borrow().is_none() && self.managed.get() && self.retained.borrow().is_empty()
@@ -599,6 +711,7 @@ impl NativeDocument {
                 retained: 0,
                 reclaimed,
                 immutable_nodes: 0,
+                external_bytes: self.reported_heap_bytes.get(),
             };
         }
         if let Some(arena) = self.arena.borrow_mut().as_mut() {
@@ -610,6 +723,7 @@ impl NativeDocument {
                 retained: stats.retained,
                 reclaimed: stats.reclaimed,
                 immutable_nodes: 0,
+                external_bytes: self.reported_heap_bytes.get(),
             }
         } else {
             let count = self.ids.borrow().len() as u32;
@@ -619,6 +733,7 @@ impl NativeDocument {
                 retained: self.retained.borrow().len() as u32,
                 reclaimed: 0,
                 immutable_nodes: count,
+                external_bytes: self.reported_heap_bytes.get(),
             }
         }
     }
@@ -629,19 +744,30 @@ impl NativeDocument {
     }
 
     #[napi]
-    pub fn root_id(&self) -> u32 {
+    pub fn root_id(&self, env: Env) -> u32 {
+        self.report_heap_bytes(env);
         0
     }
 
-    #[napi]
+    #[napi(js_name = "select")]
+    pub fn select_and_report(
+        &self,
+        env: Env,
+        selector: String,
+        contexts: Option<Vec<u32>>,
+    ) -> Result<Vec<u32>> {
+        self.reported(env, self.select(selector, contexts))
+    }
+
     pub fn select(&self, selector: String, contexts: Option<Vec<u32>>) -> Result<Vec<u32>> {
         self.select_ids(&selector, contexts.as_deref())
     }
 
     #[napi]
-    pub fn matches(&self, selector: String, ids: Vec<u32>) -> Result<Vec<u32>> {
+    pub fn matches(&self, env: Env, selector: String, ids: Vec<u32>) -> Result<Vec<u32>> {
         self.ensure_arena()?;
-        selector::filter(self.arena.borrow().as_ref().unwrap(), &selector, &ids)
+        let matched = selector::filter(self.arena.borrow().as_ref().unwrap(), &selector, &ids);
+        self.reported(env, matched)
     }
 
     #[napi]
@@ -671,7 +797,11 @@ impl NativeDocument {
         self.text_ids(&ids)
     }
 
-    #[napi]
+    #[napi(js_name = "innerHtml")]
+    pub fn inner_html_and_report(&self, env: Env, id: u32) -> String {
+        self.reported(env, self.inner_html(id))
+    }
+
     pub fn inner_html(&self, id: u32) -> String {
         if (self.tag_name(id).as_deref() == Some("template") || self.arena.borrow().is_some())
             && self.ensure_arena().is_ok()
@@ -704,7 +834,11 @@ impl NativeDocument {
         .flatten()
     }
 
-    #[napi]
+    #[napi(js_name = "exportTree")]
+    pub fn export_tree_and_report(&self, env: Env) -> Result<String> {
+        self.reported(env, self.export_tree())
+    }
+
     pub fn export_tree(&self) -> Result<String> {
         if self.source.borrow().is_some() {
             self.ensure_arena()?;
@@ -718,7 +852,11 @@ impl NativeDocument {
         serde_json::to_string(&records).map_err(json_error)
     }
 
-    #[napi]
+    #[napi(js_name = "node")]
+    pub fn node_and_report(&self, env: Env, id: u32) -> Result<String> {
+        self.reported(env, self.node(id))
+    }
+
     pub fn node(&self, id: u32) -> Result<String> {
         if self.source.borrow().is_some() {
             self.ensure_arena()?;
@@ -729,13 +867,26 @@ impl NativeDocument {
         serde_json::to_string(&self.arena.borrow().as_ref().unwrap().node(id)).map_err(json_error)
     }
 
-    #[napi]
+    #[napi(js_name = "create")]
+    pub fn create_and_report(
+        &self,
+        env: Env,
+        html: String,
+        context_id: Option<u32>,
+        options_json: Option<String>,
+    ) -> Result<Vec<u32>> {
+        let created = self.create(html, context_id, options_json);
+        self.reported(env, created)
+    }
+
     pub fn create(
         &self,
         html: String,
         context_id: Option<u32>,
         _options_json: Option<String>,
     ) -> Result<Vec<u32>> {
+        self.content_bytes
+            .set(self.content_bytes.get().saturating_add(html.len()));
         self.ensure_arena()?;
         self.arena
             .borrow_mut()
@@ -746,7 +897,19 @@ impl NativeDocument {
 
     /// Move a branch between native documents. JavaScript only redirects its
     /// existing stable handles using the returned complete descendant mapping.
-    #[napi]
+    #[napi(js_name = "adopt")]
+    pub fn adopt_and_report(
+        &self,
+        env: Env,
+        source: &NativeDocument,
+        ids: Vec<u32>,
+        detach: Option<bool>,
+    ) -> Result<String> {
+        let adopted = self.adopt(source, ids, detach);
+        source.report_heap_bytes(env);
+        self.reported(env, adopted)
+    }
+
     pub fn adopt(
         &self,
         source: &NativeDocument,
@@ -840,7 +1003,11 @@ impl NativeDocument {
             .map_err(json_error)
     }
 
-    #[napi]
+    #[napi(js_name = "op")]
+    pub fn op_and_report(&self, env: Env, command: String, args_json: String) -> Result<String> {
+        self.reported(env, self.op(command, args_json))
+    }
+
     pub fn op(&self, command: String, args_json: String) -> Result<String> {
         self.maybe_collect();
         let args: Value = serde_json::from_str(&args_json).map_err(json_error)?;
@@ -964,6 +1131,8 @@ pub struct MemoryStats {
     pub retained: u32,
     pub reclaimed: u32,
     pub immutable_nodes: u32,
+    /// Native bytes currently reported to V8 for this document.
+    pub external_bytes: i64,
 }
 
 /// The Cheerio DOM adapter exposes foreign attributes by local name, whereas
@@ -1156,11 +1325,12 @@ fn serialize_node(node: NodeRef<'_, Node>, output: &mut String) {
                 output.push_str(element.name());
                 for (name, value) in &element.attrs {
                     output.push(' ');
-                    if let Some(prefix) = &name.prefix {
-                        output.push_str(prefix);
-                        output.push(':');
-                    }
-                    output.push_str(&name.local);
+                    push_attribute_name(
+                        output,
+                        &name.local,
+                        Some(name.ns.as_ref()),
+                        name.prefix.as_deref(),
+                    );
                     output.push_str("=\"");
                     escape_html(value, true, output);
                     output.push('"');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rusteerio",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Cheerio-compatible HTML processing with a Rust engine and parallel, non-blocking extraction",
   "license": "MIT",
   "repository": {

package/src/router.ts

@@ -2,10 +2,11 @@ import { requireNative, type NativeDocument, type NativeNodeRecord } from './nat
 import { hasParserHooks, parseNativeDocument } from './hooks.js';
 import type { CheerioOptions } from './types.js';
 
+interface NativeMemoryStats { live: number; slots: number; retained: number; reclaimed: number; immutableNodes: number; externalBytes: number }
 interface ManagedNativeDocument extends NativeDocument {
   retain?(ids: number[]): void;
   release?(ids: number[]): void;
-  collectGarbage?(): { live: number; slots: number; retained: number; reclaimed: number };
+  collectGarbage?(): NativeMemoryStats;
 }
 interface PinRecord { global: number; document: WeakRef<ManagedNativeDocument>; local: number }
 interface Handle { global: number; document: ManagedNativeDocument; local: number; data?: object; pin: PinRecord }
@@ -105,7 +106,7 @@ export class RoutedDocument implements NativeDocument {
   retainNode(id: number): void { this.lookup(id); }
   retainNodes(ids: number[]): object { return ids.filter((id) => id !== undefined).map((id) => this.lookup(id)); }
   nodeDocument(id: number): NativeDocument { return new RoutedDocument(this.raw, this.options, this.lookup(id)); }
-  collectGarbage(): { live: number; slots: number; retained: number; reclaimed: number } | undefined { registry.snapshots.delete(this.raw); return this.raw.collectGarbage?.(); }
+  collectGarbage(): NativeMemoryStats | undefined { registry.snapshots.delete(this.raw); return this.raw.collectGarbage?.(); }
   retainNodeData(id: number, data: object): void { this.lookup(id).data = data; }
   nodeData(id: number): object | undefined { return this.lookup(id).data; }
   nodeDataOperation(id: number): (command: string, args: any) => any {