tiny-essentials 1.18.0 → 1.19.0

package/dist/v1/libs/TinySmartScroller.mjs

@@ -1,5 +1,6 @@
 import TinyHtml from './TinyHtml.mjs';
 import * as TinyCollision from '../basics/collision.mjs';
+import TinyEvents from './TinyEvents.mjs';
 /**
  * Represents the dimensions of a DOM element.
  *
@@ -42,6 +43,179 @@ import * as TinyCollision from '../basics/collision.mjs';
  */
 class TinySmartScroller {
     static Utils = { ...TinyCollision, TinyHtml };
+    #events = new TinyEvents();
+    /**
+     * Enables or disables throwing an error when the maximum number of listeners is exceeded.
+     *
+     * @param {boolean} shouldThrow - If true, an error will be thrown when the max is exceeded.
+     */
+    setThrowOnMaxListeners(shouldThrow) {
+        return this.#events.setThrowOnMaxListeners(shouldThrow);
+    }
+    /**
+     * Checks whether an error will be thrown when the max listener limit is exceeded.
+     *
+     * @returns {boolean} True if an error will be thrown, false if only a warning is shown.
+     */
+    getThrowOnMaxListeners() {
+        return this.#events.getThrowOnMaxListeners();
+    }
+    /////////////////////////////////////////////////////////////
+    /**
+     * Adds a listener to the beginning of the listeners array for the specified event.
+     *
+     * @param {string} event - Event name.
+     * @param {ScrollListenersFunc} handler - The callback function.
+     */
+    prependListener(event, handler) {
+        return this.#events.prependListener(event, handler);
+    }
+    /**
+     * Adds a one-time listener to the beginning of the listeners array for the specified event.
+     *
+     * @param {string} event - Event name.
+     * @param {ScrollListenersFunc} handler - The callback function.
+     * @returns {ScrollListenersFunc} - The wrapped handler used internally.
+     */
+    prependListenerOnce(event, handler) {
+        return this.#events.prependListenerOnce(event, handler);
+    }
+    //////////////////////////////////////////////////////////////////////
+    /**
+     * Adds a event listener.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {ScrollListenersFunc} handler - Callback function to be called when event fires.
+     */
+    appendListener(event, handler) {
+        return this.#events.appendListener(event, handler);
+    }
+    /**
+     * Registers an event listener that runs only once, then is removed.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {ScrollListenersFunc} handler - The callback function to run on event.
+     * @returns {ScrollListenersFunc} - The wrapped version of the handler.
+     */
+    appendListenerOnce(event, handler) {
+        return this.#events.appendListenerOnce(event, handler);
+    }
+    /**
+     * Adds a event listener.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {ScrollListenersFunc} handler - Callback function to be called when event fires.
+     */
+    on(event, handler) {
+        return this.#events.on(event, handler);
+    }
+    /**
+     * Registers an event listener that runs only once, then is removed.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {ScrollListenersFunc} handler - The callback function to run on event.
+     * @returns {ScrollListenersFunc} - The wrapped version of the handler.
+     */
+    once(event, handler) {
+        return this.#events.once(event, handler);
+    }
+    ////////////////////////////////////////////////////////////////////
+    /**
+     * Removes a previously registered event listener.
+     *
+     * @param {string} event - The name of the event to remove the handler from.
+     * @param {ScrollListenersFunc} handler - The specific callback function to remove.
+     */
+    off(event, handler) {
+        return this.#events.off(event, handler);
+    }
+    /**
+     * Removes all event listeners of a specific type from the element.
+     *
+     * @param {string} event - The event type to remove (e.g. 'onScrollBoundary').
+     */
+    offAll(event) {
+        return this.#events.offAll(event);
+    }
+    /**
+     * Removes all event listeners of all types from the element.
+     */
+    offAllTypes() {
+        return this.#events.offAllTypes();
+    }
+    ////////////////////////////////////////////////////////////
+    /**
+     * Returns the number of listeners for a given event.
+     *
+     * @param {string} event - The name of the event.
+     * @returns {number} Number of listeners for the event.
+     */
+    listenerCount(event) {
+        return this.#events.listenerCount(event);
+    }
+    /**
+     * Returns a copy of the array of listeners for the specified event.
+     *
+     * @param {string} event - The name of the event.
+     * @returns {ScrollListenersFunc[]} Array of listener functions.
+     */
+    listeners(event) {
+        return this.#events.listeners(event);
+    }
+    /**
+     * Returns a copy of the array of listeners for the specified event.
+     *
+     * @param {string} event - The name of the event.
+     * @returns {ScrollListenersFunc[]} Array of listener functions.
+     */
+    onceListeners(event) {
+        return this.#events.onceListeners(event);
+    }
+    /**
+     * Returns a copy of the internal listeners array for the specified event,
+     * including wrapper functions like those used by `.once()`.
+     * @param {string | symbol} event - The event name.
+     * @returns {ScrollListenersFunc[]} An array of raw listener functions.
+     */
+    allListeners(event) {
+        return this.#events.allListeners(event);
+    }
+    /**
+     * Returns an array of event names for which there are registered listeners.
+     *
+     * @returns {string[]} Array of registered event names.
+     */
+    eventNames() {
+        return this.#events.eventNames();
+    }
+    //////////////////////////////////////////////////////
+    /**
+     * Emits an event, triggering all registered handlers for that event.
+     *
+     * @param {string} event - The event name to emit.
+     * @param {...any} payload - Optional data to pass to each handler.
+     * @returns {boolean} True if any listeners were called, false otherwise.
+     */
+    emit(event, ...payload) {
+        return this.#events.emit(event, ...payload);
+    }
+    /**
+     * Sets the maximum number of listeners per event before a warning is shown.
+     *
+     * @param {number} n - The maximum number of listeners.
+     */
+    setMaxListeners(n) {
+        return this.#events.setMaxListeners(n);
+    }
+    /**
+     * Gets the maximum number of listeners allowed per event.
+     *
+     * @returns {number} The maximum number of listeners.
+     */
+    getMaxListeners() {
+        return this.#events.getMaxListeners();
+    }
+    ///////////////////////////////////////////////////
     /** @type {WeakMap<Element, NodeSizes>} */
     #oldSizes = new WeakMap();
     /** @type {WeakMap<Element, NodeSizes>} */
@@ -54,8 +228,6 @@ class TinySmartScroller {
     #newVisiblesByTime = new WeakMap();
     /** @type {WeakMap<Element, boolean>} */
     #oldVisiblesByTime = new WeakMap();
-    /** @type {Record<string, ScrollListenersFunc[]>} */
-    #scrollListeners = {};
     /** @type {ResizeObserver|null} */
     #resizeObserver = null;
     /** @type {MutationObserver|null} */
@@ -319,46 +491,6 @@ class TinySmartScroller {
             throw new TypeError('offSize(handler): handler must be a function');
         this.#sizeFilter.delete(handler);
     }
-    /**
-     * Adds a scroll-related event listener.
-     *
-     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
-     * @param {ScrollListenersFunc} handler - Callback function to be called when event fires.
-     */
-    on(event, handler) {
-        if (this.#destroyed)
-            return;
-        if (typeof event !== 'string')
-            throw new TypeError('on(event, handler): event name must be a string');
-        if (typeof handler !== 'function')
-            throw new TypeError('on(event, handler): handler must be a function');
-        if (!this.#scrollListeners[event])
-            this.#scrollListeners[event] = [];
-        this.#scrollListeners[event].push(handler);
-    }
-    /**
-     * Removes a previously registered scroll-related event listener.
-     *
-     * @param {string} event - The name of the event to remove the handler from.
-     * @param {ScrollListenersFunc} handler - The specific callback function to remove.
-     */
-    off(event, handler) {
-        if (this.#destroyed)
-            return;
-        if (typeof event !== 'string')
-            throw new TypeError('off(event, handler): event name must be a string');
-        if (typeof handler !== 'function')
-            throw new TypeError('off(event, handler): handler must be a function');
-        const listeners = this.#scrollListeners[event];
-        if (!Array.isArray(listeners))
-            return;
-        const index = listeners.indexOf(handler);
-        if (index !== -1)
-            listeners.splice(index, 1);
-        // Optionally clean up empty arrays (optional)
-        if (listeners.length === 0)
-            delete this.#scrollListeners[event];
-    }
     /**
      * Checks which elements inside the target are currently visible and updates internal maps.
      *
@@ -380,13 +512,10 @@ class TinySmartScroller {
      *
      * @param {string} event - Event name.
      * @param {*} [payload] - Optional event data payload.
+     * @deprecated - Use emit() instead.
      */
     _emit(event, payload) {
-        if (this.#destroyed)
-            return;
-        if (typeof event !== 'string')
-            throw new TypeError('_emit(event, payload): event name must be a string');
-        (this.#scrollListeners[event] || []).forEach((fn) => fn(payload));
+        this.emit(event, payload);
     }
     /**
      * Handles scroll events, calculates position-related statuses, and emits appropriate events.
@@ -428,13 +557,13 @@ class TinySmartScroller {
         this.#scrollPaused = !(this.#autoScrollBottom && this.#isAtBottom);
         this.#lastKnownScrollBottomOffset = scrollHeight - scrollTop - clientHeight;
         // Send results
-        this._emit('onScrollBoundary', { status: atResult, ...scrollResult, scrollCache });
-        this._emit('onExtraScrollBoundary', { status: atCustomResult, ...scrollResult, scrollCache });
+        this.emit('onScrollBoundary', { status: atResult, ...scrollResult, scrollCache });
+        this.emit('onExtraScrollBoundary', { status: atCustomResult, ...scrollResult, scrollCache });
         if (!this.#scrollPaused) {
-            this._emit('onAutoScroll', { ...scrollResult, scrollCache });
+            this.emit('onAutoScroll', { ...scrollResult, scrollCache });
         }
         else {
-            this._emit('onScrollPause', { ...scrollResult, scrollCache });
+            this.emit('onScrollPause', { ...scrollResult, scrollCache });
         }
     }
     /**
@@ -848,7 +977,7 @@ class TinySmartScroller {
         this.#newVisiblesByTime = new WeakMap();
         this.#oldVisiblesByTime = new WeakMap();
         // Cleans listeners and filters
-        this.#scrollListeners = {};
+        this.#events.offAllTypes();
         this.#sizeFilter.clear();
         this.#loadTags.clear();
     }

package/dist/v1/libs/TinyTimeout.cjs

@@ -0,0 +1,194 @@
+'use strict';
+
+/**
+ * A utility class to manage dynamically adjusted timeouts based on how often
+ * each unique ID is triggered. Also provides polling support for asynchronous conditions.
+ */
+class TinyTimeout {
+  /** @type {boolean} Whether this instance has been destroyed. */
+  #isDestroyed = false;
+
+  /** @type {boolean} Whether to allow auto-updating an ID's timeout config if `value` changes. */
+  #allowAutoConfigChange;
+
+  /** @type {number} The interval time (ms) used to decrement cooldown counters. */
+  #cooldownWatcherTime;
+
+  /** @type {NodeJS.Timeout|null} Reference to the internal cooldown interval. */
+  #cooldownWatcher = null;
+
+  /**
+   * Internal map that keeps track of how many times each ID has been triggered,
+   * along with the base multiplier used to calculate delays.
+   *
+   * @type {Map<string, { value: number, now: number }>}
+   */
+  #timeoutFixer = new Map();
+
+  /**
+   * Creates a new instance of TinyTimeout.
+   *
+   * @param {Object} [options={}] Optional configuration object.
+   * @param {number} [options.cooldownWatcherTime=5000] Interval in milliseconds for reducing `now` counters.
+   * @param {boolean} [options.allowAutoConfigChange=false] Whether to allow auto value changes for existing IDs.
+   */
+  constructor({ cooldownWatcherTime = 5000, allowAutoConfigChange = false } = {}) {
+    if (!Number.isFinite(cooldownWatcherTime) || cooldownWatcherTime <= 0)
+      throw new TypeError(`Expected 'cooldownWatcherTime' to be a positive number.`);
+    if (typeof allowAutoConfigChange !== 'boolean')
+      throw new TypeError(`Expected 'allowAutoConfigChange' to be a boolean.`);
+    this.#cooldownWatcherTime = cooldownWatcherTime;
+    this.#allowAutoConfigChange = allowAutoConfigChange;
+    this.setCooldownWatcherTime(cooldownWatcherTime);
+  }
+
+  /**
+   * Whether this instance has been destroyed and is no longer usable.
+   *
+   * @returns {boolean}
+   */
+  isDestroyed() {
+    return this.#isDestroyed;
+  }
+
+  /**
+   * Whether auto config change is enabled.
+   *
+   * @returns {boolean}
+   */
+  getAllowAutoConfigChange() {
+    return this.#allowAutoConfigChange;
+  }
+
+  /**
+   * Gets the interval time used for cooldown decrementing.
+   *
+   * @returns {number}
+   */
+  getCooldownWatcherTime() {
+    return this.#cooldownWatcherTime;
+  }
+
+  /**
+   * Sets whether to allow auto-updating an ID's timeout config if `value` changes.
+   *
+   * @param {boolean} value
+   */
+  setAllowAutoConfigChange(value) {
+    if (typeof value !== 'boolean') throw new TypeError(`Expected 'value' to be a boolean.`);
+    this.#allowAutoConfigChange = value;
+  }
+
+  /**
+   * Sets the cooldown watcher interval time.
+   * Automatically resets the interval if it was already running.
+   *
+   * @param {number} value
+   */
+  setCooldownWatcherTime(value) {
+    if (this.#isDestroyed) throw new Error('TinyTimeout has been destroyed.');
+    if (!Number.isFinite(value) || value <= 0)
+      throw new TypeError(`Expected 'value' to be a positive number.`);
+
+    this.#cooldownWatcherTime = value;
+
+    if (this.#cooldownWatcher) clearInterval(this.#cooldownWatcher);
+    this.#cooldownWatcher = setInterval(() => {
+      this.#timeoutFixer.forEach((data) => {
+        if (data.now > 0) data.now--;
+      });
+    }, this.#cooldownWatcherTime);
+  }
+
+  /**
+   * Schedules a callback using a dynamically adjusted timeout based on usage frequency.
+   * The more often an ID is triggered, the longer the timeout becomes,
+   * scaled by the provided `value`. Optionally, the delay can be limited by `limit`.
+   *
+   * @param {string} id - A unique identifier to track timeout usage.
+   * @param {Function} callback - The function to execute after the delay.
+   * @param {number} value - Base delay multiplier in milliseconds.
+   * @param {number|null} [limit=null] - Optional maximum delay cap.
+   * @returns {number} Handle to the scheduled timeout.
+   * @throws {Error} Throws if the instance has been destroyed or arguments are invalid.
+   */
+  set(id, callback, value, limit = null) {
+    if (this.#isDestroyed) throw new Error('TinyTimeout has been destroyed.');
+    if (typeof id !== 'string' || id.trim() === '')
+      throw new TypeError(`Expected 'id' to be a non-empty string.`);
+    if (typeof callback !== 'function')
+      throw new TypeError(`Expected 'callback' to be a function.`);
+    if (!Number.isFinite(value) || value < 0)
+      throw new TypeError(`Expected 'value' to be a non-negative number.`);
+    if (limit !== null && (!Number.isFinite(limit) || limit < 0))
+      throw new TypeError(`Expected 'limit' to be null or a non-negative number.`);
+
+    let entry = this.#timeoutFixer.get(id);
+    if (!entry || (this.#allowAutoConfigChange && value !== entry.value)) {
+      entry = { value, now: 0 };
+      this.#timeoutFixer.set(id, entry);
+    }
+
+    const delay = entry.value * entry.now;
+    entry.now++;
+
+    return setTimeout(callback, typeof limit === 'number' ? Math.min(delay, limit) : delay);
+  }
+
+  /**
+   * Waits until a provided function returns `true`, checking repeatedly at the defined interval.
+   * Useful for polling asynchronous conditions.
+   *
+   * @param {() => boolean} getValue - A function that returns `true` when the condition is met.
+   * @param {number} [checkInterval=100] - How often (in ms) to check the condition.
+   * @returns {Promise<void>} Resolves when the condition is met.
+   * @throws {TypeError} If arguments are invalid.
+   */
+  static waitForTrue(getValue, checkInterval = 100) {
+    if (typeof getValue !== 'function')
+      throw new TypeError(`Expected 'getValue' to be a function.`);
+    if (!Number.isFinite(checkInterval) || checkInterval <= 0)
+      throw new TypeError(`Expected 'checkInterval' to be a positive number.`);
+
+    return new Promise((resolve) => {
+      const interval = setInterval(() => {
+        if (getValue()) {
+          clearInterval(interval);
+          resolve();
+        }
+      }, checkInterval);
+    });
+  }
+
+  /**
+   * Instance version of `waitForTrue`, which defaults to using the instance's
+   * cooldownWatcherTime if not explicitly provided.
+   *
+   * @param {() => boolean} getValue - A function that returns `true` when the condition is met.
+   * @param {number|null} [checkInterval=100] - How often (in ms) to check the condition.
+   * @returns {Promise<void>} Resolves when the condition is met.
+   * @throws {Error} If the instance is destroyed or arguments are invalid.
+   */
+  waitForTrue(getValue, checkInterval = 100) {
+    if (this.#isDestroyed) throw new Error('TinyTimeout has been destroyed.');
+    if (typeof getValue !== 'function')
+      throw new TypeError(`Expected 'getValue' to be a function.`);
+    if (checkInterval !== null && (!Number.isFinite(checkInterval) || checkInterval <= 0))
+      throw new TypeError(`Expected 'checkInterval' to be null or a positive number.`);
+    return TinyTimeout.waitForTrue(getValue, checkInterval ?? this.#cooldownWatcherTime);
+  }
+
+  /**
+   * Cleans up all internal references and stops the cooldown watcher.
+   * After calling this, the instance becomes unusable.
+   */
+  destroy() {
+    if (this.#isDestroyed) return;
+    this.#isDestroyed = true;
+    if (this.#cooldownWatcher) clearInterval(this.#cooldownWatcher);
+    this.#cooldownWatcher = null;
+    this.#timeoutFixer.clear();
+  }
+}
+
+module.exports = TinyTimeout;

package/dist/v1/libs/TinyTimeout.d.mts

@@ -0,0 +1,89 @@
+export default TinyTimeout;
+/**
+ * A utility class to manage dynamically adjusted timeouts based on how often
+ * each unique ID is triggered. Also provides polling support for asynchronous conditions.
+ */
+declare class TinyTimeout {
+    /**
+     * Waits until a provided function returns `true`, checking repeatedly at the defined interval.
+     * Useful for polling asynchronous conditions.
+     *
+     * @param {() => boolean} getValue - A function that returns `true` when the condition is met.
+     * @param {number} [checkInterval=100] - How often (in ms) to check the condition.
+     * @returns {Promise<void>} Resolves when the condition is met.
+     * @throws {TypeError} If arguments are invalid.
+     */
+    static waitForTrue(getValue: () => boolean, checkInterval?: number): Promise<void>;
+    /**
+     * Creates a new instance of TinyTimeout.
+     *
+     * @param {Object} [options={}] Optional configuration object.
+     * @param {number} [options.cooldownWatcherTime=5000] Interval in milliseconds for reducing `now` counters.
+     * @param {boolean} [options.allowAutoConfigChange=false] Whether to allow auto value changes for existing IDs.
+     */
+    constructor({ cooldownWatcherTime, allowAutoConfigChange }?: {
+        cooldownWatcherTime?: number | undefined;
+        allowAutoConfigChange?: boolean | undefined;
+    });
+    /**
+     * Whether this instance has been destroyed and is no longer usable.
+     *
+     * @returns {boolean}
+     */
+    isDestroyed(): boolean;
+    /**
+     * Whether auto config change is enabled.
+     *
+     * @returns {boolean}
+     */
+    getAllowAutoConfigChange(): boolean;
+    /**
+     * Gets the interval time used for cooldown decrementing.
+     *
+     * @returns {number}
+     */
+    getCooldownWatcherTime(): number;
+    /**
+     * Sets whether to allow auto-updating an ID's timeout config if `value` changes.
+     *
+     * @param {boolean} value
+     */
+    setAllowAutoConfigChange(value: boolean): void;
+    /**
+     * Sets the cooldown watcher interval time.
+     * Automatically resets the interval if it was already running.
+     *
+     * @param {number} value
+     */
+    setCooldownWatcherTime(value: number): void;
+    /**
+     * Schedules a callback using a dynamically adjusted timeout based on usage frequency.
+     * The more often an ID is triggered, the longer the timeout becomes,
+     * scaled by the provided `value`. Optionally, the delay can be limited by `limit`.
+     *
+     * @param {string} id - A unique identifier to track timeout usage.
+     * @param {Function} callback - The function to execute after the delay.
+     * @param {number} value - Base delay multiplier in milliseconds.
+     * @param {number|null} [limit=null] - Optional maximum delay cap.
+     * @returns {number} Handle to the scheduled timeout.
+     * @throws {Error} Throws if the instance has been destroyed or arguments are invalid.
+     */
+    set(id: string, callback: Function, value: number, limit?: number | null): number;
+    /**
+     * Instance version of `waitForTrue`, which defaults to using the instance's
+     * cooldownWatcherTime if not explicitly provided.
+     *
+     * @param {() => boolean} getValue - A function that returns `true` when the condition is met.
+     * @param {number|null} [checkInterval=100] - How often (in ms) to check the condition.
+     * @returns {Promise<void>} Resolves when the condition is met.
+     * @throws {Error} If the instance is destroyed or arguments are invalid.
+     */
+    waitForTrue(getValue: () => boolean, checkInterval?: number | null): Promise<void>;
+    /**
+     * Cleans up all internal references and stops the cooldown watcher.
+     * After calling this, the instance becomes unusable.
+     */
+    destroy(): void;
+    #private;
+}
+//# sourceMappingURL=TinyTimeout.d.mts.map