@reactor-team/js-sdk 3.0.1 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -155,10 +155,11 @@ declare class RecorderDisabledError extends ReactorError {
155
155
  }
156
156
 
157
157
  /**
158
- * Reference to a file uploaded via `Reactor.uploadFile()`. Pass it back as a
159
- * top-level value in `sendCommand()`'s `data` and it's extracted and sent as
160
- * a separate upload reference rather than embedded in the JSON payload —
161
- * see `extractFileRefs()`.
158
+ * Reference to a file uploaded via `Reactor.uploadFile()`. Pass it back in
159
+ * `sendCommand()`'s `data` wherever the model's schema declares a file: as a
160
+ * top-level value it's extracted and sent as a separate upload reference,
161
+ * and inside an array or object it's serialized as one — see
162
+ * `extractFileRefs()`.
162
163
  */
163
164
  declare class FileRef {
164
165
  readonly uploadId: string;
@@ -475,7 +476,7 @@ interface ReactorEventMap {
475
476
  * that want the binding's own identifier (e.g. for
476
477
  * `getTrackByMid`/`getStreamByMid`). */
477
478
  trackReceived: (name: string, track: MediaStreamTrack, stream: MediaStream, mid: string | undefined) => void;
478
- /** Fired every `STATS_INTERVAL_MS` while the session is "ready" — see
479
+ /** Fired every `LOCAL_STATS_INTERVAL_MS` while the session is "ready" — see
479
480
  * `getStats()`. */
480
481
  statsUpdate: (stats: ConnectionStats) => void;
481
482
  }
@@ -622,11 +623,14 @@ declare class Reactor implements Disposable {
622
623
  private capabilities;
623
624
  private stats;
624
625
  private connectionTimings;
625
- private statsPollHandle;
626
- /** Bumped on every `startStatsPolling()`/`stopStatsPolling()` call — lets an
627
- * in-flight `getStats()` recognize it's stale once it resolves, even if
628
- * `this.client` hasn't changed in the meantime. */
629
- private statsPollGeneration;
626
+ /** The stop functions of the running stats pollers — see `pollPeerStats()`. */
627
+ private stopStatsPollers;
628
+ /** Whether this connection has already reported its time to connect —
629
+ * a one-time fact, sent on the first client-stats report that carries it
630
+ * and omitted on every one after. Set only once a batch actually went out
631
+ * with it, so a batch sent before the timings exist doesn't use it up.
632
+ * Reset per `startStatsPolling()` call, i.e. per connect()/reconnect(). */
633
+ private hasSentConnectTime;
630
634
  /** Set on the "connecting" status transition, cleared once `connectionTimings`
631
635
  * is finalized on "ready" — see `handleStatusChanged()`. */
632
636
  private connectStartTime;
@@ -639,6 +643,43 @@ declare class Reactor implements Disposable {
639
643
  * take ownership of Rust value while it was borrowed") or corrupt it
640
644
  * outright. */
641
645
  private readonly queue;
646
+ /** In-flight calls to `withReaderAccess()` — a "reply" `.catch(() => {})`
647
+ * copy of each, never the caller's own promise, so one rejecting can't
648
+ * make `Promise.all()` in `withWriterAccess()` reject and skip waiting
649
+ * for the rest. See `withReaderAccess()`/`withWriterAccess()`. */
650
+ private readonly activeReads;
651
+ /** True for the span of a `withWriterAccess()` call — after it has waited
652
+ * out every read active when it started, before it releases the ones
653
+ * that arrived while it ran. */
654
+ private writerActive;
655
+ /** Readers parked in `withReaderAccess()`'s wait loop, woken once
656
+ * `withWriterAccess()` finishes; each re-checks `writerActive` rather
657
+ * than assuming its turn, since another writer already queued behind the
658
+ * first one may have claimed it first. */
659
+ private writerIdleWaiters;
660
+ /**
661
+ * Runs a read — sendCommand()/requestSchema()/requestClip()/
662
+ * requestRecording() — excluded from a lifecycle op (`withWriterAccess()`)
663
+ * but not from other reads: unlike `queue`, concurrent reads run
664
+ * concurrently. Queuing them the same way `queue` serializes writes would
665
+ * head-of-line block an unrelated command, or even disconnect() itself,
666
+ * behind one slow reply (the binding correlates replies independently, so
667
+ * nothing requires this to be serial).
668
+ *
669
+ * Race-free the same way the wasm binding's own `readyState` check is: the
670
+ * `writerActive` check and this call's registration in `activeReads` both
671
+ * happen before the first `await` inside *fn*, so nothing can run between
672
+ * them on a single-threaded JS event loop.
673
+ */
674
+ private withReaderAccess;
675
+ /**
676
+ * Runs a lifecycle op's client-touching body exclusively: waits out every
677
+ * read already in flight, then blocks new ones (`writerActive`) until it
678
+ * finishes. Only ever called from inside a `queue`-serialized task, so at
679
+ * most one writer runs this at a time — it doesn't serialize against
680
+ * itself, only against `activeReads`.
681
+ */
682
+ private withWriterAccess;
642
683
  constructor(options: ReactorOptions);
643
684
  /**
644
685
  * `jwt`, when given, replaces whatever `new Reactor({ jwt })` was given —
@@ -680,9 +721,11 @@ declare class Reactor implements Disposable {
680
721
  * mode) actually hands back `null` — normalized here so callers can rely
681
722
  * on the documented type instead of the binding's serialization quirk.
682
723
  *
683
- * A `FileRef` (from `uploadFile`) may be passed as a top-level value in
684
- * `data` alongside regular parameters — it is extracted and sent as a
685
- * separate upload reference rather than embedded in the JSON payload.
724
+ * A `FileRef` (from `uploadFile`) may be passed in `data` wherever the
725
+ * model's schema declares a file. As a top-level value it is extracted and
726
+ * sent as a separate upload reference rather than embedded in the JSON
727
+ * payload; inside an array or object (a parameter that takes several files,
728
+ * say) it is serialized as an upload reference in place.
686
729
  *
687
730
  * Unlike every other method here, this never rejects — a failure (the
688
731
  * session isn't `"ready"`, the send itself fails, …) is reported through
@@ -806,8 +849,9 @@ declare class Reactor implements Disposable {
806
849
  downloadClipAsFile(clip: Clip, filename?: string | null, options?: DownloadClipOptions): Promise<Blob>;
807
850
  /**
808
851
  * Uploads a file to the session's object store, resolving with a
809
- * `FileRef` to pass as a top-level value in a `sendCommand()`'s `data`
810
- * (see `extractFileRefs`). The binding itself takes `(file, name?)`
852
+ * `FileRef` to pass in a `sendCommand()`'s `data`, at the top level or
853
+ * inside an array or object (see `extractFileRefs`). The binding itself
854
+ * takes `(file, name?)`
811
855
  * positionally and already applies the right defaulting — a bare
812
856
  * `Blob`'s name falls back to `"upload"`, and an empty/missing mime type
813
857
  * to `"application/octet-stream"` — so there's nothing to wrap here.
@@ -856,7 +900,7 @@ declare class Reactor implements Disposable {
856
900
  * rejected call — whichever landed last. `undefined` until the first
857
901
  * failure. */
858
902
  getLastError(): ReactorError | undefined;
859
- /** The most recent WebRTC connection stats, polled every `STATS_INTERVAL_MS`
903
+ /** The most recent WebRTC connection stats, polled every `LOCAL_STATS_INTERVAL_MS`
860
904
  * while "ready" — see `statsUpdate`. `undefined` before the first sample. */
861
905
  getStats(): ConnectionStats | undefined;
862
906
  /** Timing breakdown from the most recent `connect()`/`reconnect()`
@@ -899,7 +943,24 @@ declare class Reactor implements Disposable {
899
943
  * → "ready" status sequence (see `ReactorStatus`), and starts/stops stats
900
944
  * polling around the "ready" window. */
901
945
  private handleStatusChanged;
946
+ /** Starts both stats pollers: the local one updates `getStats()` and emits
947
+ * `statsUpdate`, the runtime one sends a client-stats batch. Each owns the
948
+ * extractor it computes bitrates with, so a bitrate covers its own
949
+ * poller's interval. */
902
950
  private startStatsPolling;
951
+ /** Report one quality batch to the runtime: a reading per negotiated
952
+ * track — audio and video, sent and received — see
953
+ * `createTrackStatsExtractor`, and the connection-wide reading — see
954
+ * `toClientConnectionStat`. The connection reading goes even while no
955
+ * track has one yet (none negotiated onto a named track, or no codec
956
+ * reported yet), so the runtime gets the bandwidth estimate, the
957
+ * round-trip time and the time to connect without waiting on the tracks.
958
+ * Skipped only when there is nothing at all to say; one is due again in
959
+ * `RUNTIME_REPORT_INTERVAL_MS`. The time to connect goes on the first batch
960
+ * actually sent for this connection — see `hasSentConnectTime`.
961
+ * `sendClientStats` throws synchronously on a closing connection; caught
962
+ * here for the same reason `getStats()`'s rejection is above. */
963
+ private reportClientStats;
903
964
  private stopStatsPolling;
904
965
  /** Called on every `disconnect()` and on `[Symbol.dispose]`. Leaves
905
966
  * `client`/`schema` alone — that's `freeClient()`'s job, run separately
package/dist/index.d.ts CHANGED
@@ -155,10 +155,11 @@ declare class RecorderDisabledError extends ReactorError {
155
155
  }
156
156
 
157
157
  /**
158
- * Reference to a file uploaded via `Reactor.uploadFile()`. Pass it back as a
159
- * top-level value in `sendCommand()`'s `data` and it's extracted and sent as
160
- * a separate upload reference rather than embedded in the JSON payload —
161
- * see `extractFileRefs()`.
158
+ * Reference to a file uploaded via `Reactor.uploadFile()`. Pass it back in
159
+ * `sendCommand()`'s `data` wherever the model's schema declares a file: as a
160
+ * top-level value it's extracted and sent as a separate upload reference,
161
+ * and inside an array or object it's serialized as one — see
162
+ * `extractFileRefs()`.
162
163
  */
163
164
  declare class FileRef {
164
165
  readonly uploadId: string;
@@ -475,7 +476,7 @@ interface ReactorEventMap {
475
476
  * that want the binding's own identifier (e.g. for
476
477
  * `getTrackByMid`/`getStreamByMid`). */
477
478
  trackReceived: (name: string, track: MediaStreamTrack, stream: MediaStream, mid: string | undefined) => void;
478
- /** Fired every `STATS_INTERVAL_MS` while the session is "ready" — see
479
+ /** Fired every `LOCAL_STATS_INTERVAL_MS` while the session is "ready" — see
479
480
  * `getStats()`. */
480
481
  statsUpdate: (stats: ConnectionStats) => void;
481
482
  }
@@ -622,11 +623,14 @@ declare class Reactor implements Disposable {
622
623
  private capabilities;
623
624
  private stats;
624
625
  private connectionTimings;
625
- private statsPollHandle;
626
- /** Bumped on every `startStatsPolling()`/`stopStatsPolling()` call — lets an
627
- * in-flight `getStats()` recognize it's stale once it resolves, even if
628
- * `this.client` hasn't changed in the meantime. */
629
- private statsPollGeneration;
626
+ /** The stop functions of the running stats pollers — see `pollPeerStats()`. */
627
+ private stopStatsPollers;
628
+ /** Whether this connection has already reported its time to connect —
629
+ * a one-time fact, sent on the first client-stats report that carries it
630
+ * and omitted on every one after. Set only once a batch actually went out
631
+ * with it, so a batch sent before the timings exist doesn't use it up.
632
+ * Reset per `startStatsPolling()` call, i.e. per connect()/reconnect(). */
633
+ private hasSentConnectTime;
630
634
  /** Set on the "connecting" status transition, cleared once `connectionTimings`
631
635
  * is finalized on "ready" — see `handleStatusChanged()`. */
632
636
  private connectStartTime;
@@ -639,6 +643,43 @@ declare class Reactor implements Disposable {
639
643
  * take ownership of Rust value while it was borrowed") or corrupt it
640
644
  * outright. */
641
645
  private readonly queue;
646
+ /** In-flight calls to `withReaderAccess()` — a "reply" `.catch(() => {})`
647
+ * copy of each, never the caller's own promise, so one rejecting can't
648
+ * make `Promise.all()` in `withWriterAccess()` reject and skip waiting
649
+ * for the rest. See `withReaderAccess()`/`withWriterAccess()`. */
650
+ private readonly activeReads;
651
+ /** True for the span of a `withWriterAccess()` call — after it has waited
652
+ * out every read active when it started, before it releases the ones
653
+ * that arrived while it ran. */
654
+ private writerActive;
655
+ /** Readers parked in `withReaderAccess()`'s wait loop, woken once
656
+ * `withWriterAccess()` finishes; each re-checks `writerActive` rather
657
+ * than assuming its turn, since another writer already queued behind the
658
+ * first one may have claimed it first. */
659
+ private writerIdleWaiters;
660
+ /**
661
+ * Runs a read — sendCommand()/requestSchema()/requestClip()/
662
+ * requestRecording() — excluded from a lifecycle op (`withWriterAccess()`)
663
+ * but not from other reads: unlike `queue`, concurrent reads run
664
+ * concurrently. Queuing them the same way `queue` serializes writes would
665
+ * head-of-line block an unrelated command, or even disconnect() itself,
666
+ * behind one slow reply (the binding correlates replies independently, so
667
+ * nothing requires this to be serial).
668
+ *
669
+ * Race-free the same way the wasm binding's own `readyState` check is: the
670
+ * `writerActive` check and this call's registration in `activeReads` both
671
+ * happen before the first `await` inside *fn*, so nothing can run between
672
+ * them on a single-threaded JS event loop.
673
+ */
674
+ private withReaderAccess;
675
+ /**
676
+ * Runs a lifecycle op's client-touching body exclusively: waits out every
677
+ * read already in flight, then blocks new ones (`writerActive`) until it
678
+ * finishes. Only ever called from inside a `queue`-serialized task, so at
679
+ * most one writer runs this at a time — it doesn't serialize against
680
+ * itself, only against `activeReads`.
681
+ */
682
+ private withWriterAccess;
642
683
  constructor(options: ReactorOptions);
643
684
  /**
644
685
  * `jwt`, when given, replaces whatever `new Reactor({ jwt })` was given —
@@ -680,9 +721,11 @@ declare class Reactor implements Disposable {
680
721
  * mode) actually hands back `null` — normalized here so callers can rely
681
722
  * on the documented type instead of the binding's serialization quirk.
682
723
  *
683
- * A `FileRef` (from `uploadFile`) may be passed as a top-level value in
684
- * `data` alongside regular parameters — it is extracted and sent as a
685
- * separate upload reference rather than embedded in the JSON payload.
724
+ * A `FileRef` (from `uploadFile`) may be passed in `data` wherever the
725
+ * model's schema declares a file. As a top-level value it is extracted and
726
+ * sent as a separate upload reference rather than embedded in the JSON
727
+ * payload; inside an array or object (a parameter that takes several files,
728
+ * say) it is serialized as an upload reference in place.
686
729
  *
687
730
  * Unlike every other method here, this never rejects — a failure (the
688
731
  * session isn't `"ready"`, the send itself fails, …) is reported through
@@ -806,8 +849,9 @@ declare class Reactor implements Disposable {
806
849
  downloadClipAsFile(clip: Clip, filename?: string | null, options?: DownloadClipOptions): Promise<Blob>;
807
850
  /**
808
851
  * Uploads a file to the session's object store, resolving with a
809
- * `FileRef` to pass as a top-level value in a `sendCommand()`'s `data`
810
- * (see `extractFileRefs`). The binding itself takes `(file, name?)`
852
+ * `FileRef` to pass in a `sendCommand()`'s `data`, at the top level or
853
+ * inside an array or object (see `extractFileRefs`). The binding itself
854
+ * takes `(file, name?)`
811
855
  * positionally and already applies the right defaulting — a bare
812
856
  * `Blob`'s name falls back to `"upload"`, and an empty/missing mime type
813
857
  * to `"application/octet-stream"` — so there's nothing to wrap here.
@@ -856,7 +900,7 @@ declare class Reactor implements Disposable {
856
900
  * rejected call — whichever landed last. `undefined` until the first
857
901
  * failure. */
858
902
  getLastError(): ReactorError | undefined;
859
- /** The most recent WebRTC connection stats, polled every `STATS_INTERVAL_MS`
903
+ /** The most recent WebRTC connection stats, polled every `LOCAL_STATS_INTERVAL_MS`
860
904
  * while "ready" — see `statsUpdate`. `undefined` before the first sample. */
861
905
  getStats(): ConnectionStats | undefined;
862
906
  /** Timing breakdown from the most recent `connect()`/`reconnect()`
@@ -899,7 +943,24 @@ declare class Reactor implements Disposable {
899
943
  * → "ready" status sequence (see `ReactorStatus`), and starts/stops stats
900
944
  * polling around the "ready" window. */
901
945
  private handleStatusChanged;
946
+ /** Starts both stats pollers: the local one updates `getStats()` and emits
947
+ * `statsUpdate`, the runtime one sends a client-stats batch. Each owns the
948
+ * extractor it computes bitrates with, so a bitrate covers its own
949
+ * poller's interval. */
902
950
  private startStatsPolling;
951
+ /** Report one quality batch to the runtime: a reading per negotiated
952
+ * track — audio and video, sent and received — see
953
+ * `createTrackStatsExtractor`, and the connection-wide reading — see
954
+ * `toClientConnectionStat`. The connection reading goes even while no
955
+ * track has one yet (none negotiated onto a named track, or no codec
956
+ * reported yet), so the runtime gets the bandwidth estimate, the
957
+ * round-trip time and the time to connect without waiting on the tracks.
958
+ * Skipped only when there is nothing at all to say; one is due again in
959
+ * `RUNTIME_REPORT_INTERVAL_MS`. The time to connect goes on the first batch
960
+ * actually sent for this connection — see `hasSentConnectTime`.
961
+ * `sendClientStats` throws synchronously on a closing connection; caught
962
+ * here for the same reason `getStats()`'s rejection is above. */
963
+ private reportClientStats;
903
964
  private stopStatsPolling;
904
965
  /** Called on every `disconnect()` and on `[Symbol.dispose]`. Leaves
905
966
  * `client`/`schema` alone — that's `freeClient()`'s job, run separately