tiny-essentials 1.28.6 → 1.28.8

package/dist/v1/libs/TinyMediaPlayer.mjs

@@ -1,4 +1,4 @@
-import { EventEmitter } from 'events';
+import TinyDebugger from './TinyDebugger.mjs';
 import { getMediaContentBase, getMediaContentMetadata, parseMediaMetadata, valMediaContentMetadata, } from '../basics/mediaContent.mjs';
 import { createCheckDestroyed } from './utils.mjs';
 import { BaseMediaAdapter } from './TinyMediaPlayer/index.mjs';
@@ -28,6 +28,9 @@ const checkDestroy = createCheckDestroyed('TinyMediaPlayer');
  * @property {boolean} [repeatCurrentOnPrev=false] - If true, clicking 'previous' repeats the current track on the first click.
  * @property {boolean} [smoothPlayPauseVolume=false] - If true, volume fades smoothly during play/pause transitions.
  * @property {boolean} [smoothStopVolume=false] - If true, volume fades smoothly to zero when stopping.
+ * @property {boolean} [debugMode=false] - Whether to enable internal debug logging.
+ * @property {boolean} [useLogColors=false] - Whether to enable log color support.
+ * @property {Console} [logger=console] - A custom logger object (must implement console methods).
  */
 /**
  * Represents a search match containing the media object and its exact playlist index.
@@ -38,7 +41,7 @@ const checkDestroy = createCheckDestroyed('TinyMediaPlayer');
 /**
  * A universal media player manager capable of orchestrating multiple API adapters.
  */
-class TinyMediaPlayer extends EventEmitter {
+class TinyMediaPlayer extends TinyDebugger {
     static BaseMediaAdapter = BaseMediaAdapter;
     /**
      * @type {UnknownArtistGetter}
@@ -98,6 +101,8 @@ class TinyMediaPlayer extends EventEmitter {
     #isRandom = false;
     /** @type {boolean} */
     #isPlaying = false;
+    /** @type {boolean} */
+    #isMuted = false;
     /** @type {number} */
     #volume = 1.0;
     /** @type {boolean} */
@@ -216,10 +221,16 @@ class TinyMediaPlayer extends EventEmitter {
      * @throws {RangeError} If numeric options are out of valid ranges.
      */
     constructor(options = {}) {
-        super();
         if (!isValidObj(options)) {
             throw new TypeError('Options must be a non-null object.');
         }
+        // Debug Configuration
+        super({
+            id: '[_blue_TinyMediaPlayer_reset_] :debug:',
+            logger: options.logger ?? console,
+            debugMode: options.debugMode ?? false,
+            useLogColors: options.useLogColors ?? false,
+        });
         // Volume configuration
         if (options.persistVolume !== undefined) {
             if (typeof options.persistVolume !== 'boolean') {
@@ -268,6 +279,7 @@ class TinyMediaPlayer extends EventEmitter {
         }
         if (this.#persistVolume)
             this.#loadVolumeFromStorage();
+        this.log('info', 'Instance initialized.', { options });
     }
     // ==========================================
     // STORAGE HELPERS
@@ -283,6 +295,7 @@ class TinyMediaPlayer extends EventEmitter {
                     const parsedVolume = parseFloat(storedValue);
                     if (!isNaN(parsedVolume) && parsedVolume >= 0 && parsedVolume <= 1) {
                         this.#volume = parsedVolume;
+                        this.log('info', `Volume loaded from storage: ${this.#volume}`);
                     }
                 }
             }
@@ -298,6 +311,7 @@ class TinyMediaPlayer extends EventEmitter {
         try {
             if (this.#persistVolume && typeof window !== 'undefined' && window.localStorage) {
                 window.localStorage.setItem(this.#volumeStorageKey, this.#volume.toString());
+                this.log('info', `Volume saved to storage: ${this.#volume}`);
             }
         }
         catch (error) {
@@ -360,11 +374,14 @@ class TinyMediaPlayer extends EventEmitter {
         const startVolume = adapter.getVolume();
         const startTime = performance.now();
         const duration = this.#fadeVolumeSpeed;
+        this.log('info', `Starting volume fade: ${startVolume} -> ${targetVolume}`);
         return new Promise((resolve) => {
             /** @param {number} currentTime */
             const step = (currentTime) => {
-                if (signal.aborted)
+                if (signal.aborted) {
+                    this.log('info', 'Volume fade aborted.');
                     return resolve();
+                }
                 const elapsed = currentTime - startTime;
                 const progress = Math.min(elapsed / duration, 1);
                 const calculatedVolume = startVolume + (targetVolume - startVolume) * progress;
@@ -375,6 +392,7 @@ class TinyMediaPlayer extends EventEmitter {
                 }
                 else {
                     adapter.setVolume(targetVolume);
+                    this.log('info', `Volume fade completed: ${targetVolume}`);
                     resolve();
                 }
             };
@@ -411,6 +429,7 @@ class TinyMediaPlayer extends EventEmitter {
             }
         }
         this.#playlist = value;
+        this.log('info', `Playlist updated. New size: ${this.#playlist.length}`);
         this.emit('playlistUpdate', this.playlist);
         // Validation to correct currentIndex ensuring it aligns with the new playlist limits
         if (this.#playlist.length === 0) {
@@ -433,6 +452,7 @@ class TinyMediaPlayer extends EventEmitter {
                         await this.play();
                 }
                 catch (error) {
+                    this.log('error', 'Background transition error on playlist update:', error);
                     console.warn('[TinyMediaPlayer] Background transition error on playlist update:', error);
                 }
             })();
@@ -458,6 +478,7 @@ class TinyMediaPlayer extends EventEmitter {
         }
         if (this.#currentIndex === value)
             return; // Optimization: do nothing if index is the same
+        this.log('info', `Index change requested: ${this.#currentIndex} -> ${value}`);
         const wasPlaying = this.#isPlaying;
         let oldAdapter = null;
         if (this.#currentIndex !== -1 && this.#playlist.length > 0) {
@@ -480,6 +501,7 @@ class TinyMediaPlayer extends EventEmitter {
                         await this.play();
                 }
                 catch (error) {
+                    this.log('error', 'Background transition error on index update:', error);
                     console.warn('[TinyMediaPlayer] Background transition error on index update:', error);
                 }
             })();
@@ -501,6 +523,7 @@ class TinyMediaPlayer extends EventEmitter {
             throw new TypeError(`Loop mode must be one of: ${validModes.join(', ')}.`);
         }
         this.#loopMode = value;
+        this.log('info', `Loop mode changed to: ${this.#loopMode}`);
         this.emit('loopModeChange', this.#loopMode);
     }
     /** @returns {boolean} The current random mode status. */
@@ -518,6 +541,7 @@ class TinyMediaPlayer extends EventEmitter {
             throw new TypeError('Random mode state must be a boolean.');
         }
         this.#isRandom = value;
+        this.log('info', `Random mode: ${this.#isRandom}`);
         this.emit('randomModeChange', this.#isRandom);
     }
     /** @returns {boolean} True if media is actively playing. */
@@ -544,6 +568,7 @@ class TinyMediaPlayer extends EventEmitter {
         // Abort any ongoing fade to ensure manual control is immediate
         if (this.#fadeController)
             this.#fadeController.abort();
+        this.log('info', `Volume changed: ${this.#volume} -> ${value}`);
         this.#volume = value;
         this.#saveVolumeToStorage();
         this.emit('volumeChange', this.#volume);
@@ -574,6 +599,7 @@ class TinyMediaPlayer extends EventEmitter {
             throw new TypeError('Persist volume parameter must be a boolean.');
         }
         this.#persistVolume = value;
+        this.log('info', `Persist volume: ${this.#persistVolume}`);
         if (value) {
             this.#saveVolumeToStorage();
         }
@@ -608,6 +634,39 @@ class TinyMediaPlayer extends EventEmitter {
             console.warn('[TinyMediaPlayer] Failed to migrate volume storage key.', error);
         }
     }
+    /** @returns {boolean} True if the player is currently muted. */
+    get isMuted() {
+        checkDestroy(this.#destroyed);
+        return this.#isMuted;
+    }
+    /**
+     * Mutes the current playback.
+     * @returns {Promise<void>}
+     */
+    async mute() {
+        checkDestroy(this.#destroyed);
+        const adapter = this.#getActiveAdapter();
+        if (!adapter)
+            return;
+        await adapter.mute();
+        this.#isMuted = true;
+        this.emit('muteChange', this.#isMuted);
+        this.log('info', 'Playback muted successfully.');
+    }
+    /**
+     * Unmutes the current playback.
+     * @returns {Promise<void>}
+     */
+    async unMute() {
+        checkDestroy(this.#destroyed);
+        const adapter = this.#getActiveAdapter();
+        if (!adapter)
+            return;
+        await adapter.unMute();
+        this.#isMuted = false;
+        this.emit('muteChange', this.#isMuted);
+        this.log('info', 'Playback unmuted successfully.');
+    }
     // ==========================================
     // ADAPTER MANAGEMENT
     // ==========================================
@@ -655,6 +714,7 @@ class TinyMediaPlayer extends EventEmitter {
         if (!(adapter instanceof BaseMediaAdapter)) {
             throw new TypeError('Adapter must be an instance of BaseMediaAdapter.');
         }
+        this.log('info', 'Registering new adapter:', adapter);
         const events = new Map();
         this.#adapterHandlers.set(adapter, events);
         // Use the controlled helper to ensure each event is registered
@@ -674,6 +734,7 @@ class TinyMediaPlayer extends EventEmitter {
         if (!(adapter instanceof BaseMediaAdapter)) {
             throw new TypeError('Adapter must be an instance of BaseMediaAdapter.');
         }
+        this.log('info', 'Removing adapter:', adapter);
         this.#removeHandler(adapter);
         return this.#adapters.delete(adapter);
     }
@@ -687,6 +748,7 @@ class TinyMediaPlayer extends EventEmitter {
         if (!(adapter instanceof BaseMediaAdapter)) {
             throw new TypeError('Adapter must be an instance of BaseMediaAdapter.');
         }
+        this.log('info', 'Destroying adapter:', adapter);
         this.#removeHandler(adapter);
         const result = this.#adapters.delete(adapter);
         if (result)
@@ -710,6 +772,7 @@ class TinyMediaPlayer extends EventEmitter {
      */
     destroyAllAdapters() {
         checkDestroy(this.#destroyed);
+        this.log('info', 'Destroying all adapters.');
         this.#adapters.forEach((adapter) => {
             this.#removeHandler(adapter);
             adapter.destroy();
@@ -721,6 +784,7 @@ class TinyMediaPlayer extends EventEmitter {
      */
     clearAdapters() {
         checkDestroy(this.#destroyed);
+        this.log('info', 'Clearing all adapters.');
         this.#adapters.forEach((adapter) => this.#removeHandler(adapter));
         this.#adapters.clear();
     }
@@ -753,7 +817,9 @@ class TinyMediaPlayer extends EventEmitter {
         const adapter = this.getMediaAdapter(currentContent);
         if (adapter)
             return adapter;
-        throw new Error(`No compatible adapter found for content ID: ${currentContent.id}.`);
+        const errorMsg = `No compatible adapter found for content ID: ${currentContent.id}.`;
+        this.log('error', errorMsg);
+        throw new Error(errorMsg);
     }
     // ==========================================
     // EVENT MANAGEMENT (CONTROLLED)
@@ -771,6 +837,7 @@ class TinyMediaPlayer extends EventEmitter {
         // If the event is already in the list, do nothing to avoid duplicates
         if (this.#adapterEventNames.has(eventName))
             return;
+        this.log('info', `Adding adapter event listener: ${eventName}`);
         this.#adapterEventNames.add(eventName);
         // Synchronize: Add the listener to all already registered adapters
         this.#adapters.forEach((adapter) => {
@@ -789,6 +856,7 @@ class TinyMediaPlayer extends EventEmitter {
         }
         if (!this.#adapterEventNames.has(eventName))
             return;
+        this.log('info', `Removing adapter event listener: ${eventName}`);
         this.#adapterEventNames.delete(eventName);
         // Synchronize: Remove the listener from all registered adapters
         this.#adapters.forEach((adapter) => {
@@ -830,6 +898,8 @@ class TinyMediaPlayer extends EventEmitter {
         /** @type {(...args: any[]) => any} */
         const handler = (...args) => {
             if (!this.#destroyed) {
+                if (eventName !== 'timeupdate')
+                    this.log('debug', `Adapter event triggered: ${eventName}`, ...args);
                 this.emit(eventName, ...args);
             }
         };
@@ -869,6 +939,7 @@ class TinyMediaPlayer extends EventEmitter {
         const newContent = { ...getMediaContentBase(), ...getMediaContentMetadata(), ...content };
         valMediaContentMetadata(newContent);
         const newLength = this.#playlist.push(newContent);
+        this.log('info', `Track added. New length: ${newLength}`, newContent);
         if (this.#currentIndex === -1) {
             this.#currentIndex = 0;
             this.emit('trackChange', this.#currentIndex);
@@ -921,6 +992,7 @@ class TinyMediaPlayer extends EventEmitter {
         if (!this.existsTrack(index)) {
             throw new RangeError(`Index ${index} is out of bounds for the current playlist.`);
         }
+        this.log('info', `Removing track at index: ${index}`);
         if (index === this.#currentIndex) {
             // Stop the current track if it is the one being removed
             await this.stop();
@@ -956,6 +1028,7 @@ class TinyMediaPlayer extends EventEmitter {
         if (typeof query !== 'string' && typeof query !== 'function') {
             throw new TypeError('Search query must be a string or a boolean evaluation function.');
         }
+        this.log('info', 'Searching playlist...', { query });
         const results = [];
         for (let i = 0; i < this.#playlist.length; i++) {
             const track = this.#playlist[i];
@@ -974,6 +1047,7 @@ class TinyMediaPlayer extends EventEmitter {
                 results.push({ track, index: i });
             }
         }
+        this.log('info', `Search completed. Found ${results.length} results.`);
         return results;
     }
     /**
@@ -981,6 +1055,7 @@ class TinyMediaPlayer extends EventEmitter {
      */
     async clearPlaylist() {
         checkDestroy(this.#destroyed);
+        this.log('info', 'Clearing entire playlist.');
         await this.stop();
         this.#playlist = [];
         this.#currentIndex = -1;
@@ -996,6 +1071,7 @@ class TinyMediaPlayer extends EventEmitter {
      */
     async play() {
         checkDestroy(this.#destroyed);
+        this.log('info', `Attempting to play track at index: ${this.#currentIndex}`);
         const adapter = this.#getActiveAdapter();
         if (!adapter)
             return;
@@ -1006,9 +1082,18 @@ class TinyMediaPlayer extends EventEmitter {
         else {
             adapter.setVolume(this.#volume);
         }
-        await adapter.play(this.#playlist[this.#currentIndex]);
-        this.#isPlaying = true;
-        this.emit('play', this.#currentIndex);
+        try {
+            await adapter.play(this.#playlist[this.#currentIndex]);
+            if (this.#isMuted)
+                await adapter.mute();
+            this.#isPlaying = true;
+            this.log('info', 'Playback started successfully.');
+            this.emit('play', this.#currentIndex);
+        }
+        catch (error) {
+            this.log('error', 'Failed to play track:', error);
+            throw error;
+        }
     }
     /**
      * Pauses the current track.
@@ -1016,6 +1101,7 @@ class TinyMediaPlayer extends EventEmitter {
      */
     async pause() {
         checkDestroy(this.#destroyed);
+        this.log('info', 'Attempting to pause playback.');
         const adapter = this.#getActiveAdapter();
         if (!adapter)
             return;
@@ -1024,6 +1110,7 @@ class TinyMediaPlayer extends EventEmitter {
         }
         await adapter.pause();
         this.#isPlaying = false;
+        this.log('info', 'Playback paused.');
         this.emit('pause', this.#currentIndex);
     }
     /**
@@ -1032,6 +1119,7 @@ class TinyMediaPlayer extends EventEmitter {
      */
     async stop() {
         checkDestroy(this.#destroyed);
+        this.log('info', 'Attempting to stop playback.');
         const adapter = this.#getActiveAdapter();
         if (!adapter)
             return;
@@ -1040,6 +1128,7 @@ class TinyMediaPlayer extends EventEmitter {
         }
         await adapter.stop();
         this.#isPlaying = false;
+        this.log('info', 'Playback stopped.');
         this.emit('stop', this.#currentIndex);
     }
     /**
@@ -1050,23 +1139,27 @@ class TinyMediaPlayer extends EventEmitter {
         checkDestroy(this.#destroyed);
         if (this.#playlist.length === 0)
             return;
+        this.log('info', 'Next track requested.');
         await this.stop();
         if (this.#loopMode === 'TRACK') {
+            this.log('info', 'Loop mode: TRACK. Repeating current track.');
             // Index remains the same
             await this.play();
             return;
         }
         if (this.#isRandom) {
             this.#currentIndex = this._getWeightedRandomIndex();
+            this.log('info', `Random mode: Selected index ${this.#currentIndex}`);
         }
         else {
             let nextIndex = this.#currentIndex + 1;
             if (nextIndex >= this.#playlist.length) {
                 if (this.#loopMode === 'PLAYLIST') {
                     nextIndex = 0;
+                    this.log('info', 'Loop mode: PLAYLIST. Returning to start.');
                 }
                 else {
-                    // End of playlist, stop playing
+                    this.log('info', 'End of playlist reached. Stopping.');
                     return;
                 }
             }
@@ -1085,6 +1178,7 @@ class TinyMediaPlayer extends EventEmitter {
             return;
         // UX: Repeat current track if "repeat on prev" is enabled and it's the first click
         if (this.#repeatCurrentOnPrev && !this.#prevClickedToRepeat) {
+            this.log('info', 'UX: Repeat current track on first "prev" click.');
             this.#prevClickedToRepeat = true;
             // Reset the "repeat" state after 2 seconds of inactivity to prevent glitches
             if (this.#prevClickTimer)
@@ -1103,18 +1197,21 @@ class TinyMediaPlayer extends EventEmitter {
             this.#prevClickTimer = null;
         }
         this.#prevClickedToRepeat = false;
+        this.log('info', 'Previous track requested.');
         await this.stop();
         if (this.#isRandom) {
             this.#currentIndex = this._getWeightedRandomIndex();
+            this.log('info', `Random mode: Selected index ${this.#currentIndex}`);
         }
         else {
             let prevIndex = this.#currentIndex - 1;
             if (prevIndex < 0) {
                 if (this.#loopMode === 'PLAYLIST') {
                     prevIndex = this.#playlist.length - 1;
+                    this.log('info', 'Loop mode: PLAYLIST. Returning to end.');
                 }
                 else {
-                    // End of playlist, stop playing
+                    this.log('info', 'Start of playlist reached. Stopping.');
                     return;
                 }
             }
@@ -1123,6 +1220,27 @@ class TinyMediaPlayer extends EventEmitter {
         this.emit('trackChange', this.#currentIndex);
         await this.play();
     }
+    /**
+     * Jumps directly to a specific index in the playlist.
+     * @param {number} index - The target index to skip to.
+     * @returns {Promise<void>}
+     * @throws {TypeError} If the index is not a number.
+     * @throws {RangeError} If the index is out of the playlist bounds.
+     */
+    async skipTo(index) {
+        checkDestroy(this.#destroyed);
+        if (typeof index !== 'number') {
+            throw new TypeError('Index must be a number.');
+        }
+        if (!this.existsTrack(index)) {
+            throw new RangeError(`Index ${index} is out of bounds for the current playlist.`);
+        }
+        this.log('info', `Skipping to index: ${index}`);
+        await this.stop();
+        this.#currentIndex = index;
+        this.emit('trackChange', this.#currentIndex);
+        await this.play();
+    }
     /**
      * Jumps to a specific absolute time in the timeline.
      * @param {number} timeMs - The target time in milliseconds.
@@ -1138,6 +1256,7 @@ class TinyMediaPlayer extends EventEmitter {
         if (timeMs < 0) {
             throw new RangeError('Seek time cannot be negative.');
         }
+        this.log('info', `Seeking to: ${timeMs}ms`);
         const adapter = this.#getActiveAdapter();
         if (adapter) {
             await adapter.seek(timeMs);
@@ -1155,6 +1274,7 @@ class TinyMediaPlayer extends EventEmitter {
         if (typeof stepMs !== 'number') {
             throw new TypeError('Step amount must be a number in milliseconds.');
         }
+        this.log('info', `Stepping by: ${stepMs}ms`);
         const adapter = this.#getActiveAdapter();
         if (!adapter)
             return;
@@ -1224,6 +1344,34 @@ class TinyMediaPlayer extends EventEmitter {
             return 0;
         }
     }
+    /**
+     * Checks whether the media adapter is paused.
+     * @returns {boolean} True if the adapter is ready, false otherwise.
+     */
+    get isPaused() {
+        checkDestroy(this.#destroyed);
+        try {
+            const adapter = this.#getActiveAdapter();
+            return adapter ? adapter.isPaused() : false;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Checks whether the media adapter is ended.
+     * @returns {boolean} True if the adapter is ready, false otherwise.
+     */
+    get isEnded() {
+        checkDestroy(this.#destroyed);
+        try {
+            const adapter = this.#getActiveAdapter();
+            return adapter ? adapter.isEnded() : true;
+        }
+        catch {
+            return true;
+        }
+    }
     /**
      * Retrieves the metadata of the currently loaded content, returning a structured
      * object containing details such as the content ID, title, author, and duration.
@@ -1275,6 +1423,7 @@ class TinyMediaPlayer extends EventEmitter {
     async destroy() {
         if (this.#destroyed)
             return;
+        this.log('info', 'Destroying TinyMediaPlayer instance.');
         // 1. Stop current playback if active to halt media processes
         try {
             if (this.#isPlaying) {
@@ -1282,6 +1431,7 @@ class TinyMediaPlayer extends EventEmitter {
             }
         }
         catch (error) {
+            this.log('error', 'Non-fatal error during playback termination:', error);
             console.warn('[TinyMediaPlayer] Non-fatal error during playback termination:', error);
         }
         if (this.#prevClickTimer)

package/dist/v1/libs/TinyPromiseQueue.cjs

@@ -182,9 +182,10 @@ class TinyPromiseQueue {
    * Inserts a point in the queue where subsequent tasks will be grouped and executed together in a Promise.all.
    * If the queue is currently empty, behaves like a regular promise.
    *
-   * @param {(...args: any[]) => Promise<any>|Promise<any>} task A function that returns a Promise.
+   * @template {any} PromiseResult
+   * @param {(...args: any[]) => Promise<PromiseResult>} task A function that returns a Promise.
    * @param {string} [id] Optional ID to identify the task in the queue.
-   * @returns {Promise<any>} A Promise that resolves or rejects with the result of the task once it's processed.
+   * @returns {Promise<PromiseResult>} A Promise that resolves or rejects with the result of the task once it's processed.
    * @throws {Error} Throws if param is invalid.
    */
   async enqueuePoint(task, id) {
@@ -206,10 +207,11 @@ class TinyPromiseQueue {
    * If the task is canceled before execution, it will be rejected with the message:
    * "The function was canceled on TinyPromiseQueue."
    *
-   * @param {(...args: any[]) => Promise<any>|Promise<any>} task A function that returns a Promise to be executed sequentially.
+   * @template {any} PromiseResult
+   * @param {(...args: any[]) => Promise<PromiseResult>} task A function that returns a Promise to be executed sequentially.
    * @param {number|null} [delay] Optional delay (in ms) before the task is executed.
    * @param {string} [id] Optional ID to identify the task in the queue.
-   * @returns {Promise<any>} A Promise that resolves or rejects with the result of the task once it's processed.
+   * @returns {Promise<PromiseResult>} A Promise that resolves or rejects with the result of the task once it's processed.
    * @throws {Error} Throws if param is invalid.
    */
   enqueue(task, delay, id) {

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

@@ -76,12 +76,13 @@ declare class TinyPromiseQueue {
      * Inserts a point in the queue where subsequent tasks will be grouped and executed together in a Promise.all.
      * If the queue is currently empty, behaves like a regular promise.
      *
-     * @param {(...args: any[]) => Promise<any>|Promise<any>} task A function that returns a Promise.
+     * @template {any} PromiseResult
+     * @param {(...args: any[]) => Promise<PromiseResult>} task A function that returns a Promise.
      * @param {string} [id] Optional ID to identify the task in the queue.
-     * @returns {Promise<any>} A Promise that resolves or rejects with the result of the task once it's processed.
+     * @returns {Promise<PromiseResult>} A Promise that resolves or rejects with the result of the task once it's processed.
      * @throws {Error} Throws if param is invalid.
      */
-    enqueuePoint(task: (...args: any[]) => Promise<any> | Promise<any>, id?: string): Promise<any>;
+    enqueuePoint<PromiseResult extends any>(task: (...args: any[]) => Promise<PromiseResult>, id?: string): Promise<PromiseResult>;
     /**
      * Adds a new async task to the queue and ensures it runs in order after previous tasks.
      * Optionally, a delay can be added before the task is executed.
@@ -89,13 +90,14 @@ declare class TinyPromiseQueue {
      * If the task is canceled before execution, it will be rejected with the message:
      * "The function was canceled on TinyPromiseQueue."
      *
-     * @param {(...args: any[]) => Promise<any>|Promise<any>} task A function that returns a Promise to be executed sequentially.
+     * @template {any} PromiseResult
+     * @param {(...args: any[]) => Promise<PromiseResult>} task A function that returns a Promise to be executed sequentially.
      * @param {number|null} [delay] Optional delay (in ms) before the task is executed.
      * @param {string} [id] Optional ID to identify the task in the queue.
-     * @returns {Promise<any>} A Promise that resolves or rejects with the result of the task once it's processed.
+     * @returns {Promise<PromiseResult>} A Promise that resolves or rejects with the result of the task once it's processed.
      * @throws {Error} Throws if param is invalid.
      */
-    enqueue(task: (...args: any[]) => Promise<any> | Promise<any>, delay?: number | null, id?: string): Promise<any>;
+    enqueue<PromiseResult extends any>(task: (...args: any[]) => Promise<PromiseResult>, delay?: number | null, id?: string): Promise<PromiseResult>;
     /**
      * Cancels a scheduled delay and removes the task from the queue.
      * Adds the ID to a blacklist so the task is skipped if already being processed.

package/dist/v1/libs/TinyPromiseQueue.mjs

@@ -162,9 +162,10 @@ class TinyPromiseQueue {
      * Inserts a point in the queue where subsequent tasks will be grouped and executed together in a Promise.all.
      * If the queue is currently empty, behaves like a regular promise.
      *
-     * @param {(...args: any[]) => Promise<any>|Promise<any>} task A function that returns a Promise.
+     * @template {any} PromiseResult
+     * @param {(...args: any[]) => Promise<PromiseResult>} task A function that returns a Promise.
      * @param {string} [id] Optional ID to identify the task in the queue.
-     * @returns {Promise<any>} A Promise that resolves or rejects with the result of the task once it's processed.
+     * @returns {Promise<PromiseResult>} A Promise that resolves or rejects with the result of the task once it's processed.
      * @throws {Error} Throws if param is invalid.
      */
     async enqueuePoint(task, id) {
@@ -186,10 +187,11 @@ class TinyPromiseQueue {
      * If the task is canceled before execution, it will be rejected with the message:
      * "The function was canceled on TinyPromiseQueue."
      *
-     * @param {(...args: any[]) => Promise<any>|Promise<any>} task A function that returns a Promise to be executed sequentially.
+     * @template {any} PromiseResult
+     * @param {(...args: any[]) => Promise<PromiseResult>} task A function that returns a Promise to be executed sequentially.
      * @param {number|null} [delay] Optional delay (in ms) before the task is executed.
      * @param {string} [id] Optional ID to identify the task in the queue.
-     * @returns {Promise<any>} A Promise that resolves or rejects with the result of the task once it's processed.
+     * @returns {Promise<PromiseResult>} A Promise that resolves or rejects with the result of the task once it's processed.
      * @throws {Error} Throws if param is invalid.
      */
     enqueue(task, delay, id) {