@asamuzakjp/dom-selector 0.18.1 → 0.19.2

package/README.md

@@ -8,7 +8,7 @@
 [![release](https://img.shields.io/github/v/release/asamuzaK/domSelector)](https://github.com/asamuzaK/domSelector/releases)
 -->
 
-Retrieve DOM node from the given CSS selector.
+Retrieve DOM node from the given CSS selector.  
 **Experimental**
 
 ## Install
@@ -20,9 +20,9 @@ npm i @asamuzakjp/dom-selector
 ## Usage
 
 ```javascript
-const {
+import {
   matches, closest, querySelector, querySelectorAll
-} = require('@asamuzakjp/dom-selector');
+} from '@asamuzakjp/dom-selector';
 ```
 
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
@@ -38,7 +38,7 @@ matches - same functionality as [Element.matches()][64]
 - `opt` **[object][60]?** options
   - `opt.warn` **[boolean][61]?** console warn e.g. unsupported pseudo-class
 
-Returns **[boolean][61]** result
+Returns **[boolean][61]** `true` if matched, `false` otherwise
 
 
 ### closest(selector, node, opt)
@@ -71,7 +71,7 @@ Returns **[object][60]?** matched node
 
 ### querySelectorAll(selector, refPoint, opt)
 
-querySelectorAll - same functionality as [Document.querySelectorAll()][69], [DocumentFragment.querySelectorAll()][70], [Element.querySelectorAll()][71]
+querySelectorAll - same functionality as [Document.querySelectorAll()][69], [DocumentFragment.querySelectorAll()][70], [Element.querySelectorAll()][71]  
 **NOTE**: returns Array, not NodeList
 
 #### Parameters
@@ -79,6 +79,7 @@ querySelectorAll - same functionality as [Document.querySelectorAll()][69], [Doc
 - `selector` **[string][59]** CSS selector
 - `refPoint` **[object][60]** Document, DocumentFragment or Element node
 - `opt` **[object][60]?** options
+  - `opt.sort` **[boolean][61]?** sort matched nodes
   - `opt.warn` **[boolean][61]?** console warn e.g. unsupported pseudo-class
 
 Returns **[Array][62]&lt;([object][60] \| [undefined][63])>** array of matched nodes

package/package.json

@@ -16,10 +16,10 @@
     "types"
   ],
   "main": "src/index.js",
+  "type": "module",
   "types": "types/index.d.ts",
   "dependencies": {
     "css-tree": "^2.3.1",
-    "domexception": "^4.0.0",
     "is-potential-custom-element-name": "^1.0.1"
   },
   "devDependencies": {
@@ -29,7 +29,7 @@
     "chai": "^4.3.7",
     "eslint": "^8.43.0",
     "eslint-config-standard": "^17.1.0",
-    "eslint-plugin-jsdoc": "^46.2.6",
+    "eslint-plugin-jsdoc": "^46.3.0",
     "eslint-plugin-regexp": "^1.15.0",
     "eslint-plugin-unicorn": "^47.0.0",
     "jsdom": "^22.1.0",
@@ -46,5 +46,5 @@
     "test": "c8 --reporter=text mocha --exit test/**/*.test.js",
     "tsc": "npx tsc"
   },
-  "version": "0.18.1"
+  "version": "0.19.2"
 }

package/src/index.js

@@ -4,67 +4,52 @@
  * @copyright asamuzaK (Kazz)
  * @see {@link https://github.com/asamuzaK/domSelector/blob/main/LICENSE}
  */
-'use strict';
 
 /* import */
-const { Matcher } = require('./js/matcher.js');
+import { Matcher } from './js/matcher.js';
 
 /**
- * matches - Element.matches()
+ * matches
  * @param {string} selector - CSS selector
  * @param {object} node - Element node
  * @param {object} [opt] - options
- * @param {object} [opt.warn] - console warn e.g. unsupported pseudo-class
- * @returns {boolean} - result
+ * @param {boolean} [opt.warn] - console warn e.g. unsupported pseudo-class
+ * @returns {boolean} - `true` if matched `false` otherwise
  */
-const matches = (selector, node, opt) => {
-  const matcher = new Matcher(selector, node, opt);
-  return matcher.matches();
-};
+export const matches = (selector, node, opt) =>
+  new Matcher(selector, node, opt).matches();
 
 /**
- * closest - Element.closest()
+ * closest
  * @param {string} selector - CSS selector
  * @param {object} node - Element node
  * @param {object} [opt] - options
- * @param {object} [opt.warn] - console warn e.g. unsupported pseudo-class
+ * @param {boolean} [opt.warn] - console warn e.g. unsupported pseudo-class
  * @returns {?object} - matched node
  */
-const closest = (selector, node, opt) => {
-  const matcher = new Matcher(selector, node, opt);
-  return matcher.closest();
-};
+export const closest = (selector, node, opt) =>
+  new Matcher(selector, node, opt).closest();
 
 /**
- * querySelector - Document.querySelector(), Element.querySelector()
+ * querySelector
  * @param {string} selector - CSS selector
- * @param {object} refPoint - Document or Element node
+ * @param {object} refPoint - Document, DocumentFragment or Element node
  * @param {object} [opt] - options
- * @param {object} [opt.warn] - console warn e.g. unsupported pseudo-class
+ * @param {boolean} [opt.warn] - console warn e.g. unsupported pseudo-class
  * @returns {?object} - matched node
  */
-const querySelector = (selector, refPoint, opt) => {
-  const matcher = new Matcher(selector, refPoint, opt);
-  return matcher.querySelector();
-};
+export const querySelector = (selector, refPoint, opt) =>
+  new Matcher(selector, refPoint, opt).querySelector();
 
 /**
- * querySelectorAll - Document.querySelectorAll(), Element.querySelectorAll()
+ * querySelectorAll
  * NOTE: returns Array, not NodeList
  * @param {string} selector - CSS selector
- * @param {object} refPoint - Document or Element node
+ * @param {object} refPoint - Document, DocumentFragment or Element node
  * @param {object} [opt] - options
- * @param {object} [opt.warn] - console warn e.g. unsupported pseudo-class
+ * @param {boolean} [opt.sort] - sort matched nodes
+ * @param {boolean} [opt.warn] - console warn e.g. unsupported pseudo-class
  * @returns {Array.<object|undefined>} - array of matched nodes
  */
-const querySelectorAll = (selector, refPoint, opt) => {
-  const matcher = new Matcher(selector, refPoint, opt);
-  return matcher.querySelectorAll();
-};
-
-module.exports = {
-  closest,
-  matches,
-  querySelector,
-  querySelectorAll
-};
+export const querySelectorAll = (selector, refPoint, opt) =>
+  new Matcher(selector, refPoint, opt).querySelectorAll();

package/src/js/constant.js

@@ -1,36 +1,18 @@
 /**
  * constant.js
  */
-'use strict';
 
-const AN_PLUS_B = 'AnPlusB';
-const ATTRIBUTE_SELECTOR = 'AttributeSelector';
-const CLASS_SELECTOR = 'ClassSelector';
-const COMBINATOR = 'Combinator';
-const ID_SELECTOR = 'IdSelector';
-const IDENTIFIER = 'Identifier';
-const NTH = 'Nth';
-const PSEUDO_CLASS_SELECTOR = 'PseudoClassSelector';
-const PSEUDO_ELEMENT_SELECTOR = 'PseudoElementSelector';
-const RAW = 'Raw';
-const SELECTOR = 'Selector';
-const SELECTOR_LIST = 'SelectorList';
-const STRING = 'String';
-const TYPE_SELECTOR = 'TypeSelector';
-
-module.exports = {
-  AN_PLUS_B,
-  ATTRIBUTE_SELECTOR,
-  CLASS_SELECTOR,
-  COMBINATOR,
-  ID_SELECTOR,
-  IDENTIFIER,
-  NTH,
-  PSEUDO_CLASS_SELECTOR,
-  PSEUDO_ELEMENT_SELECTOR,
-  RAW,
-  SELECTOR,
-  SELECTOR_LIST,
-  STRING,
-  TYPE_SELECTOR
-};
+export const AN_PLUS_B = 'AnPlusB';
+export const ATTRIBUTE_SELECTOR = 'AttributeSelector';
+export const CLASS_SELECTOR = 'ClassSelector';
+export const COMBINATOR = 'Combinator';
+export const ID_SELECTOR = 'IdSelector';
+export const IDENTIFIER = 'Identifier';
+export const NTH = 'Nth';
+export const PSEUDO_CLASS_SELECTOR = 'PseudoClassSelector';
+export const PSEUDO_ELEMENT_SELECTOR = 'PseudoElementSelector';
+export const RAW = 'Raw';
+export const SELECTOR = 'Selector';
+export const SELECTOR_LIST = 'SelectorList';
+export const STRING = 'String';
+export const TYPE_SELECTOR = 'TypeSelector';

package/src/js/matcher.js

@@ -1,18 +1,16 @@
 /**
  * matcher.js
  */
-'use strict';
 
 /* import */
-const isCustomElementName = require('is-potential-custom-element-name');
-const DOMException = require('./domexception.js');
-const { generateCSS, parseSelector, walkAST } = require('./parser.js');
+import isCustomElementName from 'is-potential-custom-element-name';
+import { generateCSS, parseSelector, walkAST } from './parser.js';
 
 /* constants */
-const {
+import {
   ATTRIBUTE_SELECTOR, CLASS_SELECTOR, COMBINATOR, ID_SELECTOR,
   PSEUDO_CLASS_SELECTOR, PSEUDO_ELEMENT_SELECTOR, TYPE_SELECTOR
-} = require('./constant.js');
+} from './constant.js';
 const BIT_ATTRIBUTE_SELECTOR = 16;
 const BIT_CLASS_SELECTOR = 2;
 const BIT_ID_SELECTOR = 4;
@@ -46,7 +44,7 @@ const WHITESPACE = /^[\n\r\f]/;
  * @param {object} node - Element
  * @returns {boolean} - result
  */
-const isContentEditable = (node = {}) => {
+export const isContentEditable = (node = {}) => {
   let res;
   if (node.nodeType === ELEMENT_NODE) {
     if (node.ownerDocument.designMode === 'on') {
@@ -76,7 +74,7 @@ const isContentEditable = (node = {}) => {
  * @param {object} node - Element node
  * @returns {boolean} - result
  */
-const isNamespaceDeclared = (ns = '', node = {}) => {
+export const isNamespaceDeclared = (ns = '', node = {}) => {
   let res;
   if (ns && typeof ns === 'string' && node.nodeType === ELEMENT_NODE) {
     const attr = `xmlns:${ns}`;
@@ -102,7 +100,7 @@ const isNamespaceDeclared = (ns = '', node = {}) => {
  * @param {object} root - Document, DocumentFragment, Element node
  * @returns {boolean} - result
  */
-const isDescendant = (node = {}, root = {}) => {
+export const isDescendant = (node = {}, root = {}) => {
   const { nodeType, ownerDocument } = node;
   let res;
   if (nodeType === ELEMENT_NODE && ownerDocument) {
@@ -123,7 +121,7 @@ const isDescendant = (node = {}, root = {}) => {
  * @param {string} selector - CSS selector
  * @returns {?string} - unescaped selector
  */
-const unescapeSelector = (selector = '') => {
+export const unescapeSelector = (selector = '') => {
   if (typeof selector === 'string' && selector.indexOf('\\', 0) >= 0) {
     const arr = selector.split('\\');
     const l = arr.length;
@@ -170,7 +168,7 @@ const unescapeSelector = (selector = '') => {
  * @param {object} [node] - Element node
  * @returns {object} - parsed AST name
  */
-const parseASTName = (name, node) => {
+export const parseASTName = (name, node) => {
   let astPrefix, astNodeName;
   if (name && typeof name === 'string') {
     if (/\|/.test(name)) {
@@ -194,57 +192,63 @@ const parseASTName = (name, node) => {
 
 /**
  * Matcher
+ * NOTE: #list[i] corresponds to #matrix[i]
+ * #list: [
+ *   {
+ *     branch: branch[],
+ *     skip: boolean
+ *   },
+ *   {
+ *     branch: branch[],
+ *     skip: boolean
+ *   }
+ * ]
+ * #matrix: [
+ *   [
+ *     Set([node, node]),
+ *     Set([node, node, node]
+ *     Set([node, node])
+ *   ],
+ *   [
+ *     Set([node, node, node]),
+ *     Set([node, node])
+ *   ]
+ * ]
+ * branch[]: [twig{}, twig{}]
+ * twig{}: {
+ *   combo: leaf{}|null,
+ *   leaves: leaves[]
+ * }
+ * leaves[]: [leaf{}, leaf{}, leaf{}]
+ * leaf{}: AST leaf
+ * node: Element node
  */
-class Matcher {
+export class Matcher {
   /* private fields */
   #list;
   #matrix;
   #node;
   #root;
   #selector;
+  #sort;
   #warn;
 
-  /**
-   * NOTE: #list[i] corresponds to #matrix[i]
-   * #list: [
-   *  { branch: branch[], skip: boolean },
-   *  { branch: branch[], skip: boolean }
-   * ]
-   * branch[]: [twig{}, twig{}]
-   * twig{}: {
-   *   combo: leaf{}|null,
-   *   leaves: leaves[]
-   * }
-   * leaves[]: [leaf{}, leaf{}, leaf{}]
-   * leaf{}: AST leaf
-   * #matrix: [
-   *   [
-   *     Set([node, node]),
-   *     Set([node, node, node]
-   *     Set([node, node])
-   *   ],
-   *   [
-   *     Set([node, node, node]),
-   *     Set([node, node])
-   *   ]
-   * ]
-   * node: Element node
-   */
-
   /**
    * construct
    * @param {string} selector - CSS selector
    * @param {object} node - Document, DocumentFragment, Element node
    * @param {object} [opt] - options
+   * @param {boolean} [opt.sort] - sort results of querySelectorAll()
    * @param {boolean} [opt.warn] - console warn
    */
   constructor(selector, node, opt = {}) {
-    const { warn } = opt;
-    [this.#list, this.#matrix] = this._prepare(selector);
+    const { sort, warn } = opt;
     this.#node = node;
     this.#root = this._getRoot(node);
     this.#selector = selector;
+    this.#sort = !!sort;
     this.#warn = !!warn;
+    this._prepare(selector);
   }
 
   /**
@@ -313,29 +317,31 @@ class Matcher {
    */
   _sortLeaves(leaves) {
     const arr = [...leaves];
-    const bitMap = new Map([
-      [ATTRIBUTE_SELECTOR, BIT_ATTRIBUTE_SELECTOR],
-      [CLASS_SELECTOR, BIT_CLASS_SELECTOR],
-      [ID_SELECTOR, BIT_ID_SELECTOR],
-      [PSEUDO_CLASS_SELECTOR, BIT_PSEUDO_CLASS_SELECTOR],
-      [PSEUDO_ELEMENT_SELECTOR, BIT_PSEUDO_ELEMENT_SELECTOR],
-      [TYPE_SELECTOR, BIT_TYPE_SELECTOR]
-    ]);
-    arr.sort((a, b) => {
-      const { type: typeA } = a;
-      const { type: typeB } = b;
-      const bitA = bitMap.get(typeA);
-      const bitB = bitMap.get(typeB);
-      let res;
-      if (bitA === bitB) {
-        res = 0;
-      } else if (bitA > bitB) {
-        res = 1;
-      } else {
-        res = -1;
-      }
-      return res;
-    });
+    if (arr.length > 1) {
+      const bitMap = new Map([
+        [ATTRIBUTE_SELECTOR, BIT_ATTRIBUTE_SELECTOR],
+        [CLASS_SELECTOR, BIT_CLASS_SELECTOR],
+        [ID_SELECTOR, BIT_ID_SELECTOR],
+        [PSEUDO_CLASS_SELECTOR, BIT_PSEUDO_CLASS_SELECTOR],
+        [PSEUDO_ELEMENT_SELECTOR, BIT_PSEUDO_ELEMENT_SELECTOR],
+        [TYPE_SELECTOR, BIT_TYPE_SELECTOR]
+      ]);
+      arr.sort((a, b) => {
+        const { type: typeA } = a;
+        const { type: typeB } = b;
+        const bitA = bitMap.get(typeA);
+        const bitB = bitMap.get(typeB);
+        let res;
+        if (bitA === bitB) {
+          res = 0;
+        } else if (bitA > bitB) {
+          res = 1;
+        } else {
+          res = -1;
+        }
+        return res;
+      });
+    }
     return arr;
   }
 
@@ -735,7 +741,7 @@ class Matcher {
   }
 
   /**
-   * match logical pseudo-class functions - :is(), :has(), :not(), :where()
+   * match logical pseudo-class functions - :has(), :is(), :not(), :where()
    * @param {object} ast - AST
    * @param {object} node - Element node
    * @returns {?object} - matched node
@@ -2187,14 +2193,7 @@ class Matcher {
         if (bool) {
           for (const pendingItem of pendingItems) {
             const { leaves } = pendingItem.get('twig');
-            const leafIterator = leaves.values();
-            let matched;
-            for (const leaf of leafIterator) {
-              matched = this._matchSelector(leaf, nextNode).has(nextNode);
-              if (!matched) {
-                break;
-              }
-            }
+            const matched = this._matchLeaves(leaves, nextNode);
             if (matched) {
               const indexI = pendingItem.get('i');
               const indexJ = pendingItem.get('j');
@@ -2331,7 +2330,7 @@ class Matcher {
               const twig = branch[j];
               for (const nextNode of nextNodes) {
                 matched = this._matchTwig(twig, nextNode, {
-                  filter: 'prev'
+                  find: 'prev'
                 });
               }
               if (matched.size) {
@@ -2381,23 +2380,25 @@ class Matcher {
    */
   _sortNodes(nodes) {
     const arr = [...nodes];
-    arr.sort((a, b) => {
-      let res;
-      const posBit = a.compareDocumentPosition(b);
-      if (posBit & DOCUMENT_POSITION_PRECEDING ||
-          posBit & DOCUMENT_POSITION_CONTAINS) {
-        res = 1;
-      } else {
-        res = -1;
-      }
-      return res;
-    });
+    if (arr.length > 1) {
+      arr.sort((a, b) => {
+        let res;
+        const posBit = a.compareDocumentPosition(b);
+        if (posBit & DOCUMENT_POSITION_PRECEDING ||
+            posBit & DOCUMENT_POSITION_CONTAINS) {
+          res = 1;
+        } else {
+          res = -1;
+        }
+        return res;
+      });
+    }
     return arr;
   }
 
   /**
    * matches
-   * @returns {boolean} - matched node
+   * @returns {boolean} - `true` if matched `false` otherwise
    */
   matches() {
     let res;
@@ -2441,10 +2442,8 @@ class Matcher {
     try {
       const nodes = this._find('first');
       nodes.delete(this.#node);
-      if (nodes.size > 1) {
+      if (nodes.size) {
         [res] = this._sortNodes(nodes);
-      } else if (nodes.size) {
-        [res] = [...nodes];
       }
     } catch (e) {
       this._onError(e);
@@ -2462,7 +2461,7 @@ class Matcher {
     try {
       const nodes = this._find('all');
       nodes.delete(this.#node);
-      if (nodes.size > 1) {
+      if (nodes.size > 1 && this.#sort) {
         res.push(...this._sortNodes(nodes));
       } else if (nodes.size) {
         res.push(...nodes);
@@ -2473,12 +2472,3 @@ class Matcher {
     return res;
   }
 };
-
-module.exports = {
-  Matcher,
-  isContentEditable,
-  isDescendant,
-  isNamespaceDeclared,
-  parseASTName,
-  unescapeSelector
-};

package/src/js/parser.js

@@ -1,14 +1,12 @@
 /**
  * parser.js
  */
-'use strict';
 
 /* import */
-const { generate, findAll, parse, toPlainObject, walk } = require('css-tree');
-const DOMException = require('./domexception.js');
+import { findAll, parse, toPlainObject, walk } from 'css-tree';
 
 /* constants */
-const { PSEUDO_CLASS_SELECTOR, SELECTOR } = require('./constant.js');
+import { PSEUDO_CLASS_SELECTOR, SELECTOR } from './constant.js';
 const CODE_POINT_UNIT = parseInt('10000', 16);
 const HEX = 16;
 const PAIR = 2;
@@ -24,7 +22,7 @@ const PSEUDO_FUNC = /^(?:(?:ha|i)s|not|where)$/;
  * @param {...*} args - arguments
  * @returns {string} - filtered selector string
  */
-const preprocess = (...args) => {
+export const preprocess = (...args) => {
   if (!args.length) {
     throw new TypeError('1 argument required, but only 0 present');
   }
@@ -66,7 +64,7 @@ const preprocess = (...args) => {
  * @param {string} selector - CSS selector
  * @returns {object} - AST
  */
-const parseSelector = selector => {
+export const parseSelector = selector => {
   selector = preprocess(selector);
   // invalid selectors
   if (selector === '' || /^\s*>/.test(selector) || /,\s*$/.test(selector)) {
@@ -96,7 +94,7 @@ const parseSelector = selector => {
  * @param {object} ast - AST
  * @returns {Array.<object|undefined>} - collection of AST branches
  */
-const walkAST = (ast = {}) => {
+export const walkAST = (ast = {}) => {
   const branches = new Set();
   let hasPseudoFunc;
   const opt = {
@@ -139,9 +137,4 @@ const walkAST = (ast = {}) => {
 };
 
 /* export */
-module.exports = {
-  generateCSS: generate,
-  parseSelector,
-  preprocess,
-  walkAST
-};
+export { generate as generateCSS } from 'css-tree';

package/types/index.d.ts

@@ -1,12 +1,13 @@
-export function closest(selector: string, node: object, opt?: {
-    warn?: object;
-}): object | null;
 export function matches(selector: string, node: object, opt?: {
-    warn?: object;
+    warn?: boolean;
 }): boolean;
+export function closest(selector: string, node: object, opt?: {
+    warn?: boolean;
+}): object | null;
 export function querySelector(selector: string, refPoint: object, opt?: {
-    warn?: object;
+    warn?: boolean;
 }): object | null;
 export function querySelectorAll(selector: string, refPoint: object, opt?: {
-    warn?: object;
+    sort?: boolean;
+    warn?: boolean;
 }): Array<object | undefined>;

package/types/js/matcher.d.ts

@@ -1,5 +1,11 @@
+export function isContentEditable(node?: object): boolean;
+export function isNamespaceDeclared(ns?: string, node?: object): boolean;
+export function isDescendant(node?: object, root?: object): boolean;
+export function unescapeSelector(selector?: string): string | null;
+export function parseASTName(name: string, node?: object): object;
 export class Matcher {
     constructor(selector: string, node: object, opt?: {
+        sort?: boolean;
         warn?: boolean;
     });
     _onError(e: Error): void;
@@ -44,8 +50,3 @@ export class Matcher {
     querySelectorAll(): Array<object | undefined>;
     #private;
 }
-export function isContentEditable(node?: object): boolean;
-export function isDescendant(node?: object, root?: object): boolean;
-export function isNamespaceDeclared(ns?: string, node?: object): boolean;
-export function parseASTName(name: string, node?: object): object;
-export function unescapeSelector(selector?: string): string | null;

package/types/js/parser.d.ts

@@ -1,5 +1,4 @@
-import { generate } from "css-tree";
-export function parseSelector(selector: string): object;
 export function preprocess(...args: any[]): string;
+export function parseSelector(selector: string): object;
 export function walkAST(ast?: object): Array<object | undefined>;
-export { generate as generateCSS };
+export { generate as generateCSS } from "css-tree";

package/src/js/domexception.js

@@ -1,13 +0,0 @@
-/**
- * domexception.js
- */
-'use strict';
-
-// NOTE: Node.js has DOMException global since v17.0.0
-if (!globalThis.DOMException) {
-  /* import */
-  const DOMException = require('domexception');
-  globalThis.DOMException = DOMException;
-}
-
-module.exports = globalThis.DOMException;