tiny-essentials 1.27.1 → 1.28.1

package/dist/v1/libs/TinyRateLimiter.cjs

@@ -1,5 +1,9 @@
 'use strict';
 
+var utils = require('./utils.cjs');
+
+const checkDestroy = utils.createCheckDestroyed('TinyRateLimiter');
+
 /**
  * Callback triggered when a group's stored hit history exceeds
  * the configured memory limit.
@@ -70,6 +74,21 @@
  * and safe to use in long-running Node.js processes.
  */
 class TinyRateLimiter {
+  /**
+   * Tracks whether the instance has been destroyed.
+   * @type {boolean}
+   */
+  #destroyed = false;
+
+  /**
+   * Gets the current destruction status of the instance.
+   *
+   * @returns {boolean} True if the instance is destroyed, false otherwise.
+   */
+  get destroyed() {
+    return this.#destroyed;
+  }
+
   /**
    * Maximum number of timestamps stored per group.
    * When exceeded, older entries are discarded.
@@ -186,6 +205,7 @@ class TinyRateLimiter {
    * @param {OnMemoryExceeded} callback
    */
   setOnMemoryExceeded(callback) {
+    checkDestroy(this.#destroyed);
     if (typeof callback !== 'function') throw new Error('onMemoryExceeded must be a function');
     this.#onMemoryExceeded = callback;
   }
@@ -194,6 +214,7 @@ class TinyRateLimiter {
    * Removes the memory-exceeded callback.
    */
   clearOnMemoryExceeded() {
+    checkDestroy(this.#destroyed);
     this.#onMemoryExceeded = null;
   }
 
@@ -213,6 +234,7 @@ class TinyRateLimiter {
    * @param {OnGroupExpired} callback - A function that receives the expired groupId.
    */
   setOnGroupExpired(callback) {
+    checkDestroy(this.#destroyed);
     if (typeof callback !== 'function') throw new Error('onGroupExpired must be a function');
     this.#onGroupExpired = callback;
   }
@@ -221,6 +243,7 @@ class TinyRateLimiter {
    * Removes the group-expiration callback.
    */
   clearOnGroupExpired() {
+    checkDestroy(this.#destroyed);
     this.#onGroupExpired = null;
   }
 
@@ -285,6 +308,7 @@ class TinyRateLimiter {
    * @returns {boolean}
    */
   isGroupId(id) {
+    checkDestroy(this.#destroyed);
     const result = this.groupFlags.get(id);
     return typeof result === 'boolean' ? result : false;
   }
@@ -295,6 +319,7 @@ class TinyRateLimiter {
    * @returns {string[]}
    */
   getUsersInGroup(groupId) {
+    checkDestroy(this.#destroyed);
     const users = [];
     for (const [userId, assignedGroup] of this.userToGroup.entries()) {
       if (assignedGroup === groupId) {
@@ -311,6 +336,7 @@ class TinyRateLimiter {
    * @param {number} ttl
    */
   setGroupTTL(groupId, ttl) {
+    checkDestroy(this.#destroyed);
     if (typeof ttl !== 'number' || !Number.isFinite(ttl) || ttl <= 0)
       throw new Error('TTL must be a positive number in milliseconds');
     this.groupTTL.set(groupId, ttl);
@@ -322,6 +348,7 @@ class TinyRateLimiter {
    * @returns {number|null}
    */
   getGroupTTL(groupId) {
+    checkDestroy(this.#destroyed);
     return this.groupTTL.get(groupId) ?? null;
   }
 
@@ -330,6 +357,7 @@ class TinyRateLimiter {
    * @param {string} groupId
    */
   deleteGroupTTL(groupId) {
+    checkDestroy(this.#destroyed);
     this.groupTTL.delete(groupId);
   }
 
@@ -344,6 +372,7 @@ class TinyRateLimiter {
    * @throws {Error} If the user belongs to another group
    */
   assignToGroup(userId, groupId) {
+    checkDestroy(this.#destroyed);
     const existingGroup = this.userToGroup.get(userId);
     if (existingGroup && existingGroup !== groupId)
       throw new Error(`User ${userId} is already assigned to group ${existingGroup}`);
@@ -391,6 +420,7 @@ class TinyRateLimiter {
    * @returns {string}
    */
   getGroupId(userId) {
+    checkDestroy(this.#destroyed);
     return this.userToGroup.get(userId) || userId; // fallback: use userId as own group
   }
 
@@ -417,6 +447,7 @@ class TinyRateLimiter {
    * @param {string} userId
    */
   hit(userId) {
+    checkDestroy(this.#destroyed);
     const groupId = this.getGroupId(userId);
     const now = Date.now();
 
@@ -470,6 +501,7 @@ class TinyRateLimiter {
    * @returns {boolean}
    */
   isRateLimited(userId) {
+    checkDestroy(this.#destroyed);
     const groupId = this.getGroupId(userId);
     if (!this.groupData.has(groupId)) return false;
 
@@ -501,6 +533,7 @@ class TinyRateLimiter {
    * @param {string} groupId
    */
   resetGroup(groupId) {
+    checkDestroy(this.#destroyed);
     this.groupFlags.delete(groupId);
     this.groupData.delete(groupId);
     this.lastSeen.delete(groupId);
@@ -512,6 +545,7 @@ class TinyRateLimiter {
    * @param {string} userId
    */
   resetUserGroup(userId) {
+    checkDestroy(this.#destroyed);
     this.userToGroup.delete(userId);
   }
 
@@ -521,6 +555,7 @@ class TinyRateLimiter {
    * @param {number[]} timestamps
    */
   setData(groupId, timestamps) {
+    checkDestroy(this.#destroyed);
     if (!Array.isArray(timestamps)) throw new Error('timestamps must be an array of numbers.');
     for (const t of timestamps) {
       if (typeof t !== 'number' || !Number.isFinite(t)) {
@@ -538,6 +573,7 @@ class TinyRateLimiter {
    * @returns {boolean}
    */
   hasData(groupId) {
+    checkDestroy(this.#destroyed);
     return this.groupData.has(groupId);
   }
 
@@ -547,6 +583,7 @@ class TinyRateLimiter {
    * @returns {number[]}
    */
   getData(groupId) {
+    checkDestroy(this.#destroyed);
     return this.groupData.get(groupId) || [];
   }
 
@@ -555,6 +592,7 @@ class TinyRateLimiter {
    * @returns {number}
    */
   getMaxIdle() {
+    checkDestroy(this.#destroyed);
     if (typeof this.#maxIdle !== 'number' || !Number.isFinite(this.#maxIdle) || this.#maxIdle < 0) {
       throw new Error("'maxIdle' must be a non-negative finite number.");
     }
@@ -566,6 +604,7 @@ class TinyRateLimiter {
    * @param {number} ms
    */
   setMaxIdle(ms) {
+    checkDestroy(this.#destroyed);
     if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0) {
       throw new Error("'maxIdle' must be a non-negative finite number.");
     }
@@ -599,6 +638,7 @@ class TinyRateLimiter {
    * @returns {string[]}
    */
   getActiveGroups() {
+    checkDestroy(this.#destroyed);
     return Array.from(this.groupData.keys());
   }
 
@@ -607,6 +647,7 @@ class TinyRateLimiter {
    * @returns {Record<string, string>}
    */
   getAllUserMappings() {
+    checkDestroy(this.#destroyed);
     return Object.fromEntries(this.userToGroup);
   }
 
@@ -619,6 +660,7 @@ class TinyRateLimiter {
    * @returns {number}
    */
   getInterval() {
+    checkDestroy(this.#destroyed);
     if (typeof this.#interval !== 'number' || !Number.isFinite(this.#interval)) {
       throw new Error("'interval' is not a valid finite number.");
     }
@@ -630,6 +672,7 @@ class TinyRateLimiter {
    * @returns {number}
    */
   getMaxHits() {
+    checkDestroy(this.#destroyed);
     if (typeof this.#maxHits !== 'number' || !Number.isFinite(this.#maxHits)) {
       throw new Error("'maxHits' is not a valid finite number.");
     }
@@ -642,6 +685,7 @@ class TinyRateLimiter {
    * @returns {number}
    */
   getTotalHits(groupId) {
+    checkDestroy(this.#destroyed);
     const history = this.groupData.get(groupId);
     return Array.isArray(history) ? history.length : 0;
   }
@@ -652,6 +696,7 @@ class TinyRateLimiter {
    * @returns {number|null}
    */
   getLastHit(groupId) {
+    checkDestroy(this.#destroyed);
     const history = this.groupData.get(groupId);
     return history?.length ? history[history.length - 1] : null;
   }
@@ -662,6 +707,7 @@ class TinyRateLimiter {
    * @returns {number|null}
    */
   getTimeSinceLastHit(groupId) {
+    checkDestroy(this.#destroyed);
     const last = this.getLastHit(groupId);
     return last !== null ? Date.now() - last : null;
   }
@@ -687,6 +733,7 @@ class TinyRateLimiter {
    * @returns {number|null}
    */
   getAverageHitSpacing(groupId) {
+    checkDestroy(this.#destroyed);
     return this._calculateAverageSpacing(this.groupData.get(groupId));
   }
 
@@ -701,6 +748,7 @@ class TinyRateLimiter {
    * }}
    */
   getMetrics(groupId) {
+    checkDestroy(this.#destroyed);
     const history = this.groupData.get(groupId);
 
     if (!Array.isArray(history) || history.length === 0) {
@@ -729,6 +777,7 @@ class TinyRateLimiter {
    * Destroy the rate limiter, stopping cleanup and clearing data
    */
   destroy() {
+    if (this.destroyed) return;
     if (this.#cleanupTimer) clearInterval(this.#cleanupTimer);
     this._cleanup();
     this.groupData.clear();
@@ -736,6 +785,9 @@ class TinyRateLimiter {
     this.userToGroup.clear();
     this.groupTTL.clear();
     this.groupFlags.clear();
+
+    // Lock the instance
+    this.#destroyed = true;
   }
 }
 

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

@@ -106,6 +106,12 @@ declare class TinyRateLimiter {
         cleanupInterval?: number | undefined;
         maxIdle?: number | undefined;
     });
+    /**
+     * Gets the current destruction status of the instance.
+     *
+     * @returns {boolean} True if the instance is destroyed, false otherwise.
+     */
+    get destroyed(): boolean;
     /**
      * Stores hit timestamps per group.
      *

package/dist/v1/libs/TinyRateLimiter.mjs

@@ -1,3 +1,5 @@
+import { createCheckDestroyed } from './utils.mjs';
+const checkDestroy = createCheckDestroyed('TinyRateLimiter');
 /**
  * Callback triggered when a group's stored hit history exceeds
  * the configured memory limit.
@@ -66,6 +68,19 @@
  * and safe to use in long-running Node.js processes.
  */
 class TinyRateLimiter {
+    /**
+     * Tracks whether the instance has been destroyed.
+     * @type {boolean}
+     */
+    #destroyed = false;
+    /**
+     * Gets the current destruction status of the instance.
+     *
+     * @returns {boolean} True if the instance is destroyed, false otherwise.
+     */
+    get destroyed() {
+        return this.#destroyed;
+    }
     /**
      * Maximum number of timestamps stored per group.
      * When exceeded, older entries are discarded.
@@ -170,6 +185,7 @@ class TinyRateLimiter {
      * @param {OnMemoryExceeded} callback
      */
     setOnMemoryExceeded(callback) {
+        checkDestroy(this.#destroyed);
         if (typeof callback !== 'function')
             throw new Error('onMemoryExceeded must be a function');
         this.#onMemoryExceeded = callback;
@@ -178,6 +194,7 @@ class TinyRateLimiter {
      * Removes the memory-exceeded callback.
      */
     clearOnMemoryExceeded() {
+        checkDestroy(this.#destroyed);
         this.#onMemoryExceeded = null;
     }
     /**
@@ -195,6 +212,7 @@ class TinyRateLimiter {
      * @param {OnGroupExpired} callback - A function that receives the expired groupId.
      */
     setOnGroupExpired(callback) {
+        checkDestroy(this.#destroyed);
         if (typeof callback !== 'function')
             throw new Error('onGroupExpired must be a function');
         this.#onGroupExpired = callback;
@@ -203,6 +221,7 @@ class TinyRateLimiter {
      * Removes the group-expiration callback.
      */
     clearOnGroupExpired() {
+        checkDestroy(this.#destroyed);
         this.#onGroupExpired = null;
     }
     /**
@@ -262,6 +281,7 @@ class TinyRateLimiter {
      * @returns {boolean}
      */
     isGroupId(id) {
+        checkDestroy(this.#destroyed);
         const result = this.groupFlags.get(id);
         return typeof result === 'boolean' ? result : false;
     }
@@ -271,6 +291,7 @@ class TinyRateLimiter {
      * @returns {string[]}
      */
     getUsersInGroup(groupId) {
+        checkDestroy(this.#destroyed);
         const users = [];
         for (const [userId, assignedGroup] of this.userToGroup.entries()) {
             if (assignedGroup === groupId) {
@@ -285,6 +306,7 @@ class TinyRateLimiter {
      * @param {number} ttl
      */
     setGroupTTL(groupId, ttl) {
+        checkDestroy(this.#destroyed);
         if (typeof ttl !== 'number' || !Number.isFinite(ttl) || ttl <= 0)
             throw new Error('TTL must be a positive number in milliseconds');
         this.groupTTL.set(groupId, ttl);
@@ -295,6 +317,7 @@ class TinyRateLimiter {
      * @returns {number|null}
      */
     getGroupTTL(groupId) {
+        checkDestroy(this.#destroyed);
         return this.groupTTL.get(groupId) ?? null;
     }
     /**
@@ -302,6 +325,7 @@ class TinyRateLimiter {
      * @param {string} groupId
      */
     deleteGroupTTL(groupId) {
+        checkDestroy(this.#destroyed);
         this.groupTTL.delete(groupId);
     }
     /**
@@ -315,6 +339,7 @@ class TinyRateLimiter {
      * @throws {Error} If the user belongs to another group
      */
     assignToGroup(userId, groupId) {
+        checkDestroy(this.#destroyed);
         const existingGroup = this.userToGroup.get(userId);
         if (existingGroup && existingGroup !== groupId)
             throw new Error(`User ${userId} is already assigned to group ${existingGroup}`);
@@ -363,6 +388,7 @@ class TinyRateLimiter {
      * @returns {string}
      */
     getGroupId(userId) {
+        checkDestroy(this.#destroyed);
         return this.userToGroup.get(userId) || userId; // fallback: use userId as own group
     }
     /**
@@ -388,6 +414,7 @@ class TinyRateLimiter {
      * @param {string} userId
      */
     hit(userId) {
+        checkDestroy(this.#destroyed);
         const groupId = this.getGroupId(userId);
         const now = Date.now();
         if (!this.groupData.has(groupId)) {
@@ -437,6 +464,7 @@ class TinyRateLimiter {
      * @returns {boolean}
      */
     isRateLimited(userId) {
+        checkDestroy(this.#destroyed);
         const groupId = this.getGroupId(userId);
         if (!this.groupData.has(groupId))
             return false;
@@ -468,6 +496,7 @@ class TinyRateLimiter {
      * @param {string} groupId
      */
     resetGroup(groupId) {
+        checkDestroy(this.#destroyed);
         this.groupFlags.delete(groupId);
         this.groupData.delete(groupId);
         this.lastSeen.delete(groupId);
@@ -478,6 +507,7 @@ class TinyRateLimiter {
      * @param {string} userId
      */
     resetUserGroup(userId) {
+        checkDestroy(this.#destroyed);
         this.userToGroup.delete(userId);
     }
     /**
@@ -486,6 +516,7 @@ class TinyRateLimiter {
      * @param {number[]} timestamps
      */
     setData(groupId, timestamps) {
+        checkDestroy(this.#destroyed);
         if (!Array.isArray(timestamps))
             throw new Error('timestamps must be an array of numbers.');
         for (const t of timestamps) {
@@ -504,6 +535,7 @@ class TinyRateLimiter {
      * @returns {boolean}
      */
     hasData(groupId) {
+        checkDestroy(this.#destroyed);
         return this.groupData.has(groupId);
     }
     /**
@@ -512,6 +544,7 @@ class TinyRateLimiter {
      * @returns {number[]}
      */
     getData(groupId) {
+        checkDestroy(this.#destroyed);
         return this.groupData.get(groupId) || [];
     }
     /**
@@ -519,6 +552,7 @@ class TinyRateLimiter {
      * @returns {number}
      */
     getMaxIdle() {
+        checkDestroy(this.#destroyed);
         if (typeof this.#maxIdle !== 'number' || !Number.isFinite(this.#maxIdle) || this.#maxIdle < 0) {
             throw new Error("'maxIdle' must be a non-negative finite number.");
         }
@@ -529,6 +563,7 @@ class TinyRateLimiter {
      * @param {number} ms
      */
     setMaxIdle(ms) {
+        checkDestroy(this.#destroyed);
         if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0) {
             throw new Error("'maxIdle' must be a non-negative finite number.");
         }
@@ -559,6 +594,7 @@ class TinyRateLimiter {
      * @returns {string[]}
      */
     getActiveGroups() {
+        checkDestroy(this.#destroyed);
         return Array.from(this.groupData.keys());
     }
     /**
@@ -566,6 +602,7 @@ class TinyRateLimiter {
      * @returns {Record<string, string>}
      */
     getAllUserMappings() {
+        checkDestroy(this.#destroyed);
         return Object.fromEntries(this.userToGroup);
     }
     /**
@@ -577,6 +614,7 @@ class TinyRateLimiter {
      * @returns {number}
      */
     getInterval() {
+        checkDestroy(this.#destroyed);
         if (typeof this.#interval !== 'number' || !Number.isFinite(this.#interval)) {
             throw new Error("'interval' is not a valid finite number.");
         }
@@ -587,6 +625,7 @@ class TinyRateLimiter {
      * @returns {number}
      */
     getMaxHits() {
+        checkDestroy(this.#destroyed);
         if (typeof this.#maxHits !== 'number' || !Number.isFinite(this.#maxHits)) {
             throw new Error("'maxHits' is not a valid finite number.");
         }
@@ -598,6 +637,7 @@ class TinyRateLimiter {
      * @returns {number}
      */
     getTotalHits(groupId) {
+        checkDestroy(this.#destroyed);
         const history = this.groupData.get(groupId);
         return Array.isArray(history) ? history.length : 0;
     }
@@ -607,6 +647,7 @@ class TinyRateLimiter {
      * @returns {number|null}
      */
     getLastHit(groupId) {
+        checkDestroy(this.#destroyed);
         const history = this.groupData.get(groupId);
         return history?.length ? history[history.length - 1] : null;
     }
@@ -616,6 +657,7 @@ class TinyRateLimiter {
      * @returns {number|null}
      */
     getTimeSinceLastHit(groupId) {
+        checkDestroy(this.#destroyed);
         const last = this.getLastHit(groupId);
         return last !== null ? Date.now() - last : null;
     }
@@ -640,6 +682,7 @@ class TinyRateLimiter {
      * @returns {number|null}
      */
     getAverageHitSpacing(groupId) {
+        checkDestroy(this.#destroyed);
         return this._calculateAverageSpacing(this.groupData.get(groupId));
     }
     /**
@@ -653,6 +696,7 @@ class TinyRateLimiter {
      * }}
      */
     getMetrics(groupId) {
+        checkDestroy(this.#destroyed);
         const history = this.groupData.get(groupId);
         if (!Array.isArray(history) || history.length === 0) {
             return {
@@ -677,6 +721,8 @@ class TinyRateLimiter {
      * Destroy the rate limiter, stopping cleanup and clearing data
      */
     destroy() {
+        if (this.destroyed)
+            return;
         if (this.#cleanupTimer)
             clearInterval(this.#cleanupTimer);
         this._cleanup();
@@ -685,6 +731,8 @@ class TinyRateLimiter {
         this.userToGroup.clear();
         this.groupTTL.clear();
         this.groupFlags.clear();
+        // Lock the instance
+        this.#destroyed = true;
     }
 }
 export default TinyRateLimiter;