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

package/src/features/player/setup.ts

@@ -11,7 +11,7 @@ import type {
   UpdateOptions
 } from './options'
 import { nativeBrowser } from '../../native'
-import { validateIOSUpdateOptions } from './options'
+import { validateIOSUpdateOptions } from './validateOptions'
 
 /**
  * Parameters passed to the {@link FormatNowPlayingCallback}.

package/src/features/player/validateOptions.ts

@@ -0,0 +1,22 @@
+import type { IOSUpdateOptions } from './options'
+
+const MAX_CARPLAY_NOW_PLAYING_BUTTONS = 5
+
+/**
+ * Warns when more CarPlay now-playing buttons are configured than CarPlay renders.
+ * Shared by `updateOptions` and `setupPlayer` (both can carry `ios` options).
+ *
+ * Lives outside `options.ts` because `features/player/index.ts` re-exports that
+ * module wholesale: anything exported there joins the package's runtime surface,
+ * `@internal` or not. This file is imported directly by the two callers and by
+ * nothing in the barrel.
+ */
+export function validateIOSUpdateOptions(ios?: IOSUpdateOptions): void {
+  const buttons = ios?.carPlayNowPlayingButtons
+  if (buttons && buttons.length > MAX_CARPLAY_NOW_PLAYING_BUTTONS) {
+    console.warn(
+      `[react-native-audio-browser] ${buttons.length} CarPlay now-playing ` +
+        `buttons configured; CarPlay shows at most ${MAX_CARPLAY_NOW_PLAYING_BUTTONS}.`
+    )
+  }
+}

package/src/features/queue/activeTrack.ts

@@ -41,7 +41,7 @@ export function getActiveTrackIndex(): number | undefined {
 /**
  * Subscribes to active track change events.
  * @param callback - Called when the active track changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onActiveTrackChanged =
   NativeUpdatedValue.emitterize<PlaybackActiveTrackChangedEvent>(

package/src/features/queue/queue.ts

@@ -156,7 +156,7 @@ export function getQueue(): Track[] {
 /**
  * Subscribes to playback queue ended events.
  * @param callback - Called when playback has paused due to reaching the end of the queue
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onQueueEnded =
   NativeUpdatedValue.emitterize<PlaybackQueueEndedEvent>(
@@ -167,7 +167,7 @@ export const onQueueEnded =
  * Subscribes to queue change events.
  * Called when tracks are added, removed, reordered, or when track metadata changes.
  * @param callback - Called with the updated queue
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onQueueChanged = NativeUpdatedValue.emitterize<Track[]>(
   (cb) => (nativeBrowser.onPlaybackQueueChanged = cb)

package/src/features/queue/repeatMode.ts

@@ -40,7 +40,7 @@ export interface RepeatModeChangedEvent {
 /**
  * Subscribes to repeat mode changes.
  * @param callback - Called when repeat mode changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRepeatModeChanged =
   NativeUpdatedValue.emitterize<RepeatModeChangedEvent>(

package/src/features/queue/shuffle.ts

@@ -32,7 +32,7 @@ export function toggleShuffle(): void {
 /**
  * Subscribes to shuffle mode changes.
  * @param callback - Called when shuffle mode changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onShuffleChanged = NativeUpdatedValue.emitterize<boolean>(
   (cb) => (nativeBrowser.onPlaybackShuffleModeChanged = cb)

package/src/features/remoteControls.ts

@@ -53,90 +53,11 @@ export interface RemoteSkipEvent {
   index: number
 }
 
-// MARK: - Default Handlers
-
-// Install remote control handlers with default behavior immediately when module loads
-// Custom handlers can override the defaults using handleRemote* functions
-
-// Basic playback controls
-// AudioBrowser.onRemotePlay(() => {
-//   const customHandler = customHandlers.get('play')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     play()
-//   }
-// })
-
-// AudioBrowser.onRemotePause(() => {
-//   const customHandler = customHandlers.get('pause')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     pause()
-//   }
-// })
-
-// AudioBrowser.onRemoteNext(() => {
-//   const customHandler = customHandlers.get('next')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     skipToNext()
-//   }
-// })
-
-// AudioBrowser.onRemotePrevious(() => {
-//   const customHandler = customHandlers.get('previous')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     skipToPrevious()
-//   }
-// })
-
-// AudioBrowser.onRemoteStop(() => {
-//   const customHandler = customHandlers.get('stop')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     stop()
-//   }
-// })
-
-// // Seek controls
-// AudioBrowser.onRemoteSeek((event: any) => {
-//   const customHandler = customHandlers.get('seek')
-//   if (customHandler) {
-//     customHandler(event)
-//   } else {
-//     seekTo(event.position)
-//   }
-// })
-
-// AudioBrowser.onRemoteJumpForward((event: any) => {
-//   const customHandler = customHandlers.get('jumpForward')
-//   if (customHandler) {
-//     customHandler(event)
-//   } else {
-//     seekBy(event.interval)
-//   }
-// })
-
-// AudioBrowser.onRemoteJumpBackward((event: any) => {
-//   const customHandler = customHandlers.get('jumpBackward')
-//   if (customHandler) {
-//     customHandler(event)
-//   } else {
-//     seekBy(-event.interval)
-//   }
-// })
-
 // MARK: - Handler Override Functions
 //
 // Use these functions when you want to OVERRIDE the default remote control behavior.
 // These will replace the default handlers with your custom logic.
-// If you just want to listen to events for debugging/logging, use the onRemote* functions below.
+// If you just want to listen to events for debugging/logging, use the onRemote* emitters below.
 
 /**
  * Sets a custom handler for remote play events, overriding the default behavior.
@@ -210,7 +131,7 @@ export function handleRemoteJumpBackward(
 
 // MARK: - Event Callbacks (for listening/debugging only)
 //
-// Use these functions when you want to LISTEN to remote control events without overriding
+// Use these emitters when you want to LISTEN to remote control events without overriding
 // the default behavior. These are perfect for logging, analytics, or debugging.
 // Multiple listeners can be registered for the same event.
 // To override the default behavior, use the handleRemote* functions above.
@@ -218,7 +139,7 @@ export function handleRemoteJumpBackward(
 /**
  * Subscribes to remote jump backward events.
  * @param callback - Called when the user presses the jump backward button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteJumpBackward =
   LazyNativeEmitter.emitterize<RemoteJumpBackwardEvent>(
@@ -228,7 +149,7 @@ export const onRemoteJumpBackward =
 /**
  * Subscribes to remote jump forward events.
  * @param callback - Called when the user presses the jump forward button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteJumpForward =
   LazyNativeEmitter.emitterize<RemoteJumpForwardEvent>(
@@ -238,7 +159,7 @@ export const onRemoteJumpForward =
 /**
  * Subscribes to remote next events.
  * @param callback - Called when the user presses the next track button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteNext = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemoteNext = cb)
@@ -247,7 +168,7 @@ export const onRemoteNext = LazyNativeEmitter.emitterize<void>(
 /**
  * Subscribes to remote pause events.
  * @param callback - Called when the user presses the pause button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePause = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemotePause = cb)
@@ -256,7 +177,7 @@ export const onRemotePause = LazyNativeEmitter.emitterize<void>(
 /**
  * Subscribes to remote play events.
  * @param callback - Called when the user presses the play button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePlay = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemotePlay = cb)
@@ -265,7 +186,7 @@ export const onRemotePlay = LazyNativeEmitter.emitterize<void>(
 /**
  * Subscribes to remote play ID events (Android only).
  * @param callback - Called when the user selects a track from an external device
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePlayId = LazyNativeEmitter.emitterize<RemotePlayIdEvent>(
   (cb) => (nativeBrowser.onRemotePlayId = cb)
@@ -274,7 +195,7 @@ export const onRemotePlayId = LazyNativeEmitter.emitterize<RemotePlayIdEvent>(
 /**
  * Subscribes to remote play search events (Android only).
  * @param callback - Called when the user searches for a track (usually voice search)
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePlaySearch =
   LazyNativeEmitter.emitterize<RemotePlaySearchEvent>(
@@ -284,7 +205,7 @@ export const onRemotePlaySearch =
 /**
  * Subscribes to remote previous events.
  * @param callback - Called when the user presses the previous track button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePrevious = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemotePrevious = cb)
@@ -293,7 +214,7 @@ export const onRemotePrevious = LazyNativeEmitter.emitterize<void>(
 /**
  * Subscribes to remote seek events.
  * @param callback - Called when the user changes the position of the timeline
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteSeek = LazyNativeEmitter.emitterize<RemoteSeekEvent>(
   (cb) => (nativeBrowser.onRemoteSeek = cb)
@@ -302,7 +223,7 @@ export const onRemoteSeek = LazyNativeEmitter.emitterize<RemoteSeekEvent>(
 /**
  * Subscribes to remote skip events (Android only).
  * @param callback - Called when the user presses the skip button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteSkip = LazyNativeEmitter.emitterize<RemoteSkipEvent>(
   (cb) => (nativeBrowser.onRemoteSkip = cb)
@@ -311,7 +232,7 @@ export const onRemoteSkip = LazyNativeEmitter.emitterize<RemoteSkipEvent>(
 /**
  * Subscribes to remote stop events.
  * @param callback - Called when the user presses the stop button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteStop = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemoteStop = cb)

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)

package/src/public-surface.test.ts

@@ -0,0 +1,123 @@
+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.
+ *
+ * The package root is a chain of unfiltered `export *` barrels, so every
+ * `export` in every feature file joins the public surface by default — there is
+ * no gate to forget to pass, only one to forget to add.
+ *
+ * `@internal` alone does not keep a symbol private. It is honoured by
+ * `stripInternal` when generating `lib/typescript`, which is what a consumer's
+ * TypeScript sees — but React Native resolves `"react-native": "src/index"`, so
+ * Metro bundles the *source*, where nothing was stripped. An `@internal` value
+ * is therefore invisible to the type checker and fully reachable at runtime:
+ * `require('react-native-audio-browser').nativeBrowser` used to hand out the raw
+ * Nitro object, whose `on*` properties are the single callback slots the library's
+ * emitters own — assigning one unsubscribes every hook in the package.
+ *
+ * So: values marked `@internal` must not be reachable from the barrel at all.
+ * Move them to a module the barrel doesn't re-export (see
+ * `features/player/validateOptions.ts`) and import them directly. Types are
+ * exempt — they carry no runtime representation, and `stripInternal` genuinely
+ * removes them from the published `.d.ts`.
+ */
+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,
+      'These values are tagged @internal but are reachable from the package root ' +
+        'at runtime — stripInternal only hides them from the published types, and ' +
+        'Metro bundles src/. Move each to a module the barrels do not re-export ' +
+        '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 under test through ' +
+        'the seam it already has (a mocked native slot, say) instead:\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/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)
   }
 }