DOM Selector

A CSS selector engine built for strict specification compliance.

Features

• Strict Specification Compliance: Strictly adheres to modern web standards. It accurately parses, evaluates, and extracts elements across complex combinations of pseudo-classes and HTML attributes. Features comprehensive support for CSS Selectors Level 4 (e.g., :is(), :not(), :where(), :has()) and Shadow DOM pseudo-classes (:host, :host-context).
• Utility Functions: Provides utility methods alongside standard querying, such as check() for AST evaluation and extractSubjects() for extracting subject keys from selectors.
• jsdom's Default Engine: Adopted as the CSS selector engine for jsdom.

Install

npm i @asamuzakjp/dom-selector

Usage

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

const { window } = new JSDOM();

// Destructuring methods (all methods are bound to the instance)
const {
  check, closest, extractSubjects, matches, querySelector, querySelectorAll, supports
} = new DOMSelector(window);

API

new DOMSelector(window, document?, opt?)

Creates an instance of the DOMSelector.

• window {Window} The window object.
• document {Document}? The document object. Defaults to window.document.
• opt {object}? Options:
  • opt.cacheSize {number}? Maximum number of items to store in the internal LRU cache. Defaults to 4096. This applies to every internal cache, including the per-document cache that pairs parsed selectors with a document, so that repeatedly querying distinct selectors on a live document does not grow its cache without limits.
  • opt.idlUtils {object}? The internal IDL wrapper used for jsdom.
  • opt.maxLength {number}? The maximum length of the selector allowed. Defaults to 2048.

matches(selector, node, opt?)

Equivalent to Element.matches().

• selector {string} CSS selector.
• node {Element} Element node.
• opt {object}? Options:
  • opt.noexcept {boolean}? true to suppress exceptions (e.g., DOMException for invalid selectors) and return false instead.
  • opt.warn {boolean}? true to output warnings to the console when encountering unsupported or deprecated features.
• Returns {boolean} true if matched, false otherwise.

closest(selector, node, opt?)

Equivalent to Element.closest().

• selector {string} CSS selector.
• node {Element} Element node.
• opt {object}? Options:
  • opt.noexcept {boolean}? true to suppress exceptions and return null instead.
  • opt.warn {boolean}? true to output warnings to the console when encountering unsupported or deprecated features.
• Returns {Element | null} The matched ancestor node or null.

querySelector(selector, node, opt?)

Equivalent to Document.querySelector(), DocumentFragment.querySelector() and Element.querySelector().

• selector {string} CSS selector.
• node {Document | DocumentFragment | Element} Node to find within.
• opt {object}? Options:
  • opt.noexcept {boolean}? true to suppress exceptions and return null instead.
  • opt.warn {boolean}? true to output warnings to the console when encountering unsupported or deprecated features.
• Returns {Element | null} The matched node or null.

querySelectorAll(selector, node, opt?)

Equivalent to Document.querySelectorAll(), DocumentFragment.querySelectorAll() and Element.querySelectorAll(). NOTE: Returns a standard Array<Element>, not a NodeList.

• selector {string} CSS selector.
• node {Document | DocumentFragment | Element} Node to find within.
• opt {object}? Options:
  • opt.noexcept {boolean}? true to suppress exceptions and return an empty array [] instead.
  • opt.warn {boolean}? true to output warnings to the console when encountering unsupported or deprecated features.
• Returns {Array} Array of matched elements.

check(selector, node, opt?)

Checks if an element matches a CSS selector and returns additional abstract syntax tree (AST) information. NOTE: Any pseudo-elements in the selector are excluded from the matching evaluation.

• selector {string} CSS selector.
• node {Element} Element node.
• opt {object}? Options:
  • opt.requireAst {boolean}? Indicates whether to always try to parse and return the AST.
  • opt.noexcept {boolean}? true to suppress exceptions and store the error in the error property of the result instead of throwing.
  • opt.warn {boolean}? true to output warnings to the console when encountering unsupported or deprecated features.
• Returns {CheckResult} An object containing the following properties:
  • match {boolean} true if the element matches the selector, false otherwise.
  • pseudoElement {string | null} The pseudo-element extracted from the selector, if any.
  • ast {object | null} The parsed AST object.
  • error {DOMException | Error | null} The error object, if any.

extractSubjects(selector, caseSensitive?)

Parses a selector and extracts the rightmost subject keys (Id, Class, Tag).

• selector {string} CSS selector.
• caseSensitive {boolean}? true if the tag key should be case sensitive. Defaults to false.
• Returns {Array} An array of extracted subject keys. Each object contains:
  • id {string | null} The ID.
  • className {string | null} The class name.
  • tag {string | null} The tag name.

supports(selector)

Checks if the given CSS selector is supported by this engine. See the table below for the full list of supported selectors.

• selector {string} CSS selector.
• Returns {boolean} true if the selector is supported, false otherwise.

clear(clearAll?)

Clears the internal caches to free up memory.

• clearAll {boolean}? Whether to clear all caches. If false, only cached matching results are cleared. Defaults to false.
• Returns {void}

Supported CSS selectors

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

• CSSTree
• selery
• jsdom
• nwsapi

Copyright (c) 2023 asamuzaK (Kazz)