@umituz/react-native-sound 1.2.32 → 1.2.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-sound",
-  "version": "1.2.32",
+  "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

@@ -3,7 +3,7 @@
  */
 
 import type { AVPlaybackStatus } from 'expo-av';
-import { SoundSourceValue } from '../../domain/value-objects/SoundSource';
+import type { SoundSourceValue } from '../../domain/value-objects';
 
 export interface PlaybackStatus {
     isLoaded: boolean;

package/src/application/interfaces/ISoundCache.ts

@@ -2,7 +2,7 @@
  * Sound Cache Interface
  */
 
-import { SoundSourceValue } from '../../domain/value-objects/SoundSource';
+import type { SoundSourceValue } from '../../domain/value-objects';
 
 export interface CachedSound {
     sound: unknown;
@@ -12,10 +12,8 @@ export interface CachedSound {
 
 export interface ISoundCache {
     get(id: string): CachedSound | undefined;
-    set(id: string, cached: CachedSound): void;
-    delete(id: string): void;
+    set(id: string, cached: CachedSound): Promise<void>;
+    delete(id: string): Promise<void>;
     has(id: string): boolean;
-    clear(): void;
-    cleanExpired(): void;
-    enforceLimit(): void;
+    clear(): Promise<void>;
 }

package/src/domain/value-objects.ts

@@ -0,0 +1,128 @@
+/**
+ * Value Objects - Consolidated with Generic Base Class
+ * Eliminates duplication across multiple files
+ */
+
+// ===== Generic Base Value Object =====
+export abstract class ValueObject<T> {
+    protected readonly value: T;
+
+    constructor(value: T, validator?: (value: T) => void) {
+        if (validator) validator(value);
+        this.value = this.transform(value);
+    }
+
+    protected abstract transform(value: T): T;
+
+    getValue(): T {
+        return this.value;
+    }
+
+    equals(other: ValueObject<T>): boolean {
+        return other instanceof this.constructor && this.value === other.value;
+    }
+
+    toString(): string {
+        return String(this.value);
+    }
+}
+
+// ===== Sound ID =====
+export class SoundId extends ValueObject<string> {
+    protected transform(value: string): string {
+        if (typeof value !== 'string' || value.trim().length === 0) {
+            throw new Error('Sound id must be a non-empty string');
+        }
+        return value.trim();
+    }
+
+    override toString(): string {
+        return this.value;
+    }
+}
+
+// ===== Sound Source =====
+export type SoundSourceValue = number | { uri: string; headers?: Record<string, string> };
+
+export class SoundSource extends ValueObject<SoundSourceValue> {
+    protected transform(value: SoundSourceValue): SoundSourceValue {
+        if (value === null || value === undefined) {
+            throw new Error('Sound source cannot be null or undefined');
+        }
+        return value;
+    }
+
+    isLocal(): boolean {
+        return typeof this.value === 'number';
+    }
+
+    isRemote(): boolean {
+        return typeof this.value === 'object' && 'uri' in this.value;
+    }
+}
+
+// ===== Volume (0.0 - 1.0) =====
+export class Volume extends ValueObject<number> {
+    private readonly MIN = 0;
+    private readonly MAX = 1;
+
+    protected transform(value: number): number {
+        if (!Number.isFinite(value)) return 1.0;
+        return Math.max(this.MIN, Math.min(this.MAX, value));
+    }
+}
+
+// ===== Playback Rate (0.5 - 2.0) =====
+export class Rate extends ValueObject<number> {
+    private readonly MIN = 0.5;
+    private readonly MAX = 2.0;
+
+    protected transform(value: number): number {
+        if (!Number.isFinite(value)) return 1.0;
+        return Math.max(this.MIN, Math.min(this.MAX, value));
+    }
+}
+
+// ===== Playback Position =====
+export class PlaybackPosition extends ValueObject<number> {
+    constructor(value: number, private readonly duration?: number) {
+        super(value);
+    }
+
+    protected transform(value: number): number {
+        if (!Number.isFinite(value)) {
+            throw new Error('Position must be a finite number');
+        }
+        return this.duration ? Math.max(0, Math.min(this.duration, value)) : value;
+    }
+
+    getDuration(): number | undefined {
+        return this.duration;
+    }
+}
+
+// ===== Factory for Batch Creation =====
+export class SoundValueObjects {
+    static create(params: {
+        id: string;
+        source: SoundSourceValue;
+        volume?: number;
+        rate?: number;
+        position?: number;
+        duration?: number;
+    }): {
+        id: SoundId;
+        source: SoundSource;
+        volume: Volume;
+        rate: Rate;
+        position?: PlaybackPosition;
+    } {
+        return {
+            id: new SoundId(params.id),
+            source: new SoundSource(params.source),
+            volume: new Volume(params.volume ?? 1.0),
+            rate: new Rate(params.rate ?? 1.0),
+            position: params.position ? new PlaybackPosition(params.position, params.duration) : undefined,
+        };
+    }
+}