tiny-essentials 1.16.1 → 1.16.2

package/dist/v1/libs/TinyAfterScrollWatcher.cjs

@@ -19,8 +19,8 @@ class TinyAfterScrollWatcher {
   /** @type {Element|Window} */
   #scrollTarget;
 
-  /** @type {number} */
-  lastScrollTime = 0;
+  /** @type {null|NodeJS.Timeout} */
+  #lastScrollTime = null;
 
   /** @type {FnData[]} */
   #afterScrollQueue = [];
@@ -31,6 +31,9 @@ class TinyAfterScrollWatcher {
   /** @type {Set<OnScrollFunc>} */
   #externalScrollListeners = new Set();
 
+  /** @type {Set<FnData>} */
+  #onStopListeners = new Set();
+
   /** @type {boolean} */
   #destroyed = false;
 
@@ -44,16 +47,20 @@ class TinyAfterScrollWatcher {
     if (!(scrollTarget instanceof Element) && !(scrollTarget instanceof Window))
       throw new TypeError('scrollTarget must be an Element or the Window object.');
     this.#scrollTarget = scrollTarget;
+    this._checkTimer = this._checkTimer.bind(this);
 
-    this._onScroll = this._onScroll.bind(this);
-    this._checkQueue = this._checkQueue.bind(this);
-
-    this.#scrollTarget.addEventListener('scroll', this._onScroll);
+    this.#scrollTarget.addEventListener('scroll', this._checkTimer);
     this.#inactivityTime = inactivityTime;
-
-    requestAnimationFrame(this._checkQueue);
   }
 
+  _checkTimer = () => {
+    if (this.#lastScrollTime) clearTimeout(this.#lastScrollTime);
+    this.#lastScrollTime = setTimeout(() => {
+      this.#lastScrollTime = null;
+      this.#checkQueue();
+    }, this.#inactivityTime);
+  };
+
   /**
    * Gets the current inactivity time in milliseconds.
    * @returns {number}
@@ -74,29 +81,21 @@ class TinyAfterScrollWatcher {
     this.#inactivityTime = value;
   }
 
-  /**
-   * Internal handler for scroll events.
-   * Updates the last scroll timestamp.
-   * @private
-   */
-  _onScroll() {
-    this.lastScrollTime = Date.now();
-  }
-
   /**
    * Continuously checks whether the user has stopped scrolling,
    * and if so, runs all queued functions.
-   * @private
    */
-  _checkQueue() {
+  #checkQueue() {
     if (this.#destroyed) return;
-    requestAnimationFrame(this._checkQueue);
+    // Runs all onStop first listeners
+    for (const fn of this.#onStopListeners) {
+      if (typeof fn === 'function') fn();
+    }
 
-    if (Date.now() - this.lastScrollTime > this.#inactivityTime) {
-      while (this.#afterScrollQueue.length) {
-        const fn = this.#afterScrollQueue.pop();
-        if (typeof fn === 'function') fn();
-      }
+    // Then execute the queue afterScrollQueue
+    while (this.#afterScrollQueue.length) {
+      const fn = this.#afterScrollQueue.pop();
+      if (typeof fn === 'function') fn();
     }
   }
 
@@ -113,6 +112,29 @@ class TinyAfterScrollWatcher {
     this.#afterScrollQueue.push(fn);
   }
 
+  /**
+   * Registers a function to run once after scrolling has stopped,
+   * before any afterScrollQueue functions.
+   *
+   * @param {FnData} fn - A function to execute after scroll stop.
+   * @throws {TypeError} If the argument is not a function.
+   */
+  onStop(fn) {
+    if (typeof fn !== 'function') throw new TypeError('Argument must be a function.');
+    this.#onStopListeners.add(fn);
+  }
+
+  /**
+   * Removes a previously registered onStop function.
+   *
+   * @param {FnData} fn - The function to remove.
+   * @throws {TypeError} If the argument is not a function.
+   */
+  offStop(fn) {
+    if (typeof fn !== 'function') throw new TypeError('Argument must be a function.');
+    this.#onStopListeners.delete(fn);
+  }
+
   /**
    * Registers an external scroll listener on the tracked element.
    *
@@ -146,11 +168,12 @@ class TinyAfterScrollWatcher {
     if (this.#destroyed) return;
     this.#destroyed = true;
 
-    this.#scrollTarget.removeEventListener('scroll', this._onScroll);
+    this.#scrollTarget.removeEventListener('scroll', this._checkTimer);
     for (const fn of this.#externalScrollListeners)
       this.#scrollTarget.removeEventListener('scroll', fn);
 
     this.#externalScrollListeners.clear();
+    this.#onStopListeners.clear();
   }
 }
 

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

@@ -29,20 +29,7 @@ declare class TinyAfterScrollWatcher {
      * @throws {TypeError} If inactivityTime is not a positive number
      */
     constructor(scrollTarget?: Element | Window, inactivityTime?: number);
-    /** @type {number} */
-    lastScrollTime: number;
-    /**
-     * Internal handler for scroll events.
-     * Updates the last scroll timestamp.
-     * @private
-     */
-    private _onScroll;
-    /**
-     * Continuously checks whether the user has stopped scrolling,
-     * and if so, runs all queued functions.
-     * @private
-     */
-    private _checkQueue;
+    _checkTimer: () => void;
     /**
      * Sets a new inactivity time.
      * Must be a positive number (in milliseconds).
@@ -63,6 +50,22 @@ declare class TinyAfterScrollWatcher {
      * @throws {TypeError} If the argument is not a function.
      */
     doAfterScroll(fn: () => void): void;
+    lastScrollTime: number | undefined;
+    /**
+     * Registers a function to run once after scrolling has stopped,
+     * before any afterScrollQueue functions.
+     *
+     * @param {FnData} fn - A function to execute after scroll stop.
+     * @throws {TypeError} If the argument is not a function.
+     */
+    onStop(fn: FnData): void;
+    /**
+     * Removes a previously registered onStop function.
+     *
+     * @param {FnData} fn - The function to remove.
+     * @throws {TypeError} If the argument is not a function.
+     */
+    offStop(fn: FnData): void;
     /**
      * Registers an external scroll listener on the tracked element.
      *

package/dist/v1/libs/TinyAfterScrollWatcher.mjs

@@ -14,14 +14,16 @@
 class TinyAfterScrollWatcher {
     /** @type {Element|Window} */
     #scrollTarget;
-    /** @type {number} */
-    lastScrollTime = 0;
+    /** @type {null|NodeJS.Timeout} */
+    #lastScrollTime = null;
     /** @type {FnData[]} */
     #afterScrollQueue = [];
     /** @type {number} */
     #inactivityTime = 100;
     /** @type {Set<OnScrollFunc>} */
     #externalScrollListeners = new Set();
+    /** @type {Set<FnData>} */
+    #onStopListeners = new Set();
     /** @type {boolean} */
     #destroyed = false;
     /**
@@ -34,12 +36,18 @@ class TinyAfterScrollWatcher {
         if (!(scrollTarget instanceof Element) && !(scrollTarget instanceof Window))
             throw new TypeError('scrollTarget must be an Element or the Window object.');
         this.#scrollTarget = scrollTarget;
-        this._onScroll = this._onScroll.bind(this);
-        this._checkQueue = this._checkQueue.bind(this);
-        this.#scrollTarget.addEventListener('scroll', this._onScroll);
+        this._checkTimer = this._checkTimer.bind(this);
+        this.#scrollTarget.addEventListener('scroll', this._checkTimer);
         this.#inactivityTime = inactivityTime;
-        requestAnimationFrame(this._checkQueue);
     }
+    _checkTimer = () => {
+        if (this.#lastScrollTime)
+            clearTimeout(this.#lastScrollTime);
+        this.#lastScrollTime = setTimeout(() => {
+            this.#lastScrollTime = null;
+            this.#checkQueue();
+        }, this.#inactivityTime);
+    };
     /**
      * Gets the current inactivity time in milliseconds.
      * @returns {number}
@@ -58,29 +66,23 @@ class TinyAfterScrollWatcher {
             throw new Error('inactivityTime must be a positive number in milliseconds.');
         this.#inactivityTime = value;
     }
-    /**
-     * Internal handler for scroll events.
-     * Updates the last scroll timestamp.
-     * @private
-     */
-    _onScroll() {
-        this.lastScrollTime = Date.now();
-    }
     /**
      * Continuously checks whether the user has stopped scrolling,
      * and if so, runs all queued functions.
-     * @private
      */
-    _checkQueue() {
+    #checkQueue() {
         if (this.#destroyed)
             return;
-        requestAnimationFrame(this._checkQueue);
-        if (Date.now() - this.lastScrollTime > this.#inactivityTime) {
-            while (this.#afterScrollQueue.length) {
-                const fn = this.#afterScrollQueue.pop();
-                if (typeof fn === 'function')
-                    fn();
-            }
+        // Runs all onStop first listeners
+        for (const fn of this.#onStopListeners) {
+            if (typeof fn === 'function')
+                fn();
+        }
+        // Then execute the queue afterScrollQueue
+        while (this.#afterScrollQueue.length) {
+            const fn = this.#afterScrollQueue.pop();
+            if (typeof fn === 'function')
+                fn();
         }
     }
     /**
@@ -96,6 +98,29 @@ class TinyAfterScrollWatcher {
         this.lastScrollTime = Date.now();
         this.#afterScrollQueue.push(fn);
     }
+    /**
+     * Registers a function to run once after scrolling has stopped,
+     * before any afterScrollQueue functions.
+     *
+     * @param {FnData} fn - A function to execute after scroll stop.
+     * @throws {TypeError} If the argument is not a function.
+     */
+    onStop(fn) {
+        if (typeof fn !== 'function')
+            throw new TypeError('Argument must be a function.');
+        this.#onStopListeners.add(fn);
+    }
+    /**
+     * Removes a previously registered onStop function.
+     *
+     * @param {FnData} fn - The function to remove.
+     * @throws {TypeError} If the argument is not a function.
+     */
+    offStop(fn) {
+        if (typeof fn !== 'function')
+            throw new TypeError('Argument must be a function.');
+        this.#onStopListeners.delete(fn);
+    }
     /**
      * Registers an external scroll listener on the tracked element.
      *
@@ -129,10 +154,11 @@ class TinyAfterScrollWatcher {
         if (this.#destroyed)
             return;
         this.#destroyed = true;
-        this.#scrollTarget.removeEventListener('scroll', this._onScroll);
+        this.#scrollTarget.removeEventListener('scroll', this._checkTimer);
         for (const fn of this.#externalScrollListeners)
             this.#scrollTarget.removeEventListener('scroll', fn);
         this.#externalScrollListeners.clear();
+        this.#onStopListeners.clear();
     }
 }
 export default TinyAfterScrollWatcher;

package/docs/v1/libs/TinyAfterScrollWatcher.md

@@ -10,7 +10,8 @@ Perfect for optimizing logic that should only run **after** the user has finishe
 * ✅ Works on any scrollable element or the window
 * ⏱️ Customizable "inactivity timeout" (default: `100ms`)
 * 🧠 Executes queued callbacks after scroll ends
-* 🧩 Add/remove your own scroll listeners easily (`onScroll` / `offScroll`)
+* 🧷 Add/remove scroll listeners easily (`onScroll` / `offScroll`)
+* 🛑 Execute logic right before after-scroll queue (`onStop`)
 * 🧹 Cleanly destroy the instance when no longer needed
 
 ---
@@ -36,6 +37,11 @@ watcher.doAfterScroll(() => {
   console.log('Scroll has stopped for 300ms!');
 });
 
+// Add a function to run immediately when scroll stops
+watcher.onStop(() => {
+  console.log('User just stopped scrolling!');
+});
+
 // Add a custom scroll listener
 const myScrollHandler = () => console.log('Scrolling...');
 watcher.onScroll(myScrollHandler);
@@ -43,6 +49,9 @@ watcher.onScroll(myScrollHandler);
 // Remove it later
 watcher.offScroll(myScrollHandler);
 
+// Also remove onStop listener
+watcher.offStop(myStopFunction);
+
 // Fully destroy the watcher
 watcher.destroy();
 ```
@@ -106,6 +115,46 @@ doAfterScroll(fn: FnData): void
 
 ---
 
+### 🛑 Method: `onStop(fn)`
+
+Registers a function to be called **immediately after scrolling stops**, but **before** the `doAfterScroll` queue is executed.
+
+```ts
+onStop(fn: FnData): void
+```
+
+#### Parameters:
+
+| Name | Type     | Description                                     |
+| ---- | -------- | ----------------------------------------------- |
+| `fn` | `FnData` | Function to call as soon as scroll has stopped. |
+
+#### Throws:
+
+* `TypeError` if the argument is not a function.
+
+---
+
+### 🔁 Method: `offStop(fn)`
+
+Removes a function previously registered with `onStop`.
+
+```ts
+offStop(fn: FnData): void
+```
+
+#### Parameters:
+
+| Name | Type     | Description                        |
+| ---- | -------- | ---------------------------------- |
+| `fn` | `FnData` | Function to remove from onStop set |
+
+#### Throws:
+
+* `TypeError` if the argument is not a function.
+
+---
+
 ### 🧷 Method: `onScroll(fn)`
 
 Registers a custom scroll listener on the tracked element.
@@ -176,6 +225,7 @@ type OnScrollFunc = (ev: Event) => void;
 
 ## 📝 Notes
 
-* The scroll queue is **LIFO** (last-in, first-out)
-* The internal check loop uses `requestAnimationFrame`, so it's efficient
-* Setting `inactivityTime` to a lower value makes it more sensitive
+* `onStop` functions are called **before** the `doAfterScroll` queue.
+* The `doAfterScroll` queue runs in **LIFO** order (last-in, first-out).
+* `requestAnimationFrame` is used for efficient polling.
+* Lower `inactivityTime` makes scroll-stop detection more responsive.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.16.1",
+  "version": "1.16.2",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",