react-native-audio-browser 0.1.0 → 0.2.0-next.1

package/src/web/TrackPlayer/QueueManager.test.ts

@@ -0,0 +1,289 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type { Track } from '../../types'
+import { QueueManager } from './QueueManager'
+import { RepeatMode } from './RepeatMode'
+
+// Make shuffle deterministic (identity) so the shuffle-order navigation path is
+// assertable: shuffleOrder becomes [0,1,2,…] before the current-first swap.
+vi.mock('../util/shuffle', () => ({
+  fisherYatesShuffle: () => {}
+}))
+
+const tracks = (n: number): Track[] =>
+  Array.from({ length: n }, (_, i) => ({ src: `s${i}` }) as Track)
+
+describe('QueueManager', () => {
+  let q: QueueManager
+
+  beforeEach(() => {
+    q = new QueueManager()
+  })
+
+  describe('current index', () => {
+    it('tracks the previous index as lastIndex on set', () => {
+      q.currentIndex = 2
+      expect(q.lastIndex).toBeUndefined()
+      q.currentIndex = 5
+      expect(q.lastIndex).toBe(2)
+      expect(q.currentIndex).toBe(5)
+    })
+  })
+
+  describe('insert', () => {
+    it('adjusts currentIndex when inserting before the current track', () => {
+      q.setTracks(tracks(3))
+      q.currentIndex = 1
+
+      q.insert([{ src: 'x' } as Track], 0)
+
+      // The pointer must stay on the same track (remove()/move() already do
+      // this; native adjusts automatically).
+      expect(q.currentIndex).toBe(2)
+      expect(q.getTrack(q.currentIndex!)?.src).toBe('s1')
+    })
+
+    it('keeps currentIndex when inserting after the current track', () => {
+      q.setTracks(tracks(3))
+      q.currentIndex = 1
+
+      q.insert([{ src: 'x' } as Track], 2)
+
+      expect(q.currentIndex).toBe(1)
+    })
+
+    it('keeps currentIndex when appending', () => {
+      q.setTracks(tracks(3))
+      q.currentIndex = 1
+
+      q.insert([{ src: 'x' } as Track])
+
+      expect(q.currentIndex).toBe(1)
+    })
+  })
+
+  describe('sequential navigation', () => {
+    beforeEach(() => {
+      q.setTracks(tracks(3))
+      q.currentIndex = 0
+    })
+
+    it('advances and stops at the end (no wrap by default)', () => {
+      expect(q.nextIndex()).toBe(1)
+      q.currentIndex = 2
+      expect(q.nextIndex()).toBeUndefined()
+    })
+
+    it('goes back and stops at the start', () => {
+      q.currentIndex = 1
+      expect(q.previousIndex()).toBe(0)
+      q.currentIndex = 0
+      expect(q.previousIndex()).toBeUndefined()
+    })
+
+    it('returns undefined navigation when there is no current track', () => {
+      const empty = new QueueManager()
+      empty.setTracks(tracks(3))
+      expect(empty.nextIndex()).toBeUndefined()
+      expect(empty.previousIndex()).toBeUndefined()
+    })
+  })
+
+  describe('wrap-around (repeat playlist)', () => {
+    beforeEach(() => {
+      q.setTracks(tracks(3))
+      q.currentIndex = 2
+    })
+
+    it('only wraps when repeat mode is playlist', () => {
+      expect(q.wrapAroundFirstIndex()).toBeUndefined()
+      expect(q.wrapAroundLastIndex()).toBeUndefined()
+      q.repeatMode = RepeatMode.Queue
+      expect(q.wrapAroundFirstIndex()).toBe(0)
+      expect(q.wrapAroundLastIndex()).toBe(2)
+    })
+  })
+
+  describe('shuffle navigation', () => {
+    beforeEach(() => {
+      q.setTracks(tracks(4))
+      q.currentIndex = 0
+      q.setShuffleEnabled(true) // identity shuffle → order [0,1,2,3]
+    })
+
+    it('navigates along the shuffle order with the current track first', () => {
+      // current (0) is already at position 0, so order stays [0,1,2,3]
+      expect(q.nextIndex()).toBe(1)
+      q.currentIndex = 3
+      expect(q.nextIndex()).toBeUndefined()
+      expect(q.previousIndex()).toBe(2)
+    })
+
+    it('moves the current track to the front of the shuffle order on regen', () => {
+      q.currentIndex = 2
+      q.regenerateShuffleOrder()
+      // order was [0,1,2,3]; current (2) swapped to front → [2,1,0,3]
+      expect(q.previousIndex()).toBeUndefined()
+      expect(q.nextIndex()).toBe(1)
+    })
+
+    // Mutations maintain the shuffle order in place (matching iOS/ExoPlayer)
+    // instead of regenerating it — a regeneration erased the played history,
+    // leaving previous() dead after any add/remove/move.
+
+    it('keeps the shuffle history across an append', () => {
+      q.currentIndex = 2 // identity order [0,1,2,3], position 2
+      const random = vi.spyOn(Math, 'random').mockReturnValue(0.999)
+      try {
+        q.insert([{ src: 'x' } as Track]) // appended at the order's end
+      } finally {
+        random.mockRestore()
+      }
+      expect(q.previousIndex()).toBe(1)
+      expect(q.nextIndex()).toBe(3)
+    })
+
+    it('keeps the shuffle history across a remove of another track', () => {
+      q.currentIndex = 2
+      q.remove([0]) // order [0,1,2,3] → [0,1,2] with current now at index 1
+      expect(q.currentIndex).toBe(1)
+      expect(q.previousIndex()).toBe(0)
+      expect(q.nextIndex()).toBe(2)
+    })
+
+    it('does not let a stale order survive clear()', () => {
+      // Mutations no longer regenerate the order, so clear() must reset it —
+      // otherwise the first post-clear insert shifts a 4-entry ghost order.
+      q.clear()
+      q.insert(tracks(1))
+      q.currentIndex = 0
+      expect(q.previousIndex()).toBeUndefined()
+      expect(q.nextIndex()).toBeUndefined()
+    })
+
+    it('keeps every track at its shuffle position across a move', () => {
+      q.currentIndex = 1
+      q.move(1, 3) // tracks [s0,s2,s3,s1]; order remapped to [0,3,1,2]
+      expect(q.currentIndex).toBe(3)
+      expect(q.previousIndex()).toBe(0)
+      expect(q.nextIndex()).toBe(1)
+    })
+  })
+
+  describe('insert', () => {
+    it('appends when no insert index is given', () => {
+      q.setTracks(tracks(2))
+      q.insert(tracks(1))
+      expect(q.length).toBe(3)
+    })
+
+    it('splices at the given index', () => {
+      q.setTracks([{ src: 'a' }, { src: 'b' }] as Track[])
+      q.insert([{ src: 'x' }] as Track[], 1)
+      expect(q.tracks.map((t) => t.src)).toEqual(['a', 'x', 'b'])
+    })
+
+    it('throws on a negative index other than the -1 append sentinel', () => {
+      q.setTracks(tracks(3))
+      q.currentIndex = 1
+      // -2 used to splice from the end while still shifting the pointer,
+      // leaving currentIndex on a different track (native throws here).
+      expect(() => q.insert(tracks(1), -2)).toThrow('use -1 to append')
+      expect(q.currentIndex).toBe(1)
+      expect(q.length).toBe(3)
+    })
+
+    it('throws on a past-the-end index', () => {
+      q.setTracks(tracks(3))
+      expect(() => q.insert(tracks(1), 4)).toThrow('out of bounds')
+    })
+  })
+
+  describe('remove', () => {
+    beforeEach(() => {
+      q.setTracks(tracks(5)) // s0..s4
+      q.currentIndex = 2
+    })
+
+    it('keeps the current track, shifting its index down for removals before it', () => {
+      const result = q.remove([0])
+      expect(result).toEqual({ kind: 'kept' })
+      expect(q.currentIndex).toBe(1)
+    })
+
+    it('reports the index to reload when the current track is removed', () => {
+      const result = q.remove([2])
+      // index clamped into the shrunken queue; current reset so caller reloads
+      expect(result).toEqual({ kind: 'reload', index: 2 })
+      expect(q.currentIndex).toBeUndefined()
+    })
+
+    it('wraps to the first track when the current track was the last', () => {
+      const result = q.remove([4])
+      expect(result).toEqual({ kind: 'kept' })
+      q.currentIndex = 3 // now the last track
+      // Documented contract (and iOS behavior): removing the last-and-current
+      // track activates the first, not the new last.
+      expect(q.remove([3])).toEqual({ kind: 'reload', index: 0 })
+    })
+
+    it('reports emptied when the last remaining track is removed', () => {
+      q.setTracks(tracks(1))
+      q.currentIndex = 0
+      expect(q.remove([0])).toEqual({ kind: 'emptied' })
+    })
+
+    it('reports no-current when nothing is playing', () => {
+      const idle = new QueueManager()
+      idle.setTracks(tracks(3))
+      expect(idle.remove([0])).toEqual({ kind: 'no-current' })
+      expect(idle.length).toBe(2) // filter still applied
+    })
+  })
+
+  describe('move', () => {
+    beforeEach(() => {
+      q.setTracks(tracks(4)) // s0..s3
+    })
+
+    it('follows the current track to its new position', () => {
+      q.currentIndex = 1
+      q.move(1, 3)
+      expect(q.tracks.map((t) => t.src)).toEqual(['s0', 's2', 's3', 's1'])
+      expect(q.currentIndex).toBe(3)
+    })
+
+    it('shifts the current index when a track moves across it', () => {
+      q.currentIndex = 2
+      q.move(0, 3) // moving an earlier track past current shifts current down
+      expect(q.currentIndex).toBe(1)
+    })
+
+    it('throws on an out-of-bounds source index', () => {
+      expect(() => q.move(9, 0)).toThrow('index out of bounds')
+    })
+
+    it('throws on an out-of-bounds destination index', () => {
+      expect(() => q.move(0, 9)).toThrow('index out of bounds')
+      expect(() => q.move(0, -1)).toThrow('index out of bounds')
+    })
+  })
+
+  describe('removeUpcoming', () => {
+    it('drops everything after the current track', () => {
+      q.setTracks(tracks(5))
+      q.currentIndex = 1
+      q.removeUpcoming()
+      expect(q.tracks.map((t) => t.src)).toEqual(['s0', 's1'])
+    })
+  })
+
+  describe('clear', () => {
+    it('empties the queue and resets the index', () => {
+      q.setTracks(tracks(3))
+      q.currentIndex = 1
+      q.clear()
+      expect(q.length).toBe(0)
+      expect(q.currentIndex).toBeUndefined()
+    })
+  })
+})

package/src/web/TrackPlayer/QueueManager.ts

@@ -0,0 +1,302 @@
+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 = []
+  }
+}