@asamuzakjp/dom-selector 7.0.9 → 7.1.0

package/package.json

@@ -24,6 +24,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@asamuzakjp/generational-cache": "^1.0.1",
     "@asamuzakjp/nwsapi": "^2.3.9",
     "bidi-js": "^1.0.3",
     "css-tree": "^3.2.1",
@@ -31,7 +32,7 @@
   },
   "devDependencies": {
     "@types/css-tree": "^2.3.11",
-    "@types/node": "^25.5.2",
+    "@types/node": "^25.6.0",
     "benchmark": "^2.1.4",
     "c8": "^11.0.0",
     "chai": "^6.2.2",
@@ -42,13 +43,14 @@
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-regexp": "^3.1.0",
     "eslint-plugin-unicorn": "^64.0.0",
-    "globals": "^17.4.0",
+    "globals": "^17.5.0",
     "jsdom": "^29.0.2",
+    "mitata": "^1.0.34",
     "mocha": "^11.7.5",
     "neostandard": "^0.13.0",
-    "prettier": "^3.8.1",
-    "sinon": "^21.0.3",
-    "typescript": "^6.0.2",
+    "prettier": "^3.8.3",
+    "sinon": "^21.1.2",
+    "typescript": "^6.0.3",
     "wpt-runner": "^7.0.0"
   },
   "overrides": {
@@ -60,10 +62,12 @@
   },
   "scripts": {
     "bench": "node benchmark/bench.js",
+    "bench:cache": "node benchmark/bench-cache.js",
+    "bench:cacheMonster": "node benchmark/bench-cache-monster.js",
     "bench:sizzle": "node benchmark/bench-sizzle.js",
     "build": "npm run tsc && npm run lint && npm test",
     "lint": "eslint --fix .",
-    "test": "c8 --reporter=text mocha --parallel --exit test/**/*.test.js",
+    "test": "c8 --reporter=text mocha --exit test/**/*.test.js",
     "test:wpt": "node test/wpt/wpt-runner.js",
     "tsc": "node scripts/index clean --dir=types -i && npx tsc",
     "update:wpt": "git submodule update --init --recursive --remote"
@@ -71,5 +75,5 @@
   "engines": {
     "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
   },
-  "version": "7.0.9"
+  "version": "7.1.0"
 }

package/src/index.js

@@ -6,8 +6,9 @@
  */
 
 /* import */
-import { GenerationalCache } from './js/cache.js';
+import { GenerationalCache } from '@asamuzakjp/generational-cache';
 import { Finder } from './js/finder.js';
+import { unescapeSelector, parseAstName } from './js/parser.js';
 import { filterSelector, getType, initNwsapi } from './js/utility.js';
 
 /* constants */
@@ -18,9 +19,13 @@ import {
   TARGET_ALL,
   TARGET_FIRST,
   TARGET_LINEAL,
-  TARGET_SELF
+  TARGET_SELF,
+  COMBINATOR,
+  ID_SELECTOR,
+  CLASS_SELECTOR,
+  TYPE_SELECTOR
 } from './js/constant.js';
-const MAX_CACHE = 1024;
+const CACHE_SIZE = 2048;
 
 /**
  * @typedef {object} CheckResult
@@ -46,13 +51,13 @@ export class DOMSelector {
    * @param {object} [opt] - Options.
    */
   constructor(window, document, opt = {}) {
-    const { idlUtils } = opt;
+    const { cacheSize, idlUtils } = opt;
     this.#window = window;
     this.#document = document ?? window.document;
     this.#finder = new Finder(window);
     this.#idlUtils = idlUtils;
     this.#nwsapi = initNwsapi(window, document);
-    this.#cache = new GenerationalCache(MAX_CACHE);
+    this.#cache = new GenerationalCache(cacheSize ?? CACHE_SIZE);
   }
 
   /**
@@ -63,6 +68,59 @@ export class DOMSelector {
     this.#finder.clearResults(true);
   };
 
+  /**
+   * Parses a selector and extracts the rightmost subject keys (Id, Class, Tag).
+   * @param {string} selector - The CSS selector to parse.
+   * @returns {Array<{id: string|null, className: string|null, tag: string|null}>} The list of extracted keys for each selector group.
+   */
+  extractSubjects = selector => {
+    if (!selector || typeof selector !== 'string') {
+      return [{ id: null, className: null, tag: null }];
+    }
+    const cacheKey = `extract_${selector}`;
+    let subjects = this.#cache.get(cacheKey);
+    if (subjects !== undefined) {
+      return subjects;
+    }
+    subjects = [];
+    try {
+      const ast = this.#finder.getAST(selector);
+      if (ast?.type === 'SelectorList') {
+        for (const selectorNode of ast.children) {
+          let idKey = null;
+          let classKey = null;
+          let tagKey = null;
+          let current = selectorNode.children.tail;
+          while (current) {
+            const node = current.data;
+            if (node.type === COMBINATOR) {
+              break;
+            }
+            if (node.type === ID_SELECTOR) {
+              idKey = idKey ?? unescapeSelector(node.name);
+            } else if (node.type === CLASS_SELECTOR) {
+              classKey = classKey ?? unescapeSelector(node.name);
+            } else if (node.type === TYPE_SELECTOR) {
+              const { localName } = parseAstName(unescapeSelector(node.name));
+              if (localName !== '*') {
+                tagKey = tagKey ?? localName.toLowerCase();
+              }
+            }
+            current = current.prev;
+          }
+          subjects.push({ id: idKey, className: classKey, tag: tagKey });
+        }
+      }
+    } catch (e) {
+      // fall through
+    }
+    if (!subjects.length) {
+      subjects.push({ id: null, className: null, tag: null });
+    }
+    this.#cache.set(cacheKey, subjects);
+    return subjects;
+  };
+
   /**
    * Checks if an element matches a CSS selector.
    * @param {string} selector - The CSS selector to check against.

package/src/js/matcher.js

@@ -443,16 +443,19 @@ export const matchAttributeSelector = (ast, node, opt = {}) => {
   const { name: astIdentValue, value: astStringValue } = astValue ?? {};
   let attrValue;
   if (astIdentValue) {
+    // Ident values are not unescaped by css-tree, so we must unescape them
+    // (e.g. `\5c` hex escapes, `\n` character escapes).
     if (caseInsensitive) {
-      attrValue = astIdentValue.toLowerCase().replace(/\\(?!\\)/g, '');
+      attrValue = unescapeSelector(astIdentValue).toLowerCase();
     } else {
-      attrValue = astIdentValue.replace(/\\(?!\\)/g, '');
+      attrValue = unescapeSelector(astIdentValue);
     }
   } else if (astStringValue) {
+    // String values (quoted) are already unescaped by css-tree, so use as-is.
     if (caseInsensitive) {
-      attrValue = astStringValue.toLowerCase().replace(/\\(?!\\)/g, '');
+      attrValue = astStringValue.toLowerCase();
     } else {
-      attrValue = astStringValue.replace(/\\(?!\\)/g, '');
+      attrValue = astStringValue;
     }
   } else if (astStringValue === '') {
     attrValue = astStringValue;

package/src/js/parser.js

@@ -72,6 +72,13 @@ export const unescapeSelector = (selector = '') => {
       const item = arr[i];
       if (item === '' && i === l - 1) {
         selectorItems.push(U_FFFD);
+      } else if (item === '') {
+        // Empty segment at non-last position means \\ (escaped backslash)
+        selectorItems.push('\\');
+        i++; // skip the next segment which is the remainder after \\
+        if (i < l) {
+          selectorItems.push(arr[i]);
+        }
       } else {
         const hexExists = /^([\da-f]{1,6}\s?)/i.exec(item);
         if (hexExists) {

package/src/js/utility.js

@@ -1047,6 +1047,7 @@ export const initNwsapi = (window, document) => {
  */
 export const filterSelector = (selector, target) => {
   const isQuerySelectorAll = target === TARGET_ALL;
+  // Basic validation and fast-fail for null/undefined/non-string values
   if (
     !selector ||
     typeof selector !== 'string' ||
@@ -1054,59 +1055,54 @@ export const filterSelector = (selector, target) => {
   ) {
     return false;
   }
-  // Exclude missing close square bracket.
+  // Exclude various complex or unsupported selectors early
+  // i.e. non-ASCII, escaped selectors, namespaced selectors and pseudo-elements
+  if (selector.includes('/') || REG_EXCLUDE_BASIC.test(selector)) {
+    return false;
+  }
+  // Validate attribute selector integrity
   if (selector.includes('[')) {
     const index = selector.lastIndexOf('[');
-    const sel = selector.substring(index);
-    if (sel.indexOf(']') < 0) {
+    if (selector.indexOf(']', index) === -1) {
       return false;
     }
   }
-  // Match only simple attribute selector for TARGET_FIRST.
+  // Target-specific early exits
   if (target === TARGET_FIRST) {
-    if (REG_ATTR_SIMPLE.test(selector)) {
-      return true;
-    }
-    return false;
+    return REG_ATTR_SIMPLE.test(selector);
   }
-
-  // Exclude simple tag selector for TARGET_ALL
   if (target === TARGET_ALL && REG_TAG_SIMPLE.test(selector)) {
     return false;
   }
-
-  // Exclude various complex or unsupported selectors.
-  // - selectors containing '/'
-  // - namespaced selectors
-  // - escaped selectors
-  // - pseudo-element selectors
-  // - selectors containing non-ASCII
-  // - selectors containing control character other than whitespace
-  // - attribute selectors with case flag, e.g. [attr i]
-  // - attribute selectors with unclosed quotes
-  // - empty :is() or :where()
-  if (selector.includes('/') || REG_EXCLUDE_BASIC.test(selector)) {
-    return false;
-  }
-  // Include pseudo-classes that are known to work correctly.
+  // Logic for pseudo-classes
   if (selector.includes(':')) {
+    // Exclude descendant combinators in logical selectors for querySelectorAll
     if (isQuerySelectorAll && REG_DESCEND.test(selector)) {
       return false;
     }
-    const complex = isQuerySelectorAll ? false : REG_COMPLEX.test(selector);
-    if (!isQuerySelectorAll && /:has\(/.test(selector)) {
-      if (!complex || REG_LOGIC_HAS_COMPOUND.test(selector)) {
+    // Determine if the selector has complex logical structures
+    const isComplex = isQuerySelectorAll ? false : REG_COMPLEX.test(selector);
+    // Handle :has() specifically
+    if (selector.includes(':has(')) {
+      if (isQuerySelectorAll) {
+        return false;
+      }
+      if (!isComplex || REG_LOGIC_HAS_COMPOUND.test(selector)) {
         return false;
       }
       return REG_END_WITH_HAS.test(selector);
-    } else if (/:(?:is|not)\(/.test(selector)) {
-      if (complex) {
+    }
+    // Handle :is() and :not()
+    if (/(?:is|not)\(/.test(selector)) {
+      if (isComplex) {
         return !REG_LOGIC_COMPLEX.test(selector);
       } else {
         return !REG_LOGIC_COMPOUND.test(selector);
       }
-    } else {
-      return !REG_WO_LOGICAL.test(selector);
+    }
+    // Default check for other pseudo-classes against known list
+    if (REG_WO_LOGICAL.test(selector)) {
+      return false;
     }
   }
   return true;

package/types/index.d.ts

@@ -1,6 +1,11 @@
 export class DOMSelector {
     constructor(window: Window, document: Document, opt?: object);
     clear: () => void;
+    extractSubjects: (selector: string) => Array<{
+        id: string | null;
+        className: string | null;
+        tag: string | null;
+    }>;
     check: (selector: string, node: Element, opt?: object) => CheckResult;
     matches: (selector: string, node: Element, opt?: object) => boolean;
     closest: (selector: string, node: Element, opt?: object) => Element | null;

package/src/js/cache.js

@@ -1,77 +0,0 @@
-/**
- * cache.js
- */
-
-/* Generational Cache */
-export class GenerationalCache {
-  #max;
-  #boundary;
-  #current;
-  #old;
-
-  /**
-   * constructor
-   * @param {number} max - max cache size
-   */
-  constructor(max) {
-    this.#current = new Map();
-    this.#old = new Map();
-    this.max = max;
-  }
-
-  get size() {
-    return this.#current.size + this.#old.size;
-  }
-
-  /**
-   * @returns {number} max cache size
-   */
-  get max() {
-    return this.#max;
-  }
-
-  set max(value) {
-    if (Number.isFinite(value) && value > 4) {
-      this.#max = value;
-      this.#boundary = Math.ceil(value / 2);
-    } else {
-      this.#max = 4;
-      this.#boundary = 2;
-    }
-    this.clear();
-  }
-
-  get(key) {
-    if (this.#current.has(key)) {
-      return this.#current.get(key);
-    }
-    const value = this.#old.get(key);
-    if (value !== undefined) {
-      this.set(key, value);
-      return value;
-    }
-    return undefined;
-  }
-
-  set(key, value) {
-    this.#current.set(key, value);
-    if (this.#current.size >= this.#boundary) {
-      this.#old = this.#current;
-      this.#current = new Map();
-    }
-  }
-
-  has(key) {
-    return this.#current.has(key) || this.#old.has(key);
-  }
-
-  delete(key) {
-    this.#current.delete(key);
-    this.#old.delete(key);
-  }
-
-  clear() {
-    this.#current.clear();
-    this.#old.clear();
-  }
-}

package/types/js/cache.d.ts

@@ -1,12 +0,0 @@
-export class GenerationalCache {
-    constructor(max: number);
-    set max(value: number);
-    get max(): number;
-    get size(): number;
-    get(key: any): any;
-    set(key: any, value: any): void;
-    has(key: any): boolean;
-    delete(key: any): void;
-    clear(): void;
-    #private;
-}