tiny-essentials 1.28.0 → 1.28.2

package/dist/v1/libs/TinyRadioFm.cjs

@@ -2,11 +2,15 @@
 
 var events = require('events');
 var mediaContent = require('../basics/mediaContent.cjs');
+var utils = require('./utils.cjs');
+
+const checkDestroy = utils.createCheckDestroyed('TinyRadioFm');
 
 /**
+ * @typedef {import('../basics/mediaContent.mjs').PictureDataType} PictureDataType
  * @typedef {import('../basics/mediaContent.mjs').MediaContentBase} MediaContentBase
- * @typedef {import('../basics/mediaContent.mjs').MediaContentMetadata} MediaContentMetadata
- * @typedef {import('../basics/mediaContent.mjs').MediaContent} MediaContent
+ * @typedef {import('../basics/mediaContent.mjs').MediaContentMetadata<PictureDataType>} MediaContentMetadata
+ * @typedef {import('../basics/mediaContent.mjs').MediaContent<PictureDataType>} MediaContent
  * @typedef {import('../basics/mediaContent.mjs').IPicture} IPicture
  * @typedef {import('../basics/mediaContent.mjs').MediaNumber} MediaNumber
  * @typedef {import('../basics/mediaContent.mjs').MediaLoadingError} MediaLoadingError
@@ -179,11 +183,19 @@ class TinyRadioFm extends events.EventEmitter {
     TinyRadioFm.#unknownArtist = value;
   }
 
+  /** @type {boolean} */
+  #destroyed = false;
+
+  get destroyed() {
+    return this.#destroyed;
+  }
+
   /**
    * Gets the total count of all content items (music and voice) in the system.
    * @returns {number}
    */
   get size() {
+    checkDestroy(this.#destroyed);
     return this.#musicList.length + this.#voiceList.length;
   }
 
@@ -192,6 +204,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @returns {number}
    */
   get musicSize() {
+    checkDestroy(this.#destroyed);
     return this.#musicList.length;
   }
 
@@ -200,6 +213,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @returns {number}
    */
   get voiceSize() {
+    checkDestroy(this.#destroyed);
     return this.#voiceList.length;
   }
 
@@ -208,6 +222,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @returns {number}
    */
   get customPosSize() {
+    checkDestroy(this.#destroyed);
     return this.#customPositions.length;
   }
 
@@ -216,6 +231,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @returns {number}
    */
   get tasksSize() {
+    checkDestroy(this.#destroyed);
     return this.#scheduledTasks.length;
   }
 
@@ -224,6 +240,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @returns {number}
    */
   get cycleCacheSize() {
+    checkDestroy(this.#destroyed);
     return this.#cycleCache.size;
   }
 
@@ -234,6 +251,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @returns {MediaContent[]}
    */
   get musicList() {
+    checkDestroy(this.#destroyed);
     return structuredClone(this.#musicList);
   }
 
@@ -244,6 +262,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @returns {MediaContent[]}
    */
   get voiceList() {
+    checkDestroy(this.#destroyed);
     return structuredClone(this.#voiceList);
   }
 
@@ -254,6 +273,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @returns {CustomPosition[]}
    */
   get customPositions() {
+    checkDestroy(this.#destroyed);
     return structuredClone(this.#customPositions);
   }
 
@@ -264,6 +284,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @returns {ScheduledTask[]}
    */
   get scheduledTasks() {
+    checkDestroy(this.#destroyed);
     return structuredClone(this.#scheduledTasks);
   }
 
@@ -272,6 +293,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @returns {MediaContent[]} A cloned object of the cache.
    */
   get allList() {
+    checkDestroy(this.#destroyed);
     return [...this.musicList, ...this.voiceList];
   }
 
@@ -282,6 +304,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @returns {number}
    */
   get seed() {
+    checkDestroy(this.#destroyed);
     return this.#seed;
   }
   /**
@@ -289,6 +312,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @param {number} seed - The new seed.
    */
   set seed(seed) {
+    checkDestroy(this.#destroyed);
     if (typeof seed !== 'number') throw new TypeError('Seed must be a number.');
     this.#seed = seed;
     this.#cycleCache.clear();
@@ -302,6 +326,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @returns {number}
    */
   get anchorDate() {
+    checkDestroy(this.#destroyed);
     return this.#anchorDate;
   }
 
@@ -325,6 +350,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @returns {RadioConfig}
    */
   get config() {
+    checkDestroy(this.#destroyed);
     return structuredClone(this.#config);
   }
   /**
@@ -333,6 +359,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @throws {TypeError|RangeError} If the new configuration is invalid.
    */
   set config(config) {
+    checkDestroy(this.#destroyed);
     // Validate the entire object before applying it
     this.#validateConfig(config);
 
@@ -455,6 +482,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @throws {TypeError} If the type is invalid or the data lacks a valid ID and numerical duration.
    */
   add(type, data, smartQueue = true) {
+    checkDestroy(this.#destroyed);
     if (!['music', 'voice', 'custom'].includes(type)) {
       throw new TypeError('Type must be "music", "voice", or "custom".');
     }
@@ -491,6 +519,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @throws {TypeError} If arguments do not match the required types or action/type constraints.
    */
   scheduleTask(timestamp, action, type, payload, smartQueue = true) {
+    checkDestroy(this.#destroyed);
     if (typeof timestamp !== 'number' || isNaN(timestamp))
       throw new TypeError('timestamp must be a valid number.');
     if (!['add', 'remove', 'move'].includes(action))
@@ -560,6 +589,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @throws {TypeError} If the id is not a string.
    */
   remove(id) {
+    checkDestroy(this.#destroyed);
     if (typeof id !== 'string') throw new TypeError('id must be a string.');
 
     // Revoke Blob URLs of items being removed to free memory
@@ -571,7 +601,7 @@ class TinyRadioFm extends events.EventEmitter {
 
     /**
      * Filter function to match items against the provided ID.
-     * @type {function(any): boolean}
+     * @type {(item: any) => boolean}
      */
     const filterFn = (item) => item.id !== id && item.content?.id !== id;
 
@@ -605,6 +635,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @throws {TypeError|RangeError} If the provided values or the resulting state is invalid.
    */
   setConfig(config) {
+    checkDestroy(this.#destroyed);
     // First, validate the incoming partial object for basic type correctness
     this.#validateConfig(config);
 
@@ -624,6 +655,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @returns {RadioEvent|null} The current active event, or null if empty.
    */
   getCurrentEvent() {
+    checkDestroy(this.#destroyed);
     const now = Date.now();
     this.#syncRealTimeState(now);
     return this.#getEventAtTime(now, now);
@@ -639,6 +671,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @throws {RangeError} If the limit exceeds the configured queryLimit or is <= 0.
    */
   queryTimeline(targetDate, limit = 10) {
+    checkDestroy(this.#destroyed);
     if (typeof limit !== 'number' || isNaN(limit)) {
       throw new TypeError(`Invalid query limit value. Ensure it is a number.`);
     }
@@ -677,6 +710,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @returns {CustomPosition[]} Shallow copy of custom positions array.
    */
   searchCustomPositions() {
+    checkDestroy(this.#destroyed);
     this.#syncRealTimeState(Date.now());
     return [...this.#customPositions];
   }
@@ -693,10 +727,18 @@ class TinyRadioFm extends events.EventEmitter {
         const newItem = structuredClone(item);
         if (newItem.picture && Array.isArray(newItem.picture)) {
           newItem.picture = await Promise.all(
-            newItem.picture.map(async (pic) => ({
-              ...pic,
-              data: await mediaContent.blobUrlToBase64(pic.data),
-            })),
+            newItem.picture.map(async (pic) => {
+              // Only performs the asynchronous conversion if it really is a Blob URL
+              if (typeof pic.data === 'string' && pic.data.startsWith('blob:')) {
+                return {
+                  ...pic,
+                  data: await mediaContent.blobUrlToBase64(pic.data),
+                };
+              }
+
+              // If it is a normal URL, skip the process and keep it as it is
+              return pic;
+            }),
           );
         }
         return newItem;
@@ -726,6 +768,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @returns {Promise<string>} Stringified JSON state.
    */
   async exportState() {
+    checkDestroy(this.#destroyed);
     const processedMusic = await this._processListForExport(this.#musicList);
     const processedVoice = await this._processListForExport(this.#voiceList);
 
@@ -770,6 +813,7 @@ class TinyRadioFm extends events.EventEmitter {
    * @throws {TypeError} If json is not a valid string or object.
    */
   importState(json) {
+    checkDestroy(this.#destroyed);
     /** @type {TinyRadioFmImport} */
     let data;
     if (typeof json === 'string') {
@@ -791,7 +835,7 @@ class TinyRadioFm extends events.EventEmitter {
   /**
    * Mulberry32 Pseudo-Random Number Generator.
    * @param {number} seed - The initialization seed.
-   * @returns {function(): number} PRNG function returning a float between 0 and 1.
+   * @returns {() => number} PRNG function returning a float between 0 and 1.
    * @private
    */
   _prng(seed) {
@@ -1305,10 +1349,21 @@ class TinyRadioFm extends events.EventEmitter {
       return list.map((item) => {
         const newItem = { ...item };
         if (newItem.picture && Array.isArray(newItem.picture)) {
-          newItem.picture = newItem.picture.map((pic) => ({
-            ...pic,
-            data: mediaContent.convertToBlobUrl(pic.data, pic.format),
-          }));
+          newItem.picture = newItem.picture.map((pic) => {
+            // Check whether the data is compatible with the Blob structure (Base64 or Binary)
+            const isBase64 = typeof pic.data === 'string' && pic.data.startsWith('data:');
+            const isUint8Array = pic.data instanceof Uint8Array;
+
+            if (isBase64 || isUint8Array) {
+              return {
+                ...pic,
+                data: mediaContent.convertToBlobUrl(pic.data, pic.format),
+              };
+            }
+
+            // If it is a default web URL or local file, use the URL directly
+            return pic;
+          });
         }
         return newItem;
       });
@@ -1347,6 +1402,8 @@ class TinyRadioFm extends events.EventEmitter {
    * @param {boolean} [destroyThumbs=true]
    */
   destroy(destroyThumbs = true) {
+    if (this.#destroyed) return;
+
     if (destroyThumbs) {
       this.#musicList.forEach((item) => mediaContent.revokeContentUrls(item));
       this.#voiceList.forEach((item) => mediaContent.revokeContentUrls(item));
@@ -1371,6 +1428,7 @@ class TinyRadioFm extends events.EventEmitter {
     this.#cycleCache.clear();
     this.emit('destroyed', { timestamp: Date.now() });
     this.removeAllListeners();
+    this.#destroyed = true;
   }
 }
 

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

@@ -1,17 +1,15 @@
-export default TinyRadioFm;
-export type MediaContentBase = import("../basics/mediaContent.mjs").MediaContentBase;
-export type MediaContentMetadata = import("../basics/mediaContent.mjs").MediaContentMetadata;
-export type MediaContent = import("../basics/mediaContent.mjs").MediaContent;
-export type IPicture = import("../basics/mediaContent.mjs").IPicture;
-export type MediaNumber = import("../basics/mediaContent.mjs").MediaNumber;
-export type MediaLoadingError = import("../basics/mediaContent.mjs").MediaLoadingError;
-export type MediaLoadingErrorData = import("../basics/mediaContent.mjs").MediaLoadingErrorData;
-export type LoadingMediaProgress = import("../basics/mediaContent.mjs").LoadingMediaProgress;
-export type ParseMediaContentMetadata = import("../basics/mediaContent.mjs").ParseMediaContentMetadata;
-export type UnknownArtistGetter = import("../basics/mediaContent.mjs").UnknownArtistGetter;
-/**
- * Represents a content item injected at a specific point in the absolute timeline.
- */
+import { EventEmitter } from 'events';
+export type PictureDataType = import('../basics/mediaContent.mjs').PictureDataType;
+export type MediaContentBase = import('../basics/mediaContent.mjs').MediaContentBase;
+export type MediaContentMetadata = import('../basics/mediaContent.mjs').MediaContentMetadata<PictureDataType>;
+export type MediaContent = import('../basics/mediaContent.mjs').MediaContent<PictureDataType>;
+export type IPicture = import('../basics/mediaContent.mjs').IPicture;
+export type MediaNumber = import('../basics/mediaContent.mjs').MediaNumber;
+export type MediaLoadingError = import('../basics/mediaContent.mjs').MediaLoadingError;
+export type MediaLoadingErrorData = import('../basics/mediaContent.mjs').MediaLoadingErrorData;
+export type LoadingMediaProgress = import('../basics/mediaContent.mjs').LoadingMediaProgress;
+export type ParseMediaContentMetadata = import('../basics/mediaContent.mjs').ParseMediaContentMetadata;
+export type UnknownArtistGetter = import('../basics/mediaContent.mjs').UnknownArtistGetter;
 export type CustomPosition = {
     /**
      * - The audio/music content.
@@ -26,9 +24,6 @@ export type CustomPosition = {
      */
     originalTimestamp: number;
 };
-/**
- * Data required to relocate an existing item within a playlist.
- */
 export type ScheduledMovePayload = {
     /**
      * - Content ID to move.
@@ -39,13 +34,7 @@ export type ScheduledMovePayload = {
      */
     newIndex: number;
 };
-/**
- * A union type representing the various data formats a scheduled task payload can take.
- */
 export type ScheduledTaskPayload = MediaContent | string | ScheduledMovePayload;
-/**
- * A scheduled instruction to modify the radio state at a specific point in time.
- */
 export type ScheduledTask = {
     /**
      * - The absolute time to execute the action.
@@ -54,19 +43,16 @@ export type ScheduledTask = {
     /**
      * - The type of modification.
      */
-    action: "add" | "remove" | "move";
+    action: 'add' | 'remove' | 'move';
     /**
      * - Target playlist.
      */
-    type: "music" | "voice";
+    type: 'music' | 'voice';
     /**
      * - Data relative to the action.
      */
     payload: ScheduledTaskPayload;
 };
-/**
- * A standardized representation of an active or upcoming event in the radio timeline.
- */
 export type RadioEvent = {
     /**
      * - Content ID.
@@ -113,13 +99,7 @@ export type RadioEvent = {
      */
     isCustom: boolean;
 };
-/**
- * The available sequence logic modes for playlist playback.
- */
-export type RadioModes = "playlist" | "random";
-/**
- * Global configuration settings for the radio engine behavior.
- */
+export type RadioModes = 'playlist' | 'random';
 export type RadioConfig = {
     /**
      * - Sequence mode for music.
@@ -158,16 +138,10 @@ export type RadioConfig = {
      */
     voiceMaxConsecutive: number;
 };
-/**
- * An extension of MediaContent that includes temporal boundaries within a generated cycle.
- */
 export type CycleBlockData = MediaContent & {
     cycleStart: number;
     cycleEnd: number;
 };
-/**
- * A structural block representing a single full iteration of the radio sequence.
- */
 export type CycleBlock = {
     /**
      * - Items belonging to this cycle.
@@ -178,9 +152,6 @@ export type CycleBlock = {
      */
     duration: number;
 };
-/**
- * Information about the location of a specific cycle within the absolute timeline.
- */
 export type CycleLocation = {
     /**
      * - The located cycle block.
@@ -195,9 +166,6 @@ export type CycleLocation = {
      */
     loopIndex: number;
 };
-/**
- * The complete state object used for exporting and importing the radio system.
- */
 export type TinyRadioFmImport = {
     /**
      * - The music playlist.
@@ -229,9 +197,10 @@ export type TinyRadioFmImport = {
     config: RadioConfig;
 };
 /**
+ * @typedef {import('../basics/mediaContent.mjs').PictureDataType} PictureDataType
  * @typedef {import('../basics/mediaContent.mjs').MediaContentBase} MediaContentBase
- * @typedef {import('../basics/mediaContent.mjs').MediaContentMetadata} MediaContentMetadata
- * @typedef {import('../basics/mediaContent.mjs').MediaContent} MediaContent
+ * @typedef {import('../basics/mediaContent.mjs').MediaContentMetadata<PictureDataType>} MediaContentMetadata
+ * @typedef {import('../basics/mediaContent.mjs').MediaContent<PictureDataType>} MediaContent
  * @typedef {import('../basics/mediaContent.mjs').IPicture} IPicture
  * @typedef {import('../basics/mediaContent.mjs').MediaNumber} MediaNumber
  * @typedef {import('../basics/mediaContent.mjs').MediaLoadingError} MediaLoadingError
@@ -329,7 +298,8 @@ export type TinyRadioFmImport = {
  * A deterministic, seed-based radio management system with scheduled adaptations and weighted random generation.
  * @beta
  */
-declare class TinyRadioFm extends EventEmitter<any> {
+declare class TinyRadioFm extends EventEmitter {
+    #private;
     /**
      * A Static Factory Method that prepares a MediaContent object by
      * extracting metadata from an audio source.
@@ -351,32 +321,21 @@ declare class TinyRadioFm extends EventEmitter<any> {
         id?: string;
         weight?: number;
     }, parseFile?: ParseMediaContentMetadata, callbacks?: {
-        onProgress?: ((progress: LoadingMediaProgress) => void) | undefined;
-        onError?: ((error: MediaLoadingErrorData) => void) | undefined;
+        onProgress?: (progress: LoadingMediaProgress) => void;
+        onError?: (error: MediaLoadingErrorData) => void;
     }): Promise<MediaContent>;
     /**
-     * @type {UnknownArtistGetter}
-     * The default identifier or function used when an artist cannot be determined.
+     * Gets the current value used to represent unknown artists.
+     * @returns {UnknownArtistGetter}
      */
-    static #unknownArtist: UnknownArtistGetter;
+    static get unknownArtist(): UnknownArtistGetter;
     /**
      * Sets the value used to represent unknown artists.
      * @param {UnknownArtistGetter} value - A string or a function that returns a string.
      * @throws {TypeError} If the value is neither a string nor a function.
      */
     static set unknownArtist(value: UnknownArtistGetter);
-    /**
-     * Gets the current value used to represent unknown artists.
-     * @returns {UnknownArtistGetter}
-     */
-    static get unknownArtist(): UnknownArtistGetter;
-    /**
-     * Initializes the radio system.
-     * @param {TinyRadioFmImport|null} [initialData=null] - JSON object to hydrate the radio state.
-     * @param {number} [seed=0] - Initial seed for deterministic randomness.
-     * @throws {TypeError} If initialData is not an object or null, or if seed is not a number.
-     */
-    constructor(initialData?: TinyRadioFmImport | null, seed?: number);
+    get destroyed(): boolean;
     /**
      * Gets the total count of all content items (music and voice) in the system.
      * @returns {number}
@@ -432,21 +391,26 @@ declare class TinyRadioFm extends EventEmitter<any> {
      * @returns {MediaContent[]} A cloned object of the cache.
      */
     get allList(): MediaContent[];
-    /**
-     * Sets the core randomness seed and clears the current cycle cache.
-     * @param {number} seed - The new seed.
-     */
-    set seed(seed: number);
     /**
      * Gets the current randomness seed.
      * @returns {number}
      */
     get seed(): number;
+    /**
+     * Sets the core randomness seed and clears the current cycle cache.
+     * @param {number} seed - The new seed.
+     */
+    set seed(seed: number);
     /**
      * Gets the absolute timestamp used as the timeline anchor.
      * @returns {number}
      */
     get anchorDate(): number;
+    /**
+     * Gets a deep clone of the current radio configuration.
+     * @returns {RadioConfig}
+     */
+    get config(): RadioConfig;
     /**
      * Performs a complete replacement of the configuration.
      * @param {RadioConfig} config - The new full configuration object.
@@ -454,10 +418,12 @@ declare class TinyRadioFm extends EventEmitter<any> {
      */
     set config(config: RadioConfig);
     /**
-     * Gets a deep clone of the current radio configuration.
-     * @returns {RadioConfig}
+     * Initializes the radio system.
+     * @param {TinyRadioFmImport|null} [initialData=null] - JSON object to hydrate the radio state.
+     * @param {number} [seed=0] - Initial seed for deterministic randomness.
+     * @throws {TypeError} If initialData is not an object or null, or if seed is not a number.
      */
-    get config(): RadioConfig;
+    constructor(initialData?: TinyRadioFmImport | null, seed?: number);
     /**
      * Adds new content instantly to the radio sequence.
      * @param {'music'|'voice'|'custom'} type - The category of the content.
@@ -465,7 +431,7 @@ declare class TinyRadioFm extends EventEmitter<any> {
      * @param {boolean} [smartQueue=true] - If true, delays insertion until the end of the content playing at that timestamp (only affects 'custom').
      * @throws {TypeError} If the type is invalid or the data lacks a valid ID and numerical duration.
      */
-    add(type: "music" | "voice" | "custom", data: MediaContent & {
+    add(type: 'music' | 'voice' | 'custom', data: MediaContent & {
         timestamp?: number;
     }, smartQueue?: boolean): void;
     /**
@@ -477,7 +443,7 @@ declare class TinyRadioFm extends EventEmitter<any> {
      * @param {boolean} [smartQueue=true] - If true, delays the task execution until the end of the content playing at that timestamp.
      * @throws {TypeError} If arguments do not match the required types or action/type constraints.
      */
-    scheduleTask(timestamp: number, action: "add" | "remove" | "move", type: "music" | "voice", payload: ScheduledTaskPayload, smartQueue?: boolean): void;
+    scheduleTask(timestamp: number, action: 'add' | 'remove' | 'move', type: 'music' | 'voice', payload: ScheduledTaskPayload, smartQueue?: boolean): void;
     /**
      * Removes content instantly by ID across all active lists, positions, and future tasks.
      * @param {string} id - The unique identifier of the content.
@@ -537,7 +503,7 @@ declare class TinyRadioFm extends EventEmitter<any> {
     /**
      * Mulberry32 Pseudo-Random Number Generator.
      * @param {number} seed - The initialization seed.
-     * @returns {function(): number} PRNG function returning a float between 0 and 1.
+     * @returns {() => number} PRNG function returning a float between 0 and 1.
      * @private
      */
     private _prng;
@@ -547,7 +513,6 @@ declare class TinyRadioFm extends EventEmitter<any> {
      * @param {boolean} [destroyThumbs=true]
      */
     destroy(destroyThumbs?: boolean): void;
-    #private;
 }
-import { EventEmitter } from 'events';
+export default TinyRadioFm;
 //# sourceMappingURL=TinyRadioFm.d.mts.map