Skip to content

asamuzaK/domSelector

BranchesTags

Repository files navigation

DOM Selector

build CodeQL npm (scoped)

A CSS selector engine.

Install

npm i @asamuzakjp/dom-selector

Usage

import { DOMSelector } from '@asamuzakjp/dom-selector';
import { JSDOM } from 'jsdom';

const { window } = new JSDOM();
const {
  closest, matches, querySelector, querySelectorAll
} = new DOMSelector(window);

matches(selector, node, opt)

matches - equivalent to Element.matches()

Parameters

  • selector string CSS selector
  • node object Element node
  • opt object? options
    • opt.noexcept boolean? no exception
    • opt.warn boolean? console warn e.g. unsupported pseudo-class

Returns boolean true if matched, false otherwise

closest(selector, node, opt)

closest - equivalent to Element.closest()

Parameters

  • selector string CSS selector
  • node object Element node
  • opt object? options
    • opt.noexcept boolean? no exception
    • opt.warn boolean? console warn e.g. unsupported pseudo-class

Returns object? matched node

querySelector(selector, node, opt)

querySelector - equivalent to Document.querySelector(), DocumentFragment.querySelector() and Element.querySelector()

Parameters

  • selector string CSS selector
  • node object Document, DocumentFragment or Element node
  • opt object? options
    • opt.noexcept boolean? no exception
    • opt.warn boolean? console warn e.g. unsupported pseudo-class

Returns object? matched node

querySelectorAll(selector, node, opt)

querySelectorAll - equivalent to Document.querySelectorAll(), DocumentFragment.querySelectorAll() and Element.querySelectorAll()
NOTE: returns Array, not NodeList

Parameters

  • selector string CSS selector
  • node object Document, DocumentFragment or Element node
  • opt object? options
    • opt.noexcept boolean? no exception
    • opt.warn boolean? console warn e.g. unsupported pseudo-class

Returns Array<(object | undefined)> array of matched nodes

Monkey patch jsdom

import { DOMSelector } from '@asamuzakjp/dom-selector';
import { JSDOM } from 'jsdom';

const dom = new JSDOM('', {
  runScripts: 'dangerously',
  url: 'http://localhost/',
  beforeParse: window => {
    const domSelector = new DOMSelector(window);

    const matches = domSelector.matches.bind(domSelector);
    window.Element.prototype.matches = function (...args) {
      if (!args.length) {
        throw new window.TypeError('1 argument required, but only 0 present.');
      }
      const [selector] = args;
      return matches(selector, this);
    };

    const closest = domSelector.closest.bind(domSelector);
    window.Element.prototype.closest = function (...args) {
      if (!args.length) {
        throw new window.TypeError('1 argument required, but only 0 present.');
      }
      const [selector] = args;
      return closest(selector, this);
    };

    const querySelector = domSelector.querySelector.bind(domSelector);
    window.Document.prototype.querySelector = function (...args) {
      if (!args.length) {
        throw new window.TypeError('1 argument required, but only 0 present.');
      }
      const [selector] = args;
      return querySelector(selector, this);
    };
    window.DocumentFragment.prototype.querySelector = function (...args) {
      if (!args.length) {
        throw new window.TypeError('1 argument required, but only 0 present.');
      }
      const [selector] = args;
      return querySelector(selector, this);
    };
    window.Element.prototype.querySelector = function (...args) {
      if (!args.length) {
        throw new window.TypeError('1 argument required, but only 0 present.');
      }
      const [selector] = args;
      return querySelector(selector, this);
    };

    const querySelectorAll = domSelector.querySelectorAll.bind(domSelector);
    window.Document.prototype.querySelectorAll = function (...args) {
      if (!args.length) {
        throw new window.TypeError('1 argument required, but only 0 present.');
      }
      const [selector] = args;
      return querySelectorAll(selector, this);
    };
    window.DocumentFragment.prototype.querySelectorAll = function (...args) {
      if (!args.length) {
        throw new window.TypeError('1 argument required, but only 0 present.');
      }
      const [selector] = args;
      return querySelectorAll(selector, this);
    };
    window.Element.prototype.querySelectorAll = function (...args) {
      if (!args.length) {
        throw new window.TypeError('1 argument required, but only 0 present.');
      }
      const [selector] = args;
      return querySelectorAll(selector, this);
    };
  }
});

Supported CSS selectors

Pattern Supported Note
* ✓
ns|E ✓
*|E ✓
|E ✓
E ✓
E:not(s1, s2, …) ✓
E:is(s1, s2, …) ✓
E:where(s1, s2, …) ✓
E:has(rs1, rs2, …) ✓
E.warning ✓
E#myid ✓
E[foo] ✓
E[foo="bar"] ✓
E[foo="bar" i] ✓
E[foo="bar" s] ✓
E[foo~="bar"] ✓
E[foo^="bar"] ✓
E[foo$="bar"] ✓
E[foo*="bar"] ✓
E[foo|="en"] ✓
E:defined Partially supported Matching with MathML is not yet supported.
E:dir(ltr) ✓
E:lang(en) ✓
E:any‑link ✓
E:link ✓
E:visited ✓ Returns false or null to prevent fingerprinting.
E:local‑link ✓
E:target ✓
E:target‑within ✓
E:scope ✓
E:current Unsupported
E:current(s) Unsupported
E:past Unsupported
E:future Unsupported
E:active ✓
E:hover ✓
E:focus ✓
E:focus‑within ✓
E:focus‑visible ✓
E:open
E:closed		 Partially supported Matching with <select>, e.g. select:open, is not supported.
E:enabled
E:disabled		 ✓
E:read‑write
E:read‑only		 ✓
E:placeholder‑shown ✓
E:default ✓
E:checked ✓
E:indeterminate ✓
E:valid
E:invalid		 ✓
E:required
E:optional		 ✓
E:blank Unsupported
E:user‑valid
E:user‑invalid		 Unsupported
E:root ✓
E:empty ✓
E:nth‑child(n [of S]?) ✓
E:nth‑last‑child(n [of S]?) ✓
E:first‑child ✓
E:last‑child ✓
E:only‑child ✓
E:nth‑of‑type(n) ✓
E:nth‑last‑of‑type(n) ✓
E:first‑of‑type ✓
E:last‑of‑type ✓
E:only‑of‑type ✓
E F ✓
E > F ✓
E + F ✓
E ~ F ✓
F || E Unsupported
E:nth‑col(n) Unsupported
E:nth‑last‑col(n) Unsupported
E:host ✓
E:host(s) ✓
E:host‑context(s) ✓
E:popover-open ✓
E:state(v) ✓ *1
E:host(:state(v)) ✓ *1

*1: ElementInternals.states, i.e. CustomStateSet, is not implemented in jsdom, so you need to apply a patch in the custom element constructor.

class LabeledCheckbox extends window.HTMLElement {
  #internals;
  constructor() {
    super();
    this.#internals = this.attachInternals();
    // patch CustomStateSet
    if (!this.#internals.states) {
      this.#internals.states = new Set();
    }
    this.addEventListener('click', this._onClick.bind(this));
  }
  get checked() {
    return this.#internals.states.has('checked');
  }
  set checked(flag) {
    if (flag) {
      this.#internals.states.add('checked');
    } else {
      this.#internals.states.delete('checked');
    }
  }
  _onClick(event) {
    this.checked = !this.checked;
  }
}

Performance

See benchmark for the latest results.

F: Failed because the selector is not supported or the result was incorrect.

matches()

Selector jsdom v25.0.0 (nwsapi) happy-dom linkeDom patched-jsdom (dom-selector) Result
simple selector:
matches('.content')		 937,822 ops/sec ±0.50% 7,910,671 ops/sec ±0.27% 8,620 ops/sec ±0.75% 772,780 ops/sec ±0.30% happydom is the fastest and 10.2 times faster than patched-jsdom. jsdom is 1.2 times faster than patched-jsdom.
compound selector:
matches('p.content[id]:is(:last-child, :only-child)')		 572,176 ops/sec ±0.38% 7,693,760 ops/sec ±1.88% 8,257 ops/sec ±0.63% 402,508 ops/sec ±0.21% happydom is the fastest and 19.1 times faster than patched-jsdom. jsdom is 1.4 times faster than patched-jsdom.
compound selector:
matches('p.content[id]:is(:invalid-nth-child, :only-child)')		 F 6,987,723 ops/sec ±0.39% F 74,756 ops/sec ±1.26% happydom is the fastest and 93.5 times faster than patched-jsdom.
compound selector:
matches('p.content[id]:not(:is(.foo, .bar))')		 455,833 ops/sec ±1.90% 6,645,611 ops/sec ±1.63% 8,205 ops/sec ±1.12% 326,773 ops/sec ±1.38% happydom is the fastest and 20.3 times faster than patched-jsdom. jsdom is 1.4 times faster than patched-jsdom.
complex selector:
matches('.box:first-child ~ .box:nth-of-type(4n+1) + .box[id] .block.inner > .content')		 144,430 ops/sec ±1.65% F 5,445 ops/sec ±1.00% 121,298 ops/sec ±1.34% jsdom is the fastest and 1.2 times faster than patched-jsdom.
complex selector:
matches('.box:first-child ~ .box:nth-of-type(4n+1) + .box[id] .block.inner:has(> .content)')		 F F 5,337 ops/sec ±0.86% 17,419 ops/sec ±2.05% patched-jsdom is the fastest.
complex selector within logical pseudo-class:
matches(':is(.box > .content, .block > .content)')		 398,206 ops/sec ±0.51% F 5,719 ops/sec ±0.84% 326,625 ops/sec ±1.25% jsdom is the fastest and 1.2 times faster than patched-jsdom.

closest()

Selector jsdom v25.0.0 (nwsapi) happy-dom linkeDom patched-jsdom (dom-selector) Result
simple selector:
closest('.container')		 357,783 ops/sec ±1.70% 2,319,384 ops/sec ±0.92% 8,581 ops/sec ±0.84% 328,849 ops/sec ±1.31% happydom is the fastest and 7.1 times faster than patched-jsdom. jsdom is 1.1 times faster than patched-jsdom.
compound selector:
closest('div.container[id]:not(.foo, .box)')		 131,236 ops/sec ±0.73% F 8,052 ops/sec ±0.95% 119,653 ops/sec ±1.44% jsdom is the fastest and 1.1 times faster than patched-jsdom.
complex selector:
closest('.box:first-child ~ .box:nth-of-type(4n+1) + .box[id] .block.inner > .content')		 137,291 ops/sec ±0.17% F 5,483 ops/sec ±0.36% 116,733 ops/sec ±0.21% jsdom is the fastest and 1.2 times faster than patched-jsdom.
complex selector:
closest('.box:first-child ~ .box:nth-of-type(4n+1) + .box[id] .block.inner:has(> .content)')		 F F 5,354 ops/sec ±0.87% 14,363 ops/sec ±1.58% patched-jsdom is the fastest.
complex selector within logical pseudo-class:
closest(':is(.container > .content, .container > .box)')		 190,643 ops/sec ±1.69% 2,819,109 ops/sec ±1.22% 5,732 ops/sec ±0.34% 169,772 ops/sec ±1.48% happydom is the fastest and 16.6 times faster than patched-jsdom. jsdom is 1.1 times faster than patched-jsdom.

querySelector()

Selector jsdom v25.0.0 (nwsapi) happy-dom linkeDom patched-jsdom (dom-selector) Result
simple selector:
querySelector('.content')		 30,752 ops/sec ±1.40% 3,402,064 ops/sec ±1.11% 10,466 ops/sec ±0.91% 30,353 ops/sec ±1.46% happydom is the fastest and 112.1 times faster than patched-jsdom. jsdom is 1.0 times faster than patched-jsdom.
compound selector:
querySelector('p.content[id]:is(:last-child, :only-child)')		 9,716 ops/sec ±1.63% 3,318,668 ops/sec ±1.19% 9,481 ops/sec ±0.59% 9,123 ops/sec ±0.47% happydom is the fastest and 363.8 times faster than patched-jsdom. jsdom is 1.1 times faster than patched-jsdom.
complex selector:
querySelector('.box:first-child ~ .box:nth-of-type(4n+1) + .box[id] .block.inner > .content')		 219 ops/sec ±1.75% F 1,270 ops/sec ±0.34% 779 ops/sec ±2.08% linkedom is the fastest and 1.6 times faster than patched-jsdom. patched-jsdom is 3.6 times faster than jsdom.
complex selector:
querySelector('.box:first-child ~ .box:nth-of-type(4n+1) + .box[id] .block.inner:has(> .content)')		 F F 1,532 ops/sec ±1.81% 516 ops/sec ±1.93% linkedom is the fastest and 3.0 times faster than patched-jsdom.
complex selector within logical pseudo-class:
querySelector(':is(.box > .content, .block > .content)')		 3,215 ops/sec ±0.60% F 9,656 ops/sec ±1.10% 159,781 ops/sec ±2.23% patched-jsdom is the fastest. patched-jsdom is 49.7 times faster than jsdom.

querySelectorAll()

Selector jsdom v25.0.0 (nwsapi) happy-dom linkeDom patched-jsdom (dom-selector) Result
simple selector:
querySelectorAll('.content')		 3,145 ops/sec ±1.24% 7,471,952 ops/sec ±0.97% 1,187 ops/sec ±0.18% 3,330 ops/sec ±0.40% happydom is the fastest and 2244.1 times faster than patched-jsdom. patched-jsdom is 1.1 times faster than jsdom.
compound selector:
querySelectorAll('p.content[id]:is(:last-child, :only-child)')		 969 ops/sec ±1.23% 6,444,347 ops/sec ±0.86% 1,155 ops/sec ±1.22% 993 ops/sec ±0.21% happydom is the fastest and 6486.9 times faster than patched-jsdom. patched-jsdom is 1.0 times faster than jsdom.
complex selector:
querySelectorAll('.box:first-child ~ .box:nth-of-type(4n+1) + .box[id] .block.inner > .content')		 221 ops/sec ±1.66% F 418 ops/sec ±1.84% 905 ops/sec ±1.45% patched-jsdom is the fastest. patched-jsdom is 4.1 times faster than jsdom.
complex selector:
querySelectorAll('.box:first-child ~ .box:nth-of-type(4n+1) + .box[id] .block.inner:has(> .content)')		 F F 454 ops/sec ±0.15% 567 ops/sec ±1.60% patched-jsdom is the fastest.
complex selector within logical pseudo-class:
querySelectorAll(':is(.box > .content, .block > .content)')		 295 ops/sec ±1.89% F 515 ops/sec ±1.81% 790 ops/sec ±1.60% patched-jsdom is the fastest. patched-jsdom is 2.7 times faster than jsdom.

Acknowledgments

The following resources have been of great help in the development of the DOM Selector.

Copyright (c) 2023 asamuzaK (Kazz)

About

A CSS selector engine.

Resources

Readme

License

MIT license
Activity

Stars

7 stars

Watchers

2 watching

Forks

0 forks
Report repository

Releases 164

v6.1.1 Latest
Sep 16, 2024
+ 163 releases

Sponsor this project

Languages