react-native-audio-browser 0.2.0-next.2 → 0.2.0-next.20

package/lib/module/utils/LazyNativeEmitter.js

@@ -1,23 +1,28 @@
 "use strict";
 
 /**
- * A lightweight event emitter that lazily bridges native callbacks to multiple JavaScript listeners.
+ * The subscription object behind the library's **discrete** events — the
+ * remote-control exports (`onRemotePlay`, `onRemoteSeek`, …) and other
+ * one-shot signals with no "current value" to cache. Subscribe with
+ * {@link addListener}; the returned function unsubscribes. The emitter is
+ * not callable itself.
  *
- * The native callback is only assigned when the first listener is added, making the emitter
- * creation lightweight with no side effects until actually used.
- *
- * Use this for optional/rare events like remote controls where most apps won't need to listen.
- * For critical state changes (playback, progress, etc.), use NativeEmitter instead to ensure
- * no events are missed.
+ * "Lazy" is an implementation detail you may notice in timing: the native
+ * side only starts delivering the event once the first listener is added.
+ * State that always has a current reading uses `NativeUpdatedValue`
+ * instead.
  *
  * @example
  * ```typescript
- * export const onRemotePlay = LazyEmitter.emitterize<void>(
- *   (cb) => (nativeBrowser.onRemotePlay = cb)
- * )
+ * import { onRemotePlay } from 'react-native-audio-browser'
+ *
+ * const unsubscribe = onRemotePlay.addListener(() => console.log('play'))
+ * // later:
+ * unsubscribe()
  * ```
  */
 export class LazyNativeEmitter {
+  /** @internal */
   constructor(setter) {
     this.setter = setter;
   }
@@ -31,6 +36,13 @@ export class LazyNativeEmitter {
     });
     return listeners;
   }
+
+  /**
+   * Subscribes to the event.
+   *
+   * @param callback - Invoked with each event
+   * @returns A function that removes the listener
+   */
   addListener(callback) {
     const listeners = this.getListeners();
     listeners.add(callback);
@@ -38,13 +50,15 @@ export class LazyNativeEmitter {
   }
 
   /**
-   * 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
+   * @internal
    */
   static emitterize(setter) {
-    const emitter = new LazyNativeEmitter(setter);
-    return callback => emitter.addListener(callback);
+    return new LazyNativeEmitter(setter);
   }
 }
 //# sourceMappingURL=LazyNativeEmitter.js.map

package/lib/module/utils/LazyNativeEmitter.js.map

@@ -1 +1 @@
-{"version":3,"names":["LazyNativeEmitter","constructor","setter","getListeners","listeners","Set","data","listener","addListener","callback","add","delete","emitterize","emitter"],"sourceRoot":"../../../src","sources":["utils/LazyNativeEmitter.ts"],"mappings":";;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMA,iBAAiB,CAAI;EAIhCC,WAAWA,CAACC,MAA6C,EAAE;IACzD,IAAI,CAACA,MAAM,GAAGA,MAAM;EACtB;EAEQC,YAAYA,CAAA,EAAqB;IACvC,IAAI,IAAI,CAACC,SAAS,EAAE,OAAO,IAAI,CAACA,SAAS;IACzC,MAAMA,SAAS,GAAI,IAAI,CAACA,SAAS,GAAG,IAAIC,GAAG,CAAC,CAAE;IAC9C,IAAI,CAACH,MAAM,CAAEI,IAAO,IAAK;MACvB,KAAK,MAAMC,QAAQ,IAAIH,SAAS,EAAE;QAChCG,QAAQ,CAACD,IAAI,CAAC;MAChB;IACF,CAAC,CAAC;IACF,OAAOF,SAAS;EAClB;EAEAI,WAAWA,CAACC,QAAqB,EAAc;IAC7C,MAAML,SAAS,GAAG,IAAI,CAACD,YAAY,CAAC,CAAC;IACrCC,SAAS,CAACM,GAAG,CAACD,QAAQ,CAAC;IACvB,OAAO,MAAML,SAAS,CAACO,MAAM,CAACF,QAAQ,CAAC;EACzC;;EAEA;AACF;AACA;AACA;AACA;EACE,OAAOG,UAAUA,CACfV,MAA6C,EACN;IACvC,MAAMW,OAAO,GAAG,IAAIb,iBAAiB,CAACE,MAAM,CAAC;IAC7C,OAAQO,QAAqB,IAAKI,OAAO,CAACL,WAAW,CAACC,QAAQ,CAAC;EACjE;AACF","ignoreList":[]}
+{"version":3,"names":["LazyNativeEmitter","constructor","setter","getListeners","listeners","Set","data","listener","addListener","callback","add","delete","emitterize"],"sourceRoot":"../../../src","sources":["utils/LazyNativeEmitter.ts"],"mappings":";;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMA,iBAAiB,CAAI;EAIhC;EACAC,WAAWA,CAACC,MAA6C,EAAE;IACzD,IAAI,CAACA,MAAM,GAAGA,MAAM;EACtB;EAEQC,YAAYA,CAAA,EAAqB;IACvC,IAAI,IAAI,CAACC,SAAS,EAAE,OAAO,IAAI,CAACA,SAAS;IACzC,MAAMA,SAAS,GAAI,IAAI,CAACA,SAAS,GAAG,IAAIC,GAAG,CAAC,CAAE;IAC9C,IAAI,CAACH,MAAM,CAAEI,IAAO,IAAK;MACvB,KAAK,MAAMC,QAAQ,IAAIH,SAAS,EAAE;QAChCG,QAAQ,CAACD,IAAI,CAAC;MAChB;IACF,CAAC,CAAC;IACF,OAAOF,SAAS;EAClB;;EAEA;AACF;AACA;AACA;AACA;AACA;EACEI,WAAWA,CAACC,QAAqB,EAAc;IAC7C,MAAML,SAAS,GAAG,IAAI,CAACD,YAAY,CAAC,CAAC;IACrCC,SAAS,CAACM,GAAG,CAACD,QAAQ,CAAC;IACvB,OAAO,MAAML,SAAS,CAACO,MAAM,CAACF,QAAQ,CAAC;EACzC;;EAEA;AACF;AACA;AACA;AACA;AACA;AACA;AACA;EACE,OAAOG,UAAUA,CACfV,MAA6C,EACvB;IACtB,OAAO,IAAIF,iBAAiB,CAACE,MAAM,CAAC;EACtC;AACF","ignoreList":[]}

package/lib/module/utils/NativeUpdatedValue.js

@@ -1,29 +1,39 @@
 "use strict";
 
 /**
- * Bridges native value changes to JavaScript, storing the latest value for immediate access.
+ * The subscription object behind the library's **state** events — every
+ * `on<Thing>Changed`-style export (`onPlaybackChanged`, `onQueueChanged`, …)
+ * is one of these. Subscribe with {@link addListener}; the returned function
+ * unsubscribes. The emitter is not callable itself.
  *
- * Subscribes to native changes immediately at module load to ensure no updates are missed.
- * The `lastValue` property caches the most recent value, allowing hooks to read the current
- * state synchronously without calling a separate getter function.
- *
- * Use this for state-based values that have a "current value" (playback state, options, progress).
- * For discrete events without a current value (remote controls), use LazyNativeEmitter instead.
+ * It tracks a value that always has a *current* reading (playback state,
+ * progress, options): {@link lastValue} caches the most recent one so hooks —
+ * and you — can read it synchronously without a getter round-trip. Discrete
+ * events with no current value (remote-control presses) use
+ * `LazyNativeEmitter` instead.
  *
  * @example
  * ```typescript
- * export const onPlaybackChanged = NativeUpdatedValue.emitterize<Playback>(
- *   (cb) => (nativeBrowser.onPlaybackChanged = cb)
- * )
+ * import { onPlaybackChanged } from 'react-native-audio-browser'
  *
- * export function usePlayback(): Playback {
- *   return useUpdatedNativeValue(getPlayback, onPlaybackChanged)
- * }
+ * const unsubscribe = onPlaybackChanged.addListener((p) => {
+ *   console.log(p.state)
+ * })
+ * // later:
+ * unsubscribe()
  * ```
  */
 export class NativeUpdatedValue {
   listeners = new Set();
+
+  /**
+   * The most recent value delivered by native, or `undefined` before the
+   * first update. Subscription starts at module load, so this is safe to
+   * read synchronously at any time.
+   */
   lastValue = undefined;
+
+  /** @internal */
   constructor(setter) {
     // Install native callback immediately at module load
     setter(data => {
@@ -33,6 +43,13 @@ export class NativeUpdatedValue {
       }
     });
   }
+
+  /**
+   * Subscribes to value changes.
+   *
+   * @param callback - Invoked with each new value
+   * @returns A function that removes the listener
+   */
   addListener(callback) {
     this.listeners.add(callback);
     return () => this.listeners.delete(callback);
@@ -43,6 +60,7 @@ export class NativeUpdatedValue {
    *
    * @param setter - Function that sets the native callback property
    * @returns The subscription instance with lastValue and addListener
+   * @internal
    */
   static emitterize(setter) {
     return new NativeUpdatedValue(setter);

package/lib/module/utils/NativeUpdatedValue.js.map

@@ -1 +1 @@
-{"version":3,"names":["NativeUpdatedValue","listeners","Set","lastValue","undefined","constructor","setter","data","listener","addListener","callback","add","delete","emitterize"],"sourceRoot":"../../../src","sources":["utils/NativeUpdatedValue.ts"],"mappings":";;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMA,kBAAkB,CAAI;EACzBC,SAAS,GAAG,IAAIC,GAAG,CAAc,CAAC;EAC1CC,SAAS,GAAkBC,SAAS;EAEpCC,WAAWA,CAACC,MAA6C,EAAE;IACzD;IACAA,MAAM,CAAEC,IAAO,IAAK;MAClB,IAAI,CAACJ,SAAS,GAAGI,IAAI;MACrB,KAAK,MAAMC,QAAQ,IAAI,IAAI,CAACP,SAAS,EAAE;QACrCO,QAAQ,CAACD,IAAI,CAAC;MAChB;IACF,CAAC,CAAC;EACJ;EAEAE,WAAWA,CAACC,QAAqB,EAAc;IAC7C,IAAI,CAACT,SAAS,CAACU,GAAG,CAACD,QAAQ,CAAC;IAC5B,OAAO,MAAM,IAAI,CAACT,SAAS,CAACW,MAAM,CAACF,QAAQ,CAAC;EAC9C;;EAEA;AACF;AACA;AACA;AACA;AACA;EACE,OAAOG,UAAUA,CACfP,MAA6C,EACtB;IACvB,OAAO,IAAIN,kBAAkB,CAACM,MAAM,CAAC;EACvC;AACF","ignoreList":[]}
+{"version":3,"names":["NativeUpdatedValue","listeners","Set","lastValue","undefined","constructor","setter","data","listener","addListener","callback","add","delete","emitterize"],"sourceRoot":"../../../src","sources":["utils/NativeUpdatedValue.ts"],"mappings":";;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMA,kBAAkB,CAAI;EACzBC,SAAS,GAAG,IAAIC,GAAG,CAAc,CAAC;;EAE1C;AACF;AACA;AACA;AACA;EACEC,SAAS,GAAkBC,SAAS;;EAEpC;EACAC,WAAWA,CAACC,MAA6C,EAAE;IACzD;IACAA,MAAM,CAAEC,IAAO,IAAK;MAClB,IAAI,CAACJ,SAAS,GAAGI,IAAI;MACrB,KAAK,MAAMC,QAAQ,IAAI,IAAI,CAACP,SAAS,EAAE;QACrCO,QAAQ,CAACD,IAAI,CAAC;MAChB;IACF,CAAC,CAAC;EACJ;;EAEA;AACF;AACA;AACA;AACA;AACA;EACEE,WAAWA,CAACC,QAAqB,EAAc;IAC7C,IAAI,CAACT,SAAS,CAACU,GAAG,CAACD,QAAQ,CAAC;IAC5B,OAAO,MAAM,IAAI,CAACT,SAAS,CAACW,MAAM,CAACF,QAAQ,CAAC;EAC9C;;EAEA;AACF;AACA;AACA;AACA;AACA;AACA;EACE,OAAOG,UAAUA,CACfP,MAA6C,EACtB;IACvB,OAAO,IAAIN,kBAAkB,CAACM,MAAM,CAAC;EACvC;AACF","ignoreList":[]}

package/lib/module/utils/getTrackIdentity.js

@@ -0,0 +1,20 @@
+"use strict";
+
+/**
+ * A track's identity: its opaque `id` when present (non-blank), falling back
+ * to the playable `src`. Two tracks refer to the same item exactly when their
+ * identities are equal. Browsable-only tracks (neither `id` nor `src`) have
+ * no identity — they are addressed by their `path` instead.
+ *
+ * This is the same comparison the library uses everywhere it matches tracks:
+ * favorites (`setFavorites`), the CarPlay / Android Auto "now playing" row
+ * indicator, and queue expansion and in-place skipping when a track is
+ * selected from browse content. Use it for your own bookkeeping — keying a
+ * favorites collection, deduplicating history — so your comparisons agree
+ * with the library's.
+ */
+// Decision record: ADR 0008 (docs/adr/).
+export function getTrackIdentity(track) {
+  return track.id?.length ? track.id : track.src;
+}
+//# sourceMappingURL=getTrackIdentity.js.map

package/lib/module/utils/getTrackIdentity.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["getTrackIdentity","track","id","length","src"],"sourceRoot":"../../../src","sources":["utils/getTrackIdentity.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASA,gBAAgBA,CAACC,KAGhC,EAAsB;EACrB,OAAOA,KAAK,CAACC,EAAE,EAAEC,MAAM,GAAGF,KAAK,CAACC,EAAE,GAAGD,KAAK,CAACG,GAAG;AAChD","ignoreList":[]}

package/lib/module/utils/useNativeValueRefreshedBy.js

@@ -0,0 +1,29 @@
+"use strict";
+
+import { useEffect, useState } from 'react';
+/**
+ * Hook for a native-fetched value that must stay fresh across SEVERAL event
+ * sources — e.g. the active track, which changes on a queue transition
+ * (`onActiveTrackChanged`) but is also mutated in place by a favorite toggle
+ * (`onFavoriteChanged`).
+ *
+ * Unlike {@link useNativeUpdatedValue}, this never reads a cached event
+ * payload: every trigger re-reads `getter()`, and the mount effect re-reads
+ * once after the subscriptions attach (so an event firing between render and
+ * effect cannot be missed). The getters are cheap synchronous Nitro calls.
+ *
+ * @param getter - Synchronous native getter for the current value
+ * @param emitters - Event sources that invalidate the value (a stable,
+ *   module-level array — identity changes resubscribe)
+ */
+export function useNativeValueRefreshedBy(getter, emitters) {
+  const [value, setValue] = useState(getter);
+  useEffect(() => {
+    setValue(getter());
+    const cleanups = emitters.map(emitter => emitter.addListener(() => setValue(getter())));
+    return () => cleanups.forEach(cleanup => cleanup());
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [getter, ...emitters]);
+  return value;
+}
+//# sourceMappingURL=useNativeValueRefreshedBy.js.map

package/lib/module/utils/useNativeValueRefreshedBy.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useEffect","useState","useNativeValueRefreshedBy","getter","emitters","value","setValue","cleanups","map","emitter","addListener","forEach","cleanup"],"sourceRoot":"../../../src","sources":["utils/useNativeValueRefreshedBy.ts"],"mappings":";;AAAA,SAASA,SAAS,EAAEC,QAAQ,QAAQ,OAAO;AAM3C;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,yBAAyBA,CACvCC,MAAe,EACfC,QAAiC,EAC9B;EACH,MAAM,CAACC,KAAK,EAAEC,QAAQ,CAAC,GAAGL,QAAQ,CAACE,MAAM,CAAC;EAE1CH,SAAS,CAAC,MAAM;IACdM,QAAQ,CAACH,MAAM,CAAC,CAAC,CAAC;IAClB,MAAMI,QAAQ,GAAGH,QAAQ,CAACI,GAAG,CAAEC,OAAO,IACpCA,OAAO,CAACC,WAAW,CAAC,MAAMJ,QAAQ,CAACH,MAAM,CAAC,CAAC,CAAC,CAC9C,CAAC;IACD,OAAO,MAAMI,QAAQ,CAACI,OAAO,CAAEC,OAAO,IAAKA,OAAO,CAAC,CAAC,CAAC;IACrD;EACF,CAAC,EAAE,CAACT,MAAM,EAAE,GAAGC,QAAQ,CAAC,CAAC;EAEzB,OAAOC,KAAK;AACd","ignoreList":[]}