audio-channel-queue 1.8.0 → 1.10.0

package/dist/queue-manipulation.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Queue manipulation functions for the audio-channel-queue package
+ * Provides advanced queue management including item removal, reordering, and clearing
+ */
+import { QueueManipulationResult, QueueItem } from './types';
+/**
+ * Removes a specific item from the queue by its slot number (0-based index)
+ * Cannot remove the currently playing item (index 0) - use stopCurrentAudioInChannel instead
+ * @param queuedSlotNumber - Zero-based index of the item to remove (must be > 0)
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @throws Error if trying to remove currently playing item or invalid slot number
+ * @example
+ * ```typescript
+ * // Remove the second item in queue (index 1)
+ * const result = await removeQueuedItem(1, 0);
+ * if (result.success) {
+ *   console.log(`Removed item, queue now has ${result.updatedQueue.totalItems} items`);
+ * }
+ *
+ * // Remove the third item from channel 1
+ * await removeQueuedItem(2, 1);
+ * ```
+ */
+export declare const removeQueuedItem: (queuedSlotNumber: number, channelNumber?: number) => Promise<QueueManipulationResult>;
+/**
+ * Reorders a queue item by moving it from one position to another
+ * Cannot reorder the currently playing item (index 0)
+ * @param currentQueuedSlotNumber - Current zero-based index of the item to move (must be > 0)
+ * @param newQueuedSlotNumber - New zero-based index where the item should be placed (must be > 0)
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @throws Error if trying to reorder currently playing item or invalid slot numbers
+ * @example
+ * ```typescript
+ * // Move item from position 2 to position 1 (make it play next)
+ * const result = await reorderQueue(2, 1, 0);
+ * if (result.success) {
+ *   console.log('Item moved successfully');
+ * }
+ *
+ * // Move item from position 1 to end of queue
+ * await reorderQueue(1, 4, 0); // Assuming queue has 5+ items
+ * ```
+ */
+export declare const reorderQueue: (currentQueuedSlotNumber: number, newQueuedSlotNumber: number, channelNumber?: number) => Promise<QueueManipulationResult>;
+/**
+ * Clears all queued audio items after the currently playing item
+ * The current audio will continue playing but nothing will follow it
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @example
+ * ```typescript
+ * // Let current song finish but clear everything after it
+ * const result = await clearQueueAfterCurrent(0);
+ * if (result.success) {
+ *   console.log(`Cleared queue, current audio will be the last to play`);
+ * }
+ * ```
+ */
+export declare const clearQueueAfterCurrent: (channelNumber?: number) => Promise<QueueManipulationResult>;
+/**
+ * Gets information about a specific queue item by its slot number
+ * @param queueSlotNumber - Zero-based index of the queue item
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns QueueItem information or null if slot doesn't exist
+ * @example
+ * ```typescript
+ * const itemInfo = getQueueItemInfo(1, 0);
+ * if (itemInfo) {
+ *   console.log(`Next to play: ${itemInfo.fileName}`);
+ *   console.log(`Duration: ${itemInfo.duration}ms`);
+ * }
+ * ```
+ */
+export declare const getQueueItemInfo: (queueSlotNumber: number, channelNumber?: number) => QueueItem | null;
+/**
+ * Gets the current queue length for a specific channel
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Number of items in the queue, or 0 if channel doesn't exist
+ * @example
+ * ```typescript
+ * const queueSize = getQueueLength(0);
+ * console.log(`Channel 0 has ${queueSize} items in queue`);
+ * ```
+ */
+export declare const getQueueLength: (channelNumber?: number) => number;
+/**
+ * Swaps the positions of two queue items
+ * Cannot swap with the currently playing item (index 0)
+ * @param slotA - Zero-based index of first item to swap (must be > 0)
+ * @param slotB - Zero-based index of second item to swap (must be > 0)
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @example
+ * ```typescript
+ * // Swap the second and third items in queue
+ * const result = await swapQueueItems(1, 2, 0);
+ * if (result.success) {
+ *   console.log('Items swapped successfully');
+ * }
+ * ```
+ */
+export declare const swapQueueItems: (slotA: number, slotB: number, channelNumber?: number) => Promise<QueueManipulationResult>;

package/dist/queue-manipulation.js

@@ -0,0 +1,319 @@
+"use strict";
+/**
+ * @fileoverview Queue manipulation functions for the audio-channel-queue package
+ * Provides advanced queue management including item removal, reordering, and clearing
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.swapQueueItems = exports.getQueueLength = exports.getQueueItemInfo = exports.clearQueueAfterCurrent = exports.reorderQueue = exports.removeQueuedItem = void 0;
+const info_1 = require("./info");
+const events_1 = require("./events");
+const events_2 = require("./events");
+const utils_1 = require("./utils");
+/**
+ * Removes a specific item from the queue by its slot number (0-based index)
+ * Cannot remove the currently playing item (index 0) - use stopCurrentAudioInChannel instead
+ * @param queuedSlotNumber - Zero-based index of the item to remove (must be > 0)
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @throws Error if trying to remove currently playing item or invalid slot number
+ * @example
+ * ```typescript
+ * // Remove the second item in queue (index 1)
+ * const result = await removeQueuedItem(1, 0);
+ * if (result.success) {
+ *   console.log(`Removed item, queue now has ${result.updatedQueue.totalItems} items`);
+ * }
+ *
+ * // Remove the third item from channel 1
+ * await removeQueuedItem(2, 1);
+ * ```
+ */
+const removeQueuedItem = (queuedSlotNumber_1, ...args_1) => __awaiter(void 0, [queuedSlotNumber_1, ...args_1], void 0, function* (queuedSlotNumber, channelNumber = 0) {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel) {
+        return {
+            error: `Channel ${channelNumber} does not exist`,
+            success: false
+        };
+    }
+    if (queuedSlotNumber < 0 || queuedSlotNumber >= channel.queue.length) {
+        return {
+            error: `Invalid slot number ${queuedSlotNumber}. Queue has ${channel.queue.length} items ` +
+                `(indices 0-${channel.queue.length - 1})`,
+            success: false
+        };
+    }
+    if (queuedSlotNumber === 0) {
+        return {
+            error: 'Cannot remove currently playing item (index 0). ' +
+                'Use stopCurrentAudioInChannel() instead',
+            success: false
+        };
+    }
+    // Remove the audio element from the queue
+    const removedAudio = channel.queue.splice(queuedSlotNumber, 1)[0];
+    // Clean up any progress tracking for the removed audio
+    (0, events_2.cleanupProgressTracking)(removedAudio, channelNumber, info_1.audioChannels);
+    // Emit queue change event
+    (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
+    const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+    return {
+        success: true,
+        updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+    };
+});
+exports.removeQueuedItem = removeQueuedItem;
+/**
+ * Reorders a queue item by moving it from one position to another
+ * Cannot reorder the currently playing item (index 0)
+ * @param currentQueuedSlotNumber - Current zero-based index of the item to move (must be > 0)
+ * @param newQueuedSlotNumber - New zero-based index where the item should be placed (must be > 0)
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @throws Error if trying to reorder currently playing item or invalid slot numbers
+ * @example
+ * ```typescript
+ * // Move item from position 2 to position 1 (make it play next)
+ * const result = await reorderQueue(2, 1, 0);
+ * if (result.success) {
+ *   console.log('Item moved successfully');
+ * }
+ *
+ * // Move item from position 1 to end of queue
+ * await reorderQueue(1, 4, 0); // Assuming queue has 5+ items
+ * ```
+ */
+const reorderQueue = (currentQueuedSlotNumber_1, newQueuedSlotNumber_1, ...args_1) => __awaiter(void 0, [currentQueuedSlotNumber_1, newQueuedSlotNumber_1, ...args_1], void 0, function* (currentQueuedSlotNumber, newQueuedSlotNumber, channelNumber = 0) {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel) {
+        return {
+            error: `Channel ${channelNumber} does not exist`,
+            success: false
+        };
+    }
+    if (currentQueuedSlotNumber < 0 || currentQueuedSlotNumber >= channel.queue.length) {
+        return {
+            error: `Invalid current slot number ${currentQueuedSlotNumber}. Queue has ` +
+                `${channel.queue.length} items (indices 0-${channel.queue.length - 1})`,
+            success: false
+        };
+    }
+    if (newQueuedSlotNumber < 0 || newQueuedSlotNumber >= channel.queue.length) {
+        return {
+            error: `Invalid new slot number ${newQueuedSlotNumber}. Queue has ` +
+                `${channel.queue.length} items (indices 0-${channel.queue.length - 1})`,
+            success: false
+        };
+    }
+    if (currentQueuedSlotNumber === 0) {
+        return {
+            error: 'Cannot reorder currently playing item (index 0). ' + 'Stop current audio first if needed',
+            success: false
+        };
+    }
+    if (newQueuedSlotNumber === 0) {
+        return {
+            error: 'Cannot move item to currently playing position (index 0). ' +
+                'Use queueAudioPriority() to add items to front of queue',
+            success: false
+        };
+    }
+    if (currentQueuedSlotNumber === newQueuedSlotNumber) {
+        // No change needed, but return success
+        const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+        return {
+            success: true,
+            updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+        };
+    }
+    // Remove the item from its current position
+    const audioToMove = channel.queue.splice(currentQueuedSlotNumber, 1)[0];
+    // Insert it at the new position
+    channel.queue.splice(newQueuedSlotNumber, 0, audioToMove);
+    // Emit queue change event
+    (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
+    const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+    return {
+        success: true,
+        updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+    };
+});
+exports.reorderQueue = reorderQueue;
+/**
+ * Clears all queued audio items after the currently playing item
+ * The current audio will continue playing but nothing will follow it
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @example
+ * ```typescript
+ * // Let current song finish but clear everything after it
+ * const result = await clearQueueAfterCurrent(0);
+ * if (result.success) {
+ *   console.log(`Cleared queue, current audio will be the last to play`);
+ * }
+ * ```
+ */
+const clearQueueAfterCurrent = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (channelNumber = 0) {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel) {
+        // For empty/non-existent channels, we can consider this a successful no-op
+        // since there's nothing to clear anyway
+        return {
+            success: true,
+            updatedQueue: {
+                channelNumber,
+                currentIndex: -1,
+                isPaused: false,
+                items: [],
+                totalItems: 0,
+                volume: 1.0
+            }
+        };
+    }
+    if (channel.queue.length <= 1) {
+        // Nothing to clear - either empty queue or only current audio
+        const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+        return {
+            success: true,
+            updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+        };
+    }
+    // Clean up progress tracking for all items except the current one
+    for (let i = 1; i < channel.queue.length; i++) {
+        (0, events_2.cleanupProgressTracking)(channel.queue[i], channelNumber, info_1.audioChannels);
+    }
+    // Keep only the currently playing audio (index 0)
+    channel.queue = channel.queue.slice(0, 1);
+    // Emit queue change event
+    (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
+    const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+    return {
+        success: true,
+        updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+    };
+});
+exports.clearQueueAfterCurrent = clearQueueAfterCurrent;
+/**
+ * Gets information about a specific queue item by its slot number
+ * @param queueSlotNumber - Zero-based index of the queue item
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns QueueItem information or null if slot doesn't exist
+ * @example
+ * ```typescript
+ * const itemInfo = getQueueItemInfo(1, 0);
+ * if (itemInfo) {
+ *   console.log(`Next to play: ${itemInfo.fileName}`);
+ *   console.log(`Duration: ${itemInfo.duration}ms`);
+ * }
+ * ```
+ */
+const getQueueItemInfo = (queueSlotNumber, channelNumber = 0) => {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel || queueSlotNumber < 0 || queueSlotNumber >= channel.queue.length) {
+        return null;
+    }
+    const audio = channel.queue[queueSlotNumber];
+    const audioInfo = (0, utils_1.getAudioInfoFromElement)(audio, channelNumber, info_1.audioChannels);
+    if (!audioInfo) {
+        return null;
+    }
+    const { duration, fileName, isLooping, isPlaying, src, volume } = audioInfo;
+    return {
+        duration,
+        fileName,
+        isCurrentlyPlaying: queueSlotNumber === 0 && isPlaying,
+        isLooping,
+        src,
+        volume
+    };
+};
+exports.getQueueItemInfo = getQueueItemInfo;
+/**
+ * Gets the current queue length for a specific channel
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Number of items in the queue, or 0 if channel doesn't exist
+ * @example
+ * ```typescript
+ * const queueSize = getQueueLength(0);
+ * console.log(`Channel 0 has ${queueSize} items in queue`);
+ * ```
+ */
+const getQueueLength = (channelNumber = 0) => {
+    const channel = info_1.audioChannels[channelNumber];
+    return channel ? channel.queue.length : 0;
+};
+exports.getQueueLength = getQueueLength;
+/**
+ * Swaps the positions of two queue items
+ * Cannot swap with the currently playing item (index 0)
+ * @param slotA - Zero-based index of first item to swap (must be > 0)
+ * @param slotB - Zero-based index of second item to swap (must be > 0)
+ * @param channelNumber - The channel number (defaults to 0)
+ * @returns Promise resolving to operation result with success status and updated queue
+ * @example
+ * ```typescript
+ * // Swap the second and third items in queue
+ * const result = await swapQueueItems(1, 2, 0);
+ * if (result.success) {
+ *   console.log('Items swapped successfully');
+ * }
+ * ```
+ */
+const swapQueueItems = (slotA_1, slotB_1, ...args_1) => __awaiter(void 0, [slotA_1, slotB_1, ...args_1], void 0, function* (slotA, slotB, channelNumber = 0) {
+    const channel = info_1.audioChannels[channelNumber];
+    if (!channel) {
+        return {
+            error: `Channel ${channelNumber} does not exist`,
+            success: false
+        };
+    }
+    if (slotA < 0 || slotA >= channel.queue.length) {
+        return {
+            error: `Invalid slot A ${slotA}. Queue has ${channel.queue.length} items ` +
+                `(indices 0-${channel.queue.length - 1})`,
+            success: false
+        };
+    }
+    if (slotB < 0 || slotB >= channel.queue.length) {
+        return {
+            error: `Invalid slot B ${slotB}. Queue has ${channel.queue.length} items ` +
+                `(indices 0-${channel.queue.length - 1})`,
+            success: false
+        };
+    }
+    if (slotA === 0 || slotB === 0) {
+        return {
+            error: 'Cannot swap with currently playing item (index 0)',
+            success: false
+        };
+    }
+    if (slotA === slotB) {
+        // No change needed, but return success
+        const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+        return {
+            success: true,
+            updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+        };
+    }
+    // Swap the audio elements
+    const temp = channel.queue[slotA];
+    channel.queue[slotA] = channel.queue[slotB];
+    channel.queue[slotB] = temp;
+    // Emit queue change event
+    (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
+    const updatedQueue = (0, utils_1.createQueueSnapshot)(channelNumber, info_1.audioChannels);
+    return {
+        success: true,
+        updatedQueue: updatedQueue !== null && updatedQueue !== void 0 ? updatedQueue : undefined
+    };
+});
+exports.swapQueueItems = swapQueueItems;

package/dist/types.d.ts

@@ -1,6 +1,15 @@
 /**
  * @fileoverview Type definitions for the audio-channel-queue package
  */
+/**
+ * Maximum number of audio channels allowed to prevent memory exhaustion
+ */
+export declare const MAX_CHANNELS: number;
+/**
+ * Symbol used as a key for global (channel-wide) progress callbacks
+ * This avoids the need for `null as any` type assertions
+ */
+export declare const GLOBAL_PROGRESS_KEY: unique symbol;
 /**
  * Array of HTMLAudioElement objects representing an audio queue
  */
@@ -8,9 +17,9 @@ export type AudioQueue = HTMLAudioElement[];
 /**
  * Basic audio queue channel structure
  */
-export type AudioQueueChannel = {
+export interface AudioQueueChannel {
     queue: AudioQueue;
-};
+}
 /**
  * Volume ducking configuration for channels
  */
@@ -29,18 +38,31 @@ export interface VolumeConfig {
     transitionEasing?: EasingType;
 }
 /**
- * Audio file configuration for queueing
+ * Configuration options for queuing audio
  */
 export interface AudioQueueOptions {
-    /** Whether to add the audio to the front of the queue (defaults to false) */
+    /** Whether to add this audio to the front of the queue (after currently playing) */
     addToFront?: boolean;
     /** Whether the audio should loop when it finishes */
     loop?: boolean;
-    /** Whether to add the audio with priority (same as addToFront) */
+    /** Maximum number of items allowed in the queue (defaults to unlimited) */
+    maxQueueSize?: number;
+    /** @deprecated Use addToFront instead. Legacy support for priority queuing */
     priority?: boolean;
-    /** Volume level for this specific audio file (0-1, defaults to channel volume) */
+    /** Volume level for this specific audio (0-1) */
     volume?: number;
 }
+/**
+ * Global queue configuration options
+ */
+export interface QueueConfig {
+    /** Default maximum queue size across all channels (defaults to unlimited) */
+    defaultMaxQueueSize?: number;
+    /** Whether to drop oldest items when queue is full (defaults to false - reject new items) */
+    dropOldestWhenFull?: boolean;
+    /** Whether to show warnings when queue limits are reached (defaults to true) */
+    showQueueWarnings?: boolean;
+}
 /**
  * Comprehensive audio information interface providing metadata about currently playing audio
  */
@@ -126,6 +148,17 @@ export interface QueueSnapshot {
     /** Current volume level for the channel (0-1) */
     volume: number;
 }
+/**
+ * Information about a queue manipulation operation result
+ */
+export interface QueueManipulationResult {
+    /** Error message if operation failed */
+    error?: string;
+    /** Whether the operation was successful */
+    success: boolean;
+    /** The queue snapshot after the operation (if successful) */
+    updatedQueue?: QueueSnapshot;
+}
 /**
  * Callback function type for audio progress updates
  * @param info Current audio information
@@ -198,7 +231,7 @@ export interface ErrorRecoveryOptions {
  */
 export type AudioErrorCallback = (errorInfo: AudioErrorInfo) => void;
 /**
- * Extended audio queue channel with error handling capabilities
+ * Extended audio channel with queue management and callback support
  */
 export interface ExtendedAudioQueueChannel {
     audioCompleteCallbacks: Set<AudioCompleteCallback>;
@@ -207,13 +240,16 @@ export interface ExtendedAudioQueueChannel {
     audioResumeCallbacks: Set<AudioResumeCallback>;
     audioStartCallbacks: Set<AudioStartCallback>;
     fadeState?: ChannelFadeState;
-    isPaused?: boolean;
-    progressCallbacks: Map<HTMLAudioElement | null, Set<ProgressCallback>>;
+    isPaused: boolean;
+    /** Active operation lock to prevent race conditions */
+    isLocked?: boolean;
+    /** Maximum allowed queue size for this channel */
+    maxQueueSize?: number;
+    progressCallbacks: Map<HTMLAudioElement | typeof GLOBAL_PROGRESS_KEY, Set<ProgressCallback>>;
     queue: HTMLAudioElement[];
     queueChangeCallbacks: Set<QueueChangeCallback>;
     retryConfig?: RetryConfig;
-    volume?: number;
-    volumeConfig?: VolumeConfig;
+    volume: number;
 }
 /**
  * Easing function types for volume transitions
@@ -232,6 +268,13 @@ export declare enum FadeType {
     Gentle = "gentle",
     Dramatic = "dramatic"
 }
+/**
+ * Timer types for volume transitions to ensure proper cleanup
+ */
+export declare enum TimerType {
+    RequestAnimationFrame = "raf",
+    Timeout = "timeout"
+}
 /**
  * Configuration for fade transitions
  */
@@ -253,4 +296,8 @@ export interface ChannelFadeState {
     fadeType: FadeType;
     /** Whether the channel is currently paused due to fade */
     isPaused: boolean;
+    /** Custom duration in milliseconds if specified (overrides fade type default) */
+    customDuration?: number;
+    /** Whether the channel is currently transitioning (during any fade operation) to prevent capturing intermediate volumes during rapid pause/resume toggles */
+    isTransitioning?: boolean;
 }

package/dist/types.js

@@ -3,7 +3,16 @@
  * @fileoverview Type definitions for the audio-channel-queue package
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FadeType = exports.EasingType = void 0;
+exports.TimerType = exports.FadeType = exports.EasingType = exports.GLOBAL_PROGRESS_KEY = exports.MAX_CHANNELS = void 0;
+/**
+ * Maximum number of audio channels allowed to prevent memory exhaustion
+ */
+exports.MAX_CHANNELS = 64;
+/**
+ * Symbol used as a key for global (channel-wide) progress callbacks
+ * This avoids the need for `null as any` type assertions
+ */
+exports.GLOBAL_PROGRESS_KEY = Symbol('global-progress-callbacks');
 /**
  * Easing function types for volume transitions
  */
@@ -23,3 +32,11 @@ var FadeType;
     FadeType["Gentle"] = "gentle";
     FadeType["Dramatic"] = "dramatic";
 })(FadeType || (exports.FadeType = FadeType = {}));
+/**
+ * Timer types for volume transitions to ensure proper cleanup
+ */
+var TimerType;
+(function (TimerType) {
+    TimerType["RequestAnimationFrame"] = "raf";
+    TimerType["Timeout"] = "timeout";
+})(TimerType || (exports.TimerType = TimerType = {}));

package/dist/utils.d.ts

@@ -2,6 +2,31 @@
  * @fileoverview Utility functions for the audio-channel-queue package
  */
 import { AudioInfo, QueueSnapshot, ExtendedAudioQueueChannel } from './types';
+/**
+ * Validates an audio URL for security and correctness
+ * @param url - The URL to validate
+ * @returns The validated URL
+ * @throws Error if the URL is invalid or potentially malicious
+ * @example
+ * ```typescript
+ * validateAudioUrl('https://example.com/audio.mp3'); // Valid
+ * validateAudioUrl('./sounds/local.wav'); // Valid relative path
+ * validateAudioUrl('javascript:alert("XSS")'); // Throws error
+ * validateAudioUrl('data:text/html,<script>alert("XSS")</script>'); // Throws error
+ * ```
+ */
+export declare const validateAudioUrl: (url: string) => string;
+/**
+ * Sanitizes a string for safe display in HTML contexts
+ * @param text - The text to sanitize
+ * @returns The sanitized text safe for display
+ * @example
+ * ```typescript
+ * sanitizeForDisplay('<script>alert("XSS")</script>'); // Returns: '&lt;script&gt;alert("XSS")&lt;/script&gt;'
+ * sanitizeForDisplay('normal-file.mp3'); // Returns: 'normal-file.mp3'
+ * ```
+ */
+export declare const sanitizeForDisplay: (text: string) => string;
 /**
  * Extracts the filename from a URL string
  * @param url - The URL to extract the filename from