@miaskiewicz/turbo-dom 0.1.19 → 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.19",
+  "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';
 
@@ -516,8 +543,8 @@ export class Element extends Node {
   // ---- 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)); }
 
@@ -721,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; }
@@ -1193,18 +1220,26 @@ 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); }
+  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