@asamuzakjp/dom-selector 0.8.0 → 0.9.2

package/README.md

@@ -3,6 +3,7 @@
 [![build](https://github.com/asamuzaK/domSelector/actions/workflows/node.js.yml/badge.svg)](https://github.com/asamuzaK/domSelector/actions/workflows/node.js.yml)
 [![CodeQL](https://github.com/asamuzaK/domSelector/actions/workflows/codeql.yml/badge.svg)](https://github.com/asamuzaK/domSelector/actions/workflows/codeql.yml)
 [![npm (scoped)](https://img.shields.io/npm/v/@asamuzakjp/dom-selector)](https://www.npmjs.com/package/@asamuzakjp/dom-selector)
+
 <!--
 [![release](https://img.shields.io/github/v/release/asamuzaK/domSelector)](https://github.com/asamuzaK/domSelector/releases)
 -->
@@ -10,14 +11,12 @@
 Retrieve DOM node from the given CSS selector.
 **Experimental**
 
-
 ## Install
 
 ```console
 npm i @asamuzakjp/dom-selector
 ```
 
-
 ## Usage
 
 ```javascript
@@ -28,65 +27,65 @@ const {
 
 <!-- Generated by documentation.js. Update this documentation by updating the source code. -->
 
-#### Table of Contents
-
-- [matches][1]
-  - [Parameters][2]
-- [closest][3]
-  - [Parameters][4]
-- [querySelector][5]
-  - [Parameters][6]
-- [querySelectorAll][7]
-  - [Parameters][8]
-
-
-### matches(selector, node)
+### matches(selector, node, opt)
 
-Implementation of [Element.matches()][62].
+matches - [Element.matches()][64]
 
 #### Parameters
 
-- `selector` **[string][56]** CSS selector
-- `node` **[object][57]** Referenced Element node
+- `selector` **[string][59]** CSS selector
+- `node` **[object][60]** Element node
+- `opt` **[object][60]?** options
+  - `opt.globalObject` **[object][60]?** global object, e.g. `window`, `globalThis`
+  - `opt.jsdom` **[boolean][61]?** is jsdom
 
-Returns **[boolean][58]** Result
+Returns **[boolean][61]** result
 
 
-### closest(selector, node)
+### closest(selector, node, opt)
 
-Implementation of [Element.closest()][63].
+closest - [Element.closest()][65]
 
 #### Parameters
 
-- `selector` **[string][56]** CSS selector
-- `node` **[object][57]** Referenced Element node
+- `selector` **[string][59]** CSS selector
+- `node` **[object][60]** Element node
+- `opt` **[object][60]?** options
+  - `opt.globalObject` **[object][60]?** global object, e.g. `window`, `globalThis`
+  - `opt.jsdom` **[boolean][61]?** is jsdom
 
-Returns **[object][57]?** Matched node
+Returns **[object][60]?** matched node
 
 
-### querySelector(selector, refPoint)
+### querySelector(selector, refPoint, opt)
 
-Implementation of [Document.querySelector()][64], [Element.querySelector()][65].
+querySelector - [Document.querySelector()][66], [DocumentFragment.querySelector()][67], [Element.querySelector()][68]
 
 #### Parameters
 
-- `selector` **[string][56]** CSS selector
-- `refPoint` **[object][57]** Reference point. Document or Element node
+- `selector` **[string][59]** CSS selector
+- `refPoint` **[object][60]** Document, DocumentFragment or Element node
+- `opt` **[object][60]?** options
+  - `opt.globalObject` **[object][60]?** global object, e.g. `window`, `globalThis`
+  - `opt.jsdom` **[boolean][61]?** is jsdom
 
-Returns **[object][57]?** Matched node
+Returns **[object][60]?** matched node
 
 
-### querySelectorAll(selector, refPoint)
+### querySelectorAll(selector, refPoint, opt)
 
-Implementation of [Document.querySelectorAll()][66], [Element.querySelectorAll()][67].
-**NOTE**: returns [Array][59], not [NodeList][61].
+querySelectorAll - [Document.querySelectorAll()][69], [Document.querySelectorAll()][70], [Element.querySelectorAll()][71]
+**NOTE**: returns Array, not NodeList
 
 #### Parameters
 
-- `selector` **[string][56]** CSS selector
-- `refPoint` **[object][57]** Reference point. Document or Element node
+- `selector` **[string][59]** CSS selector
+- `refPoint` **[object][60]** Document, DocumentFragment or Element node
+- `opt` **[object][60]?** options
+  - `opt.globalObject` **[object][60]?** global object, e.g. `window`, `globalThis`
+  - `opt.jsdom` **[boolean][61]?** is jsdom
 
-Returns **[Array][59]&lt;([object][57] \| [undefined][60])>** Array of matched nodes
+Returns **[Array][62]&lt;([object][60] \| [undefined][63])>** array of matched nodes
 
 
 ## Acknowledgments
@@ -105,15 +104,16 @@ The following resources have been of great help in the development of the DOM Se
 [6]: #parameters-2
 [7]: #queryselectorall
 [8]: #parameters-3
-[56]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
-[57]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
-[58]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
-[59]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
-[60]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined
-[61]: https://developer.mozilla.org/docs/Web/API/NodeList
-[62]: https://developer.mozilla.org/docs/Web/API/Element/matches
-[63]: https://developer.mozilla.org/docs/Web/API/Element/closest
-[64]: https://developer.mozilla.org/docs/Web/API/Document/querySelector
-[65]: https://developer.mozilla.org/docs/Web/API/Element/querySelector
-[66]: https://developer.mozilla.org/docs/Web/API/Document/querySelectorAll
-[67]: https://developer.mozilla.org/docs/Web/API/Element/querySelectorAll
+[59]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+[60]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+[61]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+[62]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+[63]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined
+[64]: https://developer.mozilla.org/docs/Web/API/Element/matches
+[65]: https://developer.mozilla.org/docs/Web/API/Element/closest
+[66]: https://developer.mozilla.org/docs/Web/API/Document/querySelector
+[67]: https://developer.mozilla.org/docs/Web/API/DocumentFragment/querySelector
+[68]: https://developer.mozilla.org/docs/Web/API/Element/querySelector
+[69]: https://developer.mozilla.org/docs/Web/API/Document/querySelectorAll
+[70]: https://developer.mozilla.org/docs/Web/API/DocumentFragment/querySelectorAll
+[71]: https://developer.mozilla.org/docs/Web/API/Element/querySelectorAll

package/package.json

@@ -41,5 +41,5 @@
     "test": "c8 --reporter=text mocha --exit test/**/*.test.js",
     "tsc": "npx tsc"
   },
-  "version": "0.8.0"
+  "version": "0.9.2"
 }

package/src/index.js

@@ -4,6 +4,7 @@
  * @copyright asamuzaK (Kazz)
  * @see {@link https://github.com/asamuzaK/domSelector/blob/main/LICENSE}
  */
+'use strict';
 
 /* import */
 const { Matcher } = require('./js/matcher.js');
@@ -12,10 +13,13 @@ const { Matcher } = require('./js/matcher.js');
  * matches - Element.matches()
  * @param {string} selector - CSS selector
  * @param {object} node - Element node
+ * @param {object} [opt] - options
+ * @param {object} [opt.globalObject] - global object
+ * @param {boolean} [opt.jsdom] - is jsdom
  * @returns {boolean} - result
  */
-const matches = (selector, node) => {
-  const matcher = new Matcher(selector, node);
+const matches = (selector, node, opt) => {
+  const matcher = new Matcher(selector, node, opt);
   return matcher.matches();
 };
 
@@ -23,10 +27,13 @@ const matches = (selector, node) => {
  * closest - Element.closest()
  * @param {string} selector - CSS selector
  * @param {object} node - Element node
+ * @param {object} [opt] - options
+ * @param {object} [opt.globalObject] - global object
+ * @param {boolean} [opt.jsdom] - is jsdom
  * @returns {?object} - matched node
  */
-const closest = (selector, node) => {
-  const matcher = new Matcher(selector, node);
+const closest = (selector, node, opt) => {
+  const matcher = new Matcher(selector, node, opt);
   return matcher.closest();
 };
 
@@ -34,10 +41,13 @@ const closest = (selector, node) => {
  * querySelector - Document.querySelector(), Element.querySelector()
  * @param {string} selector - CSS selector
  * @param {object} refPoint - Document or Element node
+ * @param {object} [opt] - options
+ * @param {object} [opt.globalObject] - global object
+ * @param {boolean} [opt.jsdom] - is jsdom
  * @returns {?object} - matched node
  */
-const querySelector = (selector, refPoint) => {
-  const matcher = new Matcher(selector, refPoint);
+const querySelector = (selector, refPoint, opt) => {
+  const matcher = new Matcher(selector, refPoint, opt);
   return matcher.querySelector();
 };
 
@@ -46,10 +56,13 @@ const querySelector = (selector, refPoint) => {
  * NOTE: returns Array, not NodeList
  * @param {string} selector - CSS selector
  * @param {object} refPoint - Document or Element node
+ * @param {object} [opt] - options
+ * @param {object} [opt.globalObject] - global object
+ * @param {boolean} [opt.jsdom] - is jsdom
  * @returns {Array.<object|undefined>} - array of matched nodes
  */
-const querySelectorAll = (selector, refPoint) => {
-  const matcher = new Matcher(selector, refPoint);
+const querySelectorAll = (selector, refPoint, opt) => {
+  const matcher = new Matcher(selector, refPoint, opt);
   return matcher.querySelectorAll();
 };
 

package/src/js/constant.js

@@ -1,6 +1,7 @@
 /**
  * constant.js
  */
+'use strict';
 
 module.exports = {
   AN_PLUS_B: 'AnPlusB',

package/src/js/domexception.js

@@ -0,0 +1,13 @@
+/**
+ * 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;

package/src/js/matcher.js

@@ -1,9 +1,11 @@
 /**
  * matcher.js
  */
+'use strict';
 
 /* import */
-const DOMException = require('domexception');
+const _DOMException = require('domexception/webidl2js-wrapper');
+const DOMException = require('./domexception.js');
 const { generateCSS, parseSelector, walkAST } = require('./parser.js');
 
 /* constants */
@@ -345,8 +347,12 @@ const matchAttributeSelector = (ast = {}, node = {}) => {
   let res;
   if (astType === ATTRIBUTE_SELECTOR && nodeType === ELEMENT_NODE &&
       attributes?.length) {
+    if (typeof astFlags === 'string' && !/^[is]$/i.test(astFlags)) {
+      throw new DOMException('invalid attribute selector', 'SyntaxError');
+    }
     const { name: astAttrName } = astName;
-    const caseInsensitive = !(astFlags && /^s$/i.test(astFlags));
+    const caseInsensitive =
+      !(typeof astFlags === 'string' && /^s$/i.test(astFlags));
     const attrValues = [];
     const l = attributes.length;
     // namespaced
@@ -883,6 +889,8 @@ class Matcher {
   /* private fields */
   #ast;
   #document;
+  #global;
+  #jsdom;
   #node;
   #selector;
 
@@ -890,14 +898,32 @@ class Matcher {
    * construct
    * @param {string} selector - CSS selector
    * @param {object} refPoint - reference point
+   * @param {object} [opt] - options
+   * @param {object} [opt.globalObject] - global object
+   * @param {boolean} [opt.jsdom] - is jsdom
    */
-  constructor(selector, refPoint) {
+  constructor(selector, refPoint, opt = {}) {
+    const { globalObject, jsdom } = opt;
     this.#ast = parseSelector(selector);
     this.#document = refPoint?.ownerDocument ?? refPoint;
+    this.#global = globalObject || globalThis;
+    this.#jsdom = !!jsdom;
     this.#node = refPoint;
     this.#selector = selector;
   }
 
+  /**
+   * create DOMException
+   * @param {string} msg - message
+   * @param {string} name - name
+   * @throws
+   */
+  _createDOMException(msg, name) {
+    if (this.#jsdom) {
+      throw _DOMException.create(this.#global, [msg, name]);
+    }
+  }
+
   /**
    * create iterator
    * @param {object} ast - AST
@@ -1342,8 +1368,17 @@ class Matcher {
    * @returns {boolean} - matched node
    */
   matches() {
-    const arr = this._match(this.#ast, this.#document);
-    const res = arr.length && arr.includes(this.#node);
+    let res;
+    try {
+      const arr = this._match(this.#ast, this.#document);
+      res = arr.length && arr.includes(this.#node);
+    } catch (e) {
+      if (e instanceof DOMException && this.#jsdom) {
+        res = this._createDOMException(e.message, e.name);
+      } else {
+        throw e;
+      }
+    }
     return !!res;
   }
 
@@ -1352,15 +1387,23 @@ class Matcher {
    * @returns {?object} - matched node
    */
   closest() {
-    const arr = this._match(this.#ast, this.#document);
-    let node = this.#node;
     let res;
-    while (node) {
-      if (arr.includes(node)) {
-        res = node;
-        break;
+    try {
+      const arr = this._match(this.#ast, this.#document);
+      let node = this.#node;
+      while (node) {
+        if (arr.includes(node)) {
+          res = node;
+          break;
+        }
+        node = node.parentNode;
+      }
+    } catch (e) {
+      if (e instanceof DOMException && this.#jsdom) {
+        res = this._createDOMException(e.message, e.name);
+      } else {
+        throw e;
       }
-      node = node.parentNode;
     }
     return res || null;
   }
@@ -1370,14 +1413,23 @@ class Matcher {
    * @returns {?object} - matched node
    */
   querySelector() {
-    const arr = this._match(this.#ast, this.#node);
-    if (arr.length) {
-      const i = arr.findIndex(node => node === this.#node);
-      if (i >= 0) {
-        arr.splice(i, 1);
+    let res;
+    try {
+      const arr = this._match(this.#ast, this.#node);
+      if (arr.length) {
+        const i = arr.findIndex(node => node === this.#node);
+        if (i >= 0) {
+          arr.splice(i, 1);
+        }
+      }
+      [res] = arr;
+    } catch (e) {
+      if (e instanceof DOMException && this.#jsdom) {
+        res = this._createDOMException(e.message, e.name);
+      } else {
+        throw e;
       }
     }
-    const [res] = arr;
     return res || null;
   }
 
@@ -1387,14 +1439,25 @@ class Matcher {
    * @returns {Array.<object|undefined>} - collection of matched nodes
    */
   querySelectorAll() {
-    const arr = this._match(this.#ast, this.#node);
-    if (arr.length) {
-      const i = arr.findIndex(node => node === this.#node);
-      if (i >= 0) {
-        arr.splice(i, 1);
+    const res = [];
+    try {
+      const arr = this._match(this.#ast, this.#node);
+      if (arr.length) {
+        const i = arr.findIndex(node => node === this.#node);
+        if (i >= 0) {
+          arr.splice(i, 1);
+        }
+      }
+      const a = new Set(arr);
+      res.push(...a);
+    } catch (e) {
+      if (e instanceof DOMException && this.#jsdom) {
+        res.push(this._createDOMException(e.message, e.name));
+      } else {
+        throw e;
       }
     }
-    return [...new Set(arr)];
+    return res;
   }
 };
 

package/src/js/parser.js

@@ -1,11 +1,16 @@
 /**
  * parser.js
  */
+'use strict';
 
-/* api */
-const DOMException = require('domexception');
+/* import */
 const { generate, parse, toPlainObject, walk } = require('css-tree');
+const DOMException = require('./domexception.js');
+
+/* constants */
 const { SELECTOR } = require('./constant.js');
+const TYPE_FROM = 8;
+const TYPE_TO = -1;
 
 /**
  * create AST from CSS selector
@@ -13,10 +18,13 @@ const { SELECTOR } = require('./constant.js');
  * @returns {object} - AST
  */
 const parseSelector = selector => {
+  if (selector === undefined || selector === null) {
+    selector = Object.prototype.toString.call(selector)
+      .slice(TYPE_FROM, TYPE_TO).toLowerCase();
+  }
   // invalid selectors
   if (typeof selector !== 'string' || selector === '' ||
-      selector.startsWith('>') || selector.endsWith(',') ||
-      selector.includes('= ')) {
+      /^\s*>/.test(selector) || /,\s*$/.test(selector)) {
     throw new DOMException(`invalid selector ${selector}`, 'SyntaxError');
   }
   let res;

package/types/index.d.ts

@@ -1,4 +1,16 @@
-export function closest(selector: string, node: object): object | null;
-export function matches(selector: string, node: object): boolean;
-export function querySelector(selector: string, refPoint: object): object | null;
-export function querySelectorAll(selector: string, refPoint: object): Array<object | undefined>;
+export function closest(selector: string, node: object, opt?: {
+    globalObject?: object;
+    jsdom?: boolean;
+}): object | null;
+export function matches(selector: string, node: object, opt?: {
+    globalObject?: object;
+    jsdom?: boolean;
+}): boolean;
+export function querySelector(selector: string, refPoint: object, opt?: {
+    globalObject?: object;
+    jsdom?: boolean;
+}): object | null;
+export function querySelectorAll(selector: string, refPoint: object, opt?: {
+    globalObject?: object;
+    jsdom?: boolean;
+}): Array<object | undefined>;

package/types/js/domexception.d.ts

@@ -0,0 +1,30 @@
+declare const _exports: {
+    new (message?: string, name?: string): DOMException;
+    prototype: DOMException;
+    readonly INDEX_SIZE_ERR: 1;
+    readonly DOMSTRING_SIZE_ERR: 2;
+    readonly HIERARCHY_REQUEST_ERR: 3;
+    readonly WRONG_DOCUMENT_ERR: 4;
+    readonly INVALID_CHARACTER_ERR: 5;
+    readonly NO_DATA_ALLOWED_ERR: 6;
+    readonly NO_MODIFICATION_ALLOWED_ERR: 7;
+    readonly NOT_FOUND_ERR: 8;
+    readonly NOT_SUPPORTED_ERR: 9;
+    readonly INUSE_ATTRIBUTE_ERR: 10;
+    readonly INVALID_STATE_ERR: 11;
+    readonly SYNTAX_ERR: 12;
+    readonly INVALID_MODIFICATION_ERR: 13;
+    readonly NAMESPACE_ERR: 14;
+    readonly INVALID_ACCESS_ERR: 15;
+    readonly VALIDATION_ERR: 16;
+    readonly TYPE_MISMATCH_ERR: 17;
+    readonly SECURITY_ERR: 18;
+    readonly NETWORK_ERR: 19;
+    readonly ABORT_ERR: 20;
+    readonly URL_MISMATCH_ERR: 21;
+    readonly QUOTA_EXCEEDED_ERR: 22;
+    readonly TIMEOUT_ERR: 23;
+    readonly INVALID_NODE_TYPE_ERR: 24;
+    readonly DATA_CLONE_ERR: 25;
+};
+export = _exports;

package/types/js/matcher.d.ts

@@ -1,5 +1,9 @@
 export class Matcher {
-    constructor(selector: string, refPoint: object);
+    constructor(selector: string, refPoint: object, opt?: {
+        globalObject?: object;
+        jsdom?: boolean;
+    });
+    _createDOMException(msg: string, name: string): void;
     _createIterator(ast?: object, root?: object): object;
     _parseAST(ast: object, node: object): Array<object | undefined>;
     _matchAdjacentLeaves(leaves: Array<object>, node: object): object | null;