@miaskiewicz/turbo-dom 0.1.17 → 0.1.19

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** — ~19× lower per-file setup, 11–39× faster HTML parsing.
+- ⚡ **Faster than jsdom** — ~23× lower per-file setup, ~6× on query-heavy DOM work, 18–37× faster HTML parsing.
 - 🎯 **Honest, not lying** — no fake layout numbers; `getBoundingClientRect()` is zeros and
   `getComputedStyle` reflects only what you set. Geometry tests belong in a real browser.
 
@@ -102,16 +102,19 @@ adopted yet.
 
 Measured on darwin-arm64, Node 24 (`npm run bench:all`):
 
-| benchmark | turbo-dom | happy-dom | jsdom |
-|---|---:|---:|---:|
-| per-file setup + 1 query (ops/s) | **6,808** | 526 | 266 |
-| full suite, 200 files (ms/file) | **0.13** | 1.45 | 3.36 |
-| parse 56 KB SSR (ops/s) | **502** | 46 | 23 |
-| parse 20 KB real page (ops/s) | **3,912** | 230 | 100 |
+| 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; and `window` doesn't build the ~12 globals (storage, observers,
-matchMedia…) a render-only test never touches.
+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.
 
 ## How it works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miaskiewicz/turbo-dom",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "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",
@@ -64,10 +64,11 @@
     "bench:construct": "node bench/construct.mjs",
     "bench:suite": "node bench/suite.mjs",
     "bench:wasm": "node bench/wasm.mjs",
-    "bench:all": "node bench/parse.mjs && node bench/construct.mjs && node bench/suite.mjs && node bench/wasm.mjs",
+    "bench:all": "node bench/parse.mjs && node bench/construct.mjs && node bench/suite.mjs && node bench/query.mjs && node bench/wasm.mjs",
     "prepublishOnly": "napi build --platform --release",
     "test:vitest": "vitest run -c test-vitest/vitest.config.mjs",
-    "test:jest": "jest -c test-jest/jest.config.cjs"
+    "test:jest": "jest -c test-jest/jest.config.cjs",
+    "bench:query": "node bench/query.mjs"
   },
   "keywords": [
     "dom",

package/src/runtime/dom.mjs

@@ -158,7 +158,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 +189,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; }
 }
@@ -300,8 +306,8 @@ export class Element extends Node {
   get namespaceURI() { return nsUri(this.__ns); }
 
   // ---- attributes ----
-  getAttribute(name) { const a = this.__attrs.find((x) => x.name === name); return a ? a.value : null; }
-  hasAttribute(name) { return this.__attrs.some((x) => x.name === name); }
+  getAttribute(name) { const at = this.__attrs; for (let i = 0; i < at.length; i++) if (at[i].name === name) return at[i].value; return null; }
+  hasAttribute(name) { const at = this.__attrs; for (let i = 0; i < at.length; i++) if (at[i].name === name) return true; return false; }
   getAttributeNames() { return this.__attrs.map((a) => a.name); }
   setAttribute(name, value) {
     const a = this.__attrs.find((x) => x.name === name);
@@ -505,7 +511,7 @@ 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); }
@@ -520,6 +526,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);
@@ -726,25 +733,43 @@ function toNode(doc, n) { return typeof n === 'string' ? doc.createTextNode(n) :
 
 function collectByTag(root, tag) {
   const out = [];
+  const all = tag === '*';
   const visit = (node) => {
-    for (const c of node.__children()) {
-      if (c.nodeType === ELEMENT_NODE) {
-        if (tag === '*' || c.localName === tag) out.push(c);
-        visit(c);
-      }
+    const kids = node.__children();
+    for (let i = 0; i < kids.length; i++) {
+      const c = kids[i];
+      if (c.nodeType !== ELEMENT_NODE) continue;
+      if (all || c.localName === tag) out.push(c);
+      visit(c);
     }
   };
   visit(root);
   return out;
 }
+// allocation-free whole-word class membership (no ClassList, no split)
+function elHasClass(el, cls) {
+  const cn = el.getAttribute('class');
+  if (!cn) return false;
+  if (cn === cls) return true;
+  const L = cls.length;
+  let idx = cn.indexOf(cls);
+  while (idx !== -1) {
+    if ((idx === 0 || cn.charCodeAt(idx - 1) <= 32) && (idx + L === cn.length || cn.charCodeAt(idx + L) <= 32)) return true;
+    idx = cn.indexOf(cls, idx + 1);
+  }
+  return false;
+}
 function collectByClass(root, classes) {
   const out = [];
   const visit = (node) => {
-    for (const c of node.__children()) {
-      if (c.nodeType === ELEMENT_NODE) {
-        if (classes.every((cl) => c.classList.contains(cl))) out.push(c);
-        visit(c);
-      }
+    const kids = node.__children();
+    for (let i = 0; i < kids.length; i++) {
+      const c = kids[i];
+      if (c.nodeType !== ELEMENT_NODE) continue;
+      let ok = true;
+      for (let j = 0; j < classes.length; j++) if (!elHasClass(c, classes[j])) { ok = false; break; }
+      if (ok) out.push(c);
+      visit(c);
     }
   };
   visit(root);
@@ -938,7 +963,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;
@@ -1091,6 +1120,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; }
@@ -1173,8 +1205,28 @@ export class Document extends Node {
   }
   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)); }
+  // 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/…),

package/src/runtime/selectors.mjs

@@ -83,8 +83,17 @@ function parseComplex(src) {
   return { compounds, combinators };
 }
 
+// parsed-selector cache: querySelector(All)/matches re-run the same selector
+// strings constantly; parsing once and reusing is a large win on query-heavy
+// suites. Bounded so a pathological generator can't grow it without limit.
+const __selectorCache = new Map();
 export function parseSelectorList(selector) {
-  return splitTopLevel(selector, ',').map((s) => parseComplex(s.trim()));
+  const hit = __selectorCache.get(selector);
+  if (hit !== undefined) return hit;
+  const parsed = splitTopLevel(selector, ',').map((s) => parseComplex(s.trim()));
+  if (__selectorCache.size > 10000) __selectorCache.clear();
+  __selectorCache.set(selector, parsed);
+  return parsed;
 }
 
 function splitTopLevel(s, sep) {
@@ -106,9 +115,10 @@ function elementChildren(node) {
 }
 
 function matchAttr(el, a) {
-  if (!el.hasAttribute(a.name)) return false;
+  const raw = el.getAttribute(a.name);   // single lookup (null = absent)
+  if (raw === null) return false;
   if (a.op === null) return true;
-  const v = el.getAttribute(a.name) ?? '';
+  const v = raw;
   const t = a.value ?? '';
   switch (a.op) {
     case '=': return v === t;
@@ -211,11 +221,32 @@ function nextElement(el) {
   return n || null;
 }
 
+// allocation-free "does the class attribute contain this whole-word class"
+function hasClass(cn, cls) {
+  if (cn === cls) return true;
+  const L = cls.length;
+  let idx = cn.indexOf(cls);
+  while (idx !== -1) {
+    const before = idx === 0 || cn.charCodeAt(idx - 1) <= 32;
+    const after = idx + L === cn.length || cn.charCodeAt(idx + L) <= 32;
+    if (before && after) return true;
+    idx = cn.indexOf(cls, idx + 1);
+  }
+  return false;
+}
+
 function matchCompound(el, compound) {
   if (!el || el.nodeType !== 1) return false;
+  // cheapest checks first; tag/local is a plain property
   if (compound.tag && compound.tag !== '*' && el.localName !== compound.tag) return false;
   if (compound.id !== null && el.getAttribute('id') !== compound.id) return false;
-  for (const cls of compound.classes) if (!el.classList.contains(cls)) return false;
+  // classes: read the class attribute ONCE and test membership without
+  // allocating (no ClassList, no split, no padded copy) — dominated matching.
+  if (compound.classes.length) {
+    const cn = el.getAttribute('class');
+    if (!cn) return false;
+    for (const cls of compound.classes) if (!hasClass(cn, cls)) return false;
+  }
   for (const a of compound.attrs) if (!matchAttr(el, a)) return false;
   for (const p of compound.pseudos) if (!matchPseudo(el, p)) return false;
   return true;
@@ -268,13 +299,43 @@ export function matchesSelector(el, selector) {
   return list.some((cx) => matchComplex(el, cx));
 }
 
+// Fast paths for the overwhelmingly common simple selectors, skipping the
+// parse + per-element matchComplex machinery.
+const SIMPLE = /^\s*(#[\w-]+|\.[\w-]+|[a-zA-Z][\w-]*)\s*$/;
+function simpleMatcher(selector) {
+  const m = SIMPLE.exec(selector);
+  if (!m) return null;
+  const s = m[1];
+  if (s[0] === '#') { const id = s.slice(1); return (el) => el.getAttribute('id') === id; }
+  if (s[0] === '.') { const cls = s.slice(1); return (el) => el.classList.contains(cls); }
+  const tag = s.toLowerCase(); return (el) => el.localName === tag;
+}
+
+// child node array without allocating a filtered copy per call
+function rawChildren(node) {
+  return typeof node.__children === 'function' ? node.__children() : Array.from(node.childNodes || []);
+}
+
 export function querySelectorAll(root, selector) {
-  const list = parseSelectorList(selector);
+  const simple = simpleMatcher(selector);
   const out = [];
+  if (simple) {
+    const visit = (node) => {
+      const kids = rawChildren(node);
+      for (let i = 0; i < kids.length; i++) { const c = kids[i]; if (c.nodeType !== 1) continue; if (simple(c)) out.push(c); visit(c); }
+    };
+    visit(root);
+    return out;
+  }
+  const list = parseSelectorList(selector);
+  const single = list.length === 1 ? list[0] : null;
   const visit = (node) => {
-    for (const child of elementChildren(node)) {
-      if (list.some((cx) => matchComplex(child, cx))) out.push(child);
-      visit(child);
+    const kids = rawChildren(node);
+    for (let i = 0; i < kids.length; i++) {
+      const c = kids[i];
+      if (c.nodeType !== 1) continue;
+      if (single ? matchComplex(c, single) : list.some((cx) => matchComplex(c, cx))) out.push(c);
+      visit(c);
     }
   };
   visit(root);
@@ -282,18 +343,29 @@ export function querySelectorAll(root, selector) {
 }
 
 export function querySelector(root, selector) {
+  const simple = simpleMatcher(selector);
+  if (simple) {
+    const visit = (node) => {
+      const kids = rawChildren(node);
+      for (let i = 0; i < kids.length; i++) { const c = kids[i]; if (c.nodeType !== 1) continue; if (simple(c)) return c; const r = visit(c); if (r) return r; }
+      return null;
+    };
+    return visit(root);
+  }
   const list = parseSelectorList(selector);
-  let found = null;
+  const single = list.length === 1 ? list[0] : null;
   const visit = (node) => {
-    for (const child of elementChildren(node)) {
-      if (found) return;
-      if (list.some((cx) => matchComplex(child, cx))) { found = child; return; }
-      visit(child);
-      if (found) return;
+    const kids = rawChildren(node);
+    for (let i = 0; i < kids.length; i++) {
+      const c = kids[i];
+      if (c.nodeType !== 1) continue;
+      if (single ? matchComplex(c, single) : list.some((cx) => matchComplex(c, cx))) return c;
+      const r = visit(c);
+      if (r) return r;
     }
+    return null;
   };
-  visit(root);
-  return found;
+  return visit(root);
 }
 
 export const _internal = { parseComplex, parseSelectorList, matchCompound, matchComplex };