tiny-essentials 1.28.0 → 1.28.2

package/dist/v1/libs/TinyMediaPlayer.mjs

@@ -1,15 +1,19 @@
 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').PictureDataType} PictureDataType
+ * @typedef {import('../basics/mediaContent.mjs').MediaContent<PictureDataType>} MediaContent
  * @typedef {import('../basics/mediaContent.mjs').MediaContentBase} MediaContentBase
- * @typedef {import('../basics/mediaContent.mjs').MediaContentMetadata} MediaContentMetadata
+ * @typedef {import('../basics/mediaContent.mjs').MediaContentMetadata<PictureDataType>} MediaContentMetadata
  * @typedef {import('../basics/mediaContent.mjs').ParseMediaContentMetadata} ParseMediaContentMetadata
  * @typedef {import('../basics/mediaContent.mjs').LoadingMediaProgress} LoadingMediaProgress
  * @typedef {import('../basics/mediaContent.mjs').MediaLoadingErrorData} MediaLoadingErrorData
  * @typedef {import('../basics/mediaContent.mjs').UnknownArtistGetter} UnknownArtistGetter
  */
 /**
+ * The loop configuration modes.
  * @typedef {'NONE' | 'TRACK' | 'PLAYLIST'} LoopModeType
  */
 /**
@@ -133,6 +137,11 @@ class TinyMediaPlayer extends EventEmitter {
     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 +253,7 @@ class TinyMediaPlayer extends EventEmitter {
     // ==========================================
     /** @returns {MediaContent[]} A shallow copy of the current playlist. */
     get playlist() {
+        checkDestroy(this.#destroyed);
         return [...this.#playlist];
     }
     /**
@@ -251,6 +261,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @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 +307,7 @@ class TinyMediaPlayer extends EventEmitter {
     }
     /** @returns {number} The current active index in the playlist. */
     get currentIndex() {
+        checkDestroy(this.#destroyed);
         return this.#currentIndex;
     }
     /**
@@ -304,6 +316,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @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 +354,7 @@ class TinyMediaPlayer extends EventEmitter {
     }
     /** @returns {LoopModeType} The current loop configuration. */
     get loopMode() {
+        checkDestroy(this.#destroyed);
         return this.#loopMode;
     }
     /**
@@ -348,6 +362,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @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 +372,7 @@ class TinyMediaPlayer extends EventEmitter {
     }
     /** @returns {boolean} The current random mode status. */
     get isRandom() {
+        checkDestroy(this.#destroyed);
         return this.#isRandom;
     }
     /**
@@ -364,6 +380,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @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 +389,12 @@ class TinyMediaPlayer extends EventEmitter {
     }
     /** @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 +403,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @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 +425,7 @@ class TinyMediaPlayer extends EventEmitter {
     }
     /** @returns {boolean} Whether the volume cache is currently enabled. */
     get persistVolume() {
+        checkDestroy(this.#destroyed);
         return this.#persistVolume;
     }
     /**
@@ -412,6 +433,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @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 +444,7 @@ class TinyMediaPlayer extends EventEmitter {
     }
     /** @returns {string} The localStorage key used for volume caching. */
     get volumeStorageKey() {
+        checkDestroy(this.#destroyed);
         return this.#volumeStorageKey;
     }
     /**
@@ -429,6 +452,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @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 +482,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @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 +517,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @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 +538,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @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 +552,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @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 +569,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @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.');
         }
@@ -573,11 +602,12 @@ class TinyMediaPlayer extends EventEmitter {
     }
     /**
      * Searches the playlist for tracks matching a string query or a custom evaluation function.
-     * @param {string | function(MediaContent): boolean} query - The search string (checked against title, artist, album) or a callback returning a boolean.
+     * @param {string | ((content: MediaContent) => boolean)} query - The search string (checked against title, artist, album) or a callback returning a boolean.
      * @returns {SearchResult[]} An array containing the matched tracks and their corresponding indices.
      * @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 +635,7 @@ class TinyMediaPlayer extends EventEmitter {
      * Clears the entire playlist and stops playback.
      */
     async clearPlaylist() {
+        checkDestroy(this.#destroyed);
         await this.stop();
         this.#playlist = [];
         this.#currentIndex = -1;
@@ -619,6 +650,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @returns {Promise<void>}
      */
     async play() {
+        checkDestroy(this.#destroyed);
         const adapter = this.#getActiveAdapter();
         if (!adapter)
             return;
@@ -633,6 +665,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @returns {Promise<void>}
      */
     async pause() {
+        checkDestroy(this.#destroyed);
         const adapter = this.#getActiveAdapter();
         if (!adapter)
             return;
@@ -645,6 +678,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @returns {Promise<void>}
      */
     async stop() {
+        checkDestroy(this.#destroyed);
         const adapter = this.#getActiveAdapter();
         if (!adapter)
             return;
@@ -657,6 +691,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @returns {Promise<void>}
      */
     async next() {
+        checkDestroy(this.#destroyed);
         if (this.#playlist.length === 0)
             return;
         await this.stop();
@@ -689,6 +724,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @returns {Promise<void>}
      */
     async prev() {
+        checkDestroy(this.#destroyed);
         if (this.#playlist.length === 0)
             return;
         await this.stop();
@@ -719,6 +755,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @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 +775,7 @@ class TinyMediaPlayer extends EventEmitter {
      * @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 +789,35 @@ class TinyMediaPlayer extends EventEmitter {
             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;

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

@@ -1,4 +1,12 @@
-export default TinyNeedBar;
+/**
+ * @typedef {Object} TickResult
+ * @property {number} prevValue - Infinite value before applying decay.
+ * @property {number} removedTotal - Total amount removed this tick.
+ * @property {number} removedPercent - Percentage of max removed this tick.
+ * @property {number} currentPercent - Current percentage relative to max.
+ * @property {number} remainingValue - Current clamped value (≥ 0).
+ * @property {number} infiniteRemaining - Current infinite value (can be negative).
+ */
 export type TickResult = {
     /**
      * - Infinite value before applying decay.
@@ -25,12 +33,6 @@ export type TickResult = {
      */
     infiniteRemaining: number;
 };
-/**
- * Represents a decay factor applied to the need bar.
- *
- * - `amount`: base value reduced per tick.
- * - `multiplier`: multiplier applied to the amount.
- */
 export type BarFactor = {
     /**
      * - Base reduction value per tick.
@@ -41,12 +43,6 @@ export type BarFactor = {
      */
     multiplier: number;
 };
-/**
- * Represents the serialized state of a TinyNeedBar instance.
- *
- * This object is typically produced by {@link TinyNeedBar#toJSON} and
- * can be used to recreate an instance via {@link TinyNeedBar.fromJSON}.
- */
 export type SerializedData = {
     /**
      * - Maximum value of the bar at the moment of serialization.
@@ -65,15 +61,6 @@ export type SerializedData = {
      */
     factors: Record<string, BarFactor>;
 };
-/**
- * @typedef {Object} TickResult
- * @property {number} prevValue - Infinite value before applying decay.
- * @property {number} removedTotal - Total amount removed this tick.
- * @property {number} removedPercent - Percentage of max removed this tick.
- * @property {number} currentPercent - Current percentage relative to max.
- * @property {number} remainingValue - Current clamped value (≥ 0).
- * @property {number} infiniteRemaining - Current infinite value (can be negative).
- */
 /**
  * Represents a decay factor applied to the need bar.
  *
@@ -108,20 +95,7 @@ export type SerializedData = {
  * - `infiniteValue` → can decrease infinitely into negative numbers.
  */
 declare class TinyNeedBar {
-    /**
-     * Restores a need bar from a serialized object.
-     * @param {SerializedData} data
-     * @returns {TinyNeedBar}
-     */
-    static fromJSON(data: SerializedData): TinyNeedBar;
-    /**
-     * Creates a new need bar instance.
-     *
-     * @param {number} [maxValue=100] - Maximum value of the bar.
-     * @param {number} [baseDecay=1] - Base amount reduced each tick.
-     * @param {number} [baseDecayMulti=1] - Multiplier applied to the base decay.
-     */
-    constructor(maxValue?: number, baseDecay?: number, baseDecayMulti?: number);
+    #private;
     /**
      * Returns a snapshot of all currently active factors.
      * Each factor is returned as a plain object to prevent direct mutation of the internal map.
@@ -169,6 +143,14 @@ declare class TinyNeedBar {
      * @returns {number} Current infinite value.
      */
     get infiniteValue(): number;
+    /**
+     * Creates a new need bar instance.
+     *
+     * @param {number} [maxValue=100] - Maximum value of the bar.
+     * @param {number} [baseDecay=1] - Base amount reduced each tick.
+     * @param {number} [baseDecayMulti=1] - Multiplier applied to the base decay.
+     */
+    constructor(maxValue?: number, baseDecay?: number, baseDecayMulti?: number);
     /**
      * Retrieves a specific factor by its key.
      *
@@ -225,6 +207,12 @@ declare class TinyNeedBar {
      * @returns {SerializedData}
      */
     toJSON(): SerializedData;
+    /**
+     * Restores a need bar from a serialized object.
+     * @param {SerializedData} data
+     * @returns {TinyNeedBar}
+     */
+    static fromJSON(data: SerializedData): TinyNeedBar;
     /**
      * Creates a deep clone of this need bar.
      * @returns {TinyNeedBar}
@@ -234,6 +222,6 @@ declare class TinyNeedBar {
      * Clear the factors map, clearing all factor data.
      */
     clearFactors(): void;
-    #private;
 }
+export default TinyNeedBar;
 //# sourceMappingURL=TinyNeedBar.d.mts.map

package/dist/v1/libs/TinyNewWinEvents.cjs

@@ -1,6 +1,9 @@
 'use strict';
 
 var events = require('events');
+var utils = require('./utils.cjs');
+
+const checkDestroy = utils.createCheckDestroyed('TinyNewWinEvents');
 
 /**
  * Stores polling intervals associated with window references.
@@ -51,11 +54,27 @@ class TinyNewWinEvents extends events.EventEmitter {
   /** @type {string} Internal message type for routed communication */
   #routeEventName = '__TNE_ROUTE__';
 
+  /**
+   * 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;
+  }
+
   /**
    * Gets the internal handshake event name.
    * @returns {string}
    */
   get readyEventName() {
+    checkDestroy(this.#destroyed);
     return this.#readyEventName;
   }
 
@@ -65,6 +84,7 @@ class TinyNewWinEvents extends events.EventEmitter {
    * @throws {TypeError} If the value is not a string.
    */
   set readyEventName(name) {
+    checkDestroy(this.#destroyed);
     if (typeof name !== 'string')
       throw new TypeError('TinyNewWinEvents: readyEventName must be a string.');
     this.#readyEventName = name;
@@ -75,6 +95,7 @@ class TinyNewWinEvents extends events.EventEmitter {
    * @returns {string}
    */
   get routeEventName() {
+    checkDestroy(this.#destroyed);
     return this.#routeEventName;
   }
 
@@ -84,6 +105,7 @@ class TinyNewWinEvents extends events.EventEmitter {
    * @throws {TypeError} If the value is not a string.
    */
   set routeEventName(name) {
+    checkDestroy(this.#destroyed);
     if (typeof name !== 'string')
       throw new TypeError('TinyNewWinEvents: routeEventName must be a string.');
     this.#routeEventName = name;
@@ -142,6 +164,7 @@ class TinyNewWinEvents extends events.EventEmitter {
    * @returns {Window|null}
    */
   getWin() {
+    checkDestroy(this.#destroyed);
     return this.#windowRef;
   }
 
@@ -200,6 +223,7 @@ class TinyNewWinEvents extends events.EventEmitter {
    * @returns {void}
    */
   close() {
+    checkDestroy(this.#destroyed);
     if (!this.#isHost) throw new Error('Only host can close the window.');
     if (this.#windowRef && !this.#windowRef.closed) this.#windowRef.close();
   }
@@ -215,6 +239,7 @@ class TinyNewWinEvents extends events.EventEmitter {
    * @returns {void}
    */
   winEmit(route, payload) {
+    checkDestroy(this.#destroyed);
     if (typeof route !== 'string') throw new TypeError('Event name must be a string.');
     if (this.isDestroyed()) throw new Error('Cannot emit: instance has been destroyed.');
     if (!this.#ready) {
@@ -230,6 +255,7 @@ class TinyNewWinEvents extends events.EventEmitter {
    * @returns {boolean}
    */
   isConnected() {
+    checkDestroy(this.#destroyed);
     return this.#ready && this.#windowRef && !this.#windowRef.closed ? true : false;
   }
 
@@ -256,6 +282,7 @@ class TinyNewWinEvents extends events.EventEmitter {
    * @returns {void}
    */
   onClose(callback) {
+    checkDestroy(this.#destroyed);
     this.on('WINDOW_REF_CLOSED', callback);
   }
 
@@ -266,6 +293,7 @@ class TinyNewWinEvents extends events.EventEmitter {
    * @returns {void}
    */
   offClose(callback) {
+    checkDestroy(this.#destroyed);
     this.off('WINDOW_REF_CLOSED', callback);
   }
 
@@ -295,6 +323,7 @@ class TinyNewWinEvents extends events.EventEmitter {
     this.#ready = false;
     this.#windowRef = null;
     this.removeAllListeners();
+    this.#destroyed = true;
   }
 }
 

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

@@ -1,7 +1,4 @@
-export default TinyNewWinEvents;
-/**
- * A function to handle incoming event payloads.
- */
+import { EventEmitter } from 'events';
 export type handler = (payload: any, event: MessageEvent<any>) => any;
 /**
  * @callback handler
@@ -18,26 +15,20 @@ export type handler = (payload: any, event: MessageEvent<any>) => any;
  *
  * @class
  */
-declare class TinyNewWinEvents extends EventEmitter<any> {
+declare class TinyNewWinEvents extends EventEmitter {
+    #private;
+    _handleMessage: (event: MessageEvent) => void;
     /**
-     * Initializes a TinyNewWinEvents instance for communication.
-     *
-     * @param {Object} [settings={}] Configuration object.
-     * @param {string} [settings.targetOrigin] Origin to enforce in postMessage.
-     * @param {string} [settings.url] URL string to open.
-     * @param {string} [settings.name] Window name (required if opening a new window).
-     * @param {string} [settings.features] Features string for `window.open`.
+     * Gets the current destruction status of the instance.
      *
-     * @throws {Error} If `name` is "_blank", which is not allowed.
-     * @throws {TypeError} If `targetOrigin`, `url`, or `features` are not strings (when provided).
-     * @throws {Error} If the window reference is invalid or already being tracked.
+     * @returns {boolean} True if the instance is destroyed, false otherwise.
      */
-    constructor({ targetOrigin, url, name, features }?: {
-        targetOrigin?: string | undefined;
-        url?: string | undefined;
-        name?: string | undefined;
-        features?: string | undefined;
-    });
+    get destroyed(): boolean;
+    /**
+     * Gets the internal handshake event name.
+     * @returns {string}
+     */
+    get readyEventName(): string;
     /**
      * Sets the internal handshake event name.
      * @param {string} name
@@ -45,10 +36,10 @@ declare class TinyNewWinEvents extends EventEmitter<any> {
      */
     set readyEventName(name: string);
     /**
-     * Gets the internal handshake event name.
+     * Gets the internal route event name.
      * @returns {string}
      */
-    get readyEventName(): string;
+    get routeEventName(): string;
     /**
      * Sets the internal route event name.
      * @param {string} name
@@ -56,11 +47,24 @@ declare class TinyNewWinEvents extends EventEmitter<any> {
      */
     set routeEventName(name: string);
     /**
-     * Gets the internal route event name.
-     * @returns {string}
+     * Initializes a TinyNewWinEvents instance for communication.
+     *
+     * @param {Object} [settings={}] Configuration object.
+     * @param {string} [settings.targetOrigin] Origin to enforce in postMessage.
+     * @param {string} [settings.url] URL string to open.
+     * @param {string} [settings.name] Window name (required if opening a new window).
+     * @param {string} [settings.features] Features string for `window.open`.
+     *
+     * @throws {Error} If `name` is "_blank", which is not allowed.
+     * @throws {TypeError} If `targetOrigin`, `url`, or `features` are not strings (when provided).
+     * @throws {Error} If the window reference is invalid or already being tracked.
      */
-    get routeEventName(): string;
-    _handleMessage: (event: MessageEvent) => void;
+    constructor({ targetOrigin, url, name, features }?: {
+        targetOrigin?: string;
+        url?: string;
+        name?: string;
+        features?: string;
+    });
     /**
      * Returns the internal window reference.
      *
@@ -116,7 +120,6 @@ declare class TinyNewWinEvents extends EventEmitter<any> {
      * @returns {void}
      */
     destroy(): void;
-    #private;
 }
-import { EventEmitter } from 'events';
+export default TinyNewWinEvents;
 //# sourceMappingURL=TinyNewWinEvents.d.mts.map