livekit-client 2.17.1 → 2.17.3

package/src/room/data-track/track.ts

@@ -0,0 +1,50 @@
+import type { DataTrackFrame } from './frame';
+import { type DataTrackHandle } from './handle';
+import type OutgoingDataTrackManager from './outgoing/OutgoingDataTrackManager';
+
+export type DataTrackSid = string;
+
+/** Information about a published data track. */
+export type DataTrackInfo = {
+  sid: DataTrackSid;
+  pubHandle: DataTrackHandle;
+  name: String;
+  usesE2ee: boolean;
+};
+
+export class LocalDataTrack {
+  info: DataTrackInfo;
+
+  protected manager: OutgoingDataTrackManager;
+
+  constructor(info: DataTrackInfo, manager: OutgoingDataTrackManager) {
+    this.info = info;
+    this.manager = manager;
+  }
+
+  /** The raw descriptor from the manager containing the internal state for this local track. */
+  protected get descriptor() {
+    return this.manager.getDescriptor(this.info.pubHandle);
+  }
+
+  isPublished() {
+    return this.descriptor?.type === 'active';
+  }
+
+  /** Try pushing a frame to subscribers of the track.
+   *
+   * Pushing a frame can fail for several reasons:
+   *
+   * - The track has been unpublished by the local participant or SFU
+   * - The room is no longer connected
+   */
+  tryPush(payload: DataTrackFrame['payload']) {
+    try {
+      return this.manager.tryProcessAndSend(this.info.pubHandle, payload);
+    } catch (err) {
+      // NOTE: wrapping in the bare try/catch like this means that the Throws<...> type doesn't
+      // propegate upwards into the public interface.
+      throw err;
+    }
+  }
+}

package/src/room/data-track/utils.test.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { WrapAroundUnsignedInt } from './utils';
+import { U16_MAX_SIZE, WrapAroundUnsignedInt } from './utils';
 
 describe('WrapAroundUnsignedInt', () => {
   it('should test initialization + edge cases', () => {
@@ -25,4 +25,30 @@ describe('WrapAroundUnsignedInt', () => {
     n.update((v) => v - 1);
     expect(n.value).toBe(65535);
   });
+
+  it.each([
+    // Happy path
+    [5, 10, true],
+    [10, 5, false],
+
+    // Equality cases
+    [0, 0, false],
+    [7, 7, false],
+    [U16_MAX_SIZE + 1, U16_MAX_SIZE + 1, false],
+
+    // Boundary cases
+    [0, 2, true],
+    [U16_MAX_SIZE - 1, U16_MAX_SIZE, true],
+
+    // Wraparound cases
+    [1, U16_MAX_SIZE + 1 /* wraps around to 0 */, false],
+    [U16_MAX_SIZE + 1 /* wraps around to 0 */, 5, true],
+    [2, (U16_MAX_SIZE + 1) * 5 + 3 /* wraps around to 3 */, true],
+    [(U16_MAX_SIZE + 1) * 5 + 3 /* wraps around to 3 */, 5, true],
+  ])('should ensure isBefore works', (first, second, result) => {
+    expect(
+      WrapAroundUnsignedInt.u16(first).isBefore(WrapAroundUnsignedInt.u16(second)),
+      `${first} isBefore ${second} != ${result}`,
+    ).toStrictEqual(result);
+  });
 });

package/src/room/data-track/utils.ts

@@ -1,4 +1,5 @@
 export const U16_MAX_SIZE = 0xffff;
+export const U32_MAX_SIZE = 0xffffffff;
 
 /**
  * A number of fields withing the data tracks packet specification assume wrap around behavior when
@@ -15,6 +16,10 @@ export class WrapAroundUnsignedInt<MaxSize extends number> {
     return new WrapAroundUnsignedInt(raw, U16_MAX_SIZE);
   }
 
+  static u32(raw: number) {
+    return new WrapAroundUnsignedInt(raw, U32_MAX_SIZE);
+  }
+
   constructor(raw: number, maxSize: MaxSize) {
     this.value = raw;
     if (raw < 0) {
@@ -42,31 +47,146 @@ export class WrapAroundUnsignedInt<MaxSize extends number> {
     }
   }
 
+  clone() {
+    return new WrapAroundUnsignedInt(this.value, this.maxSize);
+  }
+
   /** When called, maps the containing value to a new containing value. After mapping, the wrap
-   * around external max size bounds are applied. */
+   * around external max size bounds are applied. Note that this is a mutative operation. */
   update(updateFn: (value: number) => number) {
     this.value = updateFn(this.value);
     this.clamp();
   }
+
+  /** Increments the given `n` to the inner value. Note that this is a mutative operation. */
+  increment(n = 1) {
+    this.update((value) => value + n);
+  }
+
+  /** Decrements the given `n` from the inner value. Note that this is a mutative operation. */
+  decrement(n = 1) {
+    this.update((value) => value - n);
+  }
+
+  getThenIncrement() {
+    const previousValue = this.value;
+    this.increment();
+    return new WrapAroundUnsignedInt(previousValue, this.maxSize);
+  }
+
+  /** Returns true if {@link this} is before the passed other {@link WrapAroundUnsignedInt}. */
+  isBefore(other: WrapAroundUnsignedInt<MaxSize>) {
+    const a = this.value >>> 0;
+    const b = other.value >>> 0;
+    const diff = (b - a) >>> 0;
+    return diff !== 0 && diff < this.maxSize + 1;
+  }
 }
 
 export class DataTrackTimestamp<RateInHz extends number> {
   rateInHz: RateInHz;
 
-  timestamp: number;
+  timestamp: WrapAroundUnsignedInt<typeof U32_MAX_SIZE>;
 
   static fromRtpTicks(rtpTicks: number) {
     return new DataTrackTimestamp(rtpTicks, 90_000);
   }
 
-  asTicks() {
-    return this.timestamp;
+  /** Generates a timestamp initialized to a non cryptographically secure random value, so that
+   * different streams are more difficult to correlate in packet capture. */
+  static rtpRandom() {
+    const randomValue = Math.round(Math.random() * U32_MAX_SIZE);
+    return DataTrackTimestamp.fromRtpTicks(randomValue);
   }
 
   private constructor(raw: number, rateInHz: RateInHz) {
-    this.timestamp = raw;
+    this.timestamp = WrapAroundUnsignedInt.u32(raw);
+    this.rateInHz = rateInHz;
+  }
+
+  asTicks() {
+    return this.timestamp.value;
+  }
+
+  clone() {
+    return new DataTrackTimestamp(this.timestamp.value, this.rateInHz);
+  }
+
+  wrappingAdd(n: number) {
+    this.timestamp.increment(n);
+  }
+
+  /** Returns true if {@link this} is before the passed other {@link DataTrackTimestamp}. */
+  isBefore(other: DataTrackTimestamp<RateInHz>) {
+    return this.timestamp.isBefore(other.timestamp);
+  }
+}
+
+export class DataTrackClock<RateInHz extends number> {
+  epoch: Date;
+
+  base: DataTrackTimestamp<RateInHz>;
+
+  previous: DataTrackTimestamp<RateInHz>;
+
+  rateInHz: RateInHz;
+
+  private constructor(rateInHz: RateInHz, epoch: Date, base: DataTrackTimestamp<RateInHz>) {
+    this.epoch = epoch;
+    this.base = base;
+    this.previous = base.clone();
     this.rateInHz = rateInHz;
   }
+
+  static startingNow<RateInHz extends number>(
+    base: DataTrackTimestamp<RateInHz>,
+    rateInHz: RateInHz,
+  ) {
+    return new DataTrackClock(rateInHz, new Date(), base);
+  }
+
+  static startingAtTime<RateInHz extends number>(
+    epoch: Date,
+    base: DataTrackTimestamp<RateInHz>,
+    rateInHz: RateInHz,
+  ) {
+    return new DataTrackClock(rateInHz, epoch, base);
+  }
+
+  static rtpStartingNow(base: DataTrackTimestamp<90_000>) {
+    return DataTrackClock.startingNow(base, 90_000);
+  }
+
+  static rtpStartingAtTime(epoch: Date, base: DataTrackTimestamp<90_000>) {
+    return DataTrackClock.startingAtTime(epoch, base, 90_000);
+  }
+
+  now(): DataTrackTimestamp<RateInHz> {
+    return this.at(new Date());
+  }
+
+  at(timestamp: Date) {
+    let elapsedMs = timestamp.getTime() - this.epoch.getTime();
+    let durationTicks = DataTrackClock.durationInMsToTicks(elapsedMs, this.rateInHz);
+
+    let result = this.base.clone();
+    result.wrappingAdd(durationTicks);
+
+    // Enforce monotonicity in RTP wraparound space
+    if (result.isBefore(this.previous)) {
+      result = this.previous;
+    }
+    this.previous = result.clone();
+    return result.clone();
+  }
+
+  /** Convert a duration since the epoch into clock ticks. */
+  static durationInMsToTicks(durationMilliseconds: number, rateInHz: number) {
+    // round(nanos * rate_hz / 1e9)
+    let durationNanoseconds = durationMilliseconds * 1e6;
+    let ticks = (durationNanoseconds * rateInHz + 500_000_000) / 1_000_000_000;
+    return Math.round(ticks);
+  }
 }
 
 export function coerceToDataView<Input extends DataView | ArrayBuffer | Uint8Array>(

package/src/room/debounce.ts

@@ -0,0 +1,115 @@
+/**
+ * Originally from ts-debounce (https://github.com/chodorowicz/ts-debounce)
+ * with the following license:
+ *
+ * MIT License
+ *
+ * Copyright (c) 2017 Jakub Chodorowicz
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ * Modified to use CriticalTimers for reliable timer execution.
+ */
+/* eslint-disable @typescript-eslint/no-this-alias, @typescript-eslint/no-unused-expressions, @typescript-eslint/no-shadow */
+import CriticalTimers from './timers';
+
+export type Options<Result> = {
+  isImmediate?: boolean;
+  maxWait?: number;
+  callback?: (data: Result) => void;
+};
+
+export interface DebouncedFunction<Args extends any[], F extends (...args: Args) => any> {
+  (this: ThisParameterType<F>, ...args: Args & Parameters<F>): Promise<ReturnType<F>>;
+  cancel: (reason?: any) => void;
+}
+
+interface DebouncedPromise<FunctionReturn> {
+  resolve: (result: FunctionReturn) => void;
+  reject: (reason?: any) => void;
+}
+
+export function debounce<Args extends any[], F extends (...args: Args) => any>(
+  func: F,
+  waitMilliseconds = 50,
+  options: Options<ReturnType<F>> = {},
+): DebouncedFunction<Args, F> {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  const isImmediate = options.isImmediate ?? false;
+  const callback = options.callback ?? false;
+  const maxWait = options.maxWait;
+  let lastInvokeTime = Date.now();
+
+  let promises: DebouncedPromise<ReturnType<F>>[] = [];
+
+  function nextInvokeTimeout() {
+    if (maxWait !== undefined) {
+      const timeSinceLastInvocation = Date.now() - lastInvokeTime;
+
+      if (timeSinceLastInvocation + waitMilliseconds >= maxWait) {
+        return maxWait - timeSinceLastInvocation;
+      }
+    }
+
+    return waitMilliseconds;
+  }
+
+  const debouncedFunction = function (this: ThisParameterType<F>, ...args: Parameters<F>) {
+    const context = this;
+    return new Promise<ReturnType<F>>((resolve, reject) => {
+      const invokeFunction = function () {
+        timeoutId = undefined;
+        lastInvokeTime = Date.now();
+        if (!isImmediate) {
+          const result = func.apply(context, args);
+          callback && callback(result);
+          // biome-ignore lint/suspicious/useIterableCallbackReturn: vendored code
+          promises.forEach(({ resolve }) => resolve(result));
+          promises = [];
+        }
+      };
+
+      const shouldCallNow = isImmediate && timeoutId === undefined;
+
+      if (timeoutId !== undefined) {
+        CriticalTimers.clearTimeout(timeoutId);
+      }
+
+      timeoutId = CriticalTimers.setTimeout(invokeFunction, nextInvokeTimeout());
+
+      if (shouldCallNow) {
+        const result = func.apply(context, args);
+        callback && callback(result);
+        return resolve(result);
+      }
+      promises.push({ resolve, reject });
+    });
+  };
+
+  debouncedFunction.cancel = function (reason?: any) {
+    if (timeoutId !== undefined) {
+      CriticalTimers.clearTimeout(timeoutId);
+    }
+    // biome-ignore lint/suspicious/useIterableCallbackReturn: vendored code
+    promises.forEach(({ reject }) => reject(reason));
+    promises = [];
+  };
+
+  return debouncedFunction;
+}

package/src/room/events.ts

@@ -34,7 +34,7 @@ export enum RoomEvent {
 
   /**
    * When disconnected from room. This fires when room.disconnect() is called or
-   * when an unrecoverable connection issue had occured.
+   * when an unrecoverable connection issue had occurred.
    *
    * DisconnectReason can be used to determine why the participant was disconnected. Notable reasons are
    * - DUPLICATE_IDENTITY: another client with the same identity has joined the room

package/src/room/participant/LocalParticipant.ts

@@ -275,6 +275,8 @@ export default class LocalParticipant extends Participant {
 
   private handleClosing = () => {
     if (this.reconnectFuture) {
+      // @throws-transformer ignore - introduced due to adding Throws into Future, investigate this
+      // further
       this.reconnectFuture.promise.catch((e) => this.log.warn(e.message, this.logContext));
       this.reconnectFuture?.reject?.(new Error('Got disconnected during reconnection attempt'));
       this.reconnectFuture = undefined;

package/src/room/track/LocalAudioTrack.ts

@@ -3,7 +3,7 @@ import { TrackEvent } from '../events';
 import { computeBitrate, monitorFrequency } from '../stats';
 import type { AudioSenderStats } from '../stats';
 import type { LoggerOptions } from '../types';
-import { isReactNative, isWeb, unwrapConstraint } from '../utils';
+import { isReactNative, isWeb } from '../utils';
 import LocalTrack from './LocalTrack';
 import { Track } from './Track';
 import type { AudioCaptureOptions } from './options';
@@ -74,18 +74,15 @@ export default class LocalAudioTrack extends LocalTrack<Track.Kind.Audio> {
         return this;
       }
 
-      const deviceHasChanged =
-        this._constraints.deviceId &&
-        this._mediaStreamTrack.getSettings().deviceId !==
-          unwrapConstraint(this._constraints.deviceId);
-
       if (
         this.source === Track.Source.Microphone &&
-        (this.stopOnMute || this._mediaStreamTrack.readyState === 'ended' || deviceHasChanged) &&
+        (this.stopOnMute ||
+          this._mediaStreamTrack.readyState === 'ended' ||
+          this.pendingDeviceChange) &&
         !this.isUserProvided
       ) {
         this.log.debug('reacquiring mic track', this.logContext);
-        await this.restartTrack();
+        await this.restart(undefined, true);
       }
       await super.unmute();
 
@@ -106,8 +103,11 @@ export default class LocalAudioTrack extends LocalTrack<Track.Kind.Audio> {
     await this.restart(constraints);
   }
 
-  protected async restart(constraints?: MediaTrackConstraints): Promise<typeof this> {
-    const track = await super.restart(constraints);
+  protected async restart(
+    constraints?: MediaTrackConstraints,
+    isUnmuting?: boolean,
+  ): Promise<typeof this> {
+    const track = await super.restart(constraints, isUnmuting);
     this.checkForSilence();
     return track;
   }

package/src/room/track/LocalTrack.ts

@@ -1,7 +1,7 @@
 import { Mutex } from '@livekit/mutex';
-import { debounce } from 'ts-debounce';
 import { getBrowser } from '../../utils/browserParser';
 import DeviceManager from '../DeviceManager';
+import { debounce } from '../debounce';
 import { DeviceUnsupportedError, TrackInvalidError } from '../errors';
 import { TrackEvent } from '../events';
 import type { LoggerOptions } from '../types';
@@ -65,6 +65,8 @@ export default abstract class LocalTrack<
 
   protected trackChangeLock: Mutex;
 
+  protected pendingDeviceChange: boolean = false;
+
   /**
    *
    * @param mediaTrack
@@ -145,7 +147,11 @@ export default abstract class LocalTrack<
     return this._mediaStreamTrack.getSettings();
   }
 
-  private async setMediaStreamTrack(newTrack: MediaStreamTrack, force?: boolean) {
+  private async setMediaStreamTrack(
+    newTrack: MediaStreamTrack,
+    force?: boolean,
+    isUnmuting?: boolean,
+  ) {
     if (newTrack === this._mediaStreamTrack && !force) {
       return;
     }
@@ -202,7 +208,8 @@ export default abstract class LocalTrack<
     this._mediaStreamTrack = newTrack;
     if (newTrack) {
       // sync muted state with the enabled state of the newly provided track
-      this._mediaStreamTrack.enabled = !this.isMuted;
+      // if restarting as part of an unmute, set enabled to true directly to avoid mute cycling
+      this._mediaStreamTrack.enabled = isUnmuting ? true : !this.isMuted;
       // when a valid track is replace, we'd want to start producing
       await this.resumeUpstream();
       this.attachedElements.forEach((el) => {
@@ -246,6 +253,7 @@ export default abstract class LocalTrack<
     // when track is muted, underlying media stream track is stopped and
     // will be restarted later
     if (this.isMuted) {
+      this.pendingDeviceChange = true;
       return true;
     }
 
@@ -320,7 +328,7 @@ export default abstract class LocalTrack<
     }
   }
 
-  protected async restart(constraints?: MediaTrackConstraints) {
+  protected async restart(constraints?: MediaTrackConstraints, isUnmuting?: boolean) {
     this.manuallyStopped = false;
     const unlock = await this.trackChangeLock.lock();
 
@@ -363,8 +371,9 @@ export default abstract class LocalTrack<
       newTrack.addEventListener('ended', this.handleEnded);
       this.log.debug('re-acquired MediaStreamTrack', this.logContext);
 
-      await this.setMediaStreamTrack(newTrack);
+      await this.setMediaStreamTrack(newTrack, false, isUnmuting);
       this._constraints = constraints;
+      this.pendingDeviceChange = false;
       this.emit(TrackEvent.Restarted, this);
       if (this.manuallyStopped) {
         this.log.warn(

package/src/room/track/LocalVideoTrack.ts

@@ -168,7 +168,7 @@ export default class LocalVideoTrack extends LocalTrack<Track.Kind.Video> {
 
       if (this.source === Track.Source.Camera && !this.isUserProvided) {
         this.log.debug('reacquiring camera track', this.logContext);
-        await this.restartTrack();
+        await this.restart(undefined, true);
       }
       await super.unmute();
       return this;

package/src/room/track/RemoteVideoTrack.ts

@@ -1,4 +1,4 @@
-import { debounce } from 'ts-debounce';
+import { debounce } from '../debounce';
 import { TrackEvent } from '../events';
 import type { VideoReceiverStats } from '../stats';
 import { computeBitrate } from '../stats';

package/src/room/types.ts

@@ -1,5 +1,4 @@
 import type { DataStream_Chunk, Encryption_Type } from '@livekit/protocol';
-import type { Future } from './utils';
 
 export type SimulationOptions = {
   publish?: {
@@ -125,7 +124,6 @@ export interface StreamController<T extends DataStream_Chunk> {
   startTime: number;
   endTime?: number;
   sendingParticipantIdentity: string;
-  outOfBandFailureRejectingFuture: Future<never, Error>;
 }
 
 export interface BaseStreamInfo {

package/src/room/utils.ts

@@ -8,6 +8,7 @@ import {
 import TypedPromise from '../utils/TypedPromise';
 import { getBrowser } from '../utils/browserParser';
 import type { BrowserDetails } from '../utils/browserParser';
+import { type Throws } from '../utils/throws';
 import { protocolVersion, version } from '../version';
 import { type ConnectionError, ConnectionErrorReason } from './errors';
 import type LocalParticipant from './participant/LocalParticipant';
@@ -457,8 +458,12 @@ export function getStereoAudioStreamTrack() {
   return stereoTrack;
 }
 
+/** An object that represents a serialized version of a `new Promise((resolve, reject) => {})`
+ * constructor. Wait for a promise resolution with `await future.promise` and explicitly resolve or
+ * reject the inner promise with `future.resolve(...)` or `future.reject(...)`.
+ */
 export class Future<T, E extends Error> {
-  promise: Promise<T>;
+  promise: Promise<Throws<T, E>>;
 
   resolve?: (arg: T) => void;
 
@@ -486,7 +491,7 @@ export class Future<T, E extends Error> {
     }).finally(() => {
       this._isResolved = true;
       this.onFinally?.();
-    });
+    }) as Promise<Throws<T, E>>;
   }
 }
 

package/src/utils/subscribeToEvents.ts

@@ -0,0 +1,63 @@
+import { type EventMap } from 'typed-emitter';
+import type TypedEventEmitter from 'typed-emitter';
+import { Future } from '../room/utils';
+
+/** A test helper to listen to events received by an event emitter and allow them to be imperatively
+ * queried after the fact. */
+export function subscribeToEvents<
+  Callbacks extends EventMap,
+  EventNames extends keyof Callbacks = keyof Callbacks,
+>(eventEmitter: TypedEventEmitter<Callbacks>, eventNames: Array<EventNames>) {
+  const nextEventListeners = new Map<EventNames, Array<Future<unknown, never>>>(
+    eventNames.map((eventName) => [eventName, []]),
+  );
+  const buffers = new Map<EventNames, Array<unknown>>(
+    eventNames.map((eventName) => [eventName, []]),
+  );
+
+  const eventHandlers = eventNames.map((eventName) => {
+    const onEvent = ((event: unknown) => {
+      const listeners = nextEventListeners.get(eventName)!;
+      if (listeners.length > 0) {
+        for (const listener of listeners) {
+          listener.resolve?.(event);
+        }
+        nextEventListeners.set(eventName, []);
+      } else {
+        buffers.get(eventName)!.push(event);
+      }
+    }) as Callbacks[keyof Callbacks];
+    return [eventName, onEvent] as [keyof Callbacks, Callbacks[keyof Callbacks]];
+  });
+  for (const [eventName, onEvent] of eventHandlers) {
+    eventEmitter.on(eventName, onEvent);
+  }
+
+  return {
+    /** Listen for the next occurrance of an event to be emitted, or return the last event that was
+     * buffered (but hasn't been processed yet). */
+    async waitFor<
+      EventPayload extends Parameters<Callbacks[EventName]>[0],
+      EventName extends EventNames = EventNames,
+    >(eventName: EventName): Promise<EventPayload> {
+      // If an event is already buffered which hasn't been processed yet, pull that off the buffer
+      // and use it.
+      const earliestBufferedEvent = buffers.get(eventName)!.shift();
+      if (earliestBufferedEvent) {
+        return earliestBufferedEvent as EventPayload;
+      }
+
+      // Otherwise wait for the next event to come in.
+      const future = new Future<unknown, never>();
+      nextEventListeners.get(eventName)!.push(future);
+      const nextEvent = await future.promise;
+      return nextEvent as EventPayload;
+    },
+    /** Cleanup any lingering subscriptions. */
+    unsubscribe: () => {
+      for (const [eventName, onEvent] of eventHandlers) {
+        eventEmitter.off(eventName, onEvent);
+      }
+    },
+  };
+}

package/src/utils/throws.ts

@@ -1,3 +1,5 @@
+type Primitives = null | undefined | string | number | bigint | boolean | symbol;
+
 /**
  * Branded type that encodes possible thrown errors in the return type.
  *
@@ -11,7 +13,7 @@
  *
  * For more info about how this is checked, see ./throws-transformer at the root of this repo.
  */
-export type Throws<T, E extends Error> = T & { readonly __throws?: E };
+export type Throws<T, E extends Error> = (T & { readonly __throws?: E }) | Extract<T, Primitives>;
 
 /**
  * Extract the error types from a Throws type.