@miaskiewicz/turbo-dom 0.1.19 → 0.1.21

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,33 @@ 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,900** | 600 | 250 |
+| **realistic suite**, 200 files (ms/file) | **0.15** | 2.1 | 4.9 |
+| **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) | **920k** | 600k | 3k |
+| html5lib conformance | **99.72%** | 37.35% | 97.03% |
+
+Roughly **~25–30× jsdom** and **~10–14× happy-dom** on per-file setup / realistic
+suites, **18–37×** on parsing, and it edges happy-dom on repeated queries while
+staying 99.7% spec-correct.
+
+**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.21",
   "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';
 
@@ -71,8 +98,12 @@ export class Node extends EventTarget {
   }
 
   get childNodes() {
+    // the NodeList reads __children() live, so one cached object per node is
+    // always correct — avoids re-allocating a Proxy on every .childNodes access
+    // (React/RTL hit this constantly).
+    if (this.__childNodesList) return this.__childNodesList;
     const self = this;
-    return liveNodeList(() => self.__children());
+    return (this.__childNodesList = liveNodeList(() => self.__children()));
   }
   get firstChild() { const k = this.__children(); return k[0] ?? null; }
   get lastChild() { const k = this.__children(); return k[k.length - 1] ?? null; }
@@ -496,8 +527,9 @@ export class Element extends Node {
 
   // ---- element-only traversal (live) ----
   get children() {
+    if (this.__childrenList) return this.__childrenList;
     const self = this;
-    return liveHTMLCollection(() => self.__children().filter((n) => n.nodeType === ELEMENT_NODE));
+    return (this.__childrenList = liveHTMLCollection(() => self.__children().filter((n) => n.nodeType === ELEMENT_NODE)));
   }
   get childElementCount() { return this.__children().filter((n) => n.nodeType === ELEMENT_NODE).length; }
   get firstElementChild() { return this.__children().find((n) => n.nodeType === ELEMENT_NODE) ?? null; }
@@ -516,8 +548,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,9 +753,9 @@ 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); }
-  get children() { const self = this; return liveHTMLCollection(() => self.__children().filter((n) => n.nodeType === ELEMENT_NODE)); }
+  querySelector(sel) { return cachedQS(this, sel); }
+  querySelectorAll(sel) { return cachedQSA(this, sel); }
+  get children() { if (this.__childrenList) return this.__childrenList; const self = this; return (this.__childrenList = 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 +1225,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

package/src/runtime/events.mjs

@@ -150,8 +150,20 @@ export class EventTarget {
   dispatchEvent(event) {
     if (!(event instanceof Event)) throw new TypeError('dispatchEvent requires an Event');
     event.target = this;
-    event._path = this.__eventPath();
-    const path = event._path;
+
+    // Single ancestor walk: build the path AND note whether any node on it has a
+    // listener for this type. React fires thousands of events with zero matching
+    // listeners on the path — those skip the capture/target/bubble invoke loops.
+    const type = event.type;
+    const path = [];
+    let hasListener = false;
+    let node = this;
+    while (node) {
+      path.push(node);
+      if (!hasListener) { const l = node.__listeners && node.__listeners.get(type); if (l && l.length) hasListener = true; }
+      node = node.parentNode || node.__owner || null;
+    }
+    event._path = path;
 
     // pre-click activation (WHATWG): checkbox/radio toggle BEFORE click listeners
     // run, so React's change detection sees the new value. Undone if preventDefault.
@@ -185,18 +197,21 @@ export class EventTarget {
       }
     };
 
-    // capturing: root -> just before target
-    for (let i = path.length - 1; i >= 1; i--) {
-      if (event._stopPropagation) break;
-      invoke(path[i], PHASE_CAPTURING);
-    }
-    // at target
-    if (!event._stopPropagation) invoke(path[0], PHASE_AT_TARGET);
-    // bubbling: target's parent -> root
-    if (event.bubbles) {
-      for (let i = 1; i < path.length; i++) {
+    // no listener anywhere on the path → skip all three propagation phases
+    if (hasListener) {
+      // capturing: root -> just before target
+      for (let i = path.length - 1; i >= 1; i--) {
         if (event._stopPropagation) break;
-        invoke(path[i], PHASE_BUBBLING);
+        invoke(path[i], PHASE_CAPTURING);
+      }
+      // at target
+      if (!event._stopPropagation) invoke(path[0], PHASE_AT_TARGET);
+      // bubbling: target's parent -> root
+      if (event.bubbles) {
+        for (let i = 1; i < path.length; i++) {
+          if (event._stopPropagation) break;
+          invoke(path[i], PHASE_BUBBLING);
+        }
       }
     }
 

package/src/runtime/stubs.mjs

@@ -83,8 +83,13 @@ export function makeMatchMedia() {
 // invents cascade/layout numbers. A property that wasn't set reads as ''.
 export function makeGetComputedStyle() {
   return (el) => {
+    // The Proxy reads el.style LIVE on each access, so one cached Proxy per
+    // element is always correct (no version needed) — avoids re-allocating a
+    // Proxy on every call, which dom-accessibility-api does per element in
+    // getByRole/getByText visibility checks.
+    if (el && el.__computedStyle) return el.__computedStyle;
     const style = el && el.style ? el.style : null;
-    return new Proxy({}, {
+    const proxy = new Proxy({}, {
       get(_t, key) {
         if (key === 'getPropertyValue') return (p) => (style ? style.getPropertyValue(p) : '');
         if (key === '__honest') return 'computed style is inline-only; no layout/cascade available';
@@ -92,6 +97,8 @@ export function makeGetComputedStyle() {
         return style ? style[key] : '';
       },
     });
+    if (el) el.__computedStyle = proxy;
+    return proxy;
   };
 }
 

package/src/runtime/window.mjs

@@ -117,8 +117,8 @@ export function createWindow(document, { url = 'http://localhost/' } = {}) {
     HTMLHeadingElement: tagClass(/^h[1-6]$/),
     HTMLDocument: Document, DocumentFragment, ShadowRoot: DocumentFragment,
     MutationObserver, DOMParser, XMLSerializer,
-    URL: makeURL(), URLSearchParams,
-    Blob: globalThis.Blob, File: makeFile(), FileReader,
+    URL: TURBO_URL, URLSearchParams,
+    Blob: globalThis.Blob, File: TURBO_FILE, FileReader,
     customElements: makeCustomElements(),
     AbortController: globalThis.AbortController, AbortSignal: globalThis.AbortSignal,
     TextEncoder: globalThis.TextEncoder, TextDecoder: globalThis.TextDecoder,
@@ -247,6 +247,9 @@ function makeFile() {
     constructor(bits = [], name = 'file', opts = {}) { super(bits, opts); this.name = String(name); this.lastModified = opts.lastModified || 0; }
   };
 }
+// stateless — build the classes ONCE, not per createWindow() (per test file).
+const TURBO_URL = makeURL();
+const TURBO_FILE = makeFile();
 
 // Minimal XMLHttpRequest backed by fetch — enough that libraries that construct
 // one and issue a request don't crash. No-network setups still get a clean object.