@umituz/react-native-sound 1.2.31 → 1.2.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-sound",
-  "version": "1.2.31",
+  "version": "1.2.33",
   "description": "Universal sound playback and caching library for React Native apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/application/SoundCommands.ts

@@ -0,0 +1,233 @@
+/**
+ * Generic Command Processor - Eliminates Use Case Duplication
+ * Replaces 8 separate use case files with single command pattern
+ */
+
+import type { SoundSourceValue } from '../domain/value-objects';
+import type { IAudioService, PlaybackStatus } from './interfaces/IAudioService';
+import type { ISoundCache } from './interfaces/ISoundCache';
+import { SoundEvents } from './SoundEvents';
+import { SoundError } from '../domain/errors/SoundError';
+import { Logger } from '../infrastructure/Logger';
+
+// ===== Command Definitions =====
+export type SoundCommand =
+    | { type: 'PLAY'; payload: PlayCommand }
+    | { type: 'PAUSE'; payload: { sound: unknown } }
+    | { type: 'RESUME'; payload: { sound: unknown } }
+    | { type: 'STOP'; payload: { sound: unknown } }
+    | { type: 'SEEK'; payload: { sound: unknown; positionMillis: number } }
+    | { type: 'SET_VOLUME'; payload: { sound: unknown; volume: number } }
+    | { type: 'SET_RATE'; payload: { sound: unknown; rate: number } }
+    | { type: 'PRELOAD'; payload: PreloadCommand }
+    | { type: 'UNLOAD'; payload: void }
+    | { type: 'CLEAR_CACHE'; payload: void };
+
+export interface PlayCommand {
+    id: string;
+    source: SoundSourceValue;
+    volume?: number;
+    rate?: number;
+    isLooping?: boolean;
+    positionMillis?: number;
+}
+
+export interface PreloadCommand {
+    id: string;
+    source: SoundSourceValue;
+    volume?: number;
+    rate?: number;
+    isLooping?: boolean;
+}
+
+// ===== Generic Command Processor =====
+export class SoundCommandProcessor {
+    private currentSound: unknown | null = null;
+    private currentId: string | null = null;
+    private currentStatusUpdater: ((status: PlaybackStatus) => void) | null = null;
+    private isPlaying = false;
+
+    constructor(
+        private readonly audioService: IAudioService,
+        private readonly cache: ISoundCache,
+        private readonly events: SoundEvents
+    ) {}
+
+    async execute(command: SoundCommand): Promise<void> {
+        try {
+            await this.handleCommand(command);
+        } catch (error) {
+            if (error instanceof SoundError) throw error;
+            throw SoundError.playbackFailed(error);
+        }
+    }
+
+    private async handleCommand(command: SoundCommand): Promise<void> {
+        switch (command.type) {
+            case 'PLAY':
+                await this.handlePlay(command.payload);
+                break;
+            case 'PAUSE':
+                await this.handlePause(command.payload);
+                break;
+            case 'RESUME':
+                await this.handleResume(command.payload);
+                break;
+            case 'STOP':
+                await this.handleStop(command.payload);
+                break;
+            case 'SEEK':
+                await this.handleSeek(command.payload);
+                break;
+            case 'SET_VOLUME':
+                await this.handleSetVolume(command.payload);
+                break;
+            case 'SET_RATE':
+                await this.handleSetRate(command.payload);
+                break;
+            case 'PRELOAD':
+                await this.handlePreload(command.payload);
+                break;
+            case 'UNLOAD':
+                await this.handleUnload();
+                break;
+            case 'CLEAR_CACHE':
+                await this.handleClearCache();
+                break;
+        }
+    }
+
+    // ===== Command Handlers =====
+    private async handlePlay(payload: PlayCommand): Promise<void> {
+        const { id, source, volume = 1.0, rate = 1.0, isLooping = false, positionMillis } = payload;
+
+        // Toggle if same sound
+        if (this.currentId === id && this.currentSound && this.isPlaying) {
+            await this.audioService.pause(this.currentSound);
+            this.isPlaying = false;
+            this.events.emit('PLAYBACK_STOPPED');
+            return;
+        }
+
+        // Cleanup current
+        await this.unloadCurrent();
+
+        // Try cache first
+        const cached = this.cache.get(id);
+        if (cached) {
+            this.currentSound = cached.sound;
+            this.cache.delete(id).catch((error) => Logger.warn('Failed to delete from cache', error));
+        } else {
+            const statusUpdater = (status: PlaybackStatus) => {
+                this.events.emit('STATUS_UPDATE', status);
+                this.isPlaying = status.isPlaying;
+            };
+
+            const { sound } = await this.audioService.createSound(
+                source,
+                { shouldPlay: true, isLooping, volume, rate, positionMillis },
+                statusUpdater
+            );
+
+            this.currentSound = sound;
+            this.currentStatusUpdater = statusUpdater;
+        }
+
+        await this.audioService.play(this.currentSound);
+        this.currentId = id;
+        this.isPlaying = true;
+
+        this.events.emit('PLAYBACK_STARTED', {
+            id,
+            source,
+            volume,
+            rate,
+            isLooping,
+        });
+    }
+
+    private async handlePause(payload: { sound: unknown }): Promise<void> {
+        if (!payload.sound) return;
+        await this.audioService.pause(payload.sound);
+        this.isPlaying = false;
+        this.events.emit('PLAYBACK_STOPPED');
+    }
+
+    private async handleResume(payload: { sound: unknown }): Promise<void> {
+        if (!payload.sound) return;
+        await this.audioService.play(payload.sound);
+        this.isPlaying = true;
+    }
+
+    private async handleStop(payload: { sound: unknown }): Promise<void> {
+        if (!payload.sound) return;
+        await this.audioService.stop(payload.sound);
+        this.isPlaying = false;
+        this.events.emit('PLAYBACK_STOPPED');
+        this.events.emit('STATE_RESET');
+    }
+
+    private async handleSeek(payload: { sound: unknown; positionMillis: number }): Promise<void> {
+        if (!payload.sound) return;
+        await this.audioService.setPosition(payload.sound, payload.positionMillis);
+    }
+
+    private async handleSetVolume(payload: { sound: unknown; volume: number }): Promise<void> {
+        if (!payload.sound) return;
+        await this.audioService.setVolume(payload.sound, payload.volume);
+        this.events.emit('VOLUME_CHANGED', payload.volume);
+    }
+
+    private async handleSetRate(payload: { sound: unknown; rate: number }): Promise<void> {
+        if (!payload.sound) return;
+        await this.audioService.setRate(payload.sound, payload.rate);
+        this.events.emit('RATE_CHANGED', payload.rate);
+    }
+
+    private async handlePreload(payload: PreloadCommand): Promise<void> {
+        const { id, source, volume = 1.0, rate = 1.0, isLooping = false } = payload;
+
+        if (this.cache.has(id)) return;
+
+        const { sound } = await this.audioService.createSound(
+            source,
+            { shouldPlay: false, isLooping, volume, rate },
+            () => {}
+        );
+
+        await this.cache.set(id, { sound, source, loadedAt: Date.now() });
+    }
+
+    private async handleUnload(): Promise<void> {
+        await this.unloadCurrent();
+        this.events.emit('STATE_RESET');
+    }
+
+    private async handleClearCache(): Promise<void> {
+        await this.cache.clear();
+    }
+
+    // ===== Private Helpers =====
+    private async unloadCurrent(): Promise<void> {
+        if (this.currentSound) {
+            try {
+                await this.audioService.unload(this.currentSound);
+            } catch (error) {
+                Logger.warn('Failed to unload sound', error);
+            }
+        }
+        this.currentStatusUpdater = null;
+        this.currentSound = null;
+        this.currentId = null;
+        this.isPlaying = false;
+    }
+
+    // ===== Public API =====
+    getCurrentSound(): unknown | null {
+        return this.currentSound;
+    }
+
+    getCurrentId(): string | null {
+        return this.currentId;
+    }
+}

package/src/application/SoundEvents.ts

@@ -0,0 +1,101 @@
+/**
+ * Event Bus - Eliminates Presenter Pattern
+ * Direct communication between commands and store
+ */
+
+import type { PlaybackStatus } from './interfaces/IAudioService';
+import type { SoundSourceValue } from '../domain/value-objects';
+import { Logger } from '../infrastructure/Logger';
+
+// ===== Event Types =====
+export type SoundEvent =
+    | { type: 'PLAYBACK_STARTED'; payload: PlaybackStartedEvent }
+    | { type: 'PLAYBACK_STOPPED' }
+    | { type: 'STATUS_UPDATE'; payload: PlaybackStatus }
+    | { type: 'VOLUME_CHANGED'; payload: number }
+    | { type: 'RATE_CHANGED'; payload: number }
+    | { type: 'STATE_RESET' }
+    | { type: 'ERROR'; payload: string };
+
+export interface PlaybackStartedEvent {
+    id: string;
+    source: SoundSourceValue;
+    volume: number;
+    rate: number;
+    isLooping: boolean;
+}
+
+// ===== Event Bus Implementation =====
+type EventListener = (payload: unknown) => void;
+
+export class SoundEvents {
+    private listeners = new Map<string, Set<EventListener>>();
+
+    on(eventType: string, listener: EventListener): () => void {
+        if (!this.listeners.has(eventType)) {
+            this.listeners.set(eventType, new Set());
+        }
+        const listeners = this.listeners.get(eventType);
+        if (listeners) {
+            listeners.add(listener);
+        }
+
+        // Return unsubscribe function
+        return () => {
+            this.off(eventType, listener);
+        };
+    }
+
+    off(eventType: string, listener: EventListener): void {
+        const eventListeners = this.listeners.get(eventType);
+        if (eventListeners) {
+            eventListeners.delete(listener);
+        }
+    }
+
+    emit<T = unknown>(eventType: string, payload?: T): void {
+        const eventListeners = this.listeners.get(eventType);
+        if (eventListeners) {
+            eventListeners.forEach((listener) => {
+                try {
+                    listener(payload as T);
+                } catch (error) {
+                    Logger.error(`Error in event listener for ${eventType}`, error);
+                }
+            });
+        }
+    }
+
+    clear(): void {
+        this.listeners.clear();
+    }
+
+    // ===== Convenience Methods =====
+    emitPlaybackStarted(event: PlaybackStartedEvent): void {
+        this.emit('PLAYBACK_STARTED', event);
+    }
+
+    emitPlaybackStopped(): void {
+        this.emit('PLAYBACK_STOPPED');
+    }
+
+    emitStatusUpdate(status: PlaybackStatus): void {
+        this.emit('STATUS_UPDATE', status);
+    }
+
+    emitVolumeChanged(volume: number): void {
+        this.emit('VOLUME_CHANGED', volume);
+    }
+
+    emitRateChanged(rate: number): void {
+        this.emit('RATE_CHANGED', rate);
+    }
+
+    emitStateReset(): void {
+        this.emit('STATE_RESET');
+    }
+
+    emitError(error: string): void {
+        this.emit('ERROR', error);
+    }
+}

package/src/application/SoundService.ts

@@ -0,0 +1,185 @@
+/**
+ * Unified Sound Service - Combines Facade + Repository Pattern
+ * Single entry point for all sound operations
+ */
+
+import type { SoundSourceValue } from '../domain/value-objects';
+import type { PlaybackOptions } from '../types';
+import { AudioConfig } from '../infrastructure/AudioConfig';
+import { AudioRepository } from '../infrastructure/AudioRepository';
+import { SoundCommandProcessor, type SoundCommand, type PlayCommand, type PreloadCommand } from './SoundCommands';
+import { SoundEvents } from './SoundEvents';
+import { Logger } from '../infrastructure/Logger';
+
+export class SoundService {
+    private static instance: SoundService | null = null;
+    private repository: AudioRepository;
+    private commandProcessor: SoundCommandProcessor;
+    private events: SoundEvents;
+
+    private constructor() {
+        this.events = new SoundEvents();
+        this.repository = new AudioRepository(this.events);
+        this.commandProcessor = new SoundCommandProcessor(
+            this.repository.audioService,
+            this.repository.cache,
+            this.events
+        );
+
+        // Initialize audio config
+        AudioConfig.configure().catch((error) => Logger.warn('Failed to configure audio', error));
+    }
+
+    static getInstance(): SoundService {
+        if (!this.instance) {
+            this.instance = new SoundService();
+        }
+        return this.instance;
+    }
+
+    // ===== Public API =====
+
+    /**
+     * Play a sound
+     */
+    async play(id: string, source: SoundSourceValue, options?: PlaybackOptions): Promise<void> {
+        const command: SoundCommand = {
+            type: 'PLAY',
+            payload: {
+                id,
+                source,
+                volume: options?.volume,
+                rate: options?.rate,
+                isLooping: options?.isLooping,
+                positionMillis: options?.positionMillis,
+            },
+        };
+        await this.commandProcessor.execute(command);
+    }
+
+    /**
+     * Pause playback
+     */
+    async pause(): Promise<void> {
+        const sound = this.commandProcessor.getCurrentSound();
+        await this.commandProcessor.execute({ type: 'PAUSE', payload: { sound } });
+    }
+
+    /**
+     * Resume playback
+     */
+    async resume(): Promise<void> {
+        const sound = this.commandProcessor.getCurrentSound();
+        await this.commandProcessor.execute({ type: 'RESUME', payload: { sound } });
+    }
+
+    /**
+     * Stop playback
+     */
+    async stop(): Promise<void> {
+        const sound = this.commandProcessor.getCurrentSound();
+        await this.commandProcessor.execute({ type: 'STOP', payload: { sound } });
+    }
+
+    /**
+     * Seek to position
+     */
+    async seek(positionMillis: number): Promise<void> {
+        const sound = this.commandProcessor.getCurrentSound();
+        await this.commandProcessor.execute({
+            type: 'SEEK',
+            payload: { sound, positionMillis },
+        });
+    }
+
+    /**
+     * Set volume
+     */
+    async setVolume(volume: number): Promise<void> {
+        const sound = this.commandProcessor.getCurrentSound();
+        await this.commandProcessor.execute({
+            type: 'SET_VOLUME',
+            payload: { sound, volume },
+        });
+    }
+
+    /**
+     * Set rate
+     */
+    async setRate(rate: number): Promise<void> {
+        const sound = this.commandProcessor.getCurrentSound();
+        await this.commandProcessor.execute({
+            type: 'SET_RATE',
+            payload: { sound, rate },
+        });
+    }
+
+    /**
+     * Preload a sound
+     */
+    async preload(id: string, source: SoundSourceValue, options?: PlaybackOptions): Promise<void> {
+        const command: SoundCommand = {
+            type: 'PRELOAD',
+            payload: {
+                id,
+                source,
+                volume: options?.volume,
+                rate: options?.rate,
+                isLooping: options?.isLooping,
+            },
+        };
+        await this.commandProcessor.execute(command);
+    }
+
+    /**
+     * Unload current sound
+     */
+    async unload(): Promise<void> {
+        await this.commandProcessor.execute({ type: 'UNLOAD', payload: undefined });
+    }
+
+    /**
+     * Clear cache
+     */
+    async clearCache(): Promise<void> {
+        await this.commandProcessor.execute({ type: 'CLEAR_CACHE', payload: undefined });
+    }
+
+    /**
+     * Check if sound is cached
+     */
+    isCached(id: string): boolean {
+        return this.repository.cache.has(id);
+    }
+
+    /**
+     * Get current playing id
+     */
+    getCurrentId(): string | null {
+        return this.commandProcessor.getCurrentId();
+    }
+
+    /**
+     * Subscribe to events
+     */
+    on(eventType: string, listener: (payload: unknown) => void): () => void {
+        return this.events.on(eventType, listener);
+    }
+
+    /**
+     * Cleanup resources
+     */
+    async dispose(): Promise<void> {
+        await this.unload();
+        await this.clearCache();
+        this.events.clear();
+    }
+
+    /**
+     * Get events instance (for internal use by useSound hook)
+     * @internal
+     */
+    getEvents(): SoundEvents {
+        return this.events;
+    }
+}

package/src/application/interfaces/IAudioService.ts

@@ -0,0 +1,42 @@
+/**
+ * Audio Service Interface
+ */
+
+import type { AVPlaybackStatus } from 'expo-av';
+import type { SoundSourceValue } from '../../domain/value-objects';
+
+export interface PlaybackStatus {
+    isLoaded: boolean;
+    isPlaying: boolean;
+    isBuffering: boolean;
+    positionMillis: number;
+    durationMillis: number;
+    rate?: number;
+    isLooping: boolean;
+    didJustFinish: boolean;
+    error?: string;
+}
+
+export interface PlaybackOptions {
+    shouldPlay: boolean;
+    isLooping: boolean;
+    volume: number;
+    rate: number;
+    positionMillis?: number;
+}
+
+export interface IAudioService {
+    createSound(
+        source: SoundSourceValue,
+        options: PlaybackOptions,
+        onStatusUpdate: (status: PlaybackStatus) => void
+    ): Promise<{ sound: unknown }>;
+    play(sound: unknown): Promise<void>;
+    pause(sound: unknown): Promise<void>;
+    stop(sound: unknown): Promise<void>;
+    unload(sound: unknown): Promise<void>;
+    setVolume(sound: unknown, volume: number): Promise<void>;
+    setRate(sound: unknown, rate: number): Promise<void>;
+    setPosition(sound: unknown, positionMillis: number): Promise<void>;
+    getStatus(sound: unknown): Promise<PlaybackStatus | null>;
+}

package/src/application/interfaces/ISoundCache.ts

@@ -0,0 +1,19 @@
+/**
+ * Sound Cache Interface
+ */
+
+import type { SoundSourceValue } from '../../domain/value-objects';
+
+export interface CachedSound {
+    sound: unknown;
+    source: SoundSourceValue;
+    loadedAt: number;
+}
+
+export interface ISoundCache {
+    get(id: string): CachedSound | undefined;
+    set(id: string, cached: CachedSound): Promise<void>;
+    delete(id: string): Promise<void>;
+    has(id: string): boolean;
+    clear(): Promise<void>;
+}

package/src/domain/errors/SoundError.ts

@@ -0,0 +1,44 @@
+/**
+ * Domain Errors for Sound Operations
+ */
+
+export enum SoundErrorCode {
+    INVALID_SOUND_ID = 'INVALID_SOUND_ID',
+    INVALID_SOUND_SOURCE = 'INVALID_SOUND_SOURCE',
+    PLAYBACK_FAILED = 'PLAYBACK_FAILED',
+    SOUND_NOT_LOADED = 'SOUND_NOT_LOADED',
+    INVALID_POSITION = 'INVALID_POSITION',
+    CACHE_ERROR = 'CACHE_ERROR',
+}
+
+export class SoundError extends Error {
+    constructor(
+        public readonly code: SoundErrorCode,
+        message: string,
+        public readonly originalError?: unknown
+    ) {
+        super(message);
+        this.name = 'SoundError';
+    }
+
+    static invalidSoundId(): SoundError {
+        return new SoundError(SoundErrorCode.INVALID_SOUND_ID, 'Sound id must be a non-empty string');
+    }
+
+    static invalidSoundSource(): SoundError {
+        return new SoundError(SoundErrorCode.INVALID_SOUND_SOURCE, 'Sound source cannot be null or undefined');
+    }
+
+    static playbackFailed(error: unknown): SoundError {
+        const message = error instanceof Error ? error.message : 'Unknown playback error';
+        return new SoundError(SoundErrorCode.PLAYBACK_FAILED, message, error);
+    }
+
+    static soundNotLoaded(): SoundError {
+        return new SoundError(SoundErrorCode.SOUND_NOT_LOADED, 'Sound is not loaded');
+    }
+
+    static invalidPosition(): SoundError {
+        return new SoundError(SoundErrorCode.INVALID_POSITION, 'Position must be a finite number');
+    }
+}