audio-channel-queue 1.9.0 → 1.11.0

package/src/index.ts

@@ -11,9 +11,24 @@ export {
   stopCurrentAudioInChannel,
   stopAllAudioInChannel,
   stopAllAudio,
-  playAudioQueue
+  playAudioQueue,
+  destroyChannel,
+  destroyAllChannels,
+  setQueueConfig,
+  getQueueConfig,
+  setChannelQueueLimit
 } from './core';
 
+// Queue manipulation functions
+export {
+  clearQueueAfterCurrent,
+  getQueueItemInfo,
+  getQueueLength,
+  removeQueuedItem,
+  reorderQueue,
+  swapQueueItems
+} from './queue-manipulation';
+
 // Error handling and recovery functions
 export {
   getErrorRecovery,
@@ -53,7 +68,9 @@ export {
   setAllChannelsVolume,
   setChannelVolume,
   setVolumeDucking,
-  transitionVolume
+  transitionVolume,
+  cancelVolumeTransition,
+  cancelAllVolumeTransitions
 } from './volume';
 
 // Audio information and progress tracking functions
@@ -61,9 +78,11 @@ export {
   getAllChannelsInfo,
   getCurrentAudioInfo,
   getQueueSnapshot,
+  offAudioComplete,
   offAudioPause,
   offAudioProgress,
   offAudioResume,
+  offAudioStart,
   offQueueChange,
   onAudioComplete,
   onAudioPause,
@@ -81,7 +100,9 @@ export {
   cleanWebpackFilename,
   createQueueSnapshot,
   extractFileName,
-  getAudioInfoFromElement
+  getAudioInfoFromElement,
+  sanitizeForDisplay,
+  validateAudioUrl
 } from './utils';
 
 // TypeScript type definitions and interfaces
@@ -103,10 +124,12 @@ export type {
   ProgressCallback,
   QueueChangeCallback,
   QueueItem,
+  QueueManipulationResult,
   QueueSnapshot,
   RetryConfig,
-  VolumeConfig
+  VolumeConfig,
+  QueueConfig
 } from './types';
 
 // Enums and constants
-export { EasingType, FadeType, GLOBAL_PROGRESS_KEY } from './types';
+export { EasingType, FadeType, MAX_CHANNELS, TimerType, GLOBAL_PROGRESS_KEY } from './types';

package/src/info.ts

@@ -12,16 +12,161 @@ import {
   AudioPauseCallback,
   AudioResumeCallback,
   ExtendedAudioQueueChannel,
-  GLOBAL_PROGRESS_KEY
+  GLOBAL_PROGRESS_KEY,
+  MAX_CHANNELS
 } from './types';
 import { getAudioInfoFromElement, createQueueSnapshot } from './utils';
 import { setupProgressTracking, cleanupProgressTracking } from './events';
 
+/**
+ * Gets the current list of whitelisted channel properties
+ * This is automatically derived from the ExtendedAudioQueueChannel interface
+ * @returns Array of whitelisted property names
+ * @internal
+ */
+export const getWhitelistedChannelProperties = (): string[] => {
+  // Create a sample channel object to extract property names
+  const sampleChannel: ExtendedAudioQueueChannel = {
+    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
+  };
+
+  // Get all property names from the interface (including optional ones)
+  const propertyNames = [
+    ...Object.getOwnPropertyNames(sampleChannel),
+    // Add optional properties that might not be present on the sample
+    'fadeState',
+    'isLocked',
+    'maxQueueSize',
+    'retryConfig',
+    'volumeConfig' // Legacy property that might still be used
+  ];
+
+  return [...new Set(propertyNames)]; // Remove duplicates
+};
+
+/**
+ * Returns the list of non-whitelisted properties found on a specific channel
+ * These are properties that will trigger warnings when modified directly
+ * @param channelNumber - The channel number to inspect (defaults to 0)
+ * @returns Array of property names that are not in the whitelist, or empty array if channel doesn't exist
+ * @example
+ * ```typescript
+ * // Add some custom property to a channel
+ * (audioChannels[0] as any).customProperty = 'test';
+ *
+ * const nonWhitelisted = getNonWhitelistedChannelProperties(0);
+ * console.log(nonWhitelisted); // ['customProperty']
+ * ```
+ * @internal
+ */
+export const getNonWhitelistedChannelProperties = (channelNumber: number = 0): string[] => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel) {
+    return [];
+  }
+
+  const whitelistedProperties: string[] = getWhitelistedChannelProperties();
+  const allChannelProperties: string[] = Object.getOwnPropertyNames(channel);
+
+  // Filter out properties that are in the whitelist
+  const nonWhitelistedProperties: string[] = allChannelProperties.filter(
+    (property: string) => !whitelistedProperties.includes(property)
+  );
+
+  return nonWhitelistedProperties;
+};
+
 /**
  * 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[] = 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
+            // Use the automatically-derived whitelist from the interface
+            const whitelistedProperties = getWhitelistedChannelProperties();
+
+            if (typeof channelProp === 'string' && !whitelistedProperties.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
  */
-export const audioChannels: ExtendedAudioQueueChannel[] = [];
+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 +216,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 +236,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 +246,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 +289,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 +308,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 +324,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 +368,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 +378,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 +407,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 +419,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 +448,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 +458,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 +487,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 +497,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(),
@@ -386,3 +551,33 @@ export const offAudioResume = (channelNumber: number): void => {
 
   channel.audioResumeCallbacks.clear();
 };
+
+/**
+ * Removes audio start event listeners for a specific channel
+ * @param channelNumber - The channel number
+ * @example
+ * ```typescript
+ * offAudioStart(0); // Stop receiving start notifications for channel 0
+ * ```
+ */
+export const offAudioStart = (channelNumber: number): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel?.audioStartCallbacks) return;
+
+  channel.audioStartCallbacks.clear();
+};
+
+/**
+ * Removes audio complete event listeners for a specific channel
+ * @param channelNumber - The channel number
+ * @example
+ * ```typescript
+ * offAudioComplete(0); // Stop receiving completion notifications for channel 0
+ * ```
+ */
+export const offAudioComplete = (channelNumber: number): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel?.audioCompleteCallbacks) return;
+
+  channel.audioCompleteCallbacks.clear();
+};

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);
 };