@umituz/react-native-sound 1.2.31 → 1.2.33

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,
+        };
+    }
+}

package/src/index.ts

@@ -1,11 +1,50 @@
-export type { SoundSource, PlaybackOptions, SoundState } from './types';
+/**
+ * @umituz/react-native-sound
+ * DDD-based audio management for React Native
+ * Optimized architecture with minimal code duplication
+ */
+
+// ===== Public API =====
+export { useSound } from './presentation/useSound';
+export { useSoundStore, setupEventListeners } from './presentation/SoundStore';
+
+// ===== Types =====
+export type { PlaybackOptions, SoundState, SoundSource } from './types';
+export type { PlaybackStatus, PlaybackOptions as ServicePlaybackOptions } from './application/interfaces/IAudioService';
+export type { CachedSound, ISoundCache } from './application/interfaces/ISoundCache';
+
+// ===== Domain (Advanced Usage) =====
+export { SoundError, SoundErrorCode } from './domain/errors/SoundError';
+export {
+    SoundId,
+    SoundSource as SoundSourceVO,
+    Volume,
+    Rate,
+    PlaybackPosition,
+    SoundValueObjects,
+    type SoundSourceValue,
+} from './domain/value-objects';
+
+// ===== Infrastructure (Testing/Customization) =====
+export { Logger } from './infrastructure/Logger';
+export { AudioConfig } from './infrastructure/AudioConfig';
+export { AudioRepository } from './infrastructure/AudioRepository';
+
+// ===== Application (Testing/Customization) =====
+export { SoundService } from './application/SoundService';
+export { SoundCommandProcessor, type SoundCommand, type PlayCommand, type PreloadCommand } from './application/SoundCommands';
+export { SoundEvents, type SoundEvent, type PlaybackStartedEvent } from './application/SoundEvents';
+
+// ===== Utilities =====
 export {
-    isPlaybackStatusSuccess,
-    isSoundSourceValid,
     clampVolume,
     clampRate,
     validateSoundId,
+    isSoundSourceValid,
+    isPlaybackStatusSuccess,
+    debounce,
+    throttle,
+    RateLimiter,
+    PeriodicTask,
+    AutoGCWeakCache,
 } from './utils';
-export { audioManager } from './AudioManager';
-export { useSound } from './useSound';
-export { useSoundStore } from './store';

package/src/infrastructure/AudioConfig.ts

@@ -0,0 +1,24 @@
+/**
+ * Audio Configuration Service
+ */
+
+import { Audio, InterruptionModeIOS, InterruptionModeAndroid } from 'expo-av';
+import { Logger } from './Logger';
+
+export class AudioConfig {
+    static async configure(): Promise<void> {
+        try {
+            await Audio.setAudioModeAsync({
+                playsInSilentModeIOS: true,
+                staysActiveInBackground: false,
+                shouldDuckAndroid: true,
+                playThroughEarpieceAndroid: false,
+                interruptionModeIOS: InterruptionModeIOS.DuckOthers,
+                interruptionModeAndroid: InterruptionModeAndroid.DuckOthers,
+            });
+            Logger.debug('Audio configured successfully');
+        } catch (error) {
+            Logger.warn('Failed to configure audio session', error);
+        }
+    }
+}

package/src/infrastructure/AudioRepository.ts

@@ -0,0 +1,216 @@
+/**
+ * Audio Repository - Combines Cache + Audio Service
+ * Single responsibility: Audio resource management
+ */
+
+import { Audio } from 'expo-av';
+import type { AVPlaybackStatus } from 'expo-av';
+import type { IAudioService, PlaybackStatus, PlaybackOptions } from '../application/interfaces/IAudioService';
+import type { ISoundCache, CachedSound } from '../application/interfaces/ISoundCache';
+import type { SoundSourceValue } from '../domain/value-objects';
+import { SoundEvents } from '../application/SoundEvents';
+import { Logger } from './Logger';
+import { RateLimiter } from '../utils';
+
+// ===== Audio Service Implementation =====
+class ExpoAudioService implements IAudioService {
+    async createSound(
+        source: SoundSourceValue,
+        options: PlaybackOptions,
+        onStatusUpdate: (status: PlaybackStatus) => void
+    ): Promise<{ sound: Audio.Sound }> {
+        const { sound } = await Audio.Sound.createAsync(
+            source,
+            {
+                shouldPlay: options.shouldPlay,
+                isLooping: options.isLooping,
+                volume: options.volume,
+                rate: options.rate,
+                positionMillis: options.positionMillis,
+            },
+            (status) => onStatusUpdate(this.mapStatus(status))
+        );
+        Logger.debug('Sound created');
+        return { sound };
+    }
+
+    async play(sound: unknown): Promise<void> {
+        await (sound as Audio.Sound).playAsync();
+    }
+
+    async pause(sound: unknown): Promise<void> {
+        await (sound as Audio.Sound).pauseAsync();
+    }
+
+    async stop(sound: unknown): Promise<void> {
+        await (sound as Audio.Sound).stopAsync();
+    }
+
+    async unload(sound: unknown): Promise<void> {
+        await (sound as Audio.Sound).unloadAsync();
+    }
+
+    async setVolume(sound: unknown, volume: number): Promise<void> {
+        await (sound as Audio.Sound).setVolumeAsync(volume);
+    }
+
+    async setRate(sound: unknown, rate: number): Promise<void> {
+        await (sound as Audio.Sound).setRateAsync(rate, false);
+    }
+
+    async setPosition(sound: unknown, positionMillis: number): Promise<void> {
+        await (sound as Audio.Sound).setStatusAsync({ positionMillis });
+    }
+
+    async getStatus(sound: unknown): Promise<PlaybackStatus | null> {
+        const status = await (sound as Audio.Sound).getStatusAsync();
+        return status.isLoaded ? this.mapStatus(status) : null;
+    }
+
+    private mapStatus(status: AVPlaybackStatus): PlaybackStatus {
+        if (!status.isLoaded) {
+            const statusRecord = status as Record<string, unknown>;
+            const hasError = 'error' in statusRecord;
+            const error = hasError && statusRecord.error instanceof Error ? statusRecord.error.message : undefined;
+            return {
+                isLoaded: false,
+                isPlaying: false,
+                isBuffering: false,
+                positionMillis: 0,
+                durationMillis: 0,
+                isLooping: false,
+                didJustFinish: false,
+                error,
+            };
+        }
+        return {
+            isLoaded: true,
+            isPlaying: status.isPlaying,
+            isBuffering: status.isBuffering,
+            positionMillis: status.positionMillis,
+            durationMillis: status.durationMillis || 0,
+            rate: status.rate,
+            isLooping: status.isLooping,
+            didJustFinish: status.didJustFinish,
+        };
+    }
+}
+
+// ===== Sound Cache Configuration =====
+const CACHE_CONFIG = {
+    MAX_SIZE: 3,
+    EXPIRE_MS: 5 * 60 * 1000, // 5 minutes
+    CLEAN_INTERVAL_MS: 30 * 1000, // 30 seconds
+} as const;
+
+// ===== Sound Cache Implementation =====
+class SoundCache implements ISoundCache {
+    private cache = new Map<string, CachedSound>();
+    private accessOrder: string[] = [];
+    private readonly maxSize = CACHE_CONFIG.MAX_SIZE;
+    private readonly expireMs = CACHE_CONFIG.EXPIRE_MS;
+    private lastCleanTime = 0;
+    private readonly cleanIntervalMs = CACHE_CONFIG.CLEAN_INTERVAL_MS;
+    private cleanLimiter = new RateLimiter(this.cleanIntervalMs);
+
+    constructor(
+        private readonly audioService: IAudioService,
+        private readonly events: SoundEvents
+    ) {}
+
+    get(id: string): CachedSound | undefined {
+        const cached = this.cache.get(id);
+        if (cached) {
+            this.updateAccessOrder(id);
+        }
+        return cached;
+    }
+
+    async set(id: string, cached: CachedSound): Promise<void> {
+        await this.cleanExpiredThrottled();
+        await this.enforceLimit();
+        this.cache.set(id, cached);
+        this.updateAccessOrder(id);
+        Logger.debug(`Cached: ${id}`);
+    }
+
+    async delete(id: string): Promise<void> {
+        const cached = this.cache.get(id);
+        if (cached) {
+            try {
+                await this.audioService.unload(cached.sound);
+            } catch (error) {
+                Logger.warn(`Failed to unload: ${id}`, error);
+            }
+        }
+        this.cache.delete(id);
+        this.removeFromAccessOrder(id);
+    }
+
+    has(id: string): boolean {
+        return this.cache.has(id);
+    }
+
+    async clear(): Promise<void> {
+        const unloadPromises = Array.from(this.cache.values()).map((cached) =>
+            this.audioService.unload(cached.sound).catch((error) => {
+                Logger.warn('Failed to unload during clear', error);
+            })
+        );
+        await Promise.all(unloadPromises);
+        this.cache.clear();
+        this.accessOrder = [];
+        Logger.debug('Cache cleared');
+    }
+
+    private async cleanExpiredThrottled(): Promise<void> {
+        await this.cleanLimiter.execute(async () => {
+            const now = Date.now();
+            const expiredIds: string[] = [];
+            for (const [id, cached] of this.cache) {
+                if (now - cached.loadedAt > this.expireMs) {
+                    expiredIds.push(id);
+                }
+            }
+            for (const id of expiredIds) {
+                await this.delete(id);
+                Logger.debug(`Expired cache removed: ${id}`);
+            }
+        });
+    }
+
+    private async enforceLimit(): Promise<void> {
+        while (this.cache.size >= this.maxSize && this.accessOrder.length > 0) {
+            const lruId = this.accessOrder[0];
+            if (lruId && this.cache.has(lruId)) {
+                await this.delete(lruId);
+                Logger.debug(`LRU enforced, removed: ${lruId}`);
+            } else {
+                break;
+            }
+        }
+    }
+
+    private updateAccessOrder(id: string): void {
+        this.removeFromAccessOrder(id);
+        this.accessOrder.push(id);
+    }
+
+    private removeFromAccessOrder(id: string): void {
+        const index = this.accessOrder.indexOf(id);
+        if (index > -1) {
+            this.accessOrder.splice(index, 1);
+        }
+    }
+}
+
+// ===== Repository Export =====
+export class AudioRepository {
+    readonly audioService: IAudioService;
+    readonly cache: ISoundCache;
+
+    constructor(events: SoundEvents) {
+        this.audioService = new ExpoAudioService();
+        this.cache = new SoundCache(this.audioService, events);
+    }
+}

package/src/infrastructure/Logger.ts

@@ -0,0 +1,23 @@
+/**
+ * Logging Service
+ */
+
+export class Logger {
+    static debug(message: string, ...args: unknown[]): void {
+        if (__DEV__) {
+            console.log(`[Sound] ${message}`, ...args);
+        }
+    }
+
+    static warn(message: string, ...args: unknown[]): void {
+        if (__DEV__) {
+            console.warn(`[Sound] ${message}`, ...args);
+        }
+    }
+
+    static error(message: string, error?: unknown): void {
+        if (__DEV__) {
+            console.error(`[Sound] ${message}`, error);
+        }
+    }
+}

package/src/presentation/SoundStore.ts

@@ -0,0 +1,156 @@
+/**
+ * Event-Driven Sound Store - Eliminates Presenter Pattern
+ * Direct event subscription from SoundService
+ */
+
+import { createStore } from '@umituz/react-native-design-system/storage';
+import type { PlaybackStatus } from '../application/interfaces/IAudioService';
+import type { SoundSourceValue } from '../domain/value-objects';
+import type { SoundEvents } from '../application/SoundEvents';
+
+// ===== Store State =====
+interface SoundState {
+    isPlaying: boolean;
+    isBuffering: boolean;
+    positionMillis: number;
+    durationMillis: number;
+    volume: number;
+    rate: number;
+    isLooping: boolean;
+    error: string | null;
+    currentId: string | null;
+    currentSource: SoundSourceValue | null;
+}
+
+interface SoundActions {
+    setPlaying: (isPlaying: boolean) => void;
+    setBuffering: (isBuffering: boolean) => void;
+    setProgress: (position: number, duration: number) => void;
+    setError: (error: string | null) => void;
+    setCurrent: (id: string | null, source: SoundSourceValue | null) => void;
+    setVolumeState: (volume: number) => void;
+    setRateState: (rate: number) => void;
+    setLooping: (isLooping: boolean) => void;
+    reset: () => void;
+}
+
+const initialState: SoundState = {
+    isPlaying: false,
+    isBuffering: false,
+    positionMillis: 0,
+    durationMillis: 0,
+    volume: 1.0,
+    rate: 1.0,
+    isLooping: false,
+    error: null,
+    currentId: null,
+    currentSource: null,
+};
+
+// ===== Store Creation =====
+export const useSoundStore = createStore<SoundState, SoundActions>({
+    name: 'sound-store',
+    initialState,
+    persist: false,
+    actions: (set) => ({
+        setPlaying: (isPlaying) => set({ isPlaying }),
+        setBuffering: (isBuffering) => set({ isBuffering }),
+        setProgress: (position, duration) => set({ positionMillis: position, durationMillis: duration }),
+        setError: (error) => set({ error }),
+        setCurrent: (currentId, currentSource) => set({ currentId, currentSource }),
+        setVolumeState: (volume) => set({ volume }),
+        setRateState: (rate) => set({ rate }),
+        setLooping: (isLooping) => set({ isLooping }),
+        reset: () => set(initialState),
+    }),
+});
+
+// ===== Event Integration =====
+export function setupEventListeners(events: SoundEvents): () => void {
+    const unsubscribers: Array<() => void> = [];
+
+    // Playback started
+    unsubscribers.push(
+        events.on('PLAYBACK_STARTED', (payload) => {
+            const p = payload as { id: string; source: SoundSourceValue; volume: number; rate: number; isLooping: boolean };
+            const store = useSoundStore.getState();
+            store.setCurrent(p.id, p.source);
+            store.setError(null);
+            store.setVolumeState(p.volume);
+            store.setRateState(p.rate);
+            store.setLooping(p.isLooping);
+            store.setPlaying(true);
+        })
+    );
+
+    // Playback stopped
+    unsubscribers.push(
+        events.on('PLAYBACK_STOPPED', () => {
+            const store = useSoundStore.getState();
+            store.setPlaying(false);
+        })
+    );
+
+    // Status update
+    unsubscribers.push(
+        events.on('STATUS_UPDATE', (payload) => {
+            const status = payload as PlaybackStatus;
+            const store = useSoundStore.getState();
+            if (status.isLoaded) {
+                store.setPlaying(status.isPlaying);
+                store.setBuffering(status.isBuffering);
+                store.setProgress(status.positionMillis, status.durationMillis);
+
+                if (status.rate !== undefined) {
+                    store.setRateState(status.rate);
+                }
+
+                if (status.didJustFinish && !status.isLooping) {
+                    store.setPlaying(false);
+                    store.setProgress(status.durationMillis, status.durationMillis);
+                }
+            }
+
+            if (status.error) {
+                store.setError(status.error);
+                store.setPlaying(false);
+            }
+        })
+    );
+
+    // Volume changed
+    unsubscribers.push(
+        events.on('VOLUME_CHANGED', (payload) => {
+            useSoundStore.getState().setVolumeState(payload as number);
+        })
+    );
+
+    // Rate changed
+    unsubscribers.push(
+        events.on('RATE_CHANGED', (payload) => {
+            useSoundStore.getState().setRateState(payload as number);
+        })
+    );
+
+    // State reset
+    unsubscribers.push(
+        events.on('STATE_RESET', () => {
+            useSoundStore.getState().reset();
+        })
+    );
+
+    // Error
+    unsubscribers.push(
+        events.on('ERROR', (payload) => {
+            const error = payload as string;
+            const store = useSoundStore.getState();
+            store.setError(error);
+            store.setPlaying(false);
+        })
+    );
+
+    // Return cleanup function
+    return () => {
+        unsubscribers.forEach((unsub) => unsub());
+    };
+}