audio-channel-queue 1.9.0 → 1.10.0

package/src/types.ts

@@ -2,6 +2,11 @@
  * @fileoverview Type definitions for the audio-channel-queue package
  */
 
+/**
+ * Maximum number of audio channels allowed to prevent memory exhaustion
+ */
+export const MAX_CHANNELS: number = 64;
+
 /**
  * Symbol used as a key for global (channel-wide) progress callbacks
  * This avoids the need for `null as any` type assertions
@@ -39,19 +44,33 @@ export interface VolumeConfig {
 }
 
 /**
- * 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
  */
@@ -142,6 +161,18 @@ export interface QueueSnapshot {
   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
@@ -224,7 +255,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>;
@@ -233,13 +264,16 @@ export interface ExtendedAudioQueueChannel {
   audioResumeCallbacks: Set<AudioResumeCallback>;
   audioStartCallbacks: Set<AudioStartCallback>;
   fadeState?: ChannelFadeState;
-  isPaused?: boolean;
+  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;
 }
 
 /**
@@ -261,6 +295,14 @@ export enum FadeType {
   Dramatic = 'dramatic'
 }
 
+/**
+ * Timer types for volume transitions to ensure proper cleanup
+ */
+export enum TimerType {
+  RequestAnimationFrame = 'raf',
+  Timeout = 'timeout'
+}
+
 /**
  * Configuration for fade transitions
  */
@@ -287,4 +329,4 @@ export interface ChannelFadeState {
   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/src/utils.ts

@@ -4,6 +4,101 @@
 
 import { AudioInfo, QueueSnapshot, ExtendedAudioQueueChannel, QueueItem } 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 const validateAudioUrl = (url: string): string => {
+  if (!url || typeof url !== 'string') {
+    throw new Error('Audio URL must be a non-empty string');
+  }
+
+  // Trim whitespace
+  const trimmedUrl: string = url.trim();
+
+  // Check for dangerous protocols
+  const dangerousProtocols: string[] = [
+    'javascript:',
+    'data:',
+    'vbscript:',
+    'file:',
+    'about:',
+    'chrome:',
+    'chrome-extension:'
+  ];
+
+  const lowerUrl: string = trimmedUrl.toLowerCase();
+  for (const protocol of dangerousProtocols) {
+    if (lowerUrl.startsWith(protocol)) {
+      throw new Error(`Invalid audio URL: dangerous protocol "${protocol}" is not allowed`);
+    }
+  }
+
+  // Check for path traversal attempts
+  if (trimmedUrl.includes('../') || trimmedUrl.includes('..\\')) {
+    throw new Error('Invalid audio URL: path traversal attempts are not allowed');
+  }
+
+  // For relative URLs, ensure they don't start with dangerous characters
+  if (!trimmedUrl.startsWith('http://') && !trimmedUrl.startsWith('https://')) {
+    // Check for protocol-less URLs that might be interpreted as protocols
+    if (trimmedUrl.includes(':') && !trimmedUrl.startsWith('//')) {
+      const colonIndex: number = trimmedUrl.indexOf(':');
+      const beforeColon: string = trimmedUrl.substring(0, colonIndex);
+      // Allow only if it looks like a Windows drive letter (e.g., C:)
+      if (!/^[a-zA-Z]$/.test(beforeColon)) {
+        throw new Error('Invalid audio URL: suspicious protocol-like pattern detected');
+      }
+    }
+  }
+
+  // Validate common audio file extensions (warning, not error)
+  const hasAudioExtension: boolean = /\.(mp3|wav|ogg|m4a|webm|aac|flac|opus|weba|mp4)$/i.test(
+    trimmedUrl
+  );
+  if (!hasAudioExtension && !trimmedUrl.includes('?')) {
+    // Log warning but don't throw - some valid URLs might not have extensions
+    // eslint-disable-next-line no-console
+    console.warn(`Audio URL "${trimmedUrl}" does not have a recognized audio file extension`);
+  }
+
+  return trimmedUrl;
+};
+
+/**
+ * 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 const sanitizeForDisplay = (text: string): string => {
+  if (!text || typeof text !== 'string') {
+    return '';
+  }
+
+  // Replace HTML special characters
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#x27;')
+    .replace(/\//g, '&#x2F;');
+};
+
 /**
  * Extracts the filename from a URL string
  * @param url - The URL to extract the filename from
@@ -15,17 +110,23 @@ import { AudioInfo, QueueSnapshot, ExtendedAudioQueueChannel, QueueItem } from '
  * ```
  */
 export const extractFileName = (url: string): string => {
+  if (!url || typeof url !== 'string') {
+    return sanitizeForDisplay('unknown');
+  }
+
+  // Always use simple string manipulation for consistency
+  const segments: string[] = url.split('/');
+  const lastSegment: string = segments[segments.length - 1] || '';
+
+  // Remove query parameters and hash
+  const fileName: string = lastSegment.split('?')[0].split('#')[0];
+
+  // Decode URI components and sanitize
   try {
-    const urlObj: URL = new URL(url);
-    const pathname: string = urlObj.pathname;
-    const segments: string[] = pathname.split('/');
-    const fileName: string = segments[segments.length - 1];
-    return fileName || 'unknown';
+    return sanitizeForDisplay(decodeURIComponent(fileName || 'unknown'));
   } catch {
-    // If URL parsing fails, try simple string manipulation
-    const segments: string[] = url.split('/');
-    const fileName: string = segments[segments.length - 1];
-    return fileName || 'unknown';
+    // If decoding fails, return the sanitized raw filename
+    return sanitizeForDisplay(fileName || 'unknown');
   }
 };
 

package/src/volume.ts

@@ -2,11 +2,27 @@
  * @fileoverview Volume management functions for the audio-channel-queue package
  */
 
-import { ExtendedAudioQueueChannel, VolumeConfig, FadeType, FadeConfig, EasingType } from './types';
+import {
+  ExtendedAudioQueueChannel,
+  VolumeConfig,
+  FadeType,
+  FadeConfig,
+  EasingType,
+  TimerType,
+  MAX_CHANNELS
+} from './types';
 import { audioChannels } from './info';
 
 // Store active volume transitions to handle interruptions
 const activeTransitions: Map<number, number> = new Map();
+// Track which timer type was used for each channel
+const timerTypes: Map<number, TimerType> = new Map();
+
+/**
+ * Global volume ducking configuration
+ * Stores the volume ducking settings that apply to all channels
+ */
+let globalVolumeConfig: VolumeConfig | null = null;
 
 /**
  * Predefined fade configurations for different transition types
@@ -81,14 +97,20 @@ export const transitionVolume = async (
   // Cancel any existing transition for this channel
   if (activeTransitions.has(channelNumber)) {
     const transitionId = activeTransitions.get(channelNumber);
+    const timerType = timerTypes.get(channelNumber);
     if (transitionId) {
-      // Handle both requestAnimationFrame and setTimeout IDs
-      if (typeof cancelAnimationFrame !== 'undefined') {
+      // Cancel based on the timer type that was actually used
+      if (
+        timerType === TimerType.RequestAnimationFrame &&
+        typeof cancelAnimationFrame !== 'undefined'
+      ) {
         cancelAnimationFrame(transitionId);
+      } else if (timerType === TimerType.Timeout) {
+        clearTimeout(transitionId);
       }
-      clearTimeout(transitionId);
     }
     activeTransitions.delete(channelNumber);
+    timerTypes.delete(channelNumber);
   }
 
   // If no change needed, resolve immediately
@@ -97,8 +119,8 @@ export const transitionVolume = async (
     return Promise.resolve();
   }
 
-  // Handle zero duration - instant change
-  if (duration === 0) {
+  // Handle zero or negative duration - instant change
+  if (duration <= 0) {
     channel.volume = targetVolume;
     if (channel.queue.length > 0) {
       channel.queue[0].volume = targetVolume;
@@ -127,16 +149,19 @@ export const transitionVolume = async (
       if (progress >= 1) {
         // Transition complete
         activeTransitions.delete(channelNumber);
+        timerTypes.delete(channelNumber);
         resolve();
       } else {
         // Use requestAnimationFrame in browser, setTimeout in tests
         if (typeof requestAnimationFrame !== 'undefined') {
           const rafId = requestAnimationFrame(updateVolume);
           activeTransitions.set(channelNumber, rafId as unknown as number);
+          timerTypes.set(channelNumber, TimerType.RequestAnimationFrame);
         } else {
           // In test environment, use shorter intervals
           const timeoutId = setTimeout(updateVolume, 1);
           activeTransitions.set(channelNumber, timeoutId as unknown as number);
+          timerTypes.set(channelNumber, TimerType.Timeout);
         }
       }
     };
@@ -151,6 +176,7 @@ export const transitionVolume = async (
  * @param volume - Volume level (0-1)
  * @param transitionDuration - Optional transition duration in milliseconds
  * @param easing - Optional easing function
+ * @throws Error if the channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * setChannelVolume(0, 0.5); // Set channel 0 to 50%
@@ -165,6 +191,16 @@ export const setChannelVolume = async (
 ): Promise<void> => {
   const clampedVolume: number = Math.max(0, Math.min(1, volume));
 
+  // Check channel number limits
+  if (channelNumber < 0) {
+    throw new Error('Channel number must be non-negative');
+  }
+  if (channelNumber >= MAX_CHANNELS) {
+    throw new Error(
+      `Channel number ${channelNumber} exceeds maximum allowed channels (${MAX_CHANNELS})`
+    );
+  }
+
   if (!audioChannels[channelNumber]) {
     audioChannels[channelNumber] = {
       audioCompleteCallbacks: new Set(),
@@ -246,6 +282,7 @@ export const setAllChannelsVolume = async (volume: number): Promise<void> => {
  * Configures volume ducking for channels. When the priority channel plays audio,
  * all other channels will be automatically reduced to the ducking volume level
  * @param config - Volume ducking configuration
+ * @throws Error if the priority channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * // When channel 1 plays, reduce all other channels to 20% volume
@@ -257,8 +294,23 @@ export const setAllChannelsVolume = async (volume: number): Promise<void> => {
  * ```
  */
 export const setVolumeDucking = (config: VolumeConfig): void => {
-  // First, ensure we have enough channels for the priority channel
-  while (audioChannels.length <= config.priorityChannel) {
+  const { priorityChannel } = config;
+
+  // Check priority channel limits
+  if (priorityChannel < 0) {
+    throw new Error('Priority channel number must be non-negative');
+  }
+  if (priorityChannel >= MAX_CHANNELS) {
+    throw new Error(
+      `Priority channel ${priorityChannel} exceeds maximum allowed channels (${MAX_CHANNELS})`
+    );
+  }
+
+  // Store the configuration globally
+  globalVolumeConfig = config;
+
+  // Ensure we have enough channels for the priority channel
+  while (audioChannels.length <= priorityChannel) {
     audioChannels.push({
       audioCompleteCallbacks: new Set(),
       audioErrorCallbacks: new Set(),
@@ -272,25 +324,6 @@ export const setVolumeDucking = (config: VolumeConfig): void => {
       volume: 1.0
     });
   }
-
-  // Apply the config to all existing channels
-  audioChannels.forEach((channel: ExtendedAudioQueueChannel, index: number) => {
-    if (!audioChannels[index]) {
-      audioChannels[index] = {
-        audioCompleteCallbacks: new Set(),
-        audioErrorCallbacks: new Set(),
-        audioPauseCallbacks: new Set(),
-        audioResumeCallbacks: new Set(),
-        audioStartCallbacks: new Set(),
-        isPaused: false,
-        progressCallbacks: new Map(),
-        queue: [],
-        queueChangeCallbacks: new Set(),
-        volume: 1.0
-      };
-    }
-    audioChannels[index].volumeConfig = config;
-  });
 };
 
 /**
@@ -301,11 +334,7 @@ export const setVolumeDucking = (config: VolumeConfig): void => {
  * ```
  */
 export const clearVolumeDucking = (): void => {
-  audioChannels.forEach((channel: ExtendedAudioQueueChannel) => {
-    if (channel) {
-      delete channel.volumeConfig;
-    }
-  });
+  globalVolumeConfig = null;
 };
 
 /**
@@ -314,27 +343,36 @@ export const clearVolumeDucking = (): void => {
  * @internal
  */
 export const applyVolumeDucking = async (activeChannelNumber: number): Promise<void> => {
+  // Check if ducking is configured and this channel is the priority channel
+  if (!globalVolumeConfig || globalVolumeConfig.priorityChannel !== activeChannelNumber) {
+    return; // No ducking configured for this channel
+  }
+
+  const config = globalVolumeConfig;
   const transitionPromises: Promise<void>[] = [];
+  const duration = config.duckTransitionDuration ?? 250;
+  const easing = config.transitionEasing ?? EasingType.EaseOut;
 
+  // Duck all channels except the priority channel
   audioChannels.forEach((channel: ExtendedAudioQueueChannel, channelNumber: number) => {
-    if (channel?.volumeConfig) {
-      const config: VolumeConfig = channel.volumeConfig;
-
-      if (activeChannelNumber === config.priorityChannel) {
-        const duration = config.duckTransitionDuration ?? 250;
-        const easing = config.transitionEasing ?? EasingType.EaseOut;
-
-        // Priority channel is active, duck other channels
-        if (channelNumber === config.priorityChannel) {
-          transitionPromises.push(
-            transitionVolume(channelNumber, config.priorityVolume, duration, easing)
-          );
-        } else {
-          transitionPromises.push(
-            transitionVolume(channelNumber, config.duckingVolume, duration, easing)
-          );
-        }
-      }
+    if (!channel || channel.queue.length === 0) {
+      return; // Skip channels without audio
+    }
+
+    if (channelNumber === activeChannelNumber) {
+      // This is the priority channel - set to priority volume
+      // Only change audio volume, preserve channel.volume as desired volume
+      const currentAudio: HTMLAudioElement = channel.queue[0];
+      transitionPromises.push(
+        transitionAudioVolume(currentAudio, config.priorityVolume, duration, easing)
+      );
+    } else {
+      // This is a background channel - duck it
+      // Only change audio volume, preserve channel.volume as desired volume
+      const currentAudio: HTMLAudioElement = channel.queue[0];
+      transitionPromises.push(
+        transitionAudioVolume(currentAudio, config.duckingVolume, duration, easing)
+      );
     }
   });
 
@@ -365,29 +403,143 @@ export const fadeVolume = async (
 };
 
 /**
- * Restores normal volume levels when priority channel stops with smooth transitions
+ * Restores normal volume levels when priority channel queue becomes empty
  * @param stoppedChannelNumber - The channel that just stopped playing
  * @internal
  */
 export const restoreVolumeLevels = async (stoppedChannelNumber: number): Promise<void> => {
+  // Check if ducking is configured and this channel is the priority channel
+  if (!globalVolumeConfig || globalVolumeConfig.priorityChannel !== stoppedChannelNumber) {
+    return; // No ducking configured for this channel
+  }
+
+  // Check if the priority channel queue is now empty
+  const priorityChannel = audioChannels[stoppedChannelNumber];
+  if (priorityChannel && priorityChannel.queue.length > 0) {
+    return; // Priority channel still has audio queued, don't restore yet
+  }
+
+  const config = globalVolumeConfig;
   const transitionPromises: Promise<void>[] = [];
 
+  // Restore volume for all channels EXCEPT the priority channel
   audioChannels.forEach((channel: ExtendedAudioQueueChannel, channelNumber: number) => {
-    if (channel?.volumeConfig) {
-      const config: VolumeConfig = channel.volumeConfig;
+    // Skip the priority channel itself and channels without audio
+    if (channelNumber === stoppedChannelNumber || !channel || channel.queue.length === 0) {
+      return;
+    }
 
-      if (stoppedChannelNumber === config.priorityChannel) {
-        const duration = config.restoreTransitionDuration ?? 500;
-        const easing = config.transitionEasing ?? EasingType.EaseOut;
+    // Restore this channel to its desired volume
+    const duration = config.restoreTransitionDuration ?? 500;
+    const easing = config.transitionEasing ?? EasingType.EaseOut;
+    const targetVolume = channel.volume ?? 1.0;
 
-        // Priority channel stopped, restore normal volumes
-        transitionPromises.push(
-          transitionVolume(channelNumber, channel.volume ?? 1.0, duration, easing)
-        );
-      }
-    }
+    // Only transition the audio element volume, keep channel.volume as the desired volume
+    const currentAudio: HTMLAudioElement = channel.queue[0];
+    transitionPromises.push(transitionAudioVolume(currentAudio, targetVolume, duration, easing));
   });
 
   // Wait for all transitions to complete
   await Promise.all(transitionPromises);
 };
+
+/**
+ * Transitions only the audio element volume without affecting channel.volume
+ * This is used for ducking/restoration where channel.volume represents desired volume
+ * @param audio - The audio element to transition
+ * @param targetVolume - Target volume level (0-1)
+ * @param duration - Transition duration in milliseconds
+ * @param easing - Easing function type
+ * @returns Promise that resolves when transition completes
+ * @internal
+ */
+const transitionAudioVolume = async (
+  audio: HTMLAudioElement,
+  targetVolume: number,
+  duration: number = 250,
+  easing: EasingType = EasingType.EaseOut
+): Promise<void> => {
+  const startVolume: number = audio.volume;
+  const volumeDelta: number = targetVolume - startVolume;
+
+  // If no change needed, resolve immediately
+  if (Math.abs(volumeDelta) < 0.001) {
+    return Promise.resolve();
+  }
+
+  // Handle zero or negative duration - instant change
+  if (duration <= 0) {
+    audio.volume = Math.max(0, Math.min(1, targetVolume));
+    return Promise.resolve();
+  }
+
+  const startTime: number = performance.now();
+  const easingFn = easingFunctions[easing];
+
+  return new Promise<void>((resolve) => {
+    const updateVolume = (): void => {
+      const elapsed: number = performance.now() - startTime;
+      const progress: number = Math.min(elapsed / duration, 1);
+      const easedProgress: number = easingFn(progress);
+
+      const currentVolume: number = startVolume + volumeDelta * easedProgress;
+      const clampedVolume: number = Math.max(0, Math.min(1, currentVolume));
+
+      // Only apply volume to audio element, not channel.volume
+      audio.volume = clampedVolume;
+
+      if (progress >= 1) {
+        resolve();
+      } else {
+        // Use requestAnimationFrame in browser, setTimeout in tests
+        if (typeof requestAnimationFrame !== 'undefined') {
+          requestAnimationFrame(updateVolume);
+        } else {
+          setTimeout(updateVolume, 1);
+        }
+      }
+    };
+
+    updateVolume();
+  });
+};
+
+/**
+ * Cancels any active volume transition for a specific channel
+ * @param channelNumber - The channel number to cancel transitions for
+ * @internal
+ */
+export const cancelVolumeTransition = (channelNumber: number): void => {
+  if (activeTransitions.has(channelNumber)) {
+    const transitionId = activeTransitions.get(channelNumber);
+    const timerType = timerTypes.get(channelNumber);
+
+    if (transitionId) {
+      // Cancel based on the timer type that was actually used
+      if (
+        timerType === TimerType.RequestAnimationFrame &&
+        typeof cancelAnimationFrame !== 'undefined'
+      ) {
+        cancelAnimationFrame(transitionId);
+      } else if (timerType === TimerType.Timeout) {
+        clearTimeout(transitionId);
+      }
+    }
+
+    activeTransitions.delete(channelNumber);
+    timerTypes.delete(channelNumber);
+  }
+};
+
+/**
+ * Cancels all active volume transitions across all channels
+ * @internal
+ */
+export const cancelAllVolumeTransitions = (): void => {
+  // Get all active channel numbers to avoid modifying Map while iterating
+  const activeChannels = Array.from(activeTransitions.keys());
+
+  activeChannels.forEach((channelNumber) => {
+    cancelVolumeTransition(channelNumber);
+  });
+};