audio-channel-queue 1.9.0 → 1.10.0

package/src/info.ts

@@ -12,7 +12,8 @@ import {
   AudioPauseCallback,
   AudioResumeCallback,
   ExtendedAudioQueueChannel,
-  GLOBAL_PROGRESS_KEY
+  GLOBAL_PROGRESS_KEY,
+  MAX_CHANNELS
 } from './types';
 import { getAudioInfoFromElement, createQueueSnapshot } from './utils';
 import { setupProgressTracking, cleanupProgressTracking } from './events';
@@ -20,8 +21,85 @@ import { setupProgressTracking, cleanupProgressTracking } from './events';
 /**
  * Global array to store audio channels with their queues and callback management
  * Each channel maintains its own audio queue and event callback sets
+ *
+ * Note: While you can inspect this array for debugging, direct modification is discouraged.
+ * Use the provided API functions for safe channel management.
  */
-export const audioChannels: ExtendedAudioQueueChannel[] = [];
+export const audioChannels: ExtendedAudioQueueChannel[] = new Proxy(
+  [] as ExtendedAudioQueueChannel[],
+  {
+    deleteProperty(target: ExtendedAudioQueueChannel[], prop: string | symbol): boolean {
+      if (typeof prop === 'string' && !isNaN(Number(prop))) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          'Warning: Direct deletion from audioChannels detected. ' +
+            'Consider using stopAllAudioInChannel() for proper cleanup.'
+        );
+      }
+      delete (target as unknown as Record<string, unknown>)[prop as string];
+      return true;
+    },
+    get(target: ExtendedAudioQueueChannel[], prop: string | symbol): unknown {
+      const value = (target as unknown as Record<string, unknown>)[prop as string];
+
+      // Return channel objects with warnings on modification attempts
+      if (
+        typeof value === 'object' &&
+        value !== null &&
+        typeof prop === 'string' &&
+        !isNaN(Number(prop))
+      ) {
+        return new Proxy(value as ExtendedAudioQueueChannel, {
+          set(
+            channelTarget: ExtendedAudioQueueChannel,
+            channelProp: string | symbol,
+            channelValue: unknown
+          ): boolean {
+            // Allow internal modifications but warn about direct property changes
+            if (
+              typeof channelProp === 'string' &&
+              !['queue', 'volume', 'isPaused', 'isLocked', 'volumeConfig'].includes(channelProp)
+            ) {
+              // eslint-disable-next-line no-console
+              console.warn(
+                `Warning: Direct modification of channel.${channelProp} detected. ` +
+                  'Use API functions for safer channel management.'
+              );
+            }
+            const key = typeof channelProp === 'symbol' ? channelProp.toString() : channelProp;
+            (channelTarget as unknown as Record<string, unknown>)[key] = channelValue;
+            return true;
+          }
+        });
+      }
+
+      return value;
+    },
+    set(target: ExtendedAudioQueueChannel[], prop: string | symbol, value: unknown): boolean {
+      // Allow normal array operations
+      const key = typeof prop === 'symbol' ? prop.toString() : prop;
+      (target as unknown as Record<string, unknown>)[key] = value;
+      return true;
+    }
+  }
+);
+
+/**
+ * Validates a channel number against MAX_CHANNELS limit
+ * @param channelNumber - The channel number to validate
+ * @throws Error if the channel number is invalid
+ * @internal
+ */
+const validateChannelNumber = (channelNumber: number): void => {
+  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})`
+    );
+  }
+};
 
 /**
  * Gets current audio information for a specific channel
@@ -71,18 +149,19 @@ export const getAllChannelsInfo = (): (AudioInfo | null)[] => {
 
 /**
  * Gets a complete snapshot of the queue state for a specific channel
- * @param channelNumber - The channel number
+ * @param channelNumber - The channel number (defaults to 0)
  * @returns QueueSnapshot object or null if channel doesn't exist
  * @example
  * ```typescript
- * const snapshot = getQueueSnapshot(0);
+ * const snapshot = getQueueSnapshot();
  * if (snapshot) {
  *   console.log(`Queue has ${snapshot.totalItems} items`);
  *   console.log(`Currently playing: ${snapshot.items[0]?.fileName}`);
  * }
+ * const channelSnapshot = getQueueSnapshot(2);
  * ```
  */
-export const getQueueSnapshot = (channelNumber: number): QueueSnapshot | null => {
+export const getQueueSnapshot = (channelNumber: number = 0): QueueSnapshot | null => {
   return createQueueSnapshot(channelNumber, audioChannels);
 };
 
@@ -90,6 +169,7 @@ export const getQueueSnapshot = (channelNumber: number): QueueSnapshot | null =>
  * Subscribes to real-time progress updates for a specific channel
  * @param channelNumber - The channel number
  * @param callback - Function to call with audio info updates
+ * @throws Error if the channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * onAudioProgress(0, (info) => {
@@ -99,6 +179,8 @@ export const getQueueSnapshot = (channelNumber: number): QueueSnapshot | null =>
  * ```
  */
 export const onAudioProgress = (channelNumber: number, callback: ProgressCallback): void => {
+  validateChannelNumber(channelNumber);
+
   if (!audioChannels[channelNumber]) {
     audioChannels[channelNumber] = {
       audioCompleteCallbacks: new Set(),
@@ -140,13 +222,14 @@ export const onAudioProgress = (channelNumber: number, callback: ProgressCallbac
 
 /**
  * Removes progress listeners for a specific channel
- * @param channelNumber - The channel number
+ * @param channelNumber - The channel number (defaults to 0)
  * @example
  * ```typescript
- * offAudioProgress(0); // Stop receiving progress updates for channel 0
+ * offAudioProgress();
+ * offAudioProgress(1); // Stop receiving progress updates for channel 1
  * ```
  */
-export const offAudioProgress = (channelNumber: number): void => {
+export function offAudioProgress(channelNumber: number = 0): void {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
   if (!channel?.progressCallbacks) return;
 
@@ -158,12 +241,13 @@ export const offAudioProgress = (channelNumber: number): void => {
 
   // Clear all callbacks for this channel
   channel.progressCallbacks.clear();
-};
+}
 
 /**
  * Subscribes to queue change events for a specific channel
  * @param channelNumber - The channel number to monitor
  * @param callback - Function to call when queue changes
+ * @throws Error if the channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * onQueueChange(0, (snapshot) => {
@@ -173,6 +257,8 @@ export const offAudioProgress = (channelNumber: number): void => {
  * ```
  */
 export const onQueueChange = (channelNumber: number, callback: QueueChangeCallback): void => {
+  validateChannelNumber(channelNumber);
+
   if (!audioChannels[channelNumber]) {
     audioChannels[channelNumber] = {
       audioCompleteCallbacks: new Set(),
@@ -215,6 +301,7 @@ export const offQueueChange = (channelNumber: number): void => {
  * Subscribes to audio start events for a specific channel
  * @param channelNumber - The channel number to monitor
  * @param callback - Function to call when audio starts playing
+ * @throws Error if the channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * onAudioStart(0, (info) => {
@@ -224,6 +311,8 @@ export const offQueueChange = (channelNumber: number): void => {
  * ```
  */
 export const onAudioStart = (channelNumber: number, callback: AudioStartCallback): void => {
+  validateChannelNumber(channelNumber);
+
   if (!audioChannels[channelNumber]) {
     audioChannels[channelNumber] = {
       audioCompleteCallbacks: new Set(),
@@ -251,6 +340,7 @@ export const onAudioStart = (channelNumber: number, callback: AudioStartCallback
  * Subscribes to audio complete events for a specific channel
  * @param channelNumber - The channel number to monitor
  * @param callback - Function to call when audio completes
+ * @throws Error if the channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * onAudioComplete(0, (info) => {
@@ -262,6 +352,8 @@ export const onAudioStart = (channelNumber: number, callback: AudioStartCallback
  * ```
  */
 export const onAudioComplete = (channelNumber: number, callback: AudioCompleteCallback): void => {
+  validateChannelNumber(channelNumber);
+
   if (!audioChannels[channelNumber]) {
     audioChannels[channelNumber] = {
       audioCompleteCallbacks: new Set(),
@@ -289,6 +381,7 @@ export const onAudioComplete = (channelNumber: number, callback: AudioCompleteCa
  * Subscribes to audio pause events for a specific channel
  * @param channelNumber - The channel number to monitor
  * @param callback - Function to call when audio is paused
+ * @throws Error if the channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * onAudioPause(0, (channelNumber, info) => {
@@ -298,6 +391,8 @@ export const onAudioComplete = (channelNumber: number, callback: AudioCompleteCa
  * ```
  */
 export const onAudioPause = (channelNumber: number, callback: AudioPauseCallback): void => {
+  validateChannelNumber(channelNumber);
+
   if (!audioChannels[channelNumber]) {
     audioChannels[channelNumber] = {
       audioCompleteCallbacks: new Set(),
@@ -325,6 +420,7 @@ export const onAudioPause = (channelNumber: number, callback: AudioPauseCallback
  * Subscribes to audio resume events for a specific channel
  * @param channelNumber - The channel number to monitor
  * @param callback - Function to call when audio is resumed
+ * @throws Error if the channel number exceeds the maximum allowed channels
  * @example
  * ```typescript
  * onAudioResume(0, (channelNumber, info) => {
@@ -334,6 +430,8 @@ export const onAudioPause = (channelNumber: number, callback: AudioPauseCallback
  * ```
  */
 export const onAudioResume = (channelNumber: number, callback: AudioResumeCallback): void => {
+  validateChannelNumber(channelNumber);
+
   if (!audioChannels[channelNumber]) {
     audioChannels[channelNumber] = {
       audioCompleteCallbacks: new Set(),

package/src/pause.ts

@@ -14,8 +14,6 @@ import { getAudioInfoFromElement } from './utils';
 import { emitAudioPause, emitAudioResume } from './events';
 import { transitionVolume, getFadeConfig } from './volume';
 
-
-
 /**
  * Gets the current volume for a channel, accounting for synchronous state
  * @param channelNumber - The channel number
@@ -81,7 +79,7 @@ export const pauseWithFade = async (
     // First fade or no transition in progress, capture current volume
     // But ensure we don't capture a volume of 0 during a transition
     const currentVolume = getChannelVolumeSync(channelNumber);
-    originalVolume = currentVolume > 0 ? currentVolume : channel.fadeState?.originalVolume ?? 1.0;
+    originalVolume = currentVolume > 0 ? currentVolume : (channel.fadeState?.originalVolume ?? 1.0);
   }
 
   // Store fade state for resumeWithFade to use (including custom duration)
@@ -111,7 +109,7 @@ export const pauseWithFade = async (
 
   // Reset volume to original for resume (synchronously to avoid state issues)
   setChannelVolumeSync(channelNumber, originalVolume);
-  
+
   // Mark transition as complete
   if (channel.fadeState) {
     channel.fadeState.isTransitioning = false;
@@ -258,11 +256,11 @@ export const pauseAllWithFade = async (
  */
 export const resumeAllWithFade = async (fadeType?: FadeType, duration?: number): Promise<void> => {
   const resumePromises: Promise<void>[] = [];
-  
+
   audioChannels.forEach((_channel: ExtendedAudioQueueChannel, index: number) => {
     resumePromises.push(resumeWithFade(fadeType, index, duration));
   });
-  
+
   await Promise.all(resumePromises);
 };
 

package/src/queue-manipulation.ts

@@ -0,0 +1,378 @@
+/**
+ * @fileoverview Queue manipulation functions for the audio-channel-queue package
+ * Provides advanced queue management including item removal, reordering, and clearing
+ */
+
+import {
+  ExtendedAudioQueueChannel,
+  QueueManipulationResult,
+  QueueSnapshot,
+  QueueItem
+} from './types';
+import { audioChannels } from './info';
+import { emitQueueChange } from './events';
+import { cleanupProgressTracking } from './events';
+import { createQueueSnapshot, getAudioInfoFromElement } from './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);
+ * ```
+ */
+export const removeQueuedItem = async (
+  queuedSlotNumber: number,
+  channelNumber: number = 0
+): Promise<QueueManipulationResult> => {
+  const channel: ExtendedAudioQueueChannel = 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: HTMLAudioElement = channel.queue.splice(queuedSlotNumber, 1)[0];
+
+  // Clean up any progress tracking for the removed audio
+  cleanupProgressTracking(removedAudio, channelNumber, audioChannels);
+
+  // Emit queue change event
+  emitQueueChange(channelNumber, audioChannels);
+
+  const updatedQueue: QueueSnapshot | null = createQueueSnapshot(channelNumber, audioChannels);
+
+  return {
+    success: true,
+    updatedQueue: updatedQueue ?? undefined
+  };
+};
+
+/**
+ * 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 const reorderQueue = async (
+  currentQueuedSlotNumber: number,
+  newQueuedSlotNumber: number,
+  channelNumber: number = 0
+): Promise<QueueManipulationResult> => {
+  const channel: ExtendedAudioQueueChannel = 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: QueueSnapshot | null = createQueueSnapshot(channelNumber, audioChannels);
+    return {
+      success: true,
+      updatedQueue: updatedQueue ?? undefined
+    };
+  }
+
+  // Remove the item from its current position
+  const audioToMove: HTMLAudioElement = channel.queue.splice(currentQueuedSlotNumber, 1)[0];
+
+  // Insert it at the new position
+  channel.queue.splice(newQueuedSlotNumber, 0, audioToMove);
+
+  // Emit queue change event
+  emitQueueChange(channelNumber, audioChannels);
+
+  const updatedQueue: QueueSnapshot | null = createQueueSnapshot(channelNumber, audioChannels);
+
+  return {
+    success: true,
+    updatedQueue: updatedQueue ?? undefined
+  };
+};
+
+/**
+ * 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 const clearQueueAfterCurrent = async (
+  channelNumber: number = 0
+): Promise<QueueManipulationResult> => {
+  const channel: ExtendedAudioQueueChannel = 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: QueueSnapshot | null = createQueueSnapshot(channelNumber, audioChannels);
+    return {
+      success: true,
+      updatedQueue: updatedQueue ?? undefined
+    };
+  }
+
+  // Clean up progress tracking for all items except the current one
+  for (let i: number = 1; i < channel.queue.length; i++) {
+    cleanupProgressTracking(channel.queue[i], channelNumber, audioChannels);
+  }
+
+  // Keep only the currently playing audio (index 0)
+  channel.queue = channel.queue.slice(0, 1);
+
+  // Emit queue change event
+  emitQueueChange(channelNumber, audioChannels);
+
+  const updatedQueue: QueueSnapshot | null = createQueueSnapshot(channelNumber, audioChannels);
+
+  return {
+    success: true,
+    updatedQueue: updatedQueue ?? undefined
+  };
+};
+
+/**
+ * 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 const getQueueItemInfo = (
+  queueSlotNumber: number,
+  channelNumber: number = 0
+): QueueItem | null => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+
+  if (!channel || queueSlotNumber < 0 || queueSlotNumber >= channel.queue.length) {
+    return null;
+  }
+
+  const audio: HTMLAudioElement = channel.queue[queueSlotNumber];
+  const audioInfo = getAudioInfoFromElement(audio, channelNumber, audioChannels);
+
+  if (!audioInfo) {
+    return null;
+  }
+
+  const { duration, fileName, isLooping, isPlaying, src, volume } = audioInfo;
+
+  return {
+    duration,
+    fileName,
+    isCurrentlyPlaying: queueSlotNumber === 0 && isPlaying,
+    isLooping,
+    src,
+    volume
+  };
+};
+
+/**
+ * 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 const getQueueLength = (channelNumber: number = 0): number => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  return channel ? channel.queue.length : 0;
+};
+
+/**
+ * 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 const swapQueueItems = async (
+  slotA: number,
+  slotB: number,
+  channelNumber: number = 0
+): Promise<QueueManipulationResult> => {
+  const channel: ExtendedAudioQueueChannel = 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: QueueSnapshot | null = createQueueSnapshot(channelNumber, audioChannels);
+    return {
+      success: true,
+      updatedQueue: updatedQueue ?? undefined
+    };
+  }
+
+  // Swap the audio elements
+  const temp: HTMLAudioElement = channel.queue[slotA];
+  channel.queue[slotA] = channel.queue[slotB];
+  channel.queue[slotB] = temp;
+
+  // Emit queue change event
+  emitQueueChange(channelNumber, audioChannels);
+
+  const updatedQueue: QueueSnapshot | null = createQueueSnapshot(channelNumber, audioChannels);
+
+  return {
+    success: true,
+    updatedQueue: updatedQueue ?? undefined
+  };
+};