shadow-dom-selector 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,280 @@
+# shadow-dom-selector
+
+A very small JavaScript utility to query DOM elements through the [Shadow DOM] subtrees in a sync or an async way.
+
+[![Deployment Status](https://github.com/elchininet/shadow-dom-selector/actions/workflows/deploy.yaml/badge.svg)](https://github.com/elchininet/shadow-dom-selector/actions/workflows/deploy.yaml)   [![Coverage Status](https://coveralls.io/repos/github/elchininet/shadow-dom-selector/badge.svg?branch=master)](https://coveralls.io/github/elchininet/shadow-dom-selector?branch=master)   [![npm version](https://badge.fury.io/js/shadow-dom-selector.svg)](https://badge.fury.io/js/shadow-dom-selector)
+
+## Introduction
+
+Having a DOM tree formed of Shadow DOM subtrees like the next one:
+
+```html
+<body>
+  <section>
+    #shadow-root (open)
+      <h1>Title</h1>
+      <article>
+        #shadow-root (open)
+          <h2>Subtitle</h2>
+          <ul>
+            <li>Item 1</li>
+            <li>Item 2</li>
+            <li>Item 1</li>
+          </ul>
+      </article>
+  </section>
+</body>
+```
+If one wants to query for the `li` elements, it is required to do this:
+
+```javascript
+const secondLi = document.querySelector('section').shadowRoot.querySelector('article').shadowRoot.querySelector('ul > li');
+
+const allLis = document.querySelector('section').shadowRoot.querySelector('article').shadowRoot.querySelectorAll('ul > li');
+
+const shadow = document.querySelector('section').shadowRoot.querySelector('article').shadowRoot;
+```
+
+`shadow-dom-selector` allows you to do the same in the next way:
+
+```javascript
+import { querySelector, querySelectorAll, shadowRootQuerySelector } from 'shadow-dom-selector';
+
+// $ character at the end of a selector means to select its Shadom DOM  
+const secondLi querySelector('section$ article$ ul > li');
+const allLis querySelectorAll('section$ article$ ul > li');
+const shadow = shadowRootQuerySelector('section$ article$');
+```
+
+It will traverse all the Shadow DOM subtrees removing all the hassle of writing long concatenated queries.
+
+### It checks for the existence of elements
+
+With the same previous DOM tree, if we do this:
+
+```javascript
+const element = document.querySelector('article').shadowRoot.querySelector('div').shadowRoot.querySelector('section > h1');
+```
+
+It will throw an error, because none of the elements in those queries exists. If you don‘t know if the elements exist or not, you will require to use [optional chaining] or wrap all the code in conditions:
+
+```javascript
+const element = document.querySelector('article')?.shadowRoot?.querySelector('div')?.shadowRoot?.querySelector('section > h1');
+const elements = document.querySelector('article')?.shadowRoot?.querySelector('div')?.shadowRoot?.querySelectorAll('p');
+const shadow = document.querySelector('article')?.shadowRoot?.querySelector('div')?.shadowRoot;
+```
+
+Which will return `undefined` if some element doesn‘t exist. With `shadow-dom-selector`, you just need to write the query and it will return the same that is returned by the native `querySelector` and `querySelectorAll` if the query cannot be satisfied.
+
+```javascript
+import { querySelector, querySelectorAll, shadowRootQuerySelector } from 'shadow-dom-selector';
+
+const element = querySelector('article$ div$ section > h1'); // null
+const elements = querySelectorAll('article div$ p'); // empty NodeList
+const shadow = shadowRootQuerySelector('article$ div$'); // null
+```
+
+### Async queries
+
+If the elements are not already rendered into the DOM in the moment that the query is made you will receive `null`. `shadow-dom-selector` allows it to wait for the elements to appear, allowing you to decide how many times it will try to query for the element before giving up and returning `null` or an empty `NodeList`.
+
+```javascript
+import { asyncQuerySelector, asyncQuerySelectorAll, asyncShadowRootQuerySelector } from 'shadow-dom-selector';
+
+const element = asyncQuerySelector('article$ div$ section > h1')
+    .then((h1) => {
+        // Do stuff with the h1 element
+        // If it is not found after all the retries, it will return null
+    });
+
+const elements = asyncQuerySelectorAll('article div$ p')
+    .then((paragraphs) => {
+        // Do stuff with the paragraphs
+        // If they are not found after all the retries, it will return an empty NodeList
+    });
+
+const shadow = asyncShadowRootQuerySelector('article$ div$')
+    .then((shadowRoot) => {
+        // Do stuff with the shadowRoot
+        // If it is not found after all the retries, it will return null
+    });
+```
+
+All these three functions allow you to to specify the amount of retries and the delay between each one of them. Consult the [API](#api) section for more details.
+
+## Install
+
+#### npm
+
+```bash
+npm install shadow-dom-selector
+```
+
+#### yarn
+
+```bash
+yarn add shadow-dom-selector
+```
+
+#### PNPM
+
+```bash
+pnpm add shadow-dom-selector
+```
+
+#### In the browser
+
+It is possible to include a compiled version of the package directly in an HTML file. It will create a global `ShadowDomSelector` object containing all the exported functions that can be accessed from anywhere in your JavaScript code.
+
+1. Copy the JavaScript file `index.js`, located in the root of the `dist/` folder
+2. Put it in the folder that you prefer in your web server
+3. Include it in your HTML file
+
+```html
+<script src="wherever/you/want/to/place/index.js"></script>
+```
+
+```javascript
+/* There will be a global variable named ShadowDomSelector containing all the functions */
+ShadowDomSelector.querySelector;
+ShadowDomSelector.querySelectorAll;
+ShadowDomSelector.shadowRootQuerySelector;
+ShadowDomSelector.asyncQuerySelector;
+ShadowDomSelector.asyncQuerySelectorAll;
+ShadowDomSelector.asyncShadowRootQuerySelector;
+```
+
+## API
+
+#### querySelector
+
+```typescript
+querySelector(selectors);
+```
+
+```typescript
+querySelector(root, selectors);
+```
+
+| Parameter    | Optional      | Description                                        |
+| ------------ | ------------- | -------------------------------------------------- |
+| selectors    | no            | A string containing one or more selectors to match. Selectors cannot end in a Shadow DOM (`$`) |
+| root         | yes           | The element from where the query should be performed, it defaults to `document` |
+
+#### querySelectorAll
+
+```typescript
+querySelectorAll(selectors);
+```
+
+```typescript
+querySelectorAll(root, selectors);
+```
+
+| Parameter    | Optional      | Description                                        |
+| ------------ | ------------- | -------------------------------------------------- |
+| selectors    | no            | A string containing one or more selectors to match. Selectors cannot end in a Shadow DOM (`$`) |
+| root         | yes           | The element from where the query should be performed, it defaults to `document` |
+
+#### shadowRootQuerySelector
+
+```typescript
+shadowRootQuerySelector(selectors);
+```
+
+```typescript
+shadowRootQuerySelector(root, selectors);
+```
+
+| Parameter    | Optional      | Description                                        |
+| ------------ | ------------- | -------------------------------------------------- |
+| selectors    | no            | A string containing one or more selectors to match. Selectors must end in a Shadow DOM (`$`) |
+| root         | yes           | The element from where the query should be performed, it defaults to `document` |
+
+#### asyncQuerySelector
+
+```typescript
+asyncQuerySelector(selectors);
+```
+
+```typescript
+asyncQuerySelector(root, selectors);
+```
+
+```typescript
+asyncQuerySelector(root, selectors, asyncParams);
+```
+
+```typescript
+// asyncParams properties
+{
+  retries?: number; // how many retries before giving up (defaults to 10)
+  delay?: number; // delay between each retry (defaults to 10)
+}
+```
+
+| Parameter    | Optional      | Description                                        |
+| ------------ | ------------- | -------------------------------------------------- |
+| selectors    | no            | A string containing one or more selectors to match. Selectors cannot end in a Shadow DOM (`$`) |
+| root         | yes           | The element from where the query should be performed, it defaults to `document` |
+| asyncParams  | yes           | An object containing the parameters which control the retries |
+
+#### asyncQuerySelectorAll
+
+```typescript
+asyncQuerySelectorAll(selectors);
+```
+
+```typescript
+asyncQuerySelectorAll(root, selectors);
+```
+
+```typescript
+asyncQuerySelectorAll(root, selectors, asyncParams);
+```
+
+```typescript
+// asyncParams properties
+{
+  retries?: number; // how many retries before giving up (defaults to 10)
+  delay?: number; // delay between each retry (defaults to 10)
+}
+```
+
+| Parameter    | Optional      | Description                                        |
+| ------------ | ------------- | -------------------------------------------------- |
+| selectors    | no            | A string containing one or more selectors to match. Selectors cannot end in a Shadow DOM (`$`) |
+| root         | yes           | The element from where the query should be performed, it defaults to `document` |
+| asyncParams  | yes           | An object containing the parameters which control the retries |
+
+#### asyncShadowRootQuerySelector
+
+```typescript
+asyncShadowRootQuerySelector(selectors);
+```
+
+```typescript
+asyncShadowRootQuerySelector(root, selectors);
+```
+
+```typescript
+asyncShadowRootQuerySelector(root, selectors, asyncParams);
+```
+
+```typescript
+// asyncParams properties
+{
+  retries?: number; // how many retries before giving up (defaults to 10)
+  delay?: number; // delay between each retry (defaults to 10)
+}
+```
+
+| Parameter    | Optional      | Description                                        |
+| ------------ | ------------- | -------------------------------------------------- |
+| selectors    | no            | A string containing one or more selectors to match. Selectors must end in a Shadow DOM (`$`) |
+| root         | yes           | The element from where the query should be performed, it defaults to `document` |
+| asyncParams  | yes           | An object containing the parameters which control the retries |
+
+
+[Shadow DOM]: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM
+[optional chaining]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining

package/dist/esm/index.d.ts

@@ -0,0 +1,17 @@
+interface AsyncParams {
+    retries?: number;
+    delay?: number;
+}
+declare function querySelector<E extends Element = Element>(root: Document | Element, selectors: string): E | null;
+declare function querySelector<E extends Element = Element>(selectors: string): E | null;
+declare function querySelectorAll<E extends Element = Element>(root: Document | Element, selectors: string): NodeListOf<E>;
+declare function querySelectorAll<E extends Element = Element>(selectors: string): NodeListOf<E>;
+declare function shadowRootQuerySelector(root: Document | Element, selectors: string): ShadowRoot | null;
+declare function shadowRootQuerySelector(selectors: string): ShadowRoot | null;
+declare function asyncQuerySelector<E extends Element = Element>(root: Document | Element, selectors: string, asyncParams?: AsyncParams): Promise<E | null>;
+declare function asyncQuerySelector<E extends Element = Element>(selectors: string, asyncParams?: AsyncParams): Promise<E | null>;
+declare function asyncQuerySelectorAll<E extends Element = Element>(root: Document | Element, selectors: string, asyncParams?: AsyncParams): Promise<NodeListOf<E>>;
+declare function asyncQuerySelectorAll<E extends Element = Element>(selectors: string, asyncParams?: AsyncParams): Promise<NodeListOf<E>>;
+declare function asyncShadowRootQuerySelector(root: Document | Element, selectors: string, asyncParams?: AsyncParams): Promise<ShadowRoot | null>;
+declare function asyncShadowRootQuerySelector(selectors: string, asyncParams?: AsyncParams): Promise<ShadowRoot | null>;
+export { querySelector, querySelectorAll, shadowRootQuerySelector, asyncQuerySelector, asyncQuerySelectorAll, asyncShadowRootQuerySelector };

package/dist/esm/index.js

@@ -0,0 +1 @@
+function n(n,e,t,r){return new(t||(t=Promise))((function(o,u){function l(n){try{a(r.next(n))}catch(n){u(n)}}function c(n){try{a(r.throw(n))}catch(n){u(n)}}function a(n){var e;n.done?o(n.value):(e=n.value,e instanceof t?e:new t((function(n){n(e)}))).then(l,c)}a((r=r.apply(n,e||[])).next())}))}function e(n,e){var t,r,o,u,l={label:0,sent:function(){if(1&o[0])throw o[1];return o[1]},trys:[],ops:[]};return u={next:c(0),throw:c(1),return:c(2)},"function"==typeof Symbol&&(u[Symbol.iterator]=function(){return this}),u;function c(c){return function(a){return function(c){if(t)throw new TypeError("Generator is already executing.");for(;u&&(u=0,c[0]&&(l=0)),l;)try{if(t=1,r&&(o=2&c[0]?r.return:c[0]?r.throw||((o=r.return)&&o.call(r),0):r.next)&&!(o=o.call(r,c[1])).done)return o;switch(r=0,o&&(c=[2&c[0],o.value]),c[0]){case 0:case 1:o=c;break;case 4:return l.label++,{value:c[1],done:!1};case 5:l.label++,r=c[1],c=[0];continue;case 7:c=l.ops.pop(),l.trys.pop();continue;default:if(!(o=l.trys,(o=o.length>0&&o[o.length-1])||6!==c[0]&&2!==c[0])){l=0;continue}if(3===c[0]&&(!o||c[1]>o[0]&&c[1]<o[3])){l.label=c[1];break}if(6===c[0]&&l.label<o[1]){l.label=o[1],o=c;break}if(o&&l.label<o[2]){l.label=o[2],l.ops.push(c);break}o[2]&&l.ops.pop(),l.trys.pop();continue}c=e.call(n,l)}catch(n){c=[6,n],r=0}finally{t=o=0}if(5&c[0])throw c[1];return{value:c[0]?c[1]:void 0,done:!0}}([c,a])}}}function t(n,e,t){if(t||2===arguments.length)for(var r,o=0,u=e.length;o<u;o++)!r&&o in e||(r||(r=Array.prototype.slice.call(e,0,o)),r[o]=e[o]);return n.concat(r||Array.prototype.slice.call(e))}"function"==typeof SuppressedError&&SuppressedError;var r="$",o=":host",u="invalid selector",l=10,c=10,a=function(n){var e,t=n[0],r=n[1];return(e=t)&&(e instanceof Document||e instanceof Element)&&"string"==typeof r};function i(n,e){return function(n){return n.split(",").map((function(n){return n.trim()}))}(n).map((function(n){var t=function(n){return n.split(r).map((function(n){return n.trim()}))}(n);return e(t)}))}function s(n,e,t,r,o){return void 0===o&&(o=!1),new Promise((function(l){var c=0,a=function(){var i=o?n.querySelectorAll(e):n.querySelector(e);o&&i.length||!o&&null!==i?l(i):++c<t?setTimeout(a,r):l(o?document.querySelectorAll(u):null)};a()}))}function f(n,e,t){return new Promise((function(r){var o=0,u=function(){var l=n.shadowRoot;l?r(l):++o<e?setTimeout(u,t):r(null)};u()}))}function h(n,e){var t=e?" If you want to select a shadowRoot, use ".concat(e," instead."):"";return"".concat(n," cannot be used with a selector ending in a shadowRoot (").concat(r,").").concat(t)}function d(n,e){return"".concat(n," must be used with a selector ending in a shadowRoot (").concat(r,"). If you don't want to select a shadowRoot, use ").concat(e," instead.")}function v(){return"You can not select a shadowRoot (".concat(r,") of the document.")}function y(n,e){for(var t,r,u=null,l=n.length,c=0;c<l;c++){if(0===c)if(n[c].length)u=e.querySelector(n[c]);else{if(e instanceof Document)throw new SyntaxError(v());u=(null===(t=e.shadowRoot)||void 0===t?void 0:t.querySelector(n[++c]))||null}else u=(null===(r=u.shadowRoot)||void 0===r?void 0:r.querySelector("".concat(o," ").concat(n[c])))||null;if(null===u)return null}return u}function w(n,e){var r,u=t([],n,!0),l=u.pop();return u.length?(null===(r=y(u,e).shadowRoot)||void 0===r?void 0:r.querySelectorAll("".concat(o," ").concat(l)))||null:e.querySelectorAll(l)}function p(n,e){var t=y(n,e);return(null==t?void 0:t.shadowRoot)||null}function g(t,r,u,l){return n(this,void 0,void 0,(function(){var n,c,a,i,h,d;return e(this,(function(e){switch(e.label){case 0:n=null,c=t.length,a=0,e.label=1;case 1:if(!(a<c))return[3,15];if(0!==a)return[3,8];if(t[a].length)return[3,5];if(r instanceof Document)throw new SyntaxError(v());return r.shadowRoot?[4,s(r.shadowRoot,t[++a],u,l)]:[3,3];case 2:return i=e.sent(),[3,4];case 3:i=null,e.label=4;case 4:return n=i,[3,7];case 5:return[4,s(r,t[a],u,l)];case 6:n=e.sent(),e.label=7;case 7:return[3,13];case 8:return[4,f(n,u,l)];case 9:return(h=e.sent())?[4,s(h,"".concat(o," ").concat(t[a]),u,l)]:[3,11];case 10:return d=e.sent(),[3,12];case 11:d=null,e.label=12;case 12:n=d,e.label=13;case 13:if(null===n)return[2,null];e.label=14;case 14:return a++,[3,1];case 15:return[2,n]}}))}))}function b(r,u,l,c){return n(this,void 0,void 0,(function(){var n,a,i,h,d,v;return e(this,(function(e){switch(e.label){case 0:return n=t([],r,!0),a=n.pop(),n.length?[3,2]:[4,s(u,a,l,c,!0)];case 1:return[2,e.sent()];case 2:return[4,g(n,u,l,c)];case 3:return(i=e.sent())?[4,f(i,l,c)]:[3,5];case 4:return d=e.sent(),[3,6];case 5:d=null,e.label=6;case 6:return(h=d)?[4,s(h,"".concat(o," ").concat(a),l,c,!0)]:[3,8];case 7:return v=e.sent(),[3,9];case 8:v=null,e.label=9;case 9:return[2,v]}}))}))}function S(t,r,o,u){return n(this,void 0,void 0,(function(){var n,l;return e(this,(function(e){switch(e.label){case 0:return[4,g(t,r,o,u)];case 1:return(n=e.sent())?[4,f(n,o,u)]:[3,3];case 2:return l=e.sent(),[3,4];case 3:l=null,e.label=4;case 4:return[2,l]}}))}))}function m(n,e){for(var t=i(n,(function(n){if(!n[n.length-1].length)throw new SyntaxError(h("querySelector","shadowRootQuerySelector"));return n})),r=t.length,o=0;o<r;o++){var u=y(t[o],e);if(u)return u}return null}function R(n,e){for(var t=i(n,(function(n){if(!n[n.length-1].length)throw new SyntaxError(h("querySelectorAll"));return n})),r=t.length,o=0;o<r;o++){var l=w(t[o],e);if(null==l?void 0:l.length)return l}return document.querySelectorAll(u)}function x(n,e){for(var t=i(n,(function(n){if(n.pop().length)throw new SyntaxError(d("shadowRootQuerySelector","querySelector"));return n})),r=t.length,o=0;o<r;o++){var u=p(t[o],e);if(u)return u}return null}function q(t,r,o,u){return n(this,void 0,void 0,(function(){var n,l,c,a;return e(this,(function(e){switch(e.label){case 0:n=i(t,(function(n){if(!n[n.length-1].length)throw new SyntaxError(h("asyncQuerySelector","asyncShadowRootQuerySelector"));return n})),l=n.length,c=0,e.label=1;case 1:return c<l?[4,g(n[c],r,o,u)]:[3,4];case 2:if(a=e.sent())return[2,a];e.label=3;case 3:return c++,[3,1];case 4:return[2,null]}}))}))}function E(t,r,o,l){return n(this,void 0,void 0,(function(){var n,c,a,s;return e(this,(function(e){switch(e.label){case 0:n=i(t,(function(n){if(!n[n.length-1].length)throw new SyntaxError(h("asyncQuerySelectorAll"));return n})),c=n.length,a=0,e.label=1;case 1:return a<c?[4,b(n[a],r,o,l)]:[3,4];case 2:if(null==(s=e.sent())?void 0:s.length)return[2,s];e.label=3;case 3:return a++,[3,1];case 4:return[2,document.querySelectorAll(u)]}}))}))}function A(t,r,o,u){return n(this,void 0,void 0,(function(){var n,l,c,a;return e(this,(function(e){switch(e.label){case 0:n=i(t,(function(n){if(n.pop().length)throw new SyntaxError(d("asyncShadowRootQuerySelector","asyncQuerySelector"));return n})),l=n.length,c=0,e.label=1;case 1:return c<l?[4,S(n[c],r,o,u)]:[3,4];case 2:if(a=e.sent())return[2,a];e.label=3;case 3:return c++,[3,1];case 4:return[2,null]}}))}))}function Q(){for(var n=[],e=0;e<arguments.length;e++)n[e]=arguments[e];var t=n[0],r=n[1];return"string"==typeof t?m(t,document):m(r,t)}function k(){for(var n=[],e=0;e<arguments.length;e++)n[e]=arguments[e];var t=n[0],r=n[1];return"string"==typeof t?R(t,document):R(r,t)}function D(){for(var n=[],e=0;e<arguments.length;e++)n[e]=arguments[e];var t=n[0],r=n[1];return"string"==typeof t?x(t,document):x(r,t)}function P(){for(var t=[],r=0;r<arguments.length;r++)t[r]=arguments[r];return n(this,void 0,void 0,(function(){var n,r,o,u,i;return e(this,(function(e){switch(e.label){case 0:return a(t)?(n=t[0],r=t[1],o=t[2],[4,q(r,n,(null==o?void 0:o.retries)||l,(null==o?void 0:o.delay)||c)]):[3,2];case 1:case 3:return[2,e.sent()];case 2:return u=t[0],i=t[1],[4,q(u,document,(null==i?void 0:i.retries)||l,(null==i?void 0:i.delay)||c)]}}))}))}function T(){for(var t=[],r=0;r<arguments.length;r++)t[r]=arguments[r];return n(this,void 0,void 0,(function(){var n,r,o,u,i;return e(this,(function(e){switch(e.label){case 0:return a(t)?(n=t[0],r=t[1],o=t[2],[4,E(r,n,(null==o?void 0:o.retries)||l,(null==o?void 0:o.delay)||c)]):[3,2];case 1:return[2,e.sent()];case 2:return u=t[0],i=t[1],[2,E(u,document,(null==i?void 0:i.retries)||l,(null==i?void 0:i.delay)||c)]}}))}))}function I(){for(var t=[],r=0;r<arguments.length;r++)t[r]=arguments[r];return n(this,void 0,void 0,(function(){var n,r,o,u,i;return e(this,(function(e){switch(e.label){case 0:return a(t)?(n=t[0],r=t[1],o=t[2],[4,A(r,n,(null==o?void 0:o.retries)||l,(null==o?void 0:o.delay)||c)]):[3,2];case 1:return[2,e.sent()];case 2:return u=t[0],i=t[1],[2,A(u,document,(null==i?void 0:i.retries)||l,(null==i?void 0:i.delay)||c)]}}))}))}export{P as asyncQuerySelector,T as asyncQuerySelectorAll,I as asyncShadowRootQuerySelector,Q as querySelector,k as querySelectorAll,D as shadowRootQuerySelector};

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+interface AsyncParams {
+    retries?: number;
+    delay?: number;
+}
+declare function querySelector<E extends Element = Element>(root: Document | Element, selectors: string): E | null;
+declare function querySelector<E extends Element = Element>(selectors: string): E | null;
+declare function querySelectorAll<E extends Element = Element>(root: Document | Element, selectors: string): NodeListOf<E>;
+declare function querySelectorAll<E extends Element = Element>(selectors: string): NodeListOf<E>;
+declare function shadowRootQuerySelector(root: Document | Element, selectors: string): ShadowRoot | null;
+declare function shadowRootQuerySelector(selectors: string): ShadowRoot | null;
+declare function asyncQuerySelector<E extends Element = Element>(root: Document | Element, selectors: string, asyncParams?: AsyncParams): Promise<E | null>;
+declare function asyncQuerySelector<E extends Element = Element>(selectors: string, asyncParams?: AsyncParams): Promise<E | null>;
+declare function asyncQuerySelectorAll<E extends Element = Element>(root: Document | Element, selectors: string, asyncParams?: AsyncParams): Promise<NodeListOf<E>>;
+declare function asyncQuerySelectorAll<E extends Element = Element>(selectors: string, asyncParams?: AsyncParams): Promise<NodeListOf<E>>;
+declare function asyncShadowRootQuerySelector(root: Document | Element, selectors: string, asyncParams?: AsyncParams): Promise<ShadowRoot | null>;
+declare function asyncShadowRootQuerySelector(selectors: string, asyncParams?: AsyncParams): Promise<ShadowRoot | null>;
+export { querySelector, querySelectorAll, shadowRootQuerySelector, asyncQuerySelector, asyncQuerySelectorAll, asyncShadowRootQuerySelector };

package/dist/index.js

@@ -0,0 +1 @@
+!function(e,n){"object"==typeof exports&&"undefined"!=typeof module?n(exports):"function"==typeof define&&define.amd?define(["exports"],n):n((e="undefined"!=typeof globalThis?globalThis:e||self).ShadowDomSelector={})}(this,(function(e){"use strict";function n(e,n,t,r){return new(t||(t=Promise))((function(o,u){function l(e){try{a(r.next(e))}catch(e){u(e)}}function c(e){try{a(r.throw(e))}catch(e){u(e)}}function a(e){var n;e.done?o(e.value):(n=e.value,n instanceof t?n:new t((function(e){e(n)}))).then(l,c)}a((r=r.apply(e,n||[])).next())}))}function t(e,n){var t,r,o,u,l={label:0,sent:function(){if(1&o[0])throw o[1];return o[1]},trys:[],ops:[]};return u={next:c(0),throw:c(1),return:c(2)},"function"==typeof Symbol&&(u[Symbol.iterator]=function(){return this}),u;function c(c){return function(a){return function(c){if(t)throw new TypeError("Generator is already executing.");for(;u&&(u=0,c[0]&&(l=0)),l;)try{if(t=1,r&&(o=2&c[0]?r.return:c[0]?r.throw||((o=r.return)&&o.call(r),0):r.next)&&!(o=o.call(r,c[1])).done)return o;switch(r=0,o&&(c=[2&c[0],o.value]),c[0]){case 0:case 1:o=c;break;case 4:return l.label++,{value:c[1],done:!1};case 5:l.label++,r=c[1],c=[0];continue;case 7:c=l.ops.pop(),l.trys.pop();continue;default:if(!(o=l.trys,(o=o.length>0&&o[o.length-1])||6!==c[0]&&2!==c[0])){l=0;continue}if(3===c[0]&&(!o||c[1]>o[0]&&c[1]<o[3])){l.label=c[1];break}if(6===c[0]&&l.label<o[1]){l.label=o[1],o=c;break}if(o&&l.label<o[2]){l.label=o[2],l.ops.push(c);break}o[2]&&l.ops.pop(),l.trys.pop();continue}c=n.call(e,l)}catch(e){c=[6,e],r=0}finally{t=o=0}if(5&c[0])throw c[1];return{value:c[0]?c[1]:void 0,done:!0}}([c,a])}}}function r(e,n,t){if(t||2===arguments.length)for(var r,o=0,u=n.length;o<u;o++)!r&&o in n||(r||(r=Array.prototype.slice.call(n,0,o)),r[o]=n[o]);return e.concat(r||Array.prototype.slice.call(n))}"function"==typeof SuppressedError&&SuppressedError;var o="$",u=":host",l="invalid selector",c=10,a=10,i=function(e){var n,t=e[0],r=e[1];return(n=t)&&(n instanceof Document||n instanceof Element)&&"string"==typeof r};function s(e,n){return function(e){return e.split(",").map((function(e){return e.trim()}))}(e).map((function(e){var t=function(e){return e.split(o).map((function(e){return e.trim()}))}(e);return n(t)}))}function f(e,n,t,r,o){return void 0===o&&(o=!1),new Promise((function(u){var c=0,a=function(){var i=o?e.querySelectorAll(n):e.querySelector(n);o&&i.length||!o&&null!==i?u(i):++c<t?setTimeout(a,r):u(o?document.querySelectorAll(l):null)};a()}))}function h(e,n,t){return new Promise((function(r){var o=0,u=function(){var l=e.shadowRoot;l?r(l):++o<n?setTimeout(u,t):r(null)};u()}))}function d(e,n){var t=n?" If you want to select a shadowRoot, use ".concat(n," instead."):"";return"".concat(e," cannot be used with a selector ending in a shadowRoot (").concat(o,").").concat(t)}function v(e,n){return"".concat(e," must be used with a selector ending in a shadowRoot (").concat(o,"). If you don't want to select a shadowRoot, use ").concat(n," instead.")}function y(){return"You can not select a shadowRoot (".concat(o,") of the document.")}function w(e,n){for(var t,r,o=null,l=e.length,c=0;c<l;c++){if(0===c)if(e[c].length)o=n.querySelector(e[c]);else{if(n instanceof Document)throw new SyntaxError(y());o=(null===(t=n.shadowRoot)||void 0===t?void 0:t.querySelector(e[++c]))||null}else o=(null===(r=o.shadowRoot)||void 0===r?void 0:r.querySelector("".concat(u," ").concat(e[c])))||null;if(null===o)return null}return o}function p(e,n){var t,o=r([],e,!0),l=o.pop();return o.length?(null===(t=w(o,n).shadowRoot)||void 0===t?void 0:t.querySelectorAll("".concat(u," ").concat(l)))||null:n.querySelectorAll(l)}function g(e,n){var t=w(e,n);return(null==t?void 0:t.shadowRoot)||null}function b(e,r,o,l){return n(this,void 0,void 0,(function(){var n,c,a,i,s,d;return t(this,(function(t){switch(t.label){case 0:n=null,c=e.length,a=0,t.label=1;case 1:if(!(a<c))return[3,15];if(0!==a)return[3,8];if(e[a].length)return[3,5];if(r instanceof Document)throw new SyntaxError(y());return r.shadowRoot?[4,f(r.shadowRoot,e[++a],o,l)]:[3,3];case 2:return i=t.sent(),[3,4];case 3:i=null,t.label=4;case 4:return n=i,[3,7];case 5:return[4,f(r,e[a],o,l)];case 6:n=t.sent(),t.label=7;case 7:return[3,13];case 8:return[4,h(n,o,l)];case 9:return(s=t.sent())?[4,f(s,"".concat(u," ").concat(e[a]),o,l)]:[3,11];case 10:return d=t.sent(),[3,12];case 11:d=null,t.label=12;case 12:n=d,t.label=13;case 13:if(null===n)return[2,null];t.label=14;case 14:return a++,[3,1];case 15:return[2,n]}}))}))}function S(e,o,l,c){return n(this,void 0,void 0,(function(){var n,a,i,s,d,v;return t(this,(function(t){switch(t.label){case 0:return n=r([],e,!0),a=n.pop(),n.length?[3,2]:[4,f(o,a,l,c,!0)];case 1:return[2,t.sent()];case 2:return[4,b(n,o,l,c)];case 3:return(i=t.sent())?[4,h(i,l,c)]:[3,5];case 4:return d=t.sent(),[3,6];case 5:d=null,t.label=6;case 6:return(s=d)?[4,f(s,"".concat(u," ").concat(a),l,c,!0)]:[3,8];case 7:return v=t.sent(),[3,9];case 8:v=null,t.label=9;case 9:return[2,v]}}))}))}function m(e,r,o,u){return n(this,void 0,void 0,(function(){var n,l;return t(this,(function(t){switch(t.label){case 0:return[4,b(e,r,o,u)];case 1:return(n=t.sent())?[4,h(n,o,u)]:[3,3];case 2:return l=t.sent(),[3,4];case 3:l=null,t.label=4;case 4:return[2,l]}}))}))}function R(e,n){for(var t=s(e,(function(e){if(!e[e.length-1].length)throw new SyntaxError(d("querySelector","shadowRootQuerySelector"));return e})),r=t.length,o=0;o<r;o++){var u=w(t[o],n);if(u)return u}return null}function x(e,n){for(var t=s(e,(function(e){if(!e[e.length-1].length)throw new SyntaxError(d("querySelectorAll"));return e})),r=t.length,o=0;o<r;o++){var u=p(t[o],n);if(null==u?void 0:u.length)return u}return document.querySelectorAll(l)}function q(e,n){for(var t=s(e,(function(e){if(e.pop().length)throw new SyntaxError(v("shadowRootQuerySelector","querySelector"));return e})),r=t.length,o=0;o<r;o++){var u=g(t[o],n);if(u)return u}return null}function A(e,r,o,u){return n(this,void 0,void 0,(function(){var n,l,c,a;return t(this,(function(t){switch(t.label){case 0:n=s(e,(function(e){if(!e[e.length-1].length)throw new SyntaxError(d("asyncQuerySelector","asyncShadowRootQuerySelector"));return e})),l=n.length,c=0,t.label=1;case 1:return c<l?[4,b(n[c],r,o,u)]:[3,4];case 2:if(a=t.sent())return[2,a];t.label=3;case 3:return c++,[3,1];case 4:return[2,null]}}))}))}function E(e,r,o,u){return n(this,void 0,void 0,(function(){var n,c,a,i;return t(this,(function(t){switch(t.label){case 0:n=s(e,(function(e){if(!e[e.length-1].length)throw new SyntaxError(d("asyncQuerySelectorAll"));return e})),c=n.length,a=0,t.label=1;case 1:return a<c?[4,S(n[a],r,o,u)]:[3,4];case 2:if(null==(i=t.sent())?void 0:i.length)return[2,i];t.label=3;case 3:return a++,[3,1];case 4:return[2,document.querySelectorAll(l)]}}))}))}function Q(e,r,o,u){return n(this,void 0,void 0,(function(){var n,l,c,a;return t(this,(function(t){switch(t.label){case 0:n=s(e,(function(e){if(e.pop().length)throw new SyntaxError(v("asyncShadowRootQuerySelector","asyncQuerySelector"));return e})),l=n.length,c=0,t.label=1;case 1:return c<l?[4,m(n[c],r,o,u)]:[3,4];case 2:if(a=t.sent())return[2,a];t.label=3;case 3:return c++,[3,1];case 4:return[2,null]}}))}))}e.asyncQuerySelector=function(){for(var e=[],r=0;r<arguments.length;r++)e[r]=arguments[r];return n(this,void 0,void 0,(function(){var n,r,o,u,l;return t(this,(function(t){switch(t.label){case 0:return i(e)?(n=e[0],r=e[1],o=e[2],[4,A(r,n,(null==o?void 0:o.retries)||c,(null==o?void 0:o.delay)||a)]):[3,2];case 1:case 3:return[2,t.sent()];case 2:return u=e[0],l=e[1],[4,A(u,document,(null==l?void 0:l.retries)||c,(null==l?void 0:l.delay)||a)]}}))}))},e.asyncQuerySelectorAll=function(){for(var e=[],r=0;r<arguments.length;r++)e[r]=arguments[r];return n(this,void 0,void 0,(function(){var n,r,o,u,l;return t(this,(function(t){switch(t.label){case 0:return i(e)?(n=e[0],r=e[1],o=e[2],[4,E(r,n,(null==o?void 0:o.retries)||c,(null==o?void 0:o.delay)||a)]):[3,2];case 1:return[2,t.sent()];case 2:return u=e[0],l=e[1],[2,E(u,document,(null==l?void 0:l.retries)||c,(null==l?void 0:l.delay)||a)]}}))}))},e.asyncShadowRootQuerySelector=function(){for(var e=[],r=0;r<arguments.length;r++)e[r]=arguments[r];return n(this,void 0,void 0,(function(){var n,r,o,u,l;return t(this,(function(t){switch(t.label){case 0:return i(e)?(n=e[0],r=e[1],o=e[2],[4,Q(r,n,(null==o?void 0:o.retries)||c,(null==o?void 0:o.delay)||a)]):[3,2];case 1:return[2,t.sent()];case 2:return u=e[0],l=e[1],[2,Q(u,document,(null==l?void 0:l.retries)||c,(null==l?void 0:l.delay)||a)]}}))}))},e.querySelector=function(){for(var e=[],n=0;n<arguments.length;n++)e[n]=arguments[n];var t=e[0],r=e[1];return"string"==typeof t?R(t,document):R(r,t)},e.querySelectorAll=function(){for(var e=[],n=0;n<arguments.length;n++)e[n]=arguments[n];var t=e[0],r=e[1];return"string"==typeof t?x(t,document):x(r,t)},e.shadowRootQuerySelector=function(){for(var e=[],n=0;n<arguments.length;n++)e[n]=arguments[n];var t=e[0],r=e[1];return"string"==typeof t?q(t,document):q(r,t)}}));

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "shadow-dom-selector",
+  "version": "1.0.0",
+  "description": "A very small JavaScript utility to query DOM elements through the Shadow Dom subtrees in a sync or an async way",
+  "keywords": [
+    "query-selector",
+    "dom",
+    "dom-query",
+    "dom-selector",
+    "shadow-dom",
+    "shadow-root",
+    "shadow-root-selector",
+    "shadow-root-query",
+    "query-selector-all",
+    "javascript-library",
+    "library"
+  ],
+  "main": "dist/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "author": "ElChiniNet",
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "yarn clean && rollup --config rollup.config.js --bundleConfigAsCjs",
+    "clean": "rm -rf dist .nyc_output coverage || true",
+    "demo": "rollup --config rollup.test.config.js --bundleConfigAsCjs -w",
+    "coverage:report": "nyc report --reporter=lcov --reporter=text-summary",
+    "lint": "eslint \"src/**/*.ts\" \"demo/**/*.ts\"",
+    "test": "cypress run",
+    "test:ts": "tsc --noEmit",
+    "test:open": "cypress open",
+    "test:ci": "start-server-and-test demo http://localhost:3000 test && yarn coverage:report",
+    "prepare": "yarn build",
+    "prepublishOnly": "yarn lint && yarn test:ts && yarn test:ci",
+    "version": "git add .",
+    "postversion": "git push && git push --tags"
+  },
+  "devDependencies": {
+    "@cypress/code-coverage": "^3.12.9",
+    "@types/eslint": "^8.44.7",
+    "@typescript-eslint/eslint-plugin": "^6.10.0",
+    "@typescript-eslint/parser": "^6.10.0",
+    "cypress": "^13.5.0",
+    "eslint": "^8.53.0",
+    "rollup": "^4.3.1",
+    "rollup-plugin-istanbul": "^5.0.0",
+    "rollup-plugin-serve": "^2.0.2",
+    "rollup-plugin-terser": "^7.0.2",
+    "rollup-plugin-ts": "^3.4.5",
+    "start-server-and-test": "^2.0.2",
+    "typescript": "^5.2.2"
+  }
+}