tiny-essentials 1.27.1 → 1.28.1

package/dist/v1/libs/TinyMediaPlayer.cjs

@@ -1,7 +1,10 @@
 'use strict';
 
-var TinyEvents = require('./TinyEvents.cjs');
+var events = require('events');
 var mediaContent = require('../basics/mediaContent.cjs');
+var utils = require('./utils.cjs');
+
+const checkDestroy = utils.createCheckDestroyed('TinyMediaPlayer');
 
 /**
  * @typedef {import('../basics/mediaContent.mjs').MediaContent} MediaContent
@@ -107,7 +110,7 @@ class BaseMediaAdapter {
 /**
  * A universal media player manager capable of orchestrating multiple API adapters.
  */
-class TinyMediaPlayer extends TinyEvents {
+class TinyMediaPlayer extends events.EventEmitter {
   static BaseMediaAdapter = BaseMediaAdapter;
 
   /**
@@ -160,6 +163,13 @@ class TinyMediaPlayer extends TinyEvents {
     );
   }
 
+  /** @type {boolean} */
+  #destroyed = false;
+
+  get destroyed() {
+    return this.#destroyed;
+  }
+
   /** @type {Map<string, BaseMediaAdapter>} */
   #adapters = new Map();
 
@@ -289,6 +299,7 @@ class TinyMediaPlayer extends TinyEvents {
 
   /** @returns {MediaContent[]} A shallow copy of the current playlist. */
   get playlist() {
+    checkDestroy(this.#destroyed);
     return [...this.#playlist];
   }
 
@@ -297,6 +308,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @throws {TypeError} If the value is not an array.
    */
   set playlist(value) {
+    checkDestroy(this.#destroyed);
     if (!Array.isArray(value)) {
       throw new TypeError('Playlist must be an array of MediaContent objects.');
     }
@@ -343,6 +355,7 @@ class TinyMediaPlayer extends TinyEvents {
 
   /** @returns {number} The current active index in the playlist. */
   get currentIndex() {
+    checkDestroy(this.#destroyed);
     return this.#currentIndex;
   }
 
@@ -352,6 +365,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @throws {RangeError} If the index is out of the playlist bounds (unless -1 for empty).
    */
   set currentIndex(value) {
+    checkDestroy(this.#destroyed);
     if (typeof value !== 'number') {
       throw new TypeError('Current index must be a number.');
     }
@@ -390,6 +404,7 @@ class TinyMediaPlayer extends TinyEvents {
 
   /** @returns {LoopModeType} The current loop configuration. */
   get loopMode() {
+    checkDestroy(this.#destroyed);
     return this.#loopMode;
   }
 
@@ -398,6 +413,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @throws {TypeError} If the value is not a valid LoopModeType.
    */
   set loopMode(value) {
+    checkDestroy(this.#destroyed);
     const validModes = ['NONE', 'TRACK', 'PLAYLIST'];
     if (!validModes.includes(value)) {
       throw new TypeError(`Loop mode must be one of: ${validModes.join(', ')}.`);
@@ -408,6 +424,7 @@ class TinyMediaPlayer extends TinyEvents {
 
   /** @returns {boolean} The current random mode status. */
   get isRandom() {
+    checkDestroy(this.#destroyed);
     return this.#isRandom;
   }
 
@@ -416,6 +433,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @throws {TypeError} If the value is not a boolean.
    */
   set isRandom(value) {
+    checkDestroy(this.#destroyed);
     if (typeof value !== 'boolean') {
       throw new TypeError('Random mode state must be a boolean.');
     }
@@ -425,11 +443,13 @@ class TinyMediaPlayer extends TinyEvents {
 
   /** @returns {boolean} True if media is actively playing. */
   get isPlaying() {
+    checkDestroy(this.#destroyed);
     return this.#isPlaying;
   }
 
   /** @returns {number} The current volume level (0.0 to 1.0). */
   get volume() {
+    checkDestroy(this.#destroyed);
     return this.#volume;
   }
 
@@ -439,6 +459,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @throws {RangeError} If the value is outside the 0.0 to 1.0 range.
    */
   set volume(value) {
+    checkDestroy(this.#destroyed);
     if (typeof value !== 'number') throw new TypeError('Volume must be a number.');
     if (value < 0 || value > 1)
       throw new RangeError('Volume must be tightly constrained between 0.0 and 1.0.');
@@ -460,6 +481,7 @@ class TinyMediaPlayer extends TinyEvents {
 
   /** @returns {boolean} Whether the volume cache is currently enabled. */
   get persistVolume() {
+    checkDestroy(this.#destroyed);
     return this.#persistVolume;
   }
 
@@ -468,6 +490,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @throws {TypeError} If the value is not a boolean.
    */
   set persistVolume(value) {
+    checkDestroy(this.#destroyed);
     if (typeof value !== 'boolean') {
       throw new TypeError('Persist volume parameter must be a boolean.');
     }
@@ -479,6 +502,7 @@ class TinyMediaPlayer extends TinyEvents {
 
   /** @returns {string} The localStorage key used for volume caching. */
   get volumeStorageKey() {
+    checkDestroy(this.#destroyed);
     return this.#volumeStorageKey;
   }
 
@@ -487,6 +511,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @throws {TypeError} If the value is not a string or is empty.
    */
   set volumeStorageKey(value) {
+    checkDestroy(this.#destroyed);
     if (typeof value !== 'string') {
       throw new TypeError('Volume storage key must be a string.');
     }
@@ -519,6 +544,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @throws {TypeError} If id is not a string or adapter is invalid.
    */
   registerAdapter(id, adapter) {
+    checkDestroy(this.#destroyed);
     if (typeof id !== 'string') {
       throw new TypeError('Adapter ID must be a string.');
     }
@@ -556,6 +582,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @throws {TypeError} If content is invalid or missing required base properties.
    */
   addTrack(content) {
+    checkDestroy(this.#destroyed);
     if (!content || typeof content !== 'object' || typeof content.url !== 'string')
       throw new TypeError('Track content must be a valid MediaContent object containing a URL.');
 
@@ -579,6 +606,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @throws {TypeError} If the index is not a number.
    */
   existsTrack(index) {
+    checkDestroy(this.#destroyed);
     if (typeof index !== 'number') {
       throw new TypeError('Index must be a number.');
     }
@@ -593,6 +621,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @throws {RangeError} If the index is out of bounds.
    */
   getTrack(index) {
+    checkDestroy(this.#destroyed);
     if (typeof index !== 'number') {
       throw new TypeError('Index must be a number.');
     }
@@ -610,6 +639,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @throws {RangeError} If the index is out of bounds.
    */
   async removeTrack(index) {
+    checkDestroy(this.#destroyed);
     if (typeof index !== 'number') {
       throw new TypeError('Index must be a number.');
     }
@@ -648,6 +678,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @throws {TypeError} If the query is neither a string nor a function.
    */
   searchTrack(query) {
+    checkDestroy(this.#destroyed);
     if (typeof query !== 'string' && typeof query !== 'function') {
       throw new TypeError('Search query must be a string or a boolean evaluation function.');
     }
@@ -681,6 +712,7 @@ class TinyMediaPlayer extends TinyEvents {
    * Clears the entire playlist and stops playback.
    */
   async clearPlaylist() {
+    checkDestroy(this.#destroyed);
     await this.stop();
     this.#playlist = [];
     this.#currentIndex = -1;
@@ -697,6 +729,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @returns {Promise<void>}
    */
   async play() {
+    checkDestroy(this.#destroyed);
     const adapter = this.#getActiveAdapter();
     if (!adapter) return;
 
@@ -712,6 +745,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @returns {Promise<void>}
    */
   async pause() {
+    checkDestroy(this.#destroyed);
     const adapter = this.#getActiveAdapter();
     if (!adapter) return;
 
@@ -725,6 +759,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @returns {Promise<void>}
    */
   async stop() {
+    checkDestroy(this.#destroyed);
     const adapter = this.#getActiveAdapter();
     if (!adapter) return;
 
@@ -738,6 +773,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @returns {Promise<void>}
    */
   async next() {
+    checkDestroy(this.#destroyed);
     if (this.#playlist.length === 0) return;
 
     await this.stop();
@@ -772,6 +808,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @returns {Promise<void>}
    */
   async prev() {
+    checkDestroy(this.#destroyed);
     if (this.#playlist.length === 0) return;
 
     await this.stop();
@@ -803,6 +840,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @returns {Promise<void>}
    */
   async seek(timeMs) {
+    checkDestroy(this.#destroyed);
     if (typeof timeMs !== 'number') {
       throw new TypeError('Seek time must be a number in milliseconds.');
     }
@@ -824,6 +862,7 @@ class TinyMediaPlayer extends TinyEvents {
    * @returns {Promise<void>}
    */
   async step(stepMs) {
+    checkDestroy(this.#destroyed);
     if (typeof stepMs !== 'number') {
       throw new TypeError('Step amount must be a number in milliseconds.');
     }
@@ -839,6 +878,39 @@ class TinyMediaPlayer extends TinyEvents {
 
     await this.seek(targetTime);
   }
+
+  /**
+   * Safely destroys the TinyMediaPlayer instance.
+   * This method stops active playback, clears the internal playlist,
+   * removes all registered media adapters, and detaches all event listeners
+   * to ensure proper garbage collection and prevent memory leaks.
+   *
+   * @returns {Promise<void>} A promise that resolves when the destruction sequence is complete.
+   */
+  async destroy() {
+    if (this.#destroyed) return;
+
+    // 1. Stop current playback if active to halt media processes
+    try {
+      if (this.#isPlaying) {
+        await this.stop();
+      }
+    } catch (error) {
+      console.warn('[TinyMediaPlayer] Non-fatal error during playback termination:', error);
+    }
+
+    // 2. Clear internal state variables
+    this.#playlist = [];
+    this.#currentIndex = -1;
+    this.#isPlaying = false;
+
+    // 3. Clear all registered API adapters
+    this.#adapters.clear();
+
+    // 4. Remove all event listeners inherited from EventEmitter
+    this.removeAllListeners();
+    this.#destroyed = true;
+  }
 }
 
 module.exports = TinyMediaPlayer;

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

@@ -42,7 +42,7 @@ export type SearchResult = {
 /**
  * A universal media player manager capable of orchestrating multiple API adapters.
  */
-declare class TinyMediaPlayer extends TinyEvents {
+declare class TinyMediaPlayer extends EventEmitter<any> {
     static BaseMediaAdapter: typeof BaseMediaAdapter;
     /**
      * @type {UnknownArtistGetter}
@@ -88,6 +88,7 @@ declare class TinyMediaPlayer extends TinyEvents {
      * @param {TinyMediaPlayerOptions} [options={}] - Configuration parameters for the player.
      */
     constructor(options?: TinyMediaPlayerOptions);
+    get destroyed(): boolean;
     /**
      * Calculates a random index based on the weighted probability of each track,
      * strictly excluding the currently active track to prevent immediate repetition.
@@ -236,9 +237,18 @@ declare class TinyMediaPlayer extends TinyEvents {
      * @returns {Promise<void>}
      */
     step(stepMs: number): Promise<void>;
+    /**
+     * Safely destroys the TinyMediaPlayer instance.
+     * This method stops active playback, clears the internal playlist,
+     * removes all registered media adapters, and detaches all event listeners
+     * to ensure proper garbage collection and prevent memory leaks.
+     *
+     * @returns {Promise<void>} A promise that resolves when the destruction sequence is complete.
+     */
+    destroy(): Promise<void>;
     #private;
 }
-import TinyEvents from './TinyEvents.mjs';
+import { EventEmitter } from 'events';
 /**
  * @typedef {import('../basics/mediaContent.mjs').MediaContent} MediaContent
  * @typedef {import('../basics/mediaContent.mjs').MediaContentBase} MediaContentBase

package/dist/v1/libs/TinyMediaPlayer.mjs

@@ -1,5 +1,7 @@
-import TinyEvents from './TinyEvents.mjs';
+import { EventEmitter } from 'events';
 import { getMediaContentBase, getMediaContentMetadata, parseMediaMetadata, valMediaContentMetadata, } from '../basics/mediaContent.mjs';
+import { createCheckDestroyed } from './utils.mjs';
+const checkDestroy = createCheckDestroyed('TinyMediaPlayer');
 /**
  * @typedef {import('../basics/mediaContent.mjs').MediaContent} MediaContent
  * @typedef {import('../basics/mediaContent.mjs').MediaContentBase} MediaContentBase
@@ -92,7 +94,7 @@ class BaseMediaAdapter {
 /**
  * A universal media player manager capable of orchestrating multiple API adapters.
  */
-class TinyMediaPlayer extends TinyEvents {
+class TinyMediaPlayer extends EventEmitter {
     static BaseMediaAdapter = BaseMediaAdapter;
     /**
      * @type {UnknownArtistGetter}
@@ -133,6 +135,11 @@ class TinyMediaPlayer extends TinyEvents {
     static async parseContent(source, defaultMetadata, metadata, parseFile, callbacks) {
         return parseMediaMetadata(source, defaultMetadata, metadata, parseFile, callbacks, TinyMediaPlayer.#unknownArtist);
     }
+    /** @type {boolean} */
+    #destroyed = false;
+    get destroyed() {
+        return this.#destroyed;
+    }
     /** @type {Map<string, BaseMediaAdapter>} */
     #adapters = new Map();
     /** @type {MediaContent[]} */
@@ -244,6 +251,7 @@ class TinyMediaPlayer extends TinyEvents {
     // ==========================================
     /** @returns {MediaContent[]} A shallow copy of the current playlist. */
     get playlist() {
+        checkDestroy(this.#destroyed);
         return [...this.#playlist];
     }
     /**
@@ -251,6 +259,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @throws {TypeError} If the value is not an array.
      */
     set playlist(value) {
+        checkDestroy(this.#destroyed);
         if (!Array.isArray(value)) {
             throw new TypeError('Playlist must be an array of MediaContent objects.');
         }
@@ -296,6 +305,7 @@ class TinyMediaPlayer extends TinyEvents {
     }
     /** @returns {number} The current active index in the playlist. */
     get currentIndex() {
+        checkDestroy(this.#destroyed);
         return this.#currentIndex;
     }
     /**
@@ -304,6 +314,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @throws {RangeError} If the index is out of the playlist bounds (unless -1 for empty).
      */
     set currentIndex(value) {
+        checkDestroy(this.#destroyed);
         if (typeof value !== 'number') {
             throw new TypeError('Current index must be a number.');
         }
@@ -341,6 +352,7 @@ class TinyMediaPlayer extends TinyEvents {
     }
     /** @returns {LoopModeType} The current loop configuration. */
     get loopMode() {
+        checkDestroy(this.#destroyed);
         return this.#loopMode;
     }
     /**
@@ -348,6 +360,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @throws {TypeError} If the value is not a valid LoopModeType.
      */
     set loopMode(value) {
+        checkDestroy(this.#destroyed);
         const validModes = ['NONE', 'TRACK', 'PLAYLIST'];
         if (!validModes.includes(value)) {
             throw new TypeError(`Loop mode must be one of: ${validModes.join(', ')}.`);
@@ -357,6 +370,7 @@ class TinyMediaPlayer extends TinyEvents {
     }
     /** @returns {boolean} The current random mode status. */
     get isRandom() {
+        checkDestroy(this.#destroyed);
         return this.#isRandom;
     }
     /**
@@ -364,6 +378,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @throws {TypeError} If the value is not a boolean.
      */
     set isRandom(value) {
+        checkDestroy(this.#destroyed);
         if (typeof value !== 'boolean') {
             throw new TypeError('Random mode state must be a boolean.');
         }
@@ -372,10 +387,12 @@ class TinyMediaPlayer extends TinyEvents {
     }
     /** @returns {boolean} True if media is actively playing. */
     get isPlaying() {
+        checkDestroy(this.#destroyed);
         return this.#isPlaying;
     }
     /** @returns {number} The current volume level (0.0 to 1.0). */
     get volume() {
+        checkDestroy(this.#destroyed);
         return this.#volume;
     }
     /**
@@ -384,6 +401,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @throws {RangeError} If the value is outside the 0.0 to 1.0 range.
      */
     set volume(value) {
+        checkDestroy(this.#destroyed);
         if (typeof value !== 'number')
             throw new TypeError('Volume must be a number.');
         if (value < 0 || value > 1)
@@ -405,6 +423,7 @@ class TinyMediaPlayer extends TinyEvents {
     }
     /** @returns {boolean} Whether the volume cache is currently enabled. */
     get persistVolume() {
+        checkDestroy(this.#destroyed);
         return this.#persistVolume;
     }
     /**
@@ -412,6 +431,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @throws {TypeError} If the value is not a boolean.
      */
     set persistVolume(value) {
+        checkDestroy(this.#destroyed);
         if (typeof value !== 'boolean') {
             throw new TypeError('Persist volume parameter must be a boolean.');
         }
@@ -422,6 +442,7 @@ class TinyMediaPlayer extends TinyEvents {
     }
     /** @returns {string} The localStorage key used for volume caching. */
     get volumeStorageKey() {
+        checkDestroy(this.#destroyed);
         return this.#volumeStorageKey;
     }
     /**
@@ -429,6 +450,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @throws {TypeError} If the value is not a string or is empty.
      */
     set volumeStorageKey(value) {
+        checkDestroy(this.#destroyed);
         if (typeof value !== 'string') {
             throw new TypeError('Volume storage key must be a string.');
         }
@@ -458,6 +480,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @throws {TypeError} If id is not a string or adapter is invalid.
      */
     registerAdapter(id, adapter) {
+        checkDestroy(this.#destroyed);
         if (typeof id !== 'string') {
             throw new TypeError('Adapter ID must be a string.');
         }
@@ -492,6 +515,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @throws {TypeError} If content is invalid or missing required base properties.
      */
     addTrack(content) {
+        checkDestroy(this.#destroyed);
         if (!content || typeof content !== 'object' || typeof content.url !== 'string')
             throw new TypeError('Track content must be a valid MediaContent object containing a URL.');
         /** @type {MediaContent} */
@@ -512,6 +536,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @throws {TypeError} If the index is not a number.
      */
     existsTrack(index) {
+        checkDestroy(this.#destroyed);
         if (typeof index !== 'number') {
             throw new TypeError('Index must be a number.');
         }
@@ -525,6 +550,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @throws {RangeError} If the index is out of bounds.
      */
     getTrack(index) {
+        checkDestroy(this.#destroyed);
         if (typeof index !== 'number') {
             throw new TypeError('Index must be a number.');
         }
@@ -541,6 +567,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @throws {RangeError} If the index is out of bounds.
      */
     async removeTrack(index) {
+        checkDestroy(this.#destroyed);
         if (typeof index !== 'number') {
             throw new TypeError('Index must be a number.');
         }
@@ -578,6 +605,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @throws {TypeError} If the query is neither a string nor a function.
      */
     searchTrack(query) {
+        checkDestroy(this.#destroyed);
         if (typeof query !== 'string' && typeof query !== 'function') {
             throw new TypeError('Search query must be a string or a boolean evaluation function.');
         }
@@ -605,6 +633,7 @@ class TinyMediaPlayer extends TinyEvents {
      * Clears the entire playlist and stops playback.
      */
     async clearPlaylist() {
+        checkDestroy(this.#destroyed);
         await this.stop();
         this.#playlist = [];
         this.#currentIndex = -1;
@@ -619,6 +648,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @returns {Promise<void>}
      */
     async play() {
+        checkDestroy(this.#destroyed);
         const adapter = this.#getActiveAdapter();
         if (!adapter)
             return;
@@ -633,6 +663,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @returns {Promise<void>}
      */
     async pause() {
+        checkDestroy(this.#destroyed);
         const adapter = this.#getActiveAdapter();
         if (!adapter)
             return;
@@ -645,6 +676,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @returns {Promise<void>}
      */
     async stop() {
+        checkDestroy(this.#destroyed);
         const adapter = this.#getActiveAdapter();
         if (!adapter)
             return;
@@ -657,6 +689,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @returns {Promise<void>}
      */
     async next() {
+        checkDestroy(this.#destroyed);
         if (this.#playlist.length === 0)
             return;
         await this.stop();
@@ -689,6 +722,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @returns {Promise<void>}
      */
     async prev() {
+        checkDestroy(this.#destroyed);
         if (this.#playlist.length === 0)
             return;
         await this.stop();
@@ -719,6 +753,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @returns {Promise<void>}
      */
     async seek(timeMs) {
+        checkDestroy(this.#destroyed);
         if (typeof timeMs !== 'number') {
             throw new TypeError('Seek time must be a number in milliseconds.');
         }
@@ -738,6 +773,7 @@ class TinyMediaPlayer extends TinyEvents {
      * @returns {Promise<void>}
      */
     async step(stepMs) {
+        checkDestroy(this.#destroyed);
         if (typeof stepMs !== 'number') {
             throw new TypeError('Step amount must be a number in milliseconds.');
         }
@@ -751,5 +787,35 @@ class TinyMediaPlayer extends TinyEvents {
             targetTime = 0;
         await this.seek(targetTime);
     }
+    /**
+     * Safely destroys the TinyMediaPlayer instance.
+     * This method stops active playback, clears the internal playlist,
+     * removes all registered media adapters, and detaches all event listeners
+     * to ensure proper garbage collection and prevent memory leaks.
+     *
+     * @returns {Promise<void>} A promise that resolves when the destruction sequence is complete.
+     */
+    async destroy() {
+        if (this.#destroyed)
+            return;
+        // 1. Stop current playback if active to halt media processes
+        try {
+            if (this.#isPlaying) {
+                await this.stop();
+            }
+        }
+        catch (error) {
+            console.warn('[TinyMediaPlayer] Non-fatal error during playback termination:', error);
+        }
+        // 2. Clear internal state variables
+        this.#playlist = [];
+        this.#currentIndex = -1;
+        this.#isPlaying = false;
+        // 3. Clear all registered API adapters
+        this.#adapters.clear();
+        // 4. Remove all event listeners inherited from EventEmitter
+        this.removeAllListeners();
+        this.#destroyed = true;
+    }
 }
 export default TinyMediaPlayer;