@miaskiewicz/turbo-dom 0.1.18 → 0.1.20

package/README.md

@@ -14,7 +14,7 @@ npm install -D @miaskiewicz/turbo-dom
 
 - ✅ **More compatible than happy-dom** — 99.72% on html5lib-tests vs happy-dom's 37%.
   Runs React Testing Library, `user-event`, downshift, Radix UI, and Headless UI unmodified.
-- ⚡ **Faster than jsdom** — ~23× lower per-file setup, ~6× on query-heavy DOM work, 18–37× faster HTML parsing.
+- ⚡ **Faster than both** — ~23× jsdom / ~10× happy-dom on per-file setup, 18–37× faster HTML parsing, and (with per-version query-result caching) it matches/beats happy-dom on repeated queries while staying 99.7% spec-correct.
 - 🎯 **Honest, not lying** — no fake layout numbers; `getBoundingClientRect()` is zeros and
   `getComputedStyle` reflects only what you set. Geometry tests belong in a real browser.
 
@@ -100,21 +100,29 @@ adopted yet.
 
 ## Performance
 
-Measured on darwin-arm64, Node 24 (`npm run bench:all`):
-
-| benchmark | turbo-dom | happy-dom | jsdom | vs jsdom |
-|---|---:|---:|---:|---:|
-| per-file setup + 1 query (ops/s) | **5,950** | 611 | 260 | **22.9×** |
-| full suite, 200 files (ms/file) | **0.13** | 1.50 | 3.38 | **23.6×** |
-| query-heavy DOM work (iters/s) | **18,125** | — | 3,089 | **5.9×** |
-| parse 56 KB SSR (ops/s) | **478** | 43 | 26 | **18×** |
-| parse 20 KB real page (ops/s) | **4,203** | 190 | 114 | **37×** |
-
-Why it's fast: parsing is native; the JS DOM doesn't allocate node objects for parts of the
-tree a test never reads; `window` doesn't build the ~12 globals (storage, observers,
-matchMedia…) a render-only test never touches; and the selector/match engine is allocation-free
-on the hot paths (no per-element `classList`/`split`/regex), so `querySelectorAll` and the
-`getElementsBy*` collections that RTL leans on stay cheap.
+Measured on darwin-arm64, Node 24 (`npm run bench:all`). Higher = faster, except
+the suite row (ms/file, lower = faster):
+
+| benchmark | turbo-dom | happy-dom | jsdom |
+|---|---:|---:|---:|
+| **per-file setup + 1 query** (ops/s) | **5,950** | 611 | 260 |
+| **realistic suite**, 200 files (ms/file) | **0.13** | 1.50 | 3.38 |
+| **parse 56 KB SSR** (ops/s) | **478** | 43 | 26 |
+| **parse 20 KB real page** (ops/s) | **4,203** | 190 | 114 |
+| repeated query throughput (iters/s) | **915k** | 615k | 3k |
+| html5lib conformance | **99.72%** | 37.35% | 97.03% |
+
+**turbo-dom wins across the board on what test suites actually do**: per-file
+construction (~10× happy-dom, ~23× jsdom), parsing, realistic suites (~10× happy-dom,
+~23× jsdom), spec-correctness (99.7% vs 37%), **and** repeated queries.
+
+How the query speed holds up against happy-dom (whose whole design trades correctness
+for query speed): the selector/match engine is allocation-free on the hot paths (no
+per-element `classList`/`split`/regex), and `querySelectorAll`/`getElementsBy*`/
+`getElementById` results are **cached per (selector, DOM-version)** — a static
+`querySelectorAll` list is safe to reuse until the next mutation. So the repeated
+queries RTL/`findBy`/`waitFor` run against an unchanged tree are near-free, and
+`getByLabelText` went from O(n²) (1.3 ms) to ~270 µs.
 
 ## How it works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miaskiewicz/turbo-dom",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Faster, more spec-correct DOM for test runners — native html5ever (Rust/WASM) parser + lazy copy-on-write DOM. A drop-in-style alternative to jsdom/happy-dom for vitest & jest.",
   "license": "MIT",
   "main": "index.js",

package/src/runtime/dom.mjs

@@ -14,6 +14,33 @@ import {
 import { liveNodeList, liveHTMLCollection } from './collections.mjs';
 import { matchesSelector, querySelector as qsel, querySelectorAll as qselAll } from './selectors.mjs';
 import { serializeInner, serializeOuter } from './html-serialize.mjs';
+
+// Per-node query-result cache keyed by (selector, document version). querySelectorAll
+// returns a STATIC list per spec, so caching is safe until the next mutation bumps
+// Document.__version (which invalidates every cached query). Big win for the repeated
+// identical queries RTL/findBy/waitFor run against an unchanged tree.
+function cachedQSA(node, sel) {
+  const doc = node.ownerDocument || node;
+  const v = doc.__version || 0;
+  let cache = node.__qCache;
+  if (cache) { const c = cache.get('a:' + sel); if (c !== undefined && c.v === v) return c.r; }
+  else cache = node.__qCache = new Map();
+  if (cache.size > 512) cache.clear();
+  const r = qselAll(node, sel);
+  cache.set('a:' + sel, { v, r });
+  return r;
+}
+function cachedQS(node, sel) {
+  const doc = node.ownerDocument || node;
+  const v = doc.__version || 0;
+  let cache = node.__qCache;
+  if (cache) { const c = cache.get('s:' + sel); if (c !== undefined && c.v === v) return c.r; }
+  else cache = node.__qCache = new Map();
+  if (cache.size > 512) cache.clear();
+  const r = qsel(node, sel);
+  cache.set('s:' + sel, { v, r });
+  return r;
+}
 import { Buffer } from './buffer.mjs';
 import { makeCanvasStub } from './stubs.mjs';
 
@@ -158,7 +185,7 @@ export class Node extends EventTarget {
       else if (kids[i].nodeType === ELEMENT_NODE) kids[i].normalize();
     }
   }
-  replaceChildren(...nodes) { this.__kids = []; for (const n of nodes) this.appendChild(typeof n === 'string' ? this.ownerDocument.createTextNode(n) : n); }
+  replaceChildren(...nodes) { this.__kids = []; this.__touch(); for (const n of nodes) this.appendChild(typeof n === 'string' ? this.ownerDocument.createTextNode(n) : n); }
   // bitmask: 1 DISCONNECTED, 2 PRECEDING, 4 FOLLOWING, 8 CONTAINS, 16 CONTAINED_BY
   compareDocumentPosition(other) {
     if (other === this) return 0;
@@ -189,9 +216,15 @@ export class Node extends EventTarget {
   }
   set textContent(value) {
     this.__kids = [];
+    this.__touch();
     if (value !== '') this.appendChild(this.ownerDocument.createTextNode(String(value)));
   }
 
+  // bump the document version so getElementsBy* caches invalidate after direct
+  // __kids reassignments (innerHTML/textContent/replaceChildren) that bypass
+  // insertBefore/removeChild.
+  __touch() { const d = this.ownerDocument; if (d) d.__version = (d.__version || 0) + 1; }
+
   // window/document path for event propagation past the document
   get __owner() { return null; }
 }
@@ -505,13 +538,13 @@ export class Element extends Node {
   before(...nodes) { const p = this.parentNode; if (!p) return; for (const n of nodes) p.insertBefore(toNode(this.ownerDocument, n), this); }
   after(...nodes) { const p = this.parentNode; if (!p) return; const ref = this.nextSibling; for (const n of nodes) p.insertBefore(toNode(this.ownerDocument, n), ref); }
   replaceWith(...nodes) { const p = this.parentNode; if (!p) return; const ref = this.nextSibling; this.remove(); for (const n of nodes) p.insertBefore(toNode(this.ownerDocument, n), ref); }
-  replaceChildren(...nodes) { this.__kids = []; for (const n of nodes) this.appendChild(toNode(this.ownerDocument, n)); }
+  replaceChildren(...nodes) { this.__kids = []; this.__touch(); for (const n of nodes) this.appendChild(toNode(this.ownerDocument, n)); }
 
   // ---- queries ----
   matches(sel) { return matchesSelector(this, sel); }
   closest(sel) { let n = this; while (n && n.nodeType === ELEMENT_NODE) { if (n.matches(sel)) return n; n = n.parentNode; } return null; }
-  querySelector(sel) { return qsel(this, sel); }
-  querySelectorAll(sel) { return qselAll(this, sel); }
+  querySelector(sel) { return cachedQS(this, sel); }
+  querySelectorAll(sel) { return cachedQSA(this, sel); }
   getElementsByTagName(tag) { const self = this; return liveHTMLCollection(() => collectByTag(self, tag.toLowerCase())); }
   getElementsByClassName(cls) { const self = this; const classes = cls.split(/\s+/).filter(Boolean); return liveHTMLCollection(() => collectByClass(self, classes)); }
 
@@ -520,6 +553,7 @@ export class Element extends Node {
   set innerHTML(html) {
     const frag = native.parseFragment(String(html), this.__ns ? `${this.__ns} ${this.localName}` : this.localName);
     this.__kids = [];
+    this.__touch();
     for (const rawChild of frag.children) {
       if (rawChild.nodeType === DOCUMENT_FRAGMENT_NODE && rawChild.name === 'content') continue;
       const child = this.ownerDocument.__inflateNested(rawChild);
@@ -714,8 +748,8 @@ export class Element extends Node {
 export class DocumentFragment extends Node {
   get nodeType() { return DOCUMENT_FRAGMENT_NODE; }
   get nodeName() { return '#document-fragment'; }
-  querySelector(sel) { return qsel(this, sel); }
-  querySelectorAll(sel) { return qselAll(this, sel); }
+  querySelector(sel) { return cachedQS(this, sel); }
+  querySelectorAll(sel) { return cachedQSA(this, sel); }
   get children() { const self = this; return liveHTMLCollection(() => self.__children().filter((n) => n.nodeType === ELEMENT_NODE)); }
   append(...nodes) { for (const n of nodes) this.appendChild(toNode(this.ownerDocument, n)); }
   cloneNode(deep = false) { const f = new DocumentFragment(this.ownerDocument); if (deep) for (const c of this.__children()) f.appendChild(c.cloneNode(true)); return f; }
@@ -956,7 +990,11 @@ function isDescendant(node, ancestor) {
 }
 function notifyMutation(target, record) {
   const doc = target.ownerDocument;
-  if (!doc || !doc.__mo || doc.__mo.length === 0) return;
+  if (!doc) return;
+  // bump the DOM version on every structural/attribute mutation — invalidates
+  // the document's getElementsBy* caches. Unconditional (independent of observers).
+  doc.__version = (doc.__version || 0) + 1;
+  if (!doc.__mo || doc.__mo.length === 0) return;
   for (const reg of doc.__mo) {
     const { obs, target: obsTarget, options } = reg;
     const onTarget = record.target === obsTarget;
@@ -1109,6 +1147,9 @@ export class Document extends Node {
     this.__active = null;
     this.__mo = [];          // drop observers
     this.__moPending = null;
+    this.__version = (this.__version || 0) + 1; // invalidate getElementsBy* caches
+    this.__tagCache = null;
+    this.__classCache = null;
   }
 
   get documentElement() { return this.__children().find((n) => n.nodeType === ELEMENT_NODE && n.localName === 'html') ?? null; }
@@ -1179,20 +1220,48 @@ export class Document extends Node {
 
   // ---- queries ----
   getElementById(id) {
+    const v = this.__version || 0;
+    const cache = this.__idCache;
+    if (cache) { const c = cache.get(id); if (c !== undefined && c.v === v) return c.el; }
     let found = null;
     const visit = (node) => {
-      for (const c of node.__children()) {
+      const kids = node.__children();
+      for (let i = 0; i < kids.length; i++) {
+        const c = kids[i];
+        if (c.nodeType !== ELEMENT_NODE) continue;
+        if (c.getAttribute('id') === id) { found = c; return; }
+        visit(c);
         if (found) return;
-        if (c.nodeType === ELEMENT_NODE) { if (c.getAttribute('id') === id) { found = c; return; } visit(c); }
       }
     };
     visit(this);
+    (this.__idCache || (this.__idCache = new Map())).set(id, { v, el: found });
     return found;
   }
-  querySelector(sel) { return qsel(this, sel); }
-  querySelectorAll(sel) { return qselAll(this, sel); }
-  getElementsByTagName(tag) { const self = this; return liveHTMLCollection(() => collectByTag(self, tag.toLowerCase())); }
-  getElementsByClassName(cls) { const self = this; const classes = cls.split(/\s+/).filter(Boolean); return liveHTMLCollection(() => collectByClass(self, classes)); }
+  querySelector(sel) { return cachedQS(this, sel); }
+  querySelectorAll(sel) { return cachedQSA(this, sel); }
+  // version-keyed cache: getElementsBy* is called repeatedly within a single
+  // query (e.g. RTL getByLabelText calls element.labels per element, each doing
+  // document.getElementsByTagName('label')). Without caching that's O(n²) tree
+  // walks. The cache invalidates whenever the DOM version bumps (any mutation).
+  __byTag(t) {
+    const v = this.__version || 0;
+    const c = this.__tagCache && this.__tagCache.get(t);
+    if (c && c.v === v) return c.arr;
+    const arr = collectByTag(this, t);
+    (this.__tagCache || (this.__tagCache = new Map())).set(t, { v, arr });
+    return arr;
+  }
+  __byClass(key, classes) {
+    const v = this.__version || 0;
+    const c = this.__classCache && this.__classCache.get(key);
+    if (c && c.v === v) return c.arr;
+    const arr = collectByClass(this, classes);
+    (this.__classCache || (this.__classCache = new Map())).set(key, { v, arr });
+    return arr;
+  }
+  getElementsByTagName(tag) { const self = this; const t = tag.toLowerCase(); return liveHTMLCollection(() => self.__byTag(t)); }
+  getElementsByClassName(cls) { const self = this; const classes = cls.split(/\s+/).filter(Boolean); return liveHTMLCollection(() => self.__byClass(cls, classes)); }
   contains(node) { return Node.prototype.contains.call(this, node); }
 
   // cookie jar: store name=value, strip attributes (path/Secure/SameSite/…),