A CSS selector engine.
npm i @asamuzakjp/dom-selector
import { DOMSelector } from '@asamuzakjp/dom-selector';
import { JSDOM } from 'jsdom';
const { window } = new JSDOM();
const {
closest, matches, querySelector, querySelectorAll
} = new DOMSelector(window);
matches - same functionality as Element.matches()
Returns boolean true
if matched, false
otherwise
closest - same functionality as Element.closest()
Returns object? matched node
querySelector - same functionality as Document.querySelector(), DocumentFragment.querySelector(), Element.querySelector()
-
selector
string CSS selector -
node
object Document, DocumentFragment or Element node -
opt
object? options
Returns object? matched node
querySelectorAll - same functionality as Document.querySelectorAll(), DocumentFragment.querySelectorAll(), Element.querySelectorAll()
NOTE: returns Array, not NodeList
-
selector
string CSS selector -
node
object Document, DocumentFragment or Element node -
opt
object? options
Returns Array<(object | undefined)> array of matched nodes
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) | Partially supported | Comma-separated list of language codes, e.g. :lang(en, fr) , is not yet supported. |
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 | ✓ | Enabled if a mousedown / pointerdown event is passed as an option. |
E:hover | ✓ | Enabled if a mouseover / pointerover event is passed as an option. |
E:focus | ✓ | |
E:focus‑within | ✓ | |
E:focus‑visible | ✓ | Enabled if a keydown event is passed as an option. |
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) | ✓ |
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);
};
}
});
See benchmark for the latest results.
F
: Failed because the selector is not supported or the result is incorrect.
Selector | jsdom v24.0.0 (nwsapi) | happy-dom | linkeDom | patched-jsdom (dom-selector) | Result |
---|---|---|---|---|---|
simple selector:matches('.content')
|
993,434 ops/sec ±0.92% | 7,738 ops/sec ±0.82% | 9,388 ops/sec ±0.63% | 934,402 ops/sec ±1.24% | jsdom is the fastest and 1.1 times faster than patched-jsdom. |
compound selector:matches('p.content[id]:is(:last-child, :only-child)')
|
593,746 ops/sec ±0.24% | 7,510 ops/sec ±0.73% | 9,048 ops/sec ±1.11% | 510,470 ops/sec ±0.17% | jsdom is the fastest and 1.2 times faster than patched-jsdom. |
compound selector:matches('p.content[id]:is(:invalid-nth-child, :only-child)')
|
F | 7,532 ops/sec ±0.64% | F | 148,751 ops/sec ±1.43% | patched-jsdom is the fastest. |
compound selector:matches('p.content[id]:not(:is(.foo, .bar))')
|
478,481 ops/sec ±0.32% | 7,437 ops/sec ±0.57% | 8,922 ops/sec ±0.47% | 406,300 ops/sec ±0.32% | 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 > .content')
|
151,608 ops/sec ±0.24% | F | 5,749 ops/sec ±0.57% | 136,036 ops/sec ±0.46% | jsdom is the fastest and 1.1 times faster than patched-jsdom. |
complex selector:matches('.box:first-child ~ .box:nth-of-type(4n+1) + .box .block.inner:has(> .content)')
|
F | F | 5,654 ops/sec ±0.57% | 40,774 ops/sec ±0.59% | patched-jsdom is the fastest. |
complex selector within logical pseudo-class:matches(':is(.box > .content, .block > .content)')
|
F | F | 6,243 ops/sec ±0.45% | 146,879 ops/sec ±1.92% | patched-jsdom is the fastest. |
Selector | jsdom v24.0.0 (nwsapi) | happy-dom | linkeDom | patched-jsdom (dom-selector) | Result |
---|---|---|---|---|---|
simple selector:closest('.container')
|
362,505 ops/sec ±0.41% | 7,607 ops/sec ±0.62% | 9,365 ops/sec ±0.59% | 362,275 ops/sec ±0.39% | jsdom is the fastest and 1.0 times faster than patched-jsdom. |
compound selector:closest('div.container[id]:not(.foo, .box)')
|
137,678 ops/sec ±0.32% | F | 8,749 ops/sec ±0.67% | 129,174 ops/sec ±0.30% | 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')
|
139,504 ops/sec ±0.43% | F | 5,774 ops/sec ±0.51% | 126,287 ops/sec ±0.32% | 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 .block.inner:has(> .content)')
|
F | F | 5,710 ops/sec ±0.36% | 29,552 ops/sec ±0.90% | patched-jsdom is the fastest. |
complex selector within logical pseudo-class:closest(':is(.container > .content, .container > .box)')
|
F | 4,754 ops/sec ±0.73% | 5,935 ops/sec ±0.32% | 64,421 ops/sec ±0.98% | patched-jsdom is the fastest. |
Selector | jsdom v24.0.0 (nwsapi) | happy-dom | linkeDom | patched-jsdom (dom-selector) | Result |
---|---|---|---|---|---|
simple selector:querySelector('.content')
|
28,406 ops/sec ±0.62% | 9,286 ops/sec ±0.63% | 10,750 ops/sec ±0.59% | 25,303 ops/sec ±1.00% | jsdom is the fastest and 1.1 times faster than patched-jsdom. |
compound selector:querySelector('p.content[id]:is(:last-child, :only-child)')
|
9,564 ops/sec ±0.33% | 8,884 ops/sec ±0.59% | 10,834 ops/sec ±0.60% | 8,809 ops/sec ±0.53% | linkedom is the fastest and 1.2 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')
|
228 ops/sec ±0.41% | F | 1,390 ops/sec ±0.61% | 713 ops/sec ±2.32% | linkedom is the fastest and 1.9 times faster than patched-jsdom. patched-jsdom is 3.1 times faster than jsdom. |
complex selector:querySelector('.box:first-child ~ .box:nth-of-type(4n+1) + .box .block.inner:has(> .content)')
|
F | F | 1,523 ops/sec ±1.72% | 494 ops/sec ±1.97% | linkedom is the fastest and 3.1 times faster than patched-jsdom. |
complex selector within logical pseudo-class:querySelector(':is(.box > .content, .block > .content)')
|
F | F | 9,987 ops/sec ±0.59% | 101,461 ops/sec ±1.56% | patched-jsdom is the fastest. |
Selector | jsdom v24.0.0 (nwsapi) | happy-dom | linkeDom | patched-jsdom (dom-selector) | Result |
---|---|---|---|---|---|
simple selector:querySelectorAll('.content')
|
2,713 ops/sec ±1.04% | 729 ops/sec ±0.29% | 1,187 ops/sec ±0.40% | 2,988 ops/sec ±0.19% | patched-jsdom is the fastest. patched-jsdom is 1.1 times faster than jsdom. |
compound selector:querySelectorAll('p.content[id]:is(:last-child, :only-child)')
|
946 ops/sec ±0.26% | 724 ops/sec ±0.35% | 1,194 ops/sec ±0.25% | 971 ops/sec ±0.25% | linkedom is the fastest and 1.2 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')
|
225 ops/sec ±1.41% | F | 416 ops/sec ±1.46% | 818 ops/sec ±1.67% | patched-jsdom is the fastest. patched-jsdom is 3.6 times faster than jsdom. |
complex selector:querySelectorAll('.box:first-child ~ .box:nth-of-type(4n+1) + .box .block.inner:has(> .content)')
|
F | F | 443 ops/sec ±1.47% | 530 ops/sec ±1.87% | patched-jsdom is the fastest. |
complex selector within logical pseudo-class:querySelectorAll(':is(.box > .content, .block > .content)')
|
F | F | 525 ops/sec ±0.27% | 255 ops/sec ±1.13% | linkedom is the fastest and 2.1 times faster than patched-jsdom. |
The following resources have been of great help in the development of the DOM Selector.
Copyright (c) 2023 asamuzaK (Kazz)