tiny-essentials 1.28.1 → 1.28.2

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,20 @@ 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.
@@ -433,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.
@@ -455,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.
@@ -466,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;
     /**
@@ -478,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.
@@ -538,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;
@@ -548,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

package/dist/v1/libs/TinyRadioFm.mjs

@@ -3,9 +3,10 @@ import { blobUrlToBase64, convertToBlobUrl, parseMediaMetadata, revokeContentUrl
 import { createCheckDestroyed } from './utils.mjs';
 const checkDestroy = 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
@@ -503,7 +504,7 @@ class TinyRadioFm extends EventEmitter {
             .forEach((cp) => revokeContentUrls(cp.content));
         /**
          * 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;
         this.#musicList = this.#musicList.filter(filterFn);
@@ -608,10 +609,17 @@ class TinyRadioFm extends EventEmitter {
         return Promise.all(list.map(async (item) => {
             const newItem = structuredClone(item);
             if (newItem.picture && Array.isArray(newItem.picture)) {
-                newItem.picture = await Promise.all(newItem.picture.map(async (pic) => ({
-                    ...pic,
-                    data: await blobUrlToBase64(pic.data),
-                })));
+                newItem.picture = await Promise.all(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 blobUrlToBase64(pic.data),
+                        };
+                    }
+                    // If it is a normal URL, skip the process and keep it as it is
+                    return pic;
+                }));
             }
             return newItem;
         }));
@@ -695,7 +703,7 @@ class TinyRadioFm extends 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) {
@@ -1107,10 +1115,19 @@ class TinyRadioFm extends EventEmitter {
             return list.map((item) => {
                 const newItem = { ...item };
                 if (newItem.picture && Array.isArray(newItem.picture)) {
-                    newItem.picture = newItem.picture.map((pic) => ({
-                        ...pic,
-                        data: 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: convertToBlobUrl(pic.data, pic.format),
+                            };
+                        }
+                        // If it is a default web URL or local file, use the URL directly
+                        return pic;
+                    });
                 }
                 return newItem;
             });

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

@@ -1,18 +1,4 @@
-export default TinyRateLimiter;
-/**
- * Callback triggered when a group's stored hit history exceeds
- * the configured memory limit.
- *
- * This callback is purely informational and does not block execution.
- */
 export type OnMemoryExceeded = (groupId: string) => void;
-/**
- * Callback triggered when a group is considered expired and removed
- * during the cleanup process.
- *
- * This usually happens when the group remains inactive longer than
- * its configured TTL or the global maxIdle value.
- */
 export type OnGroupExpired = (groupId: string) => void;
 /**
  * Callback triggered when a group's stored hit history exceeds
@@ -82,30 +68,7 @@ export type OnGroupExpired = (groupId: string) => void;
  * and safe to use in long-running Node.js processes.
  */
 declare class TinyRateLimiter {
-    /**
-     * Creates a new TinyRateLimiter instance.
-     *
-     * At least one of `maxHits` or `interval` must be provided.
-     *
-     * @param {Object} options
-     * @param {number|null} [options.maxMemory=100000]
-     *   Maximum timestamps stored per group (memory cap).
-     * @param {number} [options.maxHits]
-     *   Maximum number of allowed hits.
-     * @param {number} [options.interval]
-     *   Sliding time window in milliseconds.
-     * @param {number} [options.cleanupInterval]
-     *   Interval (ms) for automatic cleanup execution.
-     * @param {number} [options.maxIdle=300000]
-     *   Maximum inactivity time (ms) before a group expires.
-     */
-    constructor({ maxHits, interval, cleanupInterval, maxIdle, maxMemory }: {
-        maxMemory?: number | null | undefined;
-        maxHits?: number | undefined;
-        interval?: number | undefined;
-        cleanupInterval?: number | undefined;
-        maxIdle?: number | undefined;
-    });
+    #private;
     /**
      * Gets the current destruction status of the instance.
      *
@@ -176,6 +139,30 @@ declare class TinyRateLimiter {
      * Removes the group-expiration callback.
      */
     clearOnGroupExpired(): void;
+    /**
+     * Creates a new TinyRateLimiter instance.
+     *
+     * At least one of `maxHits` or `interval` must be provided.
+     *
+     * @param {Object} options
+     * @param {number|null} [options.maxMemory=100000]
+     *   Maximum timestamps stored per group (memory cap).
+     * @param {number} [options.maxHits]
+     *   Maximum number of allowed hits.
+     * @param {number} [options.interval]
+     *   Sliding time window in milliseconds.
+     * @param {number} [options.cleanupInterval]
+     *   Interval (ms) for automatic cleanup execution.
+     * @param {number} [options.maxIdle=300000]
+     *   Maximum inactivity time (ms) before a group expires.
+     */
+    constructor({ maxHits, interval, cleanupInterval, maxIdle, maxMemory }: {
+        maxMemory?: number | null;
+        maxHits?: number;
+        interval?: number;
+        cleanupInterval?: number;
+        maxIdle?: number;
+    });
     /**
      * Check if a given ID is a groupId (not a userId)
      * @param {string} id
@@ -388,6 +375,6 @@ declare class TinyRateLimiter {
      * Destroy the rate limiter, stopping cleanup and clearing data
      */
     destroy(): void;
-    #private;
 }
+export default TinyRateLimiter;
 //# sourceMappingURL=TinyRateLimiter.d.mts.map

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

@@ -1,24 +1,7 @@
-export default TinySimpleDice;
-/**
- * Represents a list of values used in dice modifier operations.
- *
- * Each entry can be either:
- * - A number (representing a fixed numeric value), or
- * - An object describing a dice roll, containing:
- *   - `value`: The rolled result.
- *   - `sides`: The number of sides of the die (e.g., 6 for a d6).
- *
- * Examples of valid entries:
- * - `5`                   → a direct numeric value
- * - `{ value: 3, sides: 6 }` → result of rolling a d6
- */
 export type DiceModifiersValues = (number | {
     value: number;
     sides: number;
 })[];
-/**
- * Represents the result after applying all dice modifiers to a roll.
- */
 export type ApplyDiceModifiersResult = {
     /**
      * - The final computed value after all modifiers and dice results are processed.
@@ -29,9 +12,6 @@ export type ApplyDiceModifiersResult = {
      */
     steps: ApplyDiceModifiersStep[];
 };
-/**
- * Represents a single step in the dice-modification process.
- */
 export type ApplyDiceModifiersStep = {
     /**
      * - The parsed tokens used in this step after normalization.
@@ -106,6 +86,7 @@ export type ApplyDiceModifiersStep = {
  * values suitable for indexing arrays or Sets.
  */
 declare class TinySimpleDice {
+    #private;
     /**
      * Safely evaluates a mathematical expression (supports +, -, *, /, %, **, parentheses, fractions and decimals).
      * This function ensures only valid math characters are processed.
@@ -222,16 +203,10 @@ declare class TinySimpleDice {
      */
     static rollArrayIndex(arr: any[] | Set<any>): number;
     /**
-     * Creates a new TinySimpleDice instance.
-     * @param {Object} options - Configuration options for the dice.
-     * @param {number} options.maxValue - Maximum value the dice can roll.
-     * @param {boolean} [options.allowZero=true] - Whether 0 is allowed as a result.
-     * @throws {TypeError} If maxValue is not a non-negative integer or allowZero is not boolean.
+     * Maximum value the dice can roll.
+     * @type {number}
      */
-    constructor({ maxValue, allowZero }: {
-        maxValue: number;
-        allowZero?: boolean | undefined;
-    });
+    get maxValue(): number;
     /**
      * Set the maximum value the dice can roll.
      * @param {number} value - New maximum value (must be a non-negative integer)
@@ -239,10 +214,10 @@ declare class TinySimpleDice {
      */
     set maxValue(value: number);
     /**
-     * Maximum value the dice can roll.
-     * @type {number}
+     * Whether 0 is allowed as a result.
+     * @type {boolean}
      */
-    get maxValue(): number;
+    get allowZero(): boolean;
     /**
      * Set whether 0 is allowed as a result.
      * @param {boolean} value - true to allow 0, false to disallow
@@ -250,15 +225,21 @@ declare class TinySimpleDice {
      */
     set allowZero(value: boolean);
     /**
-     * Whether 0 is allowed as a result.
-     * @type {boolean}
+     * Creates a new TinySimpleDice instance.
+     * @param {Object} options - Configuration options for the dice.
+     * @param {number} options.maxValue - Maximum value the dice can roll.
+     * @param {boolean} [options.allowZero=true] - Whether 0 is allowed as a result.
+     * @throws {TypeError} If maxValue is not a non-negative integer or allowZero is not boolean.
      */
-    get allowZero(): boolean;
+    constructor({ maxValue, allowZero }: {
+        maxValue: number;
+        allowZero?: boolean;
+    });
     /**
      * Rolls the dice according to the configuration.
      * @returns {number} - Random number according to the dice configuration.
      */
     roll(): number;
-    #private;
 }
+export default TinySimpleDice;
 //# sourceMappingURL=TinySimpleDice.d.mts.map