react-native-audio-browser 0.2.0-next.9 → 0.2.0

package/src/web/TrackPlayer/QueueManager.ts

@@ -1,302 +0,0 @@
-import type { RepeatMode as RepeatModeType } from '../../features'
-import type { Track } from '../../types'
-import { assertedNotNullish } from '../../utils/validation'
-import { fisherYatesShuffle } from '../util/shuffle'
-import { RepeatMode } from './RepeatMode'
-
-/**
- * What removing tracks means for the currently-playing item — the caller (the
- * player) acts on it (reload / stop), keeping engine concerns out of the queue.
- */
-export type RemoveOutcome =
-  | { kind: 'no-current' } // nothing was playing; the queue was filtered, nothing else to do
-  | { kind: 'kept' } // the current track survived; its index was adjusted in place
-  | { kind: 'reload'; index: number } // the current track was removed; reload this index
-  | { kind: 'emptied' } // the current track was removed and the queue is now empty
-
-/**
- * Owns the play queue: the track list, the current/last index, repeat mode and
- * shuffle order, plus all the pure index math (next/previous, wrap-around,
- * shuffle ordering, index adjustment on mutation). It has no knowledge of the
- * playback engine — the web analog of iOS's `QueueManager` + `ShuffleOrder`.
- * Orchestration (loading a track when the index changes) stays with the caller.
- */
-export class QueueManager {
-  private _tracks: Track[] = []
-  private _currentIndex: number | undefined
-  private _lastIndex: number | undefined
-  private _repeatMode: RepeatModeType = RepeatMode.Off
-  private _shuffleEnabled = false
-  private shuffleOrder: number[] = []
-
-  // MARK: tracks
-
-  get tracks(): Track[] {
-    return this._tracks
-  }
-
-  get length(): number {
-    return this._tracks.length
-  }
-
-  getTrack(index: number): Track | undefined {
-    return this._tracks[index]
-  }
-
-  /** Replaces the whole queue and resets the current/last index. */
-  setTracks(tracks: Track[]): void {
-    this._tracks = tracks
-    this._currentIndex = undefined
-    this._lastIndex = undefined
-    if (this._shuffleEnabled) this.regenerateShuffleOrder()
-  }
-
-  /** Replaces a single track in place (e.g. a favorite toggle). */
-  replaceTrack(index: number, track: Track): void {
-    this._tracks[index] = track
-  }
-
-  // MARK: current index
-
-  get currentIndex(): number | undefined {
-    return this._currentIndex
-  }
-
-  set currentIndex(index: number | undefined) {
-    this._lastIndex = this._currentIndex
-    this._currentIndex = index
-  }
-
-  get lastIndex(): number | undefined {
-    return this._lastIndex
-  }
-
-  // MARK: repeat / shuffle
-
-  get repeatMode(): RepeatModeType {
-    return this._repeatMode
-  }
-
-  set repeatMode(mode: RepeatModeType) {
-    this._repeatMode = mode
-  }
-
-  get shuffleEnabled(): boolean {
-    return this._shuffleEnabled
-  }
-
-  setShuffleEnabled(enabled: boolean): void {
-    this._shuffleEnabled = enabled
-    if (enabled) this.regenerateShuffleOrder()
-  }
-
-  regenerateShuffleOrder(): void {
-    this.shuffleOrder = Array.from({ length: this._tracks.length }, (_, i) => i)
-    fisherYatesShuffle(this.shuffleOrder)
-
-    // Keep the current track at the front so navigation continues from it.
-    if (this._currentIndex === undefined) return
-    const currentPos = this.shuffleOrder.indexOf(this._currentIndex)
-    if (currentPos > 0) {
-      const first = assertedNotNullish(this.shuffleOrder[0])
-      this.shuffleOrder[0] = assertedNotNullish(this.shuffleOrder[currentPos])
-      this.shuffleOrder[currentPos] = first
-    }
-  }
-
-  // The shuffle order is maintained incrementally across mutations (matching
-  // iOS's ShuffleOrder and ExoPlayer's DefaultShuffleOrder) rather than
-  // regenerated: a regeneration re-randomizes the upcoming order and erases
-  // the played history, leaving previous() dead after any add/remove/move.
-
-  /** Shifts indices for an insertion and slots the new ones in at random positions. */
-  private shuffleOrderInsert(at: number, count: number): void {
-    if (!this._shuffleEnabled || count <= 0) return
-    this.shuffleOrder = this.shuffleOrder.map((idx) =>
-      idx >= at ? idx + count : idx
-    )
-    for (let i = 0; i < count; i++) {
-      const pos = Math.floor(Math.random() * (this.shuffleOrder.length + 1))
-      this.shuffleOrder.splice(pos, 0, at + i)
-    }
-  }
-
-  /** Drops removed indices and shifts the survivors down past them. */
-  private shuffleOrderRemove(removed: Set<number>): void {
-    if (!this._shuffleEnabled || removed.size === 0) return
-    const sorted = [...removed].sort((a, b) => a - b)
-    this.shuffleOrder = this.shuffleOrder
-      .filter((idx) => !removed.has(idx))
-      .map((idx) => idx - sorted.filter((r) => r < idx).length)
-  }
-
-  /** Remaps indices for a move, keeping every track's shuffle position. */
-  private shuffleOrderMove(fromIndex: number, toIndex: number): void {
-    if (!this._shuffleEnabled) return
-    this.shuffleOrder = this.shuffleOrder.map((idx) => {
-      if (idx === fromIndex) return toIndex
-      let adjusted = idx > fromIndex ? idx - 1 : idx
-      if (adjusted >= toIndex) adjusted += 1
-      return adjusted
-    })
-  }
-
-  // MARK: navigation
-
-  nextIndex(): number | undefined {
-    if (this._currentIndex === undefined) return undefined
-
-    if (!this._shuffleEnabled) {
-      const next = this._currentIndex + 1
-      return next >= this._tracks.length ? undefined : next
-    }
-
-    const pos = this.shuffleOrder.indexOf(this._currentIndex)
-    if (pos === -1) return undefined
-    const nextPos = pos + 1
-    return nextPos >= this.shuffleOrder.length
-      ? undefined
-      : this.shuffleOrder[nextPos]
-  }
-
-  previousIndex(): number | undefined {
-    if (this._currentIndex === undefined) return undefined
-
-    if (!this._shuffleEnabled) {
-      const prev = this._currentIndex - 1
-      return prev < 0 ? undefined : prev
-    }
-
-    const pos = this.shuffleOrder.indexOf(this._currentIndex)
-    if (pos === -1) return undefined
-    const prevPos = pos - 1
-    return prevPos < 0 ? undefined : this.shuffleOrder[prevPos]
-  }
-
-  wrapAroundFirstIndex(): number | undefined {
-    if (this._repeatMode !== RepeatMode.Queue) return undefined
-    return this._shuffleEnabled ? this.shuffleOrder[0] : 0
-  }
-
-  wrapAroundLastIndex(): number | undefined {
-    if (this._repeatMode !== RepeatMode.Queue) return undefined
-    return this._shuffleEnabled
-      ? this.shuffleOrder[this.shuffleOrder.length - 1]
-      : this._tracks.length - 1
-  }
-
-  // MARK: mutations
-
-  /** Inserts tracks at `insertBeforeIndex`, or appends when omitted/-1. */
-  insert(tracks: Track[], insertBeforeIndex?: number): void {
-    if (insertBeforeIndex !== -1 && insertBeforeIndex !== undefined) {
-      // Match Android/iOS, which throw here: a negative index other than the
-      // -1 sentinel would splice from the end and mis-shift the current
-      // pointer; past-the-end would silently append under a lying index.
-      if (insertBeforeIndex < 0 || insertBeforeIndex > this._tracks.length) {
-        throw new Error(
-          `insertBeforeIndex out of bounds: ${insertBeforeIndex} (use -1 to append)`
-        )
-      }
-      this._tracks.splice(insertBeforeIndex, 0, ...tracks)
-      // Keep the pointer on the same track (remove()/move() already do).
-      if (
-        this._currentIndex !== undefined &&
-        insertBeforeIndex <= this._currentIndex
-      ) {
-        this._currentIndex += tracks.length
-      }
-      this.shuffleOrderInsert(insertBeforeIndex, tracks.length)
-    } else {
-      this._tracks.push(...tracks)
-      this.shuffleOrderInsert(
-        this._tracks.length - tracks.length,
-        tracks.length
-      )
-    }
-  }
-
-  /**
-   * Removes the tracks at `indexes`, adjusting the current index. Returns what
-   * the caller must do for the current track (the queue itself never reloads).
-   */
-  remove(indexes: number[]): RemoveOutcome {
-    const idxSet = new Set(indexes)
-    const current = this._currentIndex
-    let removedBeforeCurrent = 0
-    let removedCurrent = false
-
-    this._tracks = this._tracks.filter((_track, idx) => {
-      if (!idxSet.has(idx)) return true
-      if (idx === current) removedCurrent = true
-      else if (current !== undefined && idx < current) removedBeforeCurrent++
-      return false
-    })
-    this.shuffleOrderRemove(idxSet)
-
-    if (current === undefined) return { kind: 'no-current' }
-
-    if (!removedCurrent) {
-      this._currentIndex = current - removedBeforeCurrent
-      return { kind: 'kept' }
-    }
-
-    if (this._tracks.length === 0) {
-      this._currentIndex = undefined
-      return { kind: 'emptied' }
-    }
-
-    // Reset so the caller's reload always loads the track at this position.
-    this._currentIndex = undefined
-    const adjusted = current - removedBeforeCurrent
-    // Wrap: removing the last-and-current track activates the first (the
-    // documented contract, matching iOS's modulo).
-    return { kind: 'reload', index: adjusted % this._tracks.length }
-  }
-
-  move(fromIndex: number, toIndex: number): void {
-    // Both ends are checked: an out-of-range destination would write a
-    // permanent out-of-range entry into the incrementally-maintained order.
-    const item = this._tracks[fromIndex]
-    if (item === undefined || toIndex < 0 || toIndex >= this._tracks.length) {
-      throw new Error('index out of bounds')
-    }
-
-    this._tracks.splice(fromIndex, 1)
-    this._tracks.splice(toIndex, 0, item)
-
-    // Track the current item's new position (matches Android's moveMediaItem).
-    const current = this._currentIndex
-    if (current !== undefined) {
-      if (fromIndex === current) this._currentIndex = toIndex
-      else if (fromIndex < current && toIndex >= current) {
-        this._currentIndex = current - 1
-      } else if (fromIndex > current && toIndex <= current) {
-        this._currentIndex = current + 1
-      }
-    }
-
-    this.shuffleOrderMove(fromIndex, toIndex)
-  }
-
-  /** Drops every track after the current one. */
-  removeUpcoming(): void {
-    if (this._currentIndex === undefined) return
-    const dropped = new Set<number>()
-    for (let i = this._currentIndex + 1; i < this._tracks.length; i++) {
-      dropped.add(i)
-    }
-    this._tracks = this._tracks.slice(0, this._currentIndex + 1)
-    this.shuffleOrderRemove(dropped)
-  }
-
-  /** Empties the queue and resets the index. */
-  clear(): void {
-    this._tracks = []
-    this._currentIndex = undefined
-    this._lastIndex = undefined
-    // Mutations maintain the order incrementally, so a stale order would
-    // survive the clear and corrupt the first post-clear insert.
-    this.shuffleOrder = []
-  }
-}

package/src/web/TrackPlayer/QueuePlayer.ts

@@ -1,188 +0,0 @@
-import type {
-  PlaybackState,
-  RepeatMode as RepeatModeType
-} from '../../features'
-import type { Track } from '../../types'
-import { Player } from './Player'
-import { QueueManager } from './QueueManager'
-import { RepeatMode } from './RepeatMode'
-import { State } from './State'
-
-/**
- * A {@link Player} with a play queue. Owns the *orchestration* — advancing the
- * queue on track end, loading the track when the index changes — while the
- * queue data and index math live in {@link QueueManager}.
- */
-export class QueuePlayer extends Player {
-  protected queue = new QueueManager()
-
-  protected applyState(state: PlaybackState) {
-    // A natural queue end exhausts the play intent — nothing is left to play.
-    // Keeping it set inverted togglePlayback (the first press after completion
-    // was a silent pause) and armed load()'s auto-play with phantom intent.
-    // Cleared before the state lands so consumers observe the native order
-    // (intent → state → queueEnded), independent of onQueueEnded overrides.
-    // Per-track ends that advance the queue keep the intent.
-    if (state === State.Ended && this.endsQueue()) {
-      this.playWhenReady = false
-    }
-
-    super.applyState(state)
-
-    // dispatch() already gates on _isStopped before reaching applyState, so a
-    // natural end while stopped never advances the queue.
-    if (state === State.Ended) {
-      this.onTrackEnded()
-    }
-  }
-
-  /** True when a natural end has nowhere to go: not repeating, no next track. */
-  private endsQueue(): boolean {
-    return (
-      this.queue.repeatMode !== RepeatMode.Track &&
-      this.queue.repeatMode !== RepeatMode.Queue &&
-      this.queue.nextIndex() === undefined
-    )
-  }
-
-  protected onTrackEnded() {
-    if (this.queue.repeatMode === RepeatMode.Track) {
-      if (this.queue.currentIndex !== undefined) {
-        this.goToIndex(this.queue.currentIndex)
-      }
-      return
-    }
-    if (this.endsQueue()) {
-      this.onQueueEnded()
-      return
-    }
-    this.skipToNext()
-  }
-
-  /**
-   * Notification hook for a natural queue end. The play intent is already
-   * cleared in {@link applyState} — this is purely for subclasses to react
-   * (e.g. emitting the queue-ended event).
-   */
-  protected onQueueEnded() {}
-
-  protected goToIndex(index: number, initialPosition?: number) {
-    const track = this.queue.getTrack(index)
-
-    if (!track) return
-
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    const onLoaded = (_track: Track) => {
-      if (initialPosition !== undefined) {
-        this.seekTo(initialPosition)
-      }
-    }
-
-    if (this.queue.currentIndex !== index) {
-      this.queue.currentIndex = index
-      this.load(track, onLoaded)
-    } else if (this._isStopped) {
-      // The element is unloaded while stopped — a bare seek does nothing.
-      this.load(track, onLoaded)
-    } else {
-      // Replay the same track - seek to start (or initialPosition if specified)
-      this.seekTo(initialPosition ?? 0)
-      if (this.playWhenReady) {
-        this.play()
-      }
-    }
-  }
-
-  public add(tracks: Track[], insertBeforeIndex?: number): void {
-    this.queue.insert(tracks, insertBeforeIndex)
-
-    if (this.queue.currentIndex === undefined) {
-      this.goToIndex(0)
-    }
-  }
-
-  public skip(index: number, initialPosition?: number): void {
-    if (this.queue.getTrack(index) === undefined) {
-      throw new Error('index out of bounds')
-    }
-
-    this.goToIndex(index, initialPosition)
-  }
-
-  public skipToNext(initialPosition?: number): void {
-    if (this.queue.currentIndex === undefined) return
-
-    const nextIndex =
-      this.queue.nextIndex() ?? this.queue.wrapAroundFirstIndex()
-    if (nextIndex === undefined) return
-
-    this.goToIndex(nextIndex, initialPosition)
-  }
-
-  public skipToPrevious(initialPosition?: number): void {
-    if (this.queue.currentIndex === undefined) return
-
-    const previousIndex =
-      this.queue.previousIndex() ?? this.queue.wrapAroundLastIndex()
-    if (previousIndex === undefined) return
-
-    this.goToIndex(previousIndex, initialPosition)
-  }
-
-  public setShuffleEnabled(enabled: boolean): void {
-    this.queue.setShuffleEnabled(enabled)
-  }
-
-  public getShuffleEnabled(): boolean {
-    return this.queue.shuffleEnabled
-  }
-
-  public getTrack(index: number): Track | undefined {
-    return this.queue.getTrack(index)
-  }
-
-  public setRepeatMode(mode: RepeatModeType): void {
-    this.queue.repeatMode = mode
-  }
-
-  public getRepeatMode(): RepeatModeType {
-    return this.queue.repeatMode
-  }
-
-  public remove(indexes: number[]): void {
-    const outcome = this.queue.remove(indexes)
-    switch (outcome.kind) {
-      case 'no-current':
-      case 'kept':
-        break
-      case 'reload':
-        this.goToIndex(outcome.index)
-        break
-      case 'emptied':
-        this.current = undefined
-        this.stop()
-        break
-    }
-  }
-
-  public stop(onComplete?: () => void): void {
-    super.stop(onComplete)
-  }
-
-  public reset(): void {
-    // Clear queue state synchronously so subsequent add()/load() calls
-    // see a clean slate. The async player.unload() in stop() can finish
-    // in the background — it only releases the Shaka source.
-    this.queue.clear()
-    this.current = undefined
-    this.stop()
-  }
-
-  public removeUpcomingTracks(): void {
-    this.queue.removeUpcoming()
-  }
-
-  public move(fromIndex: number, toIndex: number): void {
-    this.queue.move(fromIndex, toIndex)
-  }
-}

package/src/web/TrackPlayer/VolumeFader.ts

@@ -1,74 +0,0 @@
-/**
- * Ramps the player volume down over a duration (sleep-timer fade). The gain
- * follows a squared curve: loudness perception is logarithmic, so a linear
- * gain ramp sounds like a late cutoff rather than a fade.
- */
-export class VolumeFader {
-  private interval: NodeJS.Timeout | null = null
-
-  /**
-   * Volume captured when the fade started; restored after the fade resolves.
-   * Non-null from fade start until cancel/completion, even once the ramp has
-   * reached silence.
-   */
-  private preFadeVolume: number | null = null
-
-  constructor(
-    private getVolume: () => number,
-    private setVolume: (volume: number) => void
-  ) {}
-
-  get isActive(): boolean {
-    return this.preFadeVolume !== null
-  }
-
-  start(durationSeconds: number): void {
-    // If a fade is already running, keep its captured volume as the baseline —
-    // the current (partially faded) volume is not the value to restore.
-    const baseVolume = this.preFadeVolume ?? this.getVolume()
-    this.cancel(false)
-    this.preFadeVolume = baseVolume
-    if (durationSeconds <= 0) return
-
-    const startTime = Date.now()
-    this.interval = setInterval(() => {
-      const progress = Math.min(
-        1,
-        (Date.now() - startTime) / (durationSeconds * 1000)
-      )
-      this.setVolume(baseVolume * (1 - progress) ** 2)
-      if (progress >= 1 && this.interval !== null) {
-        clearInterval(this.interval)
-        this.interval = null
-      }
-    }, 50)
-  }
-
-  /**
-   * Stops the ramp. With `restoreVolume` the pre-fade volume is put back
-   * immediately (cancellation); without it the caller restores after pausing
-   * (completion path — restoring first would let full-volume audio slip out).
-   */
-  cancel(restoreVolume: boolean): void {
-    if (this.interval !== null) {
-      clearInterval(this.interval)
-      this.interval = null
-    }
-    const preFadeVolume = this.preFadeVolume
-    this.preFadeVolume = null
-    if (restoreVolume && preFadeVolume !== null) this.setVolume(preFadeVolume)
-  }
-
-  /**
-   * Resolves the fade around a halting action: stops the ramp, runs `halt`,
-   * then restores the pre-fade volume — in that order, because restoring
-   * before halting would let full-volume audio slip out. The restore is
-   * skipped when no fade was running.
-   */
-  resolve(halt: () => void): void {
-    const preFadeVolume = this.preFadeVolume
-    this.cancel(false)
-    halt()
-    if (preFadeVolume !== null) this.setVolume(preFadeVolume)
-  }
-}

package/src/web/browser/__tests__/layer-resolver.test.ts

@@ -1,69 +0,0 @@
-import { describe, it, expect, vi } from 'vitest'
-import type { HttpClient } from '../../http/HttpClient'
-import { BrowserManager } from '../BrowserManager'
-import { FavoriteManager } from '../FavoriteManager'
-import { NavigationErrorManager } from '../NavigationErrorManager'
-
-/**
- * Builds a BrowserManager wired to an HttpClient stub that always rejects.
- * Resolver invocation happens BEFORE the request fires, so call-count
- * assertions hold without any live network.
- */
-function makeManager(): BrowserManager {
-  const httpClient = {
-    executeRequest: vi.fn().mockRejectedValue(new Error('no network in test'))
-  } as unknown as HttpClient
-  return new BrowserManager(
-    httpClient,
-    new FavoriteManager(),
-    new NavigationErrorManager()
-  )
-}
-
-describe('BrowserManager layer resolver', () => {
-  it('invokes a resolver once per generation and reuses it across requests', async () => {
-    let calls = 0
-    const manager = makeManager()
-    manager.configuration = {
-      path: '/',
-      requestResolver: async () => {
-        calls += 1
-        return { baseUrl: 'https://api.example.com' }
-      }
-    }
-    await manager.navigatePath('/a')
-    await manager.navigatePath('/b')
-    expect(calls).toBe(1)
-  })
-
-  it('re-invokes the resolver after invalidateAllContent', async () => {
-    let calls = 0
-    const manager = makeManager()
-    manager.configuration = {
-      path: '/',
-      requestResolver: async () => {
-        calls += 1
-        return { baseUrl: 'https://api.example.com' }
-      }
-    }
-    await manager.navigatePath('/a')
-    expect(calls).toBe(1)
-    manager.invalidateAllContent()
-    await manager.navigatePath('/a')
-    expect(calls).toBe(2)
-  })
-
-  it('supports an async resolver and invokes it exactly once', async () => {
-    let calls = 0
-    const manager = makeManager()
-    manager.configuration = {
-      path: '/',
-      requestResolver: async () => {
-        calls += 1
-        return { baseUrl: 'https://api.example.com' }
-      }
-    }
-    await expect(manager.navigatePath('/a')).resolves.not.toThrow()
-    expect(calls).toBe(1)
-  })
-})

package/src/web/browser/assertBrowsePageShape.test.ts

@@ -1,27 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { assertBrowsePageShape } from './assertBrowsePageShape'
-
-describe('assertBrowsePageShape', () => {
-  it('passes a page object through unchanged', () => {
-    const page = { url: '/x', title: 'X', children: [] }
-    expect(assertBrowsePageShape(page, '/x')).toBe(page)
-  })
-
-  it('rejects a bare array with a shape hint', () => {
-    expect(() => assertBrowsePageShape([], '/x')).toThrow(
-      /page object .*children/
-    )
-  })
-
-  it('rejects non-object bodies', () => {
-    expect(() => assertBrowsePageShape('nope', '/x')).toThrow(
-      /Browse endpoint for "\/x" returned "nope"/
-    )
-  })
-
-  it('rejects null bodies', () => {
-    expect(() => assertBrowsePageShape(null, '/x')).toThrow(
-      /returned null.*page object/
-    )
-  })
-})

package/src/web/browser/assertBrowsePageShape.ts

@@ -1,27 +0,0 @@
-import type { ResolvedTrack } from '../../types'
-
-/**
- * Guards the cast of a browse endpoint's body to a page object. Catches the
- * most common shape mistake — returning a bare Track[] — with an actionable
- * message instead of a blank screen downstream. Browse, tabs, and search
- * endpoints all return the page shape; only `children`'s meaning differs.
- */
-export function assertBrowsePageShape(
-  response: unknown,
-  path: string
-): ResolvedTrack {
-  if (Array.isArray(response)) {
-    throw new Error(
-      `Browse endpoint for "${path}" returned a JSON array; expected a ` +
-        `page object { title, children?: Track[] }. Wrap the rows in a ` +
-        `\`children\` array.`
-    )
-  }
-  if (response === null || typeof response !== 'object') {
-    throw new Error(
-      `Browse endpoint for "${path}" returned ${JSON.stringify(response)}; ` +
-        `expected a page object { title, children?: Track[] }.`
-    )
-  }
-  return response as ResolvedTrack
-}