☰

wait-for-element

Provides utility functions to get and wait for elements asyncronously that are not yet loaded or available on the page.

Dette scriptet burde ikke installeres direkte. Det er et bibliotek for andre script å inkludere med det nye metadirektivet // @require https://update.greatest.deepsurf.us/scripts/488161/1335321/wait-for-element.js 

  1. // ==UserScript==
  2. // @name         wait-for-element
  3. // @description  Provides utility functions to query elements asyncronously that are not yet loaded or available on the page.
  4. // @version      0.1.1
  5. // @namespace    owowed.moe
  6. // @author       owowed <island@owowed.moe>
  7. // @license      LGPL-3.0
  8. // @require      https://update.greatest.deepsurf.us/scripts/488160/1335044/make-mutation-observer.js
  9. // ==/UserScript==
  10.  
  11. /**
  12.  * @typedef WaitForElementOptions Options that modify wait for element functions behavior.
  13.  * @prop {string} [id] Select element by id.
  14.  * @prop {string | string[]} selector Selector that matches target element. If `selector` is `string[]`, then `multiple` option is forced enabled.
  15.  * @prop {ParentNode} [parent] Parent element to start query select from. By default, it will query select from `document`.
  16.  * @prop {AbortSignal} [abortSignal] Abort signal to abort element querying.
  17.  * @prop {boolean} [multiple] Query multiple elements instead of a single one.
  18.  * @prop {number} [timeout] Set timeout for element querying. Reaching timeout will throw `WaitForElementTimeoutError`. If `undefined`, then timeout will be disabled.
  19.  * @prop {number} [maxTries] Set how many attempts function can do element querying. Reaching max tries will throw `WaitForElementMaxTriesError`.
  20.  * @prop {boolean} [ensureDomContentLoaded] Wait for `DOMContentLoad` event before execution, or if event already fired, it will be immediately executed.
  21.  * @prop {MutationObserverInit} [observerOptions] Set options for `MutationObserver` used in wait for element functions.
  22.  * @prop {(elem: HTMLElement) => boolean} [filter] Filter querying element.
  23.  * @prop {(elem: HTMLElement) => HTMLElement} [transform] Transform querying element.
  24.  * @prop {boolean} [throwError] Throw error in certain situation except for not finding an element, instead of returning `null`. By default, its set to `true`.
  25.  */
  26.  
  27. /**
  28.  * @typedef {Promise<Element[] | Element | null>} WaitForElementReturnValue
  29.  */
  30.  
  31. class WaitForElementError extends Error {
  32.     name = this.constructor.name;
  33. }
  34. class WaitForElementTimeoutError extends WaitForElementError {}
  35. class WaitForElementMaximumTriesError extends WaitForElementError {}
  36.  
  37. /**
  38.  * Query element asyncronously until the element is available on the page. This function immediately accepts `parent` as its first parameter. `parent` parameter will specify element to start query select from.
  39.  * @param {NonNullable<WaitForElementOptions["parent"]>} parent 
  40.  * @param {WaitForElementOptions["selector"]} selector 
  41.  * @param {WaitForElementOptions} options 
  42.  * @returns {WaitForElementReturnValue}
  43.  */
  44. function waitForElementByParent(parent, selector, options) {
  45.     return waitForElementOptions({ selector, parent, ...options });
  46. }
  47.  
  48. /**
  49.  * Query element asyncronously until the element is available on the page. This function immediately accepts `selector` as its first parameter.
  50.  * @param {WaitForElementOptions["selector"]} selector 
  51.  * @param {WaitForElementOptions} options 
  52.  * @returns {WaitForElementReturnValue}
  53.  */
  54. function waitForElement(selector, options) {
  55.     return waitForElementOptions({ selector, ...options });
  56. }
  57.  
  58. /**
  59.  * Query multiple elements asyncronously until the element is available on the page.
  60.  * @param {WaitForElementOptions["selector"]} selector 
  61.  * @param {WaitForElementOptions} options 
  62.  * @returns {WaitForElementReturnValue}
  63.  */
  64. function waitForElementAll(selectors, options) {
  65.     return waitForElementOptions({ selector: selectors, multiple: true, ...options });
  66. }
  67.  
  68. /**
  69.  * Query element asyncronously until the element is available on the page. This function immediately accepts `WaitForElementOptions` as its first parameter.
  70.  * @param {WaitForElementOptions} options 
  71.  * @returns {WaitForElementReturnValue}
  72.  */
  73. function waitForElementOptions(
  74.     { id,
  75.         selector,
  76.         parent = document.documentElement,
  77.         abortSignal, // abort controller signal
  78.         multiple = false,
  79.         timeout = 5000,
  80.         maxTries = Infinity,
  81.         ensureDomContentLoaded = true,
  82.         observerOptions = {},
  83.         filter,
  84.         transform,
  85.         throwError } = {}) {
  86.     /**
  87.      * function that apply filter and transform for multiple elements
  88.      * filter will always be applied first before transforming element
  89.      * @param {*} result result of element queries
  90.      */
  91.     function* applyFilterTransform(result) {
  92.         if (filter == undefined && transformFn == undefined) {
  93.             yield result;
  94.             return;
  95.         }
  96.         const filterFn = filter ?? (() => true);
  97.         const transformFn = transform ?? ((x) => x);
  98.         for (const elem of result) {
  99.             if (filterFn(elem)) {
  100.                 yield transformFn(elem);
  101.             }
  102.         }
  103.     }
  104.  
  105.     function queryElement() {
  106.         abortSignal?.throwIfAborted();
  107.  
  108.         if (id) {
  109.             return document.getElementById(id);
  110.         }
  111.         else if (multiple) {
  112.             if (Array.isArray(selector)) {
  113.                 selector = selector.join(", ");
  114.             }
  115.             return Array.from(applyFilterTransform(parent.querySelectorAll(selector)));
  116.         }
  117.         else if (Array.isArray(selector)) {
  118.             multiple = true;
  119.             return queryElement();
  120.         }
  121.         else {
  122.             let result = parent.querySelector(selector);
  123.  
  124.             if (transform) result = transform(result);
  125.     
  126.             if (filter != undefined && !filter(result)) {
  127.                 return null;
  128.             }
  129.     
  130.             return result;
  131.         }
  132.     }
  133.  
  134.     function waitForElement() {
  135.         const firstResult = queryElement();
  136.  
  137.         if (firstResult) return firstResult;
  138.         
  139.         return new Promise((resolve, reject) => {
  140.             let timeoutId = null;
  141.             let queryTries = 0;
  142.  
  143.             const observer = makeMutationObserver(
  144.                 parent,
  145.                 () => {
  146.                     const result = queryElement(observer);
  147.                     if (result != null && result.length != 0) {
  148.                         cleanup();
  149.                         resolve(result);
  150.                     }
  151.                     else if (queryTries >= maxTries) {
  152.                         cleanup();
  153.                         throwErrorOrNull(new WaitForElementMaximumTriesError(`maximum number of tries (${maxTries}) reached waiting for element "${selector}"`));
  154.                     }
  155.                 },
  156.                 {
  157.                     childList: true,
  158.                     subtree: true,
  159.                     abortSignal,
  160.                     ...observerOptions
  161.                 }
  162.             );
  163.     
  164.             if (timeout != undefined) {
  165.                 timeoutId = setTimeout(() => {
  166.                     cleanup();
  167.                     throwErrorOrNull(new WaitForElementTimeoutError(`timeout waiting for element "${selector}"`));
  168.                 }, timeout);
  169.             }
  170.     
  171.             abortSignal?.addEventListener("abort", () => {
  172.                 cleanup();
  173.                 throwErrorOrNull(new DOMException(abortSignal.reason, "AbortError"));
  174.             });
  175.  
  176.             function cleanup() {
  177.                 clearTimeout(timeoutId);
  178.                 observer?.disconnect();
  179.             }
  180.  
  181.             function throwErrorOrNull(error) {
  182.                 if (throwError) {
  183.                     reject(error);
  184.                 }
  185.                 else {
  186.                     resolve(null);
  187.                 }
  188.             }
  189.         });
  190.     }
  191.  
  192.     if (ensureDomContentLoaded && document.readyState == "loading") {
  193.         return new Promise((resolve, reject) => {
  194.             document.addEventListener("DOMContentLoaded", () => {
  195.                 waitForElement()
  196.                     .then((result) => resolve(result))
  197.                     .catch((reason) => reject(reason));
  198.             });
  199.         });
  200.     }
  201.     else {
  202.         return waitForElement();
  203.     }
  204. }