tiny-essentials 1.28.4 → 1.28.6

package/dist/v1/libs/TinyTimeout.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var promiseUtils = require('../basics/promiseUtils.cjs');
 var utils = require('./utils.cjs');
 
 const checkDestroy = utils.createCheckDestroyed('TinyTimeout');
@@ -152,21 +153,10 @@ class TinyTimeout {
    * @param {number} [checkInterval=100] - How often (in ms) to check the condition.
    * @returns {Promise<void>} Resolves when the condition is met.
    * @throws {TypeError} If arguments are invalid.
+   * @deprecated Script migrated to `src/v1/basics/promiseUtils.mjs`.
    */
   static waitForTrue(getValue, checkInterval = 100) {
-    if (typeof getValue !== 'function')
-      throw new TypeError(`Expected 'getValue' to be a function.`);
-    if (!Number.isFinite(checkInterval) || checkInterval <= 0)
-      throw new TypeError(`Expected 'checkInterval' to be a positive number.`);
-
-    return new Promise((resolve) => {
-      const interval = setInterval(() => {
-        if (getValue()) {
-          clearInterval(interval);
-          resolve();
-        }
-      }, checkInterval);
-    });
+    return promiseUtils.waitForTrue(getValue, checkInterval);
   }
 
   /**
@@ -185,7 +175,7 @@ class TinyTimeout {
       throw new TypeError(`Expected 'getValue' to be a function.`);
     if (checkInterval !== null && (!Number.isFinite(checkInterval) || checkInterval <= 0))
       throw new TypeError(`Expected 'checkInterval' to be null or a positive number.`);
-    return TinyTimeout.waitForTrue(getValue, checkInterval ?? this.#cooldownWatcherTime);
+    return promiseUtils.waitForTrue(getValue, checkInterval ?? this.#cooldownWatcherTime);
   }
 
   /**

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

@@ -67,6 +67,7 @@ declare class TinyTimeout {
      * @param {number} [checkInterval=100] - How often (in ms) to check the condition.
      * @returns {Promise<void>} Resolves when the condition is met.
      * @throws {TypeError} If arguments are invalid.
+     * @deprecated Script migrated to `src/v1/basics/promiseUtils.mjs`.
      */
     static waitForTrue(getValue: () => boolean, checkInterval?: number): Promise<void>;
     /**

package/dist/v1/libs/TinyTimeout.mjs

@@ -1,3 +1,4 @@
+import { waitForTrue } from '../basics/promiseUtils.mjs';
 import { createCheckDestroyed } from './utils.mjs';
 const checkDestroy = createCheckDestroyed('TinyTimeout');
 /**
@@ -136,20 +137,10 @@ class TinyTimeout {
      * @param {number} [checkInterval=100] - How often (in ms) to check the condition.
      * @returns {Promise<void>} Resolves when the condition is met.
      * @throws {TypeError} If arguments are invalid.
+     * @deprecated Script migrated to `src/v1/basics/promiseUtils.mjs`.
      */
     static waitForTrue(getValue, checkInterval = 100) {
-        if (typeof getValue !== 'function')
-            throw new TypeError(`Expected 'getValue' to be a function.`);
-        if (!Number.isFinite(checkInterval) || checkInterval <= 0)
-            throw new TypeError(`Expected 'checkInterval' to be a positive number.`);
-        return new Promise((resolve) => {
-            const interval = setInterval(() => {
-                if (getValue()) {
-                    clearInterval(interval);
-                    resolve();
-                }
-            }, checkInterval);
-        });
+        return waitForTrue(getValue, checkInterval);
     }
     /**
      * Instance version of `waitForTrue`, which defaults to using the instance's
@@ -168,7 +159,7 @@ class TinyTimeout {
             throw new TypeError(`Expected 'getValue' to be a function.`);
         if (checkInterval !== null && (!Number.isFinite(checkInterval) || checkInterval <= 0))
             throw new TypeError(`Expected 'checkInterval' to be null or a positive number.`);
-        return TinyTimeout.waitForTrue(getValue, checkInterval ?? this.#cooldownWatcherTime);
+        return waitForTrue(getValue, checkInterval ?? this.#cooldownWatcherTime);
     }
     /**
      * Cleans up all internal references and stops the cooldown watcher.

package/docs/v1/basics/mediaContent.md

@@ -13,7 +13,7 @@ These definitions ensure type safety and provide a clear blueprint for how media
 | Type | Description |
 | :--- | :--- |
 | `MediaContent` | **The Final Object.** A combination of `MediaContentBase` and `MediaContentMetadata`. This is what the system uses for playback. |
-| `MediaContentBase` | The essential properties: `id`, `title`, `artist`, `duration`, `url`, and `weight`. |
+| `MediaContentBase` | The essential properties: `id`, `title`, `artist`, `duration`, `url`, `weight`, and an optional `mediaType` (e.g., 'audio', 'video') to facilitate content filtering when using both `HtmlAudioAdapter` and `HtmlVideoAdapter` within a `TinyMediaPlayer`. |
 | `MediaContentMetadata` | Rich metadata modeled after `music-metadata`. Includes `album`, `genre`, `year`, `track` info, etc. |
 | `MediaNumber` | A structure for indexing: `{ no: number \| null, of: number \| null }`. |
 | `UnknownArtistGetter` | A type that can be a `string` or a function returning a `string`. |

package/docs/v1/basics/objChecker.md

@@ -20,6 +20,19 @@ countObj('hi');            // Throws TypeError
 
 ---
 
+### 🧼 `isValidObj(value)`
+
+Check if a value is a **JSON-compatible object** — meaning it's **not** a Array.
+
+🔒 This function ensures the object:
+
+* is not `null`
+* has `typeof === 'object'`
+
+Use this when you need to strictly validate a JSON object.
+
+---
+
 ### 🧼 `isJsonObject(value)`
 
 Check if a value is a **plain JSON-compatible object** — meaning it's created via `{}` or `new Object()`, with a prototype of `Object.prototype`, and **not** a special object like `Date`, `Map`, `Array`, etc.

package/docs/v1/basics/promiseUtils.md

@@ -0,0 +1,32 @@
+### 🔁 `waitForTrue(getValue, checkInterval = 100)`
+
+Waits until a provided function returns `true`, polling periodically.
+
+```ts
+static waitForTrue(getValue: () => boolean, checkInterval?: number): Promise<void>
+```
+
+* `getValue`: Function that returns `true` when the wait should end.
+* `checkInterval`: Polling interval in milliseconds.
+
+---
+
+### 🔒 `createSingletonTask(baseFunction)`
+
+Creates a controller object that ensures an asynchronous function is only executed once at a time. If a task is already in progress, subsequent calls to `callback` will wait for the existing promise to resolve.
+
+```ts
+createSingletonTask<T, A extends any[]>(
+  baseFunction: (...args: A) => Promise<T>
+): {
+  callback: (...args: A) => Promise<T>;
+  getActivePromise: () => Promise<T> | null;
+  resetActivePromise: () => void;
+}
+```
+
+* `callback`: The wrapped function that manages execution state.
+* `getActivePromise`: Returns the current active promise, or `null` if no task is running.
+* `resetActivePromise`: Forces the state to reset, allowing the next call to start a new execution.
+
+> **Note:** This utility is designed for **request collapsing** (all callers receive the same result). If you need to execute multiple independent tasks sequentially where each call returns its own unique result, please refer to the documentation for `TinyPromiseQueue.mjs`.

package/docs/v1/libs/TinyMediaPlayer.md

@@ -9,17 +9,158 @@
 To support different media platforms, `TinyMediaPlayer` relies on **Adapters**. You must create a class that extends `BaseMediaAdapter` for every new service you wish to support.
 
 ### 🛠️ `BaseMediaAdapter` (Abstract Class)
-*This class cannot be instantiated directly. It serves as an interface.*
+*This class cannot be instantiated directly. It serves as an interface that all specific API wrappers must extend and implement.*
 
+#### Properties
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `destroyed` | `boolean` | Indicates if the adapter instance has been destroyed. |
+
+#### Methods
 | Method | Description | Parameters | Returns |
 | :--- | :--- | :--- | :--- |
-| `canHandle` | Checks if the adapter supports a specific content item. | `content: MediaContent` | `boolean` |
-| `play` | Starts or resumes playback. | `content: MediaContent` | `Promise<void>` |
+| `canHandle` | Determines if the adapter can play the provided content. | `content: MediaContent` | `boolean` |
+| `play` | Starts or resumes playback of the provided content. | `content: MediaContent` | `Promise<void>` |
 | `pause` | Pauses the current playback. | None | `Promise<void>` |
-| `stop` | Stops playback and resets the platform state. | None | `Promise<void>` |
-| `seek` | Jumps to a specific time. | `timeMs: number` | `Promise<void>` |
-| `getCurrentTime` | Gets the current playback position. | None | `number` (ms) |
-| `setVolume` | Sets the volume level. | `volume: number` (0.0 to 1.0) | `void` |
+| `stop` | Stops the playback completely and resets the platform state. | None | `Promise<void>` |
+| `seek` | Seeks to a specific time in the media timeline. | `timeMs: number` | `Promise<void>` |
+| `getCurrentTime` | Retrieves the current playback position. | None | `number` (ms) |
+| `getTotalDuration` | Gets the total duration of the content. | None | `number` (ms) |
+| `getRemainingTime` | Gets the remaining time until the content ends. | None | `number` (ms) |
+| `getPlaybackPercentage` | Gets the percentage of the content that has been played. | None | `number` (0 to 100) |
+| `getTimeData` | Retrieves a consolidated object containing all time-related metrics. | None | `ContentTimeData` |
+| `setVolume` | Sets the playback volume for the underlying API. | `volume: number` (0.0 to 1.0) | `void` |
+| `getVolume` | Gets the current playback volume. | None | `number` (0.0 to 1.0) |
+| `destroy` | Cleans up the instance, removes listeners, and marks it as destroyed. | None | `void` |
+
+---
+
+### 🚀 Implementation Guide
+
+You can integrate `TinyMediaPlayer` into your project using two methods: using the ready-to-use adapters provided in the library, or creating your own custom adapters for unique services.
+
+#### 📦 Option 1: Using Pre-built Adapters
+The library provides several optimized adapters for common media sources. You can import them and register them directly with your player instance.
+
+**Available Adapters:**
+* `YoutubeMediaAdapter` from `tiny-essentials/libs/TinyMediaPlayer/Youtube` (https://www.youtube.com/watch?v=XXXXXXXXXXX)
+* `SoundCloudMediaAdapter` from `tiny-essentials/libs/TinyMediaPlayer/SoundCloud` (https://api.soundcloud.com/tracks/XXXXXXXXX (From SoundCloud Embed))
+* `HtmlAudioAdapter` from `tiny-essentials/libs/TinyMediaPlayer/HtmlAudio`
+* `HtmlVideoAdapter` from `tiny-essentials/libs/TinyMediaPlayer/HtmlVideo`
+
+**Example Usage:**
+```javascript
+import TinyMediaPlayer from 'tiny-essentials/libs/TinyMediaPlayer';
+import { YoutubeMediaAdapter } from 'tiny-essentials/libs/TinyMediaPlayer/Youtube';
+import { HtmlAudioAdapter } from 'tiny-essentials/libs/TinyMediaPlayer/HtmlAudio';
+
+const player = new TinyMediaPlayer({
+  persistVolume: true
+});
+
+YoutubeMediaAdapter.defaultContainer = YoutubeMediaAdapter.createIframeContainer({
+videoId: 'fzKvGbQ9SgY',
+hidden: true,
+autoplay: false,
+});
+
+// Register the ready-made adapters
+player.registerAdapter(new YoutubeMediaAdapter());
+player.registerAdapter(new HtmlAudioAdapter());
+
+// The player will now automatically select the correct adapter 
+// based on the content provided.
+```
+
+#### 🛠️ Option 2: Creating Custom Adapters
+If you need to support a service not covered by the pre-built adapters, you can create a custom class by extending the `BaseMediaAdapter`.
+
+**Example Implementation:**
+```javascript
+import { BaseMediaAdapter } from 'tiny-essentials/libs/TinyMediaPlayer/Base';
+
+/**
+ * A custom adapter for a hypothetical streaming service.
+ * @extends BaseMediaAdapter
+ */
+class MyCustomServiceAdapter extends BaseMediaAdapter {
+  /**
+   * Determines if this adapter can play the given content.
+   * @param {MediaContent} content - The media content to check.
+   * @returns {boolean} - True if the URL matches the service.
+   */
+  static canHandle(content) {
+    return content.url.startsWith('https://example.com/');
+  }
+
+  /**
+   * Determines if this adapter can play the given content.
+   * @param {MediaContent} content - The media content to check.
+   * @returns {boolean} - True if the URL matches the service.
+   */
+  canHandle(content) {
+    return MyCustomServiceAdapter.canHandle(content);
+  }
+
+  /**
+   * Starts playback for the provided content.
+   * @param {MediaContent} content - The content to play.
+   * @returns {Promise<void>}
+   */
+  async play(content) {
+    console.log(`Starting playback for: ${content.title}`);
+    // Logic to interface with the custom service API goes here
+  }
+
+  async pause() {
+    // Logic to pause custom service playback
+  }
+
+  async stop() {
+    // Logic to stop custom service playback
+  }
+
+  async seek(timeMs) {
+    // Logic to seek in custom service playback
+  }
+
+  getCurrentTime() {
+    // Logic to return current time from custom service
+    return 0; 
+  }
+
+  setVolume(volume) {
+    // Logic to set volume on custom service
+    console.log(`Volume set to: ${volume}`);
+  }
+}
+
+// Registering the custom adapter
+const player = new TinyMediaPlayer();
+player.registerAdapter(new MyCustomServiceAdapter());
+```
+
+---
+
+## 📊 Data Types
+
+### `ContentTimeData`
+This object is emitted during the `timeupdate` event and provides real-time playback information.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `total` | `number` | The total duration of the media in milliseconds. |
+| `current` | `number` | The current playback position in milliseconds. |
+| `remaining` | `number` | The remaining time until the media ends in milliseconds. |
+| `playbackPercentage` | `number` | The percentage of the media that has been played (0 to 100). |
+
+### `SearchResult`
+Returned by the `searchTrack` method.
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `track` | `MediaContent` | The matched media content object. |
+| `index` | `number` | The current index of the track in the playlist. |
 
 ---
 
@@ -28,29 +169,43 @@ To support different media platforms, `TinyMediaPlayer` relies on **Adapters**.
 The main controller for managing playlists, playback state, and adapters.
 
 ### ⚙️ Configuration (Constructor Options)
-When initializing `new TinyMediaPlayer(options)`, you can pass the following:
+When initializing `new TinyMediaPlayer(options)`, you can pass the following `TinyMediaPlayerOptions`:
 
-*   **`persistVolume`** (`boolean`): If `true`, the volume level is automatically saved to and loaded from `localStorage`. (Default: `false`).
-*   **`volumeStorageKey`** (`string`): The key name used in `localStorage` to store the volume. (Default: `'tiny_media_player_volume'`).
+* **`persistVolume`** (`boolean`): If `true`, the volume level is automatically saved to and loaded from `localStorage`. (Default: `false`).
+* **`volumeStorageKey`** (`string`): The key name used in `localStorage` to store the volume. (Default: `'tiny_media_player_volume'`).
+* **`repeatCurrentOnPrev`** (`boolean`): If `true`, clicking 'previous' repeats the current track on the first click. (Default: `false`).
+* **`smoothPlayPauseVolume`** (`boolean`): If `true`, volume fades smoothly during play/pause transitions. (Default: `false`).
+* **`smoothStopVolume`** (`boolean`): If `true`, volume fades smoothly to zero when stopping. (Default: `false`).
 
 ---
 
 ### 🏗️ Static Members
 
 #### Properties
-*   **`unknownArtist`**: A global setting for when an artist's name is unavailable.
-    *   **Type**: `string` | `function` (returns a string).
-    *   **Getter/Setter**: Allows you to define a custom string or a logic-based function.
+* **`BaseMediaAdapter`**: A reference to the `BaseMediaAdapter` class (useful for `instanceof` checks).
+* **`unknownArtist`**: A global setting for when an artist's name is unavailable.
+    * **Type**: `string` | `function` (returns a string).
+    * **Getter/Setter**: Allows you to define a custom string or a logic-based function.
+* **`defaultAdapterEventNames`**: An array of strings representing the events the player listens to by default on all registered adapters.
+    * **Type**: `string[]` (e.g., `['timeupdate', 'ended']`).
+    * **Getter/Setter**: Allows customization of the default event subscription list.
 
 #### Methods
-*   **`parseContent(source, defaultMetadata, metadata, parseFile, callbacks)`**: 
-    *   A static factory method to prepare a `MediaContent` object by extracting metadata from a URL or HTMLMediaElement.
-    *   **Returns**: `Promise<MediaContent>`.
+* **`parseContent(source, defaultMetadata, metadata, parseFile, callbacks)`**: 
+    * A static factory method to prepare a `MediaContent` object by extracting metadata from a URL or HTMLMediaElement.
+    * **Parameters**:
+        * `source`: `string | HTMLMediaElement`
+        * `defaultMetadata`: `Partial<MediaContentBase & MediaContentMetadata>`
+        * `metadata`: `Partial<MediaContentBase & MediaContentMetadata>`
+        * `parseFile`: `ParseMediaContentMetadata`
+        * `callbacks`: `Object` (containing `onProgress` and `onError`)
+    * **Returns**: `Promise<MediaContent>`.
 
 ---
 
 ### 📊 Instance Properties (Getters & Setters)
 
+#### 🔄 State & Playback
 | Property | Type | Description |
 | :--- | :--- | :--- |
 | `playlist` | `MediaContent[]` | Returns a shallow copy of the current playlist. |
@@ -58,43 +213,117 @@ When initializing `new TinyMediaPlayer(options)`, you can pass the following:
 | `loopMode` | `'NONE' \| 'TRACK' \| 'PLAYLIST'` | Defines how the player behaves at the end of a track. |
 | `isRandom` | `boolean` | Enables or disables shuffle mode. |
 | `isPlaying` | `boolean` | Indicates if media is currently playing. |
-| `volume` | `number` | The current volume (constrained between `0.0` and `1.0`). |
+| `volume` | `number` | The current volume level (strictly between `0.0` and `1.0`). |
+
+#### 🎨 UX & Customization
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `repeatCurrentOnPrev` | `boolean` | Whether clicking 'previous' repeats the current track on first click. |
+| `smoothPlayPauseVolume`| `boolean` | Enables smooth volume fading during play/pause. |
+| `smoothStopVolume` | `boolean` | Enables smooth volume fading when stopping. |
+| `fadeVolumeSpeed` | `number` | The duration (ms) of the volume fade transition (must be non-negative). |
+| `prevClickTimeoutDuration`| `number` | The duration (ms) before the "repeat on prev" state resets (must be non-negative). |
 | `persistVolume` | `boolean` | Enables/disables volume saving to `localStorage`. |
-| `volumeStorageKey`| `string` | The key used for volume persistence. |
+| `volumeStorageKey` | `string` | The key used for volume persistence (cannot be empty). |
+
+#### 🛠️ Utility & Lifecycle
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `destroyed` | `boolean` | Indicates if the instance has been destroyed. |
+| `adapters` | `BaseMediaAdapter[]` | Returns an array of all registered adapters. |
+| `adaptersSize` | `number` | The number of currently registered adapters. |
 
 ---
 
 ### 🕹️ Methods
 
 #### 🔌 Adapter Management
-*   **`registerAdapter(id, adapter)`**: Registers a new provider.
-    *   `id`: A unique string (e.g., `'youtube'`).
-    *   `adapter`: An instance of a class extending `BaseMediaAdapter`.
+* **`registerAdapter(adapter)`**: Registers a new provider.
+    * `adapter`: An instance of a class extending `BaseMediaAdapter`.
+* **`removeAdapter(adapter)`**: Removes a specific registered adapter.
+* **`destroyAdapter(adapter)`**: Destroys and removes a specific registered adapter.
+* **`hasAdapter(adapter)`**: Checks if a specific adapter is registered.
+* **`clearAdapters()`**: Clears the list of adapters (does not call `destroy` on them).
+* **`destroyAllAdapters()`**: Destroys and removes all registered media adapters.
+* **`getMediaAdapter(content)`**: Finds the compatible adapter for the provided content.
+
+#### 📡 Event Management (Controlled)
+*Use these methods to manage which events from the underlying adapters are proxied to the `TinyMediaPlayer` instance.*
+
+* **`addAdapterEvent(eventName)`**: Subscribes the player to a new event type from all registered adapters.
+    * `eventName`: `string`.
+* **`removeAdapterEvent(eventName)`**: Unsubscribes the player from a specific event type from all registered adapters.
+    * `eventName`: `string`.
+* **`resetAdapterEvents()`**: Restores the event listener list to the default state defined by `TinyMediaPlayer.defaultAdapterEventNames`.
 
 #### 📋 Playlist Management
-*   **`addTrack(content)`**: Adds a new `MediaContent` object to the end of the playlist.
-*   **`existsTrack(index)`**: Returns `true` if a track exists at the given index.
-*   **`getTrack(index)`**: Retrieves the track at the specified index.
-*   **`removeTrack(index)`**: Removes a track. If the current track is removed, playback stops or adjusts.
-*   **`searchTrack(query)`**: Searches the playlist.
-    *   `query`: A `string` (searches title, artist, or album) or a `function` (custom logic).
-    *   **Returns**: `SearchResult[]` (array of objects containing the track and its index).
-*   **`clearPlaylist()`**: Stops playback and empties the playlist.
+* **`addTrack(content)`**: Adds a new `MediaContent` object to the end of the playlist.
+    * **Returns**: `number` (the new length of the playlist).
+* **`existsTrack(index)`**: Returns `true` if the track exists at the given index.
+* **`getTrack(index)`**: Retrieves the track at the specified index.
+* **`removeTrack(index)`**: **(Async)** Removes a track and adjusts the current index/playback accordingly.
+* **`searchTrack(query)`**: Searches the playlist.
+    * `query`: A `string` (searches title, artist, or album) or a `function` (custom logic).
+    * **Returns**: `SearchResult[]` (array of objects containing the track and their corresponding indices).
+* **`clearPlaylist()`**: **(Async)** Stops playback and empties the entire playlist.
 
 #### ⏯️ Playback Controls
-*   **`play()`**: Starts playback of the current track.
-*   **`pause()`**: Pauses the current track.
-*   **`stop()`**: Stops the current track completely.
-*   **`next()`**: Advances to the next track (respects `loopMode` and `isRandom`).
-*   **`prev()`**: Returns to the previous track (respects `loopMode` and `isRandom`).
-*   **`seek(timeMs)`**: Jumps to a specific millisecond in the current track.
-*   **`step(stepMs)`**: Moves the timeline forward (positive) or backward (negative) by a specific amount.
+* **`play()`**: **(Async)** Starts playback of the current track.
+* **`pause()`**: **(Async)** Pauses the current track.
+* **`stop()`**: **(Async)** Stops the current track completely.
+* **`next()`**: **(Async)** Advances to the next track (respects `loopMode` and `isRandom`).
+* **`prev()`**: **(Async)** Returns to the previous track (respects `loopMode` and `isRandom`).
+* **`seek(timeMs)`**: **(Async)** Jumps to a specific millisecond in the current track.
+* **`step(stepMs)`**: **(Async)** Moves the timeline forward (positive) or backward (negative) by a specified amount.
+
+#### ⏳ Time Utilities
+* **`getCurrentTime()`**: Gets the current playback time in milliseconds.
+* **`getTotalDuration()`**: Gets the total duration of the current track in milliseconds.
+* **`getRemainingTime()`**: Gets the remaining time until the current track ends in milliseconds.
+* **`getPlaybackPercentage()`**: Gets the percentage of the current track that has been played (0-100).
+
+#### ♻️ Lifecycle
+* **`destroy()`**: **(Async)** Safely stops playback, clears state, removes adapters, and detaches all listeners to prevent memory leaks.
+
+---
+
+## 📡 Emitted Events
+
+`TinyMediaPlayer` extends `EventEmitter`. You can listen to the following events.
+
+### 🎶 Playback Events
+| Event | Data Type | Description |
+| :--- | :--- | :--- |
+| `play` | `number` | Emitted when playback starts. Returns the `currentIndex`. |
+| `pause` | `number` | Emitted when playback is paused. Returns the `currentIndex`. |
+| `stop` | `number` | Emitted when playback is stopped. Returns the `currentIndex`. |
+| `seek` | `number` | Emitted when the timeline is jumped to a new time (in ms). |
+| `timeupdate` | `ContentTimeData` | Emitted by the adapter every time the playback position changes (in ms). |
+
+### 🔄 State & Configuration Events
+| Event | Data Type | Description |
+| :--- | :--- | :--- |
+| `playlistUpdate` | `MediaContent[]` | Emitted when the playlist is modified. |
+| `trackChange` | `number` | Emitted when the `currentIndex` changes. |
+| `volumeChange` | `number` | Emitted when the volume is updated (0.0 to 1.0). |
+| `isRandomChange` | `boolean` | Emitted when the random mode is toggled. |
+| `loopModeChange` | `LoopModeType` | Emitted when the loop mode is changed. |
+| `repeatCurrentOnPrevChange` | `boolean` | Emitted when the "repeat on prev" setting is toggled. |
+| `smoothPlayPauseVolumeChange` | `boolean` | Emitted when the smooth play/pause volume setting is toggled. |
+| `smoothStopVolumeChange` | `boolean` | Emitted when the smooth stop volume setting is toggled. |
+| `fadeVolumeSpeedChange` | `number` | Emitted when the volume fade speed is updated. |
+| `prevClickTimeoutDurationChange` | `number` | Emitted when the "repeat on prev" timeout duration is updated. |
+
+### 💀 Lifecycle Events
+| Event | Data Type | Description |
+| :--- | :--- | :--- |
+| `destroyed` | `void` | Emitted when the `destroy()` method has finished executing. |
 
 ---
 
 ## ⚠️ Error Handling
 
 The class uses strict validation. The following errors may be thrown:
-*   **`TypeError`**: Thrown when an argument is of the wrong type (e.g., passing a string to `volume`).
-*   **`RangeError`**: Thrown when a number is out of allowed bounds (e.g., an index that doesn't exist or volume > 1.0).
-*   **`Error`**: Thrown if no compatible adapter is found for the current content.
+* **`TypeError`**: Thrown when an argument is of the wrong type (e.g., invalid index type, non-boolean options, invalid adapter instance, or empty storage key).
+* **`RangeError`**: Thrown when a number is out of allowed bounds (e.g., negative time, volume outside `0.0`-`1.0`, negative durations, or index out of playlist bounds).
+* **`Error`**: Thrown if no compatible adapter is found for the current content.

package/docs/v1/libs/TinyTimeout.md

@@ -78,20 +78,7 @@ A numeric ID returned by `setTimeout`, which can be manually canceled later usin
 
 ---
 
-### 🔁 `waitForTrue(getValue, checkInterval = 100)`
-
-Waits until a provided function returns `true`, polling periodically.
-
-```ts
-static waitForTrue(getValue: () => boolean, checkInterval?: number): Promise<void>
-```
-
-* `getValue`: Function that returns `true` when the wait should end.
-* `checkInterval`: Polling interval in milliseconds.
-
----
-
-### 🧩 `waitForTrue(getValue, checkInterval?)` *(instance version)*
+### 🧩 `waitForTrue(getValue, checkInterval?)`
 
 Same as `waitForTrue`, but uses the instance's `cooldownWatcherTime` as the default if `checkInterval` is `null`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.28.4",
+  "version": "1.28.6",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "bin": {
     "tiny-essentials-fork": "./TinyFork.mjs"
@@ -108,6 +108,10 @@
       "require": "./dist/v1/basics/text.cjs",
       "import": "./dist/v1/basics/text.mjs"
     },
+    "./basics/promiseUtils": {
+      "require": "./dist/v1/basics/promiseUtils.cjs",
+      "import": "./dist/v1/basics/promiseUtils.mjs"
+    },
     "./fileManager": {
       "require": "./dist/v1/fileManager/index.cjs",
       "import": "./dist/v1/fileManager/index.mjs"
@@ -132,6 +136,30 @@
       "require": "./dist/v1/libs/TinyMediaPlayer.cjs",
       "import": "./dist/v1/libs/TinyMediaPlayer.mjs"
     },
+    "./libs/TinyMediaPlayer/Base": {
+      "require": "./dist/v1/libs/TinyMediaPlayer/index.cjs",
+      "import": "./dist/v1/libs/TinyMediaPlayer/index.mjs"
+    },
+    "./libs/TinyMediaPlayer/Youtube": {
+      "require": "./dist/v1/libs/TinyMediaPlayer/Youtube.cjs",
+      "import": "./dist/v1/libs/TinyMediaPlayer/Youtube.mjs"
+    },
+    "./libs/TinyMediaPlayer/SoundCloud": {
+      "require": "./dist/v1/libs/TinyMediaPlayer/SoundCloud.cjs",
+      "import": "./dist/v1/libs/TinyMediaPlayer/SoundCloud.mjs"
+    },
+    "./libs/TinyMediaPlayer/HtmlAudio": {
+      "require": "./dist/v1/libs/TinyMediaPlayer/HtmlAudio.cjs",
+      "import": "./dist/v1/libs/TinyMediaPlayer/HtmlAudio.mjs"
+    },
+    "./libs/TinyMediaPlayer/HtmlVideo": {
+      "require": "./dist/v1/libs/TinyMediaPlayer/HtmlVideo.cjs",
+      "import": "./dist/v1/libs/TinyMediaPlayer/HtmlVideo.mjs"
+    },
+    "./libs/TinyMediaPlayer/docs/YouTubePlayer": {
+      "require": "./dist/v1/libs/TinyMediaPlayer/docs/YouTubePlayer.cjs",
+      "import": "./dist/v1/libs/TinyMediaPlayer/docs/YouTubePlayer.mjs"
+    },
     "./libs/TinyRadioFm": {
       "require": "./dist/v1/libs/TinyRadioFm.cjs",
       "import": "./dist/v1/libs/TinyRadioFm.mjs"
@@ -483,23 +511,16 @@
   },
   "keywords": [
     "tiny-essentials",
-    "timeout",
+    "utility-library",
     "storage",
     "text-editor",
     "color-converter",
     "clock",
     "time",
-    "text",
-    "text-range",
-    "input-editor",
-    "string-utils",
     "string-manipulation",
     "obj-type",
     "type-checker",
-    "simple-math",
-    "math-utils",
     "shuffle-array",
-    "array-utils",
     "json",
     "json-utils",
     "json-color",
@@ -516,7 +537,47 @@
     "toolkit",
     "frontend-utils",
     "backend-utils",
-    "nodejs-utils"
+    "nodejs-utils",
+    "array-utils",
+    "object-utils",
+    "string-utils",
+    "math-utils",
+    "dom-utils",
+    "html-utils",
+    "css-utils",
+    "modular-scripts",
+    "type-validation",
+    "text-manipulation",
+    "text-formatting",
+    "color-management",
+    "color-conversion",
+    "color-validation",
+    "drag-and-drop",
+    "scroll-management",
+    "clipboard-management",
+    "notifications",
+    "toast-notifications",
+    "loading-screen",
+    "cookie-consent",
+    "i18n",
+    "iframe-communication",
+    "window-communication",
+    "media-playback",
+    "audio-processing",
+    "gamepad-api",
+    "input-handling",
+    "file-upload",
+    "inventory-management",
+    "level-up-system",
+    "raffle-system",
+    "day-night-cycle",
+    "rate-limiting",
+    "promise-queue",
+    "file-management",
+    "terminal-ui",
+    "json-formatting",
+    "fuzzy-logic",
+    "text-range-editor"
   ],
   "author": "Yasmin Seidel (Jasmin Dreasond)",
   "license": "LGPL-3.0-only",