tiny-essentials 1.18.1 → 1.19.0

package/dist/v1/libs/TinySmartScroller.cjs

@@ -2,6 +2,7 @@
 
 var TinyHtml = require('./TinyHtml.cjs');
 var collision = require('../basics/collision.cjs');
+var TinyEvents = require('./TinyEvents.cjs');
 
 /**
  * Represents the dimensions of a DOM element.
@@ -49,6 +50,205 @@ var collision = require('../basics/collision.cjs');
 class TinySmartScroller {
   static Utils = { ...collision, 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>} */
@@ -64,9 +264,6 @@ class TinySmartScroller {
   /** @type {WeakMap<Element, boolean>} */
   #oldVisiblesByTime = new WeakMap();
 
-  /** @type {Record<string, ScrollListenersFunc[]>} */
-  #scrollListeners = {};
-
   /** @type {ResizeObserver|null} */
   #resizeObserver = null;
   /** @type {MutationObserver|null} */
@@ -380,46 +577,6 @@ class TinySmartScroller {
     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.
    *
@@ -444,12 +601,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);
   }
 
   /**
@@ -495,13 +650,13 @@ class TinySmartScroller {
     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 });
     }
   }
 
@@ -967,7 +1122,7 @@ class TinySmartScroller {
     this.#oldVisiblesByTime = new WeakMap();
 
     // Cleans listeners and filters
-    this.#scrollListeners = {};
+    this.#events.offAllTypes();
     this.#sizeFilter.clear();
     this.#loadTags.clear();
   }

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

@@ -88,12 +88,45 @@ declare class TinySmartScroller {
         areElsCollTop: (rect1: ObjRect, rect2: ObjRect) => boolean;
         areElsCollBottom: (rect1: ObjRect, rect2: ObjRect) => boolean;
         areElsCollLeft: (rect1: ObjRect, rect2: ObjRect) => boolean;
-        areElsCollRight: (rect1: ObjRect, rect2: ObjRect) => boolean;
+        areElsCollRight: (//////////////////////////////////////////
+        /**
+         * 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.
+         */
+        rect1: ObjRect
+        /**
+         * 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.
+         */
+        , ////////////////////////////////////
+        /**
+         * 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.
+         */
+        rect2: ObjRect
+        /**
+         * 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.
+         */
+        ) => boolean;
         areElsCollPerfTop: (rect1: ObjRect, rect2: ObjRect) => boolean;
         areElsCollPerfBottom: (rect1: ObjRect, rect2: ObjRect) => boolean;
         areElsCollPerfLeft: (rect1: ObjRect, rect2: ObjRect) => boolean;
         areElsCollPerfRight: (rect1: ObjRect, rect2: ObjRect) => boolean;
-        areElsColliding: (rect1: ObjRect, rect2: ObjRect) => boolean;
+        areElsColliding: (/**
+         * 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.
+         */ rect1: ObjRect, rect2: ObjRect) => boolean;
         areElsPerfColliding: (rect1: ObjRect, rect2: ObjRect) => boolean;
         getElsColliding: (rect1: ObjRect, rect2: ObjRect) => string | null;
         getElsPerfColliding: (rect1: ObjRect, rect2: ObjRect) => "top" | "bottom" | "left" | "right" | null;
@@ -141,6 +174,134 @@ declare class TinySmartScroller {
         querySelector?: string | null | undefined;
         attributeFilter?: string[] | Set<string> | null | undefined;
     });
+    /**
+     * 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: boolean): void;
+    /**
+     * 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(): boolean;
+    /**
+     * 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: string, handler: ScrollListenersFunc): void;
+    /**
+     * 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: string, handler: ScrollListenersFunc): ScrollListenersFunc;
+    /**
+     * 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: string, handler: ScrollListenersFunc): void;
+    /**
+     * 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: string, handler: ScrollListenersFunc): ScrollListenersFunc;
+    /**
+     * 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: string, handler: ScrollListenersFunc): void;
+    /**
+     * 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: string, handler: ScrollListenersFunc): ScrollListenersFunc;
+    /**
+     * 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: string, handler: ScrollListenersFunc): void;
+    /**
+     * Removes all event listeners of a specific type from the element.
+     *
+     * @param {string} event - The event type to remove (e.g. 'onScrollBoundary').
+     */
+    offAll(event: string): void;
+    /**
+     * Removes all event listeners of all types from the element.
+     */
+    offAllTypes(): void;
+    /**
+     * 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: string): number;
+    /**
+     * 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: string): ScrollListenersFunc[];
+    /**
+     * 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: string): ScrollListenersFunc[];
+    /**
+     * 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: string | symbol): ScrollListenersFunc[];
+    /**
+     * Returns an array of event names for which there are registered listeners.
+     *
+     * @returns {string[]} Array of registered event names.
+     */
+    eventNames(): string[];
+    /**
+     * 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: string, ...payload: any[]): boolean;
+    /**
+     * Sets the maximum number of listeners per event before a warning is shown.
+     *
+     * @param {number} n - The maximum number of listeners.
+     */
+    setMaxListeners(n: number): void;
+    /**
+     * Gets the maximum number of listeners allowed per event.
+     *
+     * @returns {number} The maximum number of listeners.
+     */
+    getMaxListeners(): number;
     /**
      * Returns a size difference callback that only reacts when height changes, filtered by tag name.
      *
@@ -232,20 +393,6 @@ declare class TinySmartScroller {
      * @param {NodeSizesEvent} handler - The handler function to remove.
      */
     offSize(handler: NodeSizesEvent): void;
-    /**
-     * 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: string, handler: ScrollListenersFunc): void;
-    /**
-     * 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: string, handler: ScrollListenersFunc): void;
     /**
      * Checks which elements inside the target are currently visible and updates internal maps.
      *
@@ -260,6 +407,7 @@ declare class TinySmartScroller {
      *
      * @param {string} event - Event name.
      * @param {*} [payload] - Optional event data payload.
+     * @deprecated - Use emit() instead.
      */
     _emit(event: string, payload?: any): void;
     /**