DOM Selector

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
*	✓
E	✓
ns\|E	✓
*\|E	✓
\|E	✓
E F	✓
E > F	✓
E + F	✓
E ~ F	✓
F \|\| E	Unsupported
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:is(s1, s2, …)	✓
E:not(s1, s2, …)	✓
E:where(s1, s2, …)	✓
E:has(rs1, rs2, …)	✓
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:hover	✓
E:active	✓
E:focus	✓
E:focus‑visible	✓
E:focus‑within	✓
E:current	Unsupported
E:current(s)	Unsupported
E:past	Unsupported
E:future	Unsupported
E:open E:closed	Partially supported	Matching with <select>, e.g. `select:open`, is not supported.
E:popover-open	Unsupported
E:enabled E:disabled	✓
E:read‑write E:read‑only	✓
E:placeholder‑shown	✓
E:default	✓
E:checked	✓
E:indeterminate	✓
E:blank	Unsupported
E:valid E:invalid	✓
E:in-range E:out-of-range	✓
E:required E:optional	✓
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:nth‑col(n)	Unsupported
E:nth‑last‑col(n)	Unsupported
CE:state(v)	✓	*1
:host	✓
:host(s)	✓
:host(:state(v))	✓	*1
:host:has(rs1, rs2, ...)	✓
:host(s):has(rs1, rs2, ...)	✓
:host‑context(s)	✓
:host‑context(s):has(rs1, rs2, ...)	✓
&	✓	Only supports outermost `&`, i.e. equivalent to `:scope`

*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.

Acknowledgments

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

Current Tags

0.2.2 ... beta (3 years ago)
6.5.0-a.16 ... dev (a year ago)
7.0.8 ... latest (3 days ago)
4.6.0-b.1 ... next (2 years ago)

244 Versions

7.0.8 ... 3 days ago
7.0.7 ... 4 days ago
7.0.6 ... 7 days ago
7.0.5 ... 7 days ago
7.0.4 ... 21 days ago
7.0.3 ... a month ago
7.0.2 ... a month ago
7.0.1 ... a month ago
7.0.0 ... 2 months ago
6.8.1 ... 2 months ago
6.8.0 ... 2 months ago
6.7.8 ... 2 months ago
6.7.7 ... 2 months ago
6.7.6 ... 4 months ago
6.7.5 ... 4 months ago
6.7.4 ... 5 months ago
6.7.3 ... 6 months ago
6.7.2 ... 6 months ago
6.7.0 ... 6 months ago
6.6.2 ... 6 months ago
6.6.1 ... 6 months ago
6.5.7 ... 6 months ago
6.5.6 ... 7 months ago
6.5.5 ... 7 months ago
6.5.4 ... 8 months ago
6.5.3 ... 9 months ago
6.5.2 ... 9 months ago
6.5.1 ... 9 months ago
6.5.0 ... a year ago
6.5.0-a.16 ... a year ago
6.5.0-a.15 ... a year ago
6.5.0-a.14 ... a year ago
6.5.0-a.13 ... a year ago
6.5.0-a.12 ... a year ago
6.5.0-a.11 ... a year ago
6.5.0-a.10 ... a year ago
6.5.0-a.9 ... a year ago
6.5.0-a.8 ... a year ago
6.5.0-a.7 ... a year ago
6.5.0-a.6 ... a year ago
6.5.0-a.5 ... a year ago
6.5.0-a.4 ... a year ago
6.5.0-a.3 ... a year ago
6.5.0-a.2 ... a year ago
6.5.0-a.1 ... a year ago
6.4.7 ... a year ago
6.4.6 ... a year ago
6.4.5 ... a year ago
6.4.4 ... a year ago
6.4.3 ... a year ago
6.4.2 ... a year ago
6.4.0 ... a year ago
6.3.7 ... a year ago
6.3.5 ... a year ago
6.3.4 ... a year ago
6.3.3 ... a year ago
6.3.2 ... a year ago
6.3.1 ... a year ago
6.3.0 ... a year ago
6.2.2 ... a year ago
6.2.1 ... a year ago
6.2.0 ... a year ago
6.1.1 ... 2 years ago
6.1.0 ... 2 years ago
6.0.5 ... 2 years ago
6.0.4 ... 2 years ago
6.0.3 ... 2 years ago
6.0.2 ... 2 years ago
6.0.1 ... 2 years ago
6.0.0 ... 2 years ago
5.4.0 ... 2 years ago
5.3.4 ... 2 years ago
5.3.3 ... 2 years ago
5.3.2 ... 2 years ago
5.3.1 ... 2 years ago
5.3.0 ... 2 years ago
5.2.2 ... 2 years ago
5.2.1 ... 2 years ago
5.2.0 ... 2 years ago
5.1.0 ... 2 years ago
5.0.9 ... 2 years ago
5.0.8 ... 2 years ago
5.0.7 ... 2 years ago
5.0.5 ... 2 years ago
5.0.4 ... 2 years ago
5.0.3 ... 2 years ago
5.0.2 ... 2 years ago
5.0.1 ... 2 years ago
5.0.0 ... 2 years ago
4.6.5 ... 2 years ago
4.6.4 ... 2 years ago
4.6.3 ... 2 years ago
4.6.1 ... 2 years ago
4.6.0 ... 2 years ago
4.6.0-b.1 ... 2 years ago
4.5.0 ... 2 years ago
4.5.0-b.7 ... 2 years ago
4.5.0-b.6 ... 2 years ago
4.5.0-b.5 ... 2 years ago
4.5.0-b.4 ... 2 years ago
4.5.0-b.3 ... 2 years ago
4.5.0-b.2 ... 2 years ago
4.5.0-b.1 ... 2 years ago
4.4.13 ... 2 years ago
4.4.12 ... 2 years ago
4.4.11 ... 2 years ago
4.4.10 ... 2 years ago
4.4.9 ... 2 years ago
4.4.8 ... 2 years ago
4.4.7 ... 2 years ago
4.4.6 ... 2 years ago
4.4.5 ... 2 years ago
4.4.4 ... 2 years ago
4.4.3 ... 2 years ago
4.4.2 ... 2 years ago
4.4.1 ... 2 years ago
4.4.0 ... 2 years ago
4.3.0 ... 2 years ago
4.2.2 ... 2 years ago
4.2.1 ... 2 years ago
4.2.0 ... 2 years ago
4.1.7 ... 2 years ago
4.1.6 ... 2 years ago
4.1.5 ... 2 years ago
4.1.4 ... 2 years ago
4.1.3 ... 2 years ago
4.1.2 ... 2 years ago
4.1.1 ... 2 years ago
4.1.0 ... 2 years ago
4.0.1 ... 2 years ago
4.0.0 ... 2 years ago
3.0.5 ... 2 years ago
3.0.4 ... 2 years ago
3.0.3 ... 2 years ago
3.0.2 ... 2 years ago
3.0.1 ... 2 years ago
2.1.0-b.4 ... 2 years ago
2.1.0-b.3 ... 2 years ago
2.1.0-b.2 ... 2 years ago
2.1.0-b.1 ... 2 years ago
2.0.3-a.8 ... 2 years ago
2.0.3-a.7 ... 2 years ago
2.0.3-a.6 ... 2 years ago
2.0.3-a.5 ... 2 years ago
2.0.3-a.4 ... 2 years ago
2.0.3-a.3 ... 2 years ago
2.0.3-a.2 ... 2 years ago
2.0.3-a.1 ... 2 years ago
2.0.2 ... 2 years ago
2.0.2-a.3 ... 2 years ago
2.0.2-a.2 ... 2 years ago
2.0.2-a.1 ... 2 years ago
2.0.1 ... 2 years ago
2.0.0 ... 2 years ago
1.2.8 ... 2 years ago
1.2.7 ... 2 years ago
1.2.6 ... 2 years ago
1.2.5 ... 2 years ago
1.2.4 ... 2 years ago
1.2.3 ... 2 years ago
1.2.2 ... 2 years ago
1.2.1 ... 2 years ago
1.2.0 ... 2 years ago
1.1.14 ... 2 years ago
1.1.13 ... 2 years ago
1.1.12 ... 2 years ago
1.1.11 ... 2 years ago
1.1.10 ... 2 years ago
1.1.9 ... 2 years ago
1.1.8 ... 2 years ago
1.1.6 ... 2 years ago
1.1.5 ... 2 years ago
1.1.4 ... 2 years ago
1.1.3 ... 2 years ago
1.1.2 ... 2 years ago
1.1.1 ... 2 years ago
1.1.0 ... 2 years ago
1.0.5 ... 2 years ago
1.0.4 ... 2 years ago
1.0.3 ... 2 years ago
1.0.2 ... 2 years ago
1.0.1 ... 2 years ago
1.0.0 ... 2 years ago
0.24.0 ... 2 years ago
0.23.2 ... 2 years ago
0.22.0 ... 2 years ago
0.21.2 ... 2 years ago
0.21.1 ... 2 years ago
0.21.0 ... 2 years ago
0.20.2 ... 2 years ago
0.20.1 ... 2 years ago
0.20.0 ... 2 years ago
0.19.6 ... 3 years ago
0.19.5 ... 3 years ago
0.19.4 ... 3 years ago
0.19.3 ... 3 years ago
0.19.2 ... 3 years ago
0.19.1 ... 3 years ago
0.18.1 ... 3 years ago
0.18.0 ... 3 years ago
0.17.0 ... 3 years ago
0.16.4 ... 3 years ago
0.16.3 ... 3 years ago
0.16.2 ... 3 years ago
0.16.1 ... 3 years ago
0.16.0 ... 3 years ago
0.15.13 ... 3 years ago
0.15.12 ... 3 years ago
0.15.10 ... 3 years ago
0.15.9 ... 3 years ago
0.15.8 ... 3 years ago
0.15.7 ... 3 years ago
0.15.6 ... 3 years ago
0.15.5 ... 3 years ago
0.15.4 ... 3 years ago
0.15.3 ... 3 years ago
0.15.1 ... 3 years ago
0.14.0 ... 3 years ago
0.13.5 ... 3 years ago
0.13.2 ... 3 years ago
0.13.1 ... 3 years ago
0.12.8 ... 3 years ago
0.12.7 ... 3 years ago
0.12.6 ... 3 years ago
0.12.5 ... 3 years ago
0.12.3 ... 3 years ago
0.12.2 ... 3 years ago
0.12.1 ... 3 years ago
0.12.0 ... 3 years ago
0.11.1 ... 3 years ago
0.10.0 ... 3 years ago
0.9.2 ... 3 years ago
0.8.1 ... 3 years ago
0.8.0 ... 3 years ago
0.7.0 ... 3 years ago
0.6.2 ... 3 years ago
0.6.1 ... 3 years ago
0.6.0 ... 3 years ago
0.5.0 ... 3 years ago
0.4.2 ... 3 years ago
0.4.1 ... 3 years ago
0.3.0 ... 3 years ago
0.2.2 ... 3 years ago
0.2.1 ... 3 years ago