audioq 2.0.0

package/src/types.ts

@@ -0,0 +1,415 @@
+/**
+ * @fileoverview Type definitions for the audioq 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
+ */
+export const GLOBAL_PROGRESS_KEY: unique symbol = Symbol('global-progress-callbacks');
+
+/**
+ * Array of HTMLAudioElement objects representing an audio queue
+ */
+export type AudioQueue = HTMLAudioElement[];
+
+/**
+ * Basic audio queue channel structure
+ */
+export interface AudioQueueChannel {
+  queue: AudioQueue;
+}
+
+/**
+ * Volume ducking configuration for channels
+ */
+export interface VolumeConfig {
+  /** Duration in milliseconds for volume duck transition (defaults to 250ms) */
+  duckTransitionDuration?: number;
+  /** Volume level for all other channels when priority channel is active (0-1) */
+  duckingVolume: number;
+  /** The channel number that should have priority */
+  priorityChannel: number;
+  /** Volume level for the priority channel (0-1) */
+  priorityVolume: number;
+  /** Duration in milliseconds for volume restore transition (defaults to 250ms) */
+  restoreTransitionDuration?: number;
+  /** Easing function for volume transitions (defaults to 'ease-out') */
+  transitionEasing?: EasingType;
+}
+
+/**
+ * Configuration options for queuing audio
+ */
+export interface AudioQueueOptions {
+  /** 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;
+  /** Maximum number of items allowed in the queue (defaults to unlimited) */
+  maxQueueSize?: number;
+  /** 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
+ */
+export interface AudioInfo {
+  /** Current playback position in milliseconds */
+  currentTime: number;
+  /** Total audio duration in milliseconds */
+  duration: number;
+  /** Extracted filename from the source URL */
+  fileName: string;
+  /** Whether the audio is set to loop */
+  isLooping: boolean;
+  /** Whether the audio is currently paused */
+  isPaused: boolean;
+  /** Whether the audio is currently playing */
+  isPlaying: boolean;
+  /** Playback progress as a decimal (0-1) */
+  progress: number;
+  /** Number of audio files remaining in the queue after current */
+  remainingInQueue: number;
+  /** Audio file source URL */
+  src: string;
+  /** Current volume level (0-1) */
+  volume: number;
+}
+
+/**
+ * Information provided when an audio file completes playback
+ */
+export interface AudioCompleteInfo {
+  /** Channel number where the audio completed */
+  channelNumber: number;
+  /** Extracted filename from the source URL */
+  fileName: string;
+  /** Number of audio files remaining in the queue after completion */
+  remainingInQueue: number;
+  /** Audio file source URL */
+  src: string;
+}
+
+/**
+ * Information provided when an audio file starts playing
+ */
+export interface AudioStartInfo {
+  /** Channel number where the audio is starting */
+  channelNumber: number;
+  /** Total audio duration in milliseconds */
+  duration: number;
+  /** Extracted filename from the source URL */
+  fileName: string;
+  /** Audio file source URL */
+  src: string;
+}
+
+/**
+ * Information about a single item in an audio queue
+ */
+export interface QueueItem {
+  /** Total audio duration in milliseconds */
+  duration: number;
+  /** Extracted filename from the source URL */
+  fileName: string;
+  /** Whether this item is currently playing */
+  isCurrentlyPlaying: boolean;
+  /** Whether this item is set to loop */
+  isLooping: boolean;
+  /** Audio file source URL */
+  src: string;
+  /** Volume level for this item (0-1) */
+  volume: number;
+}
+
+/**
+ * Complete snapshot of a queue's current state
+ */
+export interface QueueSnapshot {
+  /** Channel number this snapshot represents */
+  channelNumber: number;
+  /** Zero-based index of the currently playing item */
+  currentIndex: number;
+  /** Whether the current audio is paused */
+  isPaused: boolean;
+  /** Array of audio items in the queue with their metadata */
+  items: QueueItem[];
+  /** Total number of items in the queue */
+  totalItems: number;
+  /** 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
+ */
+export type ProgressCallback = (info: AudioInfo) => void;
+
+/**
+ * Callback function type for queue change notifications
+ * @param queueSnapshot Current state of the queue
+ */
+export type QueueChangeCallback = (queueSnapshot: QueueSnapshot) => void;
+
+/**
+ * Callback function type for audio start notifications
+ * @param audioInfo Information about the audio that started
+ */
+export type AudioStartCallback = (audioInfo: AudioStartInfo) => void;
+
+/**
+ * Callback function type for audio complete notifications
+ * @param audioInfo Information about the audio that completed
+ */
+export type AudioCompleteCallback = (audioInfo: AudioCompleteInfo) => void;
+
+/**
+ * Callback function type for audio pause notifications
+ * @param channelNumber Channel that was paused
+ * @param audioInfo Information about the audio that was paused
+ */
+export type AudioPauseCallback = (channelNumber: number, audioInfo: AudioInfo) => void;
+
+/**
+ * Callback function type for audio resume notifications
+ * @param channelNumber Channel that was resumed
+ * @param audioInfo Information about the audio that was resumed
+ */
+export type AudioResumeCallback = (channelNumber: number, audioInfo: AudioInfo) => void;
+
+/**
+ * Types of audio errors that can occur during playback
+ */
+export enum AudioErrorType {
+  Abort = 'abort',
+  Decode = 'decode',
+  Network = 'network',
+  Permission = 'permission',
+  Timeout = 'timeout',
+  Unknown = 'unknown',
+  Unsupported = 'unsupported'
+}
+
+/**
+ * Information about an audio error that occurred during playback or loading
+ */
+export interface AudioErrorInfo {
+  /** Channel number where the error occurred */
+  channelNumber: number;
+  /** The actual error object that was thrown */
+  error: Error;
+  /** Categorized type of error for handling different scenarios */
+  errorType: AudioErrorType;
+  /** Extracted filename from the source URL */
+  fileName: string;
+  /** Number of audio files remaining in the queue after this error */
+  remainingInQueue: number;
+  /** Current retry attempt number (if retrying is enabled) */
+  retryAttempt?: number;
+  /** Audio file source URL that failed */
+  src: string;
+  /** Unix timestamp when the error occurred */
+  timestamp: number;
+}
+
+/**
+ * Configuration for automatic retry behavior when audio fails to load or play
+ */
+export interface RetryConfig {
+  /** Initial delay in milliseconds before first retry attempt */
+  baseDelay: number;
+  /** Whether automatic retries are enabled for this channel */
+  enabled: boolean;
+  /** Whether to use exponential backoff (doubling delay each retry) */
+  exponentialBackoff: boolean;
+  /** Alternative URLs to try if the primary source fails */
+  fallbackUrls: string[];
+  /** Maximum number of retry attempts before giving up */
+  maxRetries: number;
+  /** Whether to skip to next track in queue if all retries fail */
+  skipOnFailure: boolean;
+  /** Timeout in milliseconds for each individual retry attempt */
+  timeoutMs: number;
+}
+
+/**
+ * Configuration options for error recovery mechanisms across the audio system
+ */
+export interface ErrorRecoveryOptions {
+  /** Whether to automatically retry failed audio loads/plays */
+  autoRetry: boolean;
+  /** Whether to automatically skip to next track when current fails */
+  fallbackToNextTrack: boolean;
+  /** Whether to send error data to analytics systems */
+  logErrorsToAnalytics: boolean;
+  /** Whether to maintain queue integrity when errors occur */
+  preserveQueueOnError: boolean;
+  /** Whether to display user-visible error feedback */
+  showUserFeedback: boolean;
+}
+
+/**
+ * Callback function type for audio error events
+ */
+export type AudioErrorCallback = (errorInfo: AudioErrorInfo) => void;
+
+/**
+ * Web Audio API configuration options
+ */
+export interface WebAudioConfig {
+  /** Whether to automatically use Web Audio API on iOS devices */
+  autoDetectIOS: boolean;
+  /** Whether Web Audio API support is enabled */
+  enabled: boolean;
+  /** Whether to force Web Audio API usage on all devices */
+  forceWebAudio: boolean;
+}
+
+/**
+ * Web Audio API support information
+ */
+export interface WebAudioSupport {
+  /** Whether Web Audio API is available in the current environment */
+  available: boolean;
+  /** Whether the current device is iOS */
+  isIOS: boolean;
+  /** Whether Web Audio API is currently being used */
+  usingWebAudio: boolean;
+  /** Reason for current Web Audio API usage state */
+  reason: string;
+}
+
+/**
+ * Web Audio API node set for audio element control
+ */
+export interface WebAudioNodeSet {
+  /** Gain node for volume control */
+  gainNode: GainNode;
+  /** Media element source node */
+  sourceNode: MediaElementAudioSourceNode;
+}
+
+/**
+ * Extended audio channel with comprehensive queue management, callback support, and state tracking
+ */
+export interface ExtendedAudioQueueChannel {
+  /** Set of callbacks triggered when audio completes playback */
+  audioCompleteCallbacks: Set<AudioCompleteCallback>;
+  /** Set of callbacks triggered when audio errors occur */
+  audioErrorCallbacks: Set<AudioErrorCallback>;
+  /** Set of callbacks triggered when audio is paused */
+  audioPauseCallbacks: Set<AudioPauseCallback>;
+  /** Set of callbacks triggered when audio is resumed */
+  audioResumeCallbacks: Set<AudioResumeCallback>;
+  /** Set of callbacks triggered when audio starts playing */
+  audioStartCallbacks: Set<AudioStartCallback>;
+  /** Current fade state if pause/resume with fade is active */
+  fadeState?: ChannelFadeState;
+  /** Whether the channel is currently paused */
+  isPaused: boolean;
+  /** Active operation lock to prevent race conditions */
+  isLocked?: boolean;
+  /** Maximum allowed queue size for this channel */
+  maxQueueSize?: number;
+  /** Map of progress callbacks keyed by audio element or global symbol */
+  progressCallbacks: Map<HTMLAudioElement | typeof GLOBAL_PROGRESS_KEY, Set<ProgressCallback>>;
+  /** Array of HTMLAudioElement objects in the queue */
+  queue: HTMLAudioElement[];
+  /** Set of callbacks triggered when the queue changes */
+  queueChangeCallbacks: Set<QueueChangeCallback>;
+  /** Retry configuration for failed audio loads/plays */
+  retryConfig?: RetryConfig;
+  /** Current volume level for the channel (0-1) */
+  volume: number;
+  /** Web Audio API context for this channel */
+  webAudioContext?: AudioContext;
+  /** Map of Web Audio API nodes for each audio element */
+  webAudioNodes?: Map<HTMLAudioElement, WebAudioNodeSet>;
+}
+
+/**
+ * Easing function types for smooth volume transitions and animations
+ */
+export enum EasingType {
+  Linear = 'linear',
+  EaseIn = 'ease-in',
+  EaseOut = 'ease-out',
+  EaseInOut = 'ease-in-out'
+}
+
+/**
+ * Predefined fade types for pause/resume operations with different transition characteristics
+ */
+export enum FadeType {
+  Linear = 'linear',
+  Gentle = 'gentle',
+  Dramatic = 'dramatic'
+}
+
+/**
+ * Timer implementation types used for volume transitions to ensure proper cleanup
+ */
+export enum TimerType {
+  RequestAnimationFrame = 'raf',
+  Timeout = 'timeout'
+}
+
+/**
+ * Configuration for fade transitions
+ */
+export interface FadeConfig {
+  /** Duration in milliseconds for the fade transition */
+  duration: number;
+  /** Easing curve to use when pausing (fading out) */
+  pauseCurve: EasingType;
+  /** Easing curve to use when resuming (fading in) */
+  resumeCurve: EasingType;
+}
+
+/**
+ * Internal fade state tracking for pause/resume with fade functionality
+ */
+export interface ChannelFadeState {
+  /** The original volume level before fading began */
+  originalVolume: number;
+  /** The type of fade being used */
+  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/src/utils.ts

@@ -0,0 +1,235 @@
+/**
+ * @fileoverview Utility functions for the audioq package
+ */
+
+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
+ * @returns The extracted filename or 'unknown' if extraction fails
+ * @example
+ * ```typescript
+ * extractFileName('https://example.com/audio/song.mp3') // Returns: 'song.mp3'
+ * extractFileName('/path/to/audio.wav') // Returns: 'audio.wav'
+ * ```
+ */
+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 {
+    return sanitizeForDisplay(decodeURIComponent(fileName || 'unknown'));
+  } catch {
+    // If decoding fails, return the sanitized raw filename
+    return sanitizeForDisplay(fileName || 'unknown');
+  }
+};
+
+/**
+ * Extracts comprehensive audio information from an HTMLAudioElement
+ * @param audio - The HTML audio element to extract information from
+ * @param channelNumber - Optional channel number to include remaining queue info
+ * @param audioChannels - Optional audio channels array to calculate remainingInQueue
+ * @returns AudioInfo object with current playback state or null if audio is invalid
+ * @example
+ * ```typescript
+ * const audioElement = new Audio('song.mp3');
+ * const info = getAudioInfoFromElement(audioElement);
+ * console.log(info?.progress); // Current progress as decimal (0-1)
+ *
+ * // With channel context for remainingInQueue
+ * const infoWithQueue = getAudioInfoFromElement(audioElement, 0, audioChannels);
+ * console.log(infoWithQueue?.remainingInQueue); // Number of items left in queue
+ * ```
+ */
+export const getAudioInfoFromElement = (
+  audio: HTMLAudioElement,
+  channelNumber?: number,
+  audioChannels?: ExtendedAudioQueueChannel[]
+): AudioInfo | null => {
+  if (!audio) return null;
+
+  const duration: number = isNaN(audio.duration) ? 0 : audio.duration * 1000; // Convert to milliseconds
+  const currentTime: number = isNaN(audio.currentTime) ? 0 : audio.currentTime * 1000; // Convert to milliseconds
+  const progress: number = duration > 0 ? Math.min(currentTime / duration, 1) : 0;
+  const isPlaying: boolean = !audio.paused && !audio.ended && audio.readyState > 2;
+
+  // Calculate remainingInQueue if channel context is provided
+  let remainingInQueue: number = 0;
+  if (channelNumber !== undefined && audioChannels?.[channelNumber]) {
+    const channel = audioChannels[channelNumber];
+    remainingInQueue = Math.max(0, channel.queue.length - 1); // Exclude current playing audio
+  }
+
+  return {
+    currentTime,
+    duration,
+    fileName: extractFileName(audio.src),
+    isLooping: audio.loop,
+    isPaused: audio.paused && !audio.ended,
+    isPlaying,
+    progress,
+    remainingInQueue,
+    src: audio.src,
+    volume: audio.volume
+  };
+};
+
+/**
+ * Creates a complete snapshot of a queue's current state
+ * @param channelNumber - The channel number to create a snapshot for
+ * @param audioChannels - Array of audio channels
+ * @returns QueueSnapshot object or null if channel doesn't exist
+ * @example
+ * ```typescript
+ * const snapshot = createQueueSnapshot(0, audioChannels);
+ * console.log(`Queue has ${snapshot?.totalItems} items`);
+ * ```
+ */
+export const createQueueSnapshot = (
+  channelNumber: number,
+  audioChannels: ExtendedAudioQueueChannel[]
+): QueueSnapshot | null => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel) return null;
+
+  const items: QueueItem[] = channel.queue.map((audio: HTMLAudioElement, index: number) => ({
+    duration: isNaN(audio.duration) ? 0 : audio.duration * 1000,
+    fileName: extractFileName(audio.src),
+    isCurrentlyPlaying: index === 0 && !audio.paused && !audio.ended,
+    isLooping: audio.loop,
+    src: audio.src,
+    volume: audio.volume
+  }));
+
+  return {
+    channelNumber,
+    currentIndex: 0, // Current playing is always index 0 in our queue structure
+    isPaused: channel.isPaused ?? false,
+    items,
+    totalItems: channel.queue.length,
+    volume: channel.volume ?? 1.0
+  };
+};
+
+/**
+ * Removes webpack hash patterns from filenames to get clean, readable names
+ * @param fileName - The filename that may contain webpack hashes
+ * @returns The cleaned filename with webpack hashes removed
+ * @example
+ * ```typescript
+ * cleanWebpackFilename('song.a1b2c3d4.mp3') // Returns: 'song.mp3'
+ * cleanWebpackFilename('notification.1a2b3c4d5e6f7890.wav') // Returns: 'notification.wav'
+ * cleanWebpackFilename('music.12345678.ogg') // Returns: 'music.ogg'
+ * cleanWebpackFilename('clean-file.mp3') // Returns: 'clean-file.mp3' (unchanged)
+ * ```
+ */
+export const cleanWebpackFilename = (fileName: string): string => {
+  // Remove webpack hash pattern: filename.hash.ext → filename.ext
+  return fileName.replace(/\.[a-f0-9]{8,}\./i, '.');
+};