tiny-essentials 1.28.0 → 1.28.1

package/dist/v1/libs/TinyRadioFm.mjs

@@ -1,5 +1,7 @@
 import { EventEmitter } from 'events';
 import { blobUrlToBase64, convertToBlobUrl, parseMediaMetadata, revokeContentUrls, } from '../basics/mediaContent.mjs';
+import { createCheckDestroyed } from './utils.mjs';
+const checkDestroy = createCheckDestroyed('TinyRadioFm');
 /**
  * @typedef {import('../basics/mediaContent.mjs').MediaContentBase} MediaContentBase
  * @typedef {import('../basics/mediaContent.mjs').MediaContentMetadata} MediaContentMetadata
@@ -147,11 +149,17 @@ class TinyRadioFm extends EventEmitter {
             throw new TypeError('unknownArtist must have an string or function.');
         TinyRadioFm.#unknownArtist = value;
     }
+    /** @type {boolean} */
+    #destroyed = false;
+    get destroyed() {
+        return this.#destroyed;
+    }
     /**
      * Gets the total count of all content items (music and voice) in the system.
      * @returns {number}
      */
     get size() {
+        checkDestroy(this.#destroyed);
         return this.#musicList.length + this.#voiceList.length;
     }
     /**
@@ -159,6 +167,7 @@ class TinyRadioFm extends EventEmitter {
      * @returns {number}
      */
     get musicSize() {
+        checkDestroy(this.#destroyed);
         return this.#musicList.length;
     }
     /**
@@ -166,6 +175,7 @@ class TinyRadioFm extends EventEmitter {
      * @returns {number}
      */
     get voiceSize() {
+        checkDestroy(this.#destroyed);
         return this.#voiceList.length;
     }
     /**
@@ -173,6 +183,7 @@ class TinyRadioFm extends EventEmitter {
      * @returns {number}
      */
     get customPosSize() {
+        checkDestroy(this.#destroyed);
         return this.#customPositions.length;
     }
     /**
@@ -180,6 +191,7 @@ class TinyRadioFm extends EventEmitter {
      * @returns {number}
      */
     get tasksSize() {
+        checkDestroy(this.#destroyed);
         return this.#scheduledTasks.length;
     }
     /**
@@ -187,6 +199,7 @@ class TinyRadioFm extends EventEmitter {
      * @returns {number}
      */
     get cycleCacheSize() {
+        checkDestroy(this.#destroyed);
         return this.#cycleCache.size;
     }
     /** @type {MediaContent[]} */
@@ -196,6 +209,7 @@ class TinyRadioFm extends EventEmitter {
      * @returns {MediaContent[]}
      */
     get musicList() {
+        checkDestroy(this.#destroyed);
         return structuredClone(this.#musicList);
     }
     /** @type {MediaContent[]} */
@@ -205,6 +219,7 @@ class TinyRadioFm extends EventEmitter {
      * @returns {MediaContent[]}
      */
     get voiceList() {
+        checkDestroy(this.#destroyed);
         return structuredClone(this.#voiceList);
     }
     /** @type {CustomPosition[]} */
@@ -214,6 +229,7 @@ class TinyRadioFm extends EventEmitter {
      * @returns {CustomPosition[]}
      */
     get customPositions() {
+        checkDestroy(this.#destroyed);
         return structuredClone(this.#customPositions);
     }
     /** @type {ScheduledTask[]} */
@@ -223,6 +239,7 @@ class TinyRadioFm extends EventEmitter {
      * @returns {ScheduledTask[]}
      */
     get scheduledTasks() {
+        checkDestroy(this.#destroyed);
         return structuredClone(this.#scheduledTasks);
     }
     /**
@@ -230,6 +247,7 @@ class TinyRadioFm extends EventEmitter {
      * @returns {MediaContent[]} A cloned object of the cache.
      */
     get allList() {
+        checkDestroy(this.#destroyed);
         return [...this.musicList, ...this.voiceList];
     }
     /** @type {number} */
@@ -239,6 +257,7 @@ class TinyRadioFm extends EventEmitter {
      * @returns {number}
      */
     get seed() {
+        checkDestroy(this.#destroyed);
         return this.#seed;
     }
     /**
@@ -246,6 +265,7 @@ class TinyRadioFm extends EventEmitter {
      * @param {number} seed - The new seed.
      */
     set seed(seed) {
+        checkDestroy(this.#destroyed);
         if (typeof seed !== 'number')
             throw new TypeError('Seed must be a number.');
         this.#seed = seed;
@@ -259,6 +279,7 @@ class TinyRadioFm extends EventEmitter {
      * @returns {number}
      */
     get anchorDate() {
+        checkDestroy(this.#destroyed);
         return this.#anchorDate;
     }
     /** @type {Map<number, CycleBlock>} */
@@ -280,6 +301,7 @@ class TinyRadioFm extends EventEmitter {
      * @returns {RadioConfig}
      */
     get config() {
+        checkDestroy(this.#destroyed);
         return structuredClone(this.#config);
     }
     /**
@@ -288,6 +310,7 @@ class TinyRadioFm extends EventEmitter {
      * @throws {TypeError|RangeError} If the new configuration is invalid.
      */
     set config(config) {
+        checkDestroy(this.#destroyed);
         // Validate the entire object before applying it
         this.#validateConfig(config);
         this.#config = structuredClone(config);
@@ -377,6 +400,7 @@ class TinyRadioFm extends EventEmitter {
      * @throws {TypeError} If the type is invalid or the data lacks a valid ID and numerical duration.
      */
     add(type, data, smartQueue = true) {
+        checkDestroy(this.#destroyed);
         if (!['music', 'voice', 'custom'].includes(type)) {
             throw new TypeError('Type must be "music", "voice", or "custom".');
         }
@@ -410,6 +434,7 @@ class TinyRadioFm extends EventEmitter {
      * @throws {TypeError} If arguments do not match the required types or action/type constraints.
      */
     scheduleTask(timestamp, action, type, payload, smartQueue = true) {
+        checkDestroy(this.#destroyed);
         if (typeof timestamp !== 'number' || isNaN(timestamp))
             throw new TypeError('timestamp must be a valid number.');
         if (!['add', 'remove', 'move'].includes(action))
@@ -467,6 +492,7 @@ class TinyRadioFm extends EventEmitter {
      * @throws {TypeError} If the id is not a string.
      */
     remove(id) {
+        checkDestroy(this.#destroyed);
         if (typeof id !== 'string')
             throw new TypeError('id must be a string.');
         // Revoke Blob URLs of items being removed to free memory
@@ -505,6 +531,7 @@ class TinyRadioFm extends EventEmitter {
      * @throws {TypeError|RangeError} If the provided values or the resulting state is invalid.
      */
     setConfig(config) {
+        checkDestroy(this.#destroyed);
         // First, validate the incoming partial object for basic type correctness
         this.#validateConfig(config);
         // Create the potential new state
@@ -520,6 +547,7 @@ class TinyRadioFm extends EventEmitter {
      * @returns {RadioEvent|null} The current active event, or null if empty.
      */
     getCurrentEvent() {
+        checkDestroy(this.#destroyed);
         const now = Date.now();
         this.#syncRealTimeState(now);
         return this.#getEventAtTime(now, now);
@@ -534,6 +562,7 @@ class TinyRadioFm extends EventEmitter {
      * @throws {RangeError} If the limit exceeds the configured queryLimit or is <= 0.
      */
     queryTimeline(targetDate, limit = 10) {
+        checkDestroy(this.#destroyed);
         if (typeof limit !== 'number' || isNaN(limit)) {
             throw new TypeError(`Invalid query limit value. Ensure it is a number.`);
         }
@@ -565,6 +594,7 @@ class TinyRadioFm extends EventEmitter {
      * @returns {CustomPosition[]} Shallow copy of custom positions array.
      */
     searchCustomPositions() {
+        checkDestroy(this.#destroyed);
         this.#syncRealTimeState(Date.now());
         return [...this.#customPositions];
     }
@@ -607,6 +637,7 @@ class TinyRadioFm extends EventEmitter {
      * @returns {Promise<string>} Stringified JSON state.
      */
     async exportState() {
+        checkDestroy(this.#destroyed);
         const processedMusic = await this._processListForExport(this.#musicList);
         const processedVoice = await this._processListForExport(this.#voiceList);
         const processedCustom = await Promise.all(this.#customPositions.map(async (cp) => {
@@ -641,6 +672,7 @@ class TinyRadioFm extends EventEmitter {
      * @throws {TypeError} If json is not a valid string or object.
      */
     importState(json) {
+        checkDestroy(this.#destroyed);
         /** @type {TinyRadioFmImport} */
         let data;
         if (typeof json === 'string') {
@@ -1111,6 +1143,8 @@ class TinyRadioFm extends EventEmitter {
      * @param {boolean} [destroyThumbs=true]
      */
     destroy(destroyThumbs = true) {
+        if (this.#destroyed)
+            return;
         if (destroyThumbs) {
             this.#musicList.forEach((item) => revokeContentUrls(item));
             this.#voiceList.forEach((item) => revokeContentUrls(item));
@@ -1131,6 +1165,7 @@ class TinyRadioFm extends EventEmitter {
         this.#cycleCache.clear();
         this.emit('destroyed', { timestamp: Date.now() });
         this.removeAllListeners();
+        this.#destroyed = true;
     }
 }
 export default TinyRadioFm;

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.
      *