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

package/src/features/sleepTimer.test.ts

@@ -0,0 +1,172 @@
+/** @vitest-environment happy-dom */
+
+import { renderHook, act, cleanup } from '@testing-library/react'
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import type { SleepTimer } from './sleepTimer'
+
+const native = vi.hoisted(() => ({
+  getSleepTimer: vi.fn<() => SleepTimer>(() => null),
+  // The single callback slot `NativeUpdatedValue` claims at module load.
+  onSleepTimerChanged: undefined as ((timer: SleepTimer) => void) | undefined
+}))
+
+vi.mock('../native', () => ({ nativeBrowser: native }))
+
+const { onSleepTimerChanged, useSleepTimer, useSleepTimerActive } =
+  await import('./sleepTimer')
+
+/** Push a value the way native would. */
+const fire = (timer: SleepTimer) =>
+  act(() => native.onSleepTimerChanged?.(timer))
+
+/**
+ * The emitter is a module-level singleton, so `lastValue` outlives each test.
+ * `undefined` is its pre-native state and distinct from `null`, which is a real
+ * value meaning "no timer" — the distinction the re-sync gate turns on.
+ */
+beforeEach(() => {
+  onSleepTimerChanged.lastValue = undefined
+  native.getSleepTimer.mockReturnValue(null)
+})
+afterEach(cleanup)
+
+describe('useSleepTimerActive', () => {
+  it('reads the getter when nothing has fired yet', () => {
+    native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+    const { result } = renderHook(() => useSleepTimerActive())
+    expect(result.current).toBe(true)
+  })
+
+  it('tracks timers being set and cleared', () => {
+    const { result } = renderHook(() => useSleepTimerActive())
+    expect(result.current).toBe(false)
+    fire({ time: Date.now() + 60_000 })
+    expect(result.current).toBe(true)
+    fire(null)
+    expect(result.current).toBe(false)
+  })
+
+  it('treats an end-of-track timer as active', () => {
+    const { result } = renderHook(() => useSleepTimerActive())
+    fire({ sleepWhenPlayedToEnd: true })
+    expect(result.current).toBe(true)
+  })
+
+  // The regression from f7a25040. The getter ran during render and saw a live
+  // timer; the clear landed before the effect subscribed. Without the re-sync
+  // the UI shows a running timer that is already gone — permanently, since
+  // nothing reads it again until the next native event.
+  it('re-syncs a clear that landed between the render read and the effect', () => {
+    native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+    onSleepTimerChanged.lastValue = null
+    const { result } = renderHook(() => useSleepTimerActive())
+    expect(result.current).toBe(false)
+  })
+
+  // The gate is `!== undefined`, not truthiness: `undefined` means native has
+  // never spoken, so the getter's answer must stand.
+  it('keeps the getter value when native has not fired at all', () => {
+    native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+    const { result } = renderHook(() => useSleepTimerActive())
+    expect(result.current).toBe(true)
+  })
+
+  it('stops tracking after unmount', () => {
+    const { result, unmount } = renderHook(() => useSleepTimerActive())
+    unmount()
+    fire({ time: Date.now() + 60_000 })
+    expect(result.current).toBe(false)
+  })
+})
+
+describe('useSleepTimer', () => {
+  it('is undefined when no timer is set', () => {
+    const { result } = renderHook(() => useSleepTimer())
+    expect(result.current).toBeUndefined()
+  })
+
+  it('reports secondsLeft for a time-based timer', () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(1_000_000_000_000)
+      native.getSleepTimer.mockReturnValue({ time: Date.now() + 30_000 })
+      const { result } = renderHook(() => useSleepTimer())
+      expect(result.current).toEqual({
+        time: 1_000_000_030_000,
+        secondsLeft: 30
+      })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('passes an end-of-track timer through without secondsLeft', () => {
+    const { result } = renderHook(() => useSleepTimer())
+    fire({ sleepWhenPlayedToEnd: true })
+    expect(result.current).toEqual({ sleepWhenPlayedToEnd: true })
+  })
+
+  it('counts down as time passes', () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(1_000_000_000_000)
+      native.getSleepTimer.mockReturnValue({ time: Date.now() + 5_000 })
+      const { result } = renderHook(() => useSleepTimer())
+      expect(result.current).toMatchObject({ secondsLeft: 5 })
+      act(() => {
+        vi.advanceTimersByTime(2_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 3 })
+      act(() => {
+        vi.advanceTimersByTime(3_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 0 })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('stops the countdown once it reaches zero', () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(1_000_000_000_000)
+      native.getSleepTimer.mockReturnValue({ time: Date.now() + 2_000 })
+      const { result } = renderHook(() => useSleepTimer())
+      act(() => {
+        vi.advanceTimersByTime(2_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 0 })
+      // Clamped at zero rather than running negative.
+      act(() => {
+        vi.advanceTimersByTime(10_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 0 })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('does not tick while inactive', () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(1_000_000_000_000)
+      native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+      const { result } = renderHook(() => useSleepTimer({ inactive: true }))
+      expect(result.current).toMatchObject({ secondsLeft: 60 })
+      act(() => {
+        vi.advanceTimersByTime(10_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 60 })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  // Same race as useSleepTimerActive, and the reason both hooks carry the gate.
+  it('re-syncs a clear that landed between the render read and the effect', () => {
+    native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+    onSleepTimerChanged.lastValue = null
+    const { result } = renderHook(() => useSleepTimer())
+    expect(result.current).toBeUndefined()
+  })
+})

package/src/features/sleepTimer.ts

@@ -86,7 +86,7 @@ export function clearSleepTimer(): boolean {
 /**
  * Subscribes to sleep timer changes.
  * @param callback - Called when the sleep timer state changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onSleepTimerChanged = NativeUpdatedValue.emitterize<SleepTimer>(
   (cb) => (nativeBrowser.onSleepTimerChanged = cb)
@@ -104,6 +104,11 @@ export function useSleepTimerActive(): boolean {
   const [isActive, setIsActive] = useState(() => getSleepTimer() !== null)
 
   useEffect(() => {
+    // Re-sync before subscribing: a change between the initial read above and this effect would
+    // otherwise be missed for good. `undefined` means nothing has fired yet, whereas `null` is a
+    // real value — the timer being cleared — so it has to re-sync too.
+    const { lastValue } = onSleepTimerChanged
+    if (lastValue !== undefined) setIsActive(lastValue !== null)
     return onSleepTimerChanged.addListener((timer) => {
       setIsActive(timer !== null)
     })
@@ -137,6 +142,9 @@ export function useSleepTimer(params?: {
   const time = state && 'time' in state ? state.time : undefined
 
   useEffect(() => {
+    // Re-sync before subscribing — see useSleepTimerActive.
+    const { lastValue } = onSleepTimerChanged
+    if (lastValue !== undefined) setState(addSecondsLeft(lastValue))
     return onSleepTimerChanged.addListener((event) => {
       setState(addSecondsLeft(event))
     })

package/src/public-surface.test.ts

@@ -0,0 +1,107 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { describe, it, expect } from 'vitest'
+
+/**
+ * Guard on what `import { … } from 'react-native-audio-browser'` can reach.
+ *
+ * `@internal` hides a value from the published types but not from the bundle:
+ * Metro resolves `"react-native": "src/index"` and compiles the source, where
+ * `stripInternal` never ran. Types are exempt — they have no runtime form.
+ * `CLAUDE.md` in this directory has the full rule.
+ */
+const SRC = join(process.cwd(), 'src')
+const ENTRY = join(SRC, 'index.ts')
+
+const VALUE_KINDS = new Set([
+  'const',
+  'let',
+  'var',
+  'function',
+  'class',
+  'enum'
+])
+
+function resolveModule(fromFile: string, spec: string): string | undefined {
+  const base = resolve(dirname(fromFile), spec.replace(/\.tsx?$/, ''))
+  return [`${base}.ts`, `${base}.tsx`, join(base, 'index.ts')].find(existsSync)
+}
+
+interface Export {
+  name: string
+  file: string
+  internal: boolean
+}
+
+/** Walks the `export *` graph from `entry`, collecting every reachable value export. */
+function collectValueExports(entry: string): Export[] {
+  const found: Export[] = []
+  const seen = new Set<string>()
+
+  const visit = (file: string) => {
+    if (seen.has(file)) return
+    seen.add(file)
+    const source = readFileSync(file, 'utf8')
+
+    for (const [, spec] of source.matchAll(/^export \* from ['"](.+?)['"]/gm)) {
+      const target = resolveModule(file, spec!)
+      if (target) visit(target)
+    }
+
+    const declaration =
+      /^export (?:declare )?(?:async )?(?:abstract )?(const|let|var|function|class|enum) (\w+)/gm
+    for (const match of source.matchAll(declaration)) {
+      if (!VALUE_KINDS.has(match[1]!)) continue
+      // The JSDoc block, if any, is whatever sits directly above the export.
+      const preceding = source.slice(0, match.index)
+      const doc = /\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/.exec(preceding)?.[0] ?? ''
+      found.push({
+        name: match[2]!,
+        file: relative(SRC, file),
+        internal: /@internal\b/.test(doc)
+      })
+    }
+  }
+
+  visit(entry)
+  return found
+}
+
+describe('public surface', () => {
+  const exports = collectValueExports(ENTRY)
+
+  it('reaches the feature modules at all (the walker still works)', () => {
+    // Cheap canary: if the barrel structure changes shape and the walker stops
+    // resolving, every other assertion here would pass vacuously.
+    expect(exports.map((e) => e.name)).toContain('trackPlaybackTime')
+    expect(exports.length).toBeGreaterThan(100)
+  })
+
+  it('exposes no value marked @internal', () => {
+    const leaked = exports
+      .filter((e) => e.internal)
+      .map((e) => `${e.name}  (${e.file})`)
+    expect(
+      leaked,
+      'Reachable from the package root at runtime despite @internal. Move each ' +
+        'to a module the barrels skip, and import it directly:\n' +
+        leaked.join('\n')
+    ).toEqual([])
+  })
+
+  it('exposes no __-prefixed test hook', () => {
+    const hooks = exports
+      .filter((e) => e.name.startsWith('__'))
+      .map((e) => `${e.name}  (${e.file})`)
+    expect(
+      hooks,
+      'Test-only exports ship to consumers. Drive the unit through a seam it ' +
+        'already has — a mocked native slot, say:\n' +
+        hooks.join('\n')
+    ).toEqual([])
+  })
+
+  it('does not re-export the raw Nitro object', () => {
+    expect(exports.map((e) => e.name)).not.toContain('nativeBrowser')
+  })
+})

package/src/specs/audio-browser.nitro.ts

@@ -115,7 +115,7 @@ export interface AudioBrowser extends HybridObject<{
   tabs: Track[] | undefined
   navigatePath(path: string): void
   navigateTrack(track: Track): void
-  onSearch(query: string): Promise<Track[]>
+  search(query: string): Promise<Track[]>
   getContent(): ResolvedTrack | undefined
   onPathChanged: (path: string) => void
   onContentChanged: (content: ResolvedTrack | undefined) => void

package/src/test-utils/reactNativeStub.ts

@@ -0,0 +1,60 @@
+/**
+ * Stands in for `react-native` under vitest, via the alias in `vitest.config.ts`.
+ *
+ * Not a convenience: `react-native/index.js` is Flow-typed (`import typeof ...`)
+ * and Rollup cannot parse it, so any test that reaches a module importing from
+ * `'react-native'` fails to load at all. Jest consumers get this from
+ * `@react-native/jest-preset`; vitest has no equivalent.
+ *
+ * Keep it to the surface the library actually touches. Two symbols so far —
+ * `AppState` (usePolledProgress) and `Image.resolveAssetSource`. Anything a test
+ * needs to drive should get an explicit control here rather than a cast at the
+ * call site.
+ *
+ * @internal — never imported by production code, only aliased in by the runner.
+ */
+
+export type AppStateStatus = 'active' | 'background' | 'inactive'
+
+type ChangeListener = (status: AppStateStatus) => void
+
+const changeListeners = new Set<ChangeListener>()
+
+export const AppState = {
+  currentState: 'active' as AppStateStatus,
+
+  // `type` is widened to string so the guard stays live: real AppState also
+  // emits 'memoryWarning' and 'focus', and silently treating one of those as a
+  // 'change' subscription would be a confusing way to find out this stub is thin.
+  addEventListener(type: string, listener: ChangeListener) {
+    if (type !== 'change') throw new Error(`AppState stub: unhandled "${type}"`)
+    changeListeners.add(listener)
+    return { remove: () => changeListeners.delete(listener) }
+  }
+}
+
+/** Move the app to the foreground or background and notify subscribers. */
+export function setAppState(status: AppStateStatus): void {
+  AppState.currentState = status
+  // Deleting from a Set mid-iteration is safe, so a listener that removes itself
+  // during the callback needs no defensive copy.
+  for (const listener of changeListeners) listener(status)
+}
+
+/**
+ * Drop every subscription and return to the foreground. Call between tests —
+ * the stub is a module singleton, so state outlives an individual test.
+ */
+export function resetAppState(): void {
+  changeListeners.clear()
+  AppState.currentState = 'active'
+}
+
+/** Number of live `change` subscriptions, for asserting cleanup. */
+export function appStateListenerCount(): number {
+  return changeListeners.size
+}
+
+export const Image = {
+  resolveAssetSource: (source: unknown) => source
+}

package/src/utils/LazyNativeEmitter.ts

@@ -12,9 +12,11 @@ type Callback<T> = (arg: T) => void
  *
  * @example
  * ```typescript
- * export const onRemotePlay = LazyEmitter.emitterize<void>(
+ * export const onRemotePlay = LazyNativeEmitter.emitterize<void>(
  *   (cb) => (nativeBrowser.onRemotePlay = cb)
  * )
+ *
+ * const unsubscribe = onRemotePlay.addListener(() => console.log('play'))
  * ```
  */
 export class LazyNativeEmitter<T> {
@@ -43,14 +45,15 @@ export class LazyNativeEmitter<T> {
   }
 
   /**
-   * Creates a lazy emitter subscription function for a native callback.
+   * Creates a lazy emitter for a native callback.
+   *
    * @param setter - Function that sets the native callback property
-   * @returns A subscription function that returns an unsubscribe function
+   * @returns The emitter instance — subscribe with `addListener`, which returns
+   * an unsubscribe function
    */
   static emitterize<T>(
     setter: (callback: (data: T) => void) => void
-  ): (callback: Callback<T>) => () => void {
-    const emitter = new LazyNativeEmitter(setter)
-    return (callback: Callback<T>) => emitter.addListener(callback)
+  ): LazyNativeEmitter<T> {
+    return new LazyNativeEmitter(setter)
   }
 }

package/src/utils/useDebug.test.ts

@@ -0,0 +1,182 @@
+/** @vitest-environment happy-dom */
+
+import { renderHook, act, cleanup } from '@testing-library/react'
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+
+const native = vi.hoisted(() => {
+  const slots = new Map<string, (event: never) => void>()
+  return {
+    slots,
+    browser: new Proxy({} as Record<string, unknown>, {
+      get(target, prop: string) {
+        // Defaults have to be shaped, not undefined: useDebugState reads
+        // `playback.state`, `queue.map(...)` and `progress.position` directly.
+        target[prop] ??= vi.fn(() => defaults[prop])
+        return target[prop]
+      },
+      set(target, prop: string, value) {
+        if (typeof value === 'function') slots.set(prop, value)
+        target[prop] = value
+        return true
+      }
+    })
+  }
+})
+
+const defaults: Record<string, unknown> = {
+  getPlayback: { state: 'none' },
+  getQueue: [],
+  getProgress: { position: 0, duration: 0, buffered: 0 },
+  getOptions: {},
+  getPlayWhenReady: false,
+  getShuffle: false,
+  getRepeatMode: 'off',
+  getOnline: true
+}
+
+vi.mock('../native', () => ({ nativeBrowser: native.browser }))
+
+const { useDebug } = await import('./useDebug')
+
+const fire = (slot: string, event: unknown) =>
+  act(() => native.slots.get(slot)?.(event as never))
+
+let logSpy: ReturnType<typeof vi.spyOn>
+
+beforeEach(() => {
+  logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+  // Emitters and the log store are module singletons, so both the last value
+  // and the entries outlive a test. Pin a baseline rather than letting each
+  // test inherit whatever the previous one happened to fire.
+  fire('onOnlineChanged', true)
+  fire('onPlaybackProgressUpdated', { position: 0, duration: 0, buffered: 0 })
+  const { result, unmount } = renderHook(() => useDebug({ enabled: false }))
+  act(() => result.current.clear())
+  unmount()
+  logSpy.mockClear()
+})
+
+afterEach(() => {
+  cleanup()
+  logSpy.mockRestore()
+})
+
+describe('useDebug', () => {
+  it('records nothing while disabled', () => {
+    const { result } = renderHook(() => useDebug({ enabled: false }))
+    fire('onOnlineChanged', false)
+    expect(result.current.logs).toEqual([])
+    expect(logSpy).not.toHaveBeenCalled()
+  })
+
+  it('logs a single initial snapshot on mount', () => {
+    const { result } = renderHook(() => useDebug({ enabled: true }))
+    expect(result.current.logs).toHaveLength(1)
+    expect(result.current.logs[0]).toMatchObject({
+      type: 'initial',
+      elapsed: null
+    })
+    expect(result.current.logs[0]!.message).toContain('online: true')
+  })
+
+  it('logs a change entry naming the field that moved', () => {
+    const { result } = renderHook(() => useDebug({ enabled: true }))
+    fire('onOnlineChanged', false)
+
+    expect(result.current.logs).toHaveLength(2)
+    const entry = result.current.logs[1]!
+    expect(entry.type).toBe('change')
+    expect(entry.message).toContain('online')
+    expect(entry.message).toContain('old → true')
+    expect(entry.message).toContain('new → false')
+  })
+
+  it('logs nothing when a re-render changes no field', () => {
+    const { result } = renderHook(() => useDebug({ enabled: true }))
+    fire('onOnlineChanged', true) // already true
+    expect(result.current.logs).toHaveLength(1)
+  })
+
+  // Progress ticks every second; logging each one would bury every other event.
+  it('ignores position drift under two seconds but reports a real seek', () => {
+    const { result } = renderHook(() => useDebug({ enabled: true }))
+
+    fire('onPlaybackProgressUpdated', { position: 1, duration: 0, buffered: 0 })
+    expect(result.current.logs).toHaveLength(1)
+
+    fire('onPlaybackProgressUpdated', {
+      position: 30,
+      duration: 0,
+      buffered: 0
+    })
+    expect(result.current.logs).toHaveLength(2)
+    expect(result.current.logs[1]!.message).toContain('position')
+  })
+
+  it('clears on demand', () => {
+    const { result } = renderHook(() => useDebug({ enabled: true }))
+    fire('onOnlineChanged', false)
+    expect(result.current.logs.length).toBeGreaterThan(0)
+
+    act(() => result.current.clear())
+    expect(result.current.logs).toEqual([])
+  })
+
+  it('caps the history and keeps the newest entries', () => {
+    const { result } = renderHook(() => useDebug({ enabled: true }))
+    for (let i = 0; i < 120; i++) fire('onOnlineChanged', i % 2 === 0)
+
+    expect(result.current.logs).toHaveLength(100)
+    // 120 alternating flips after the initial snapshot: the last one set online
+    // to false (i = 119 is odd), so the newest entry is the tail, not the head.
+    expect(result.current.logs.at(-1)!.message).toContain('new → false')
+  })
+
+  describe('metadata logging', () => {
+    it('is off by default', () => {
+      const { result } = renderHook(() => useDebug({ enabled: true }))
+      fire('onTrackMetadata', { title: 'Song' })
+      expect(result.current.logs.filter((l) => l.type === 'metadata')).toEqual(
+        []
+      )
+    })
+
+    it('records track, timed and chapter events when enabled', () => {
+      const { result } = renderHook(() =>
+        useDebug({ enabled: true, metadata: true })
+      )
+
+      fire('onTrackMetadata', { title: 'Song', artist: null })
+      fire('onTimedMetadata', { title: 'Live' })
+      fire('onChapterMetadata', [{}, {}])
+
+      const entries = result.current.logs.filter((l) => l.type === 'metadata')
+      expect(entries).toHaveLength(3)
+      expect(entries[0]!.message).toContain('[track] title: "Song"')
+      // Null fields are dropped rather than printed as `artist: "null"`.
+      expect(entries[0]!.message).not.toContain('artist')
+      expect(entries[1]!.message).toContain('[timed]')
+      expect(entries[2]!.message).toContain('2 chapters')
+    })
+
+    it('stops recording metadata after unmount', () => {
+      const { result, unmount } = renderHook(() =>
+        useDebug({ enabled: true, metadata: true })
+      )
+      const before = result.current.logs.length
+      unmount()
+      fire('onTrackMetadata', { title: 'Song' })
+      expect(result.current.logs).toHaveLength(before)
+    })
+  })
+
+  it('falls back to __DEV__ when enabled is not given', () => {
+    ;(globalThis as { __DEV__?: boolean }).__DEV__ = false
+    try {
+      const { result } = renderHook(() => useDebug())
+      expect(result.current.logs).toEqual([])
+    } finally {
+      delete (globalThis as { __DEV__?: boolean }).__DEV__
+    }
+  })
+})