fix: media-stream-track param no longer optional (#31)

* fix: media-stream-track param no longer optional

* fix: re-added optional underlying track

* feat: protect against undefined underlying mediastreamtracks

* docs: re-added optional param in docs

* Feat/propagate track ended events (#33)

* feat: move static events object to parent track class

* feat: add track-ended event

* docs: updated docs

* fix: remove unnecessary option chain

* docs: updated event docs

* docs: made docs compatible with enum

src/local-track.ts

@@ -4,41 +4,32 @@ import { Track } from './track';
  * A wrapper around MediaStreamTrack.
  */
 export class LocalTrack extends Track {
-  static Events = {
-    TrackUpdate: 'track-update',
-  };
-
   /**
-   * Exchange the underlying track with a new track. Emit the `track-update` event to alert
-   * listeners to an update on a new track.
+   * Exchange the underlying track with a new track. If there is an existing track, stop it and emit
+   * the `track-update` event to alert listeners to an update on a new track.
    *
    * @param track - New underlying track.
    * @fires LocalTrack.Events.TrackUpdate
    */
   replaceUnderlyingTrack(track: MediaStreamTrack): void {
-    this.emit(LocalTrack.Events.TrackUpdate, this.getUnderlyingTrack().id, track);
-    this.getUnderlyingTrack().stop();
+    const underlyingTrack = this.getUnderlyingTrack();
+    if (underlyingTrack) {
+      this.emit(LocalTrack.Events.TrackUpdate, underlyingTrack.id, track);
+      underlyingTrack.stop();
+    }
+
     this.setUnderlyingTrack(track);
   }
 
   /**
-   * Sets the track to be enabled or disabled.
+   * If underlying track exists, sets it to be enabled or disabled.
    *
    * @param enabled - Whether the track should be enabled.
    */
   setEnabled(enabled: boolean): void {
-    this.getUnderlyingTrack().enabled = enabled;
-  }
-
-  /**
-   * Adds the callback handler to be notified of a track ending, this event occurs when the track
-   * will no longer provide data to the stream for any reason.
-   *
-   * Note: Handler will not fire when user calls stop().
-   *
-   * @param handler - The callback function to execute.
-   */
-  setOnEndedHandler(handler: () => void): void {
-    this.getUnderlyingTrack().onended = handler;
+    const underlyingTrack = this.getUnderlyingTrack();
+    if (underlyingTrack) {
+      underlyingTrack.enabled = enabled;
+    }
   }
 }

src/peer-connection.ts

@@ -1,6 +1,6 @@
+import { EventEmitter } from './event-emitter';
 import { LocalTrack } from './local-track';
 import { log } from './util/logger';
-import { EventEmitter } from './event-emitter';
 import { createRTCPeerConnection } from './rtc-peer-connection-factory';
 
 /**
@@ -38,12 +38,18 @@ class PeerConnection extends EventEmitter {
    * @param track - A LocalTrack object representing the media track to add to the peer connection.
    * @param streams - (Optional) One or more local MediaStream objects to which the track should be
    *     added.
-   * @returns The RTCRtpSender object which will be used to transmit the media data.
+   * @returns The RTCRtpSender object which will be used to transmit the media data, or null if
+   *     there is no underlying track when a track is added.
    * @listens LocalTrack.Events.TrackUpdate
    */
-  addTrack(track: LocalTrack, ...streams: MediaStream[]): RTCRtpSender {
-    track.on(LocalTrack.Events.TrackUpdate, this.handleTrackUpdate);
-    return this.pc.addTrack(track.getUnderlyingTrack(), ...streams);
+  addTrack(track: LocalTrack, ...streams: MediaStream[]): RTCRtpSender | null {
+    const underlyingTrack = track.getUnderlyingTrack();
+    if (underlyingTrack) {
+      track.on(LocalTrack.Events.TrackUpdate, this.handleTrackUpdate);
+      return this.pc.addTrack(underlyingTrack, ...streams);
+    }
+
+    return null;
   }
 
   /**

src/track.ts

@@ -4,28 +4,47 @@ import { EventEmitter } from './event-emitter';
  * Base Track class.
  */
 export abstract class Track extends EventEmitter {
+  /**
+   * Enum for Track Events.
+   *
+   * @readonly
+   * @enum {string}
+   */
+  static Events = {
+    /** Fired when a non-null or undefined underlying track is replaced. */
+    TrackUpdate: 'track-update',
+    /**
+     * Adds the callback handler to be notified of a track ending, this event occurs when the track
+     * will no longer provide data to the stream for any reason. Note: Handler will not fire when
+     * user calls stop() on the underlying track.
+     */
+    TrackEnded: 'track-ended',
+  };
+
   /**
    * The underlying MediaStreamTrack object.
    */
-  private track: MediaStreamTrack;
+  private track: MediaStreamTrack | undefined;
 
   /**
-   * Constructor for the Track class. Will create an empty MediaStreamTrack if one is not provided.
+   * Constructor for the Track class.
    *
    * @param track - (Optional) MediaStreamTrack.
    */
   constructor(track?: MediaStreamTrack) {
     super();
 
-    this.track = track || new MediaStreamTrack();
+    if (track) {
+      this.setUnderlyingTrack(track);
+    }
   }
 
   /**
    * Gets the underlying track.
    *
    * @returns The underlying track.
    */
-  getUnderlyingTrack(): MediaStreamTrack {
+  getUnderlyingTrack(): MediaStreamTrack | undefined {
     return this.track;
   }
 
@@ -35,6 +54,10 @@ export abstract class Track extends EventEmitter {
    * @param track - The new underlying track.
    */
   setUnderlyingTrack(track: MediaStreamTrack): void {
+    // eslint-disable-next-line no-param-reassign, jsdoc/require-jsdoc
+    track.onended = (ev: Event) => {
+      this.emit(Track.Events.TrackEnded, ev);
+    };
     this.track = track;
   }
 }