rx-player 3.28.0-dev.2022061700 → 3.28.0-dev.2022062700

package/src/core/decrypt/content_decryptor.ts

@@ -491,20 +491,13 @@ export default class ContentDecryptor extends EventEmitter<IContentDecryptorEven
               return;
           }
 
-          let linkedKeys;
-          if (sessionInfo.source === MediaKeySessionLoadingType.Created) {
-            // When the license has been fetched, there might be implicit key ids
-            // linked to the session depending on the `singleLicensePer` option.
-            linkedKeys = getFetchedLicenseKeysInfo(initializationData,
-                                                   options.singleLicensePer,
-                                                   evt.value.whitelistedKeyIds,
-                                                   evt.value.blacklistedKeyIDs);
-          } else {
-            // When the MediaKeySession is just a cached/persisted one, we don't
-            // have any concept of "implicit key id".
-            linkedKeys = { whitelisted: evt.value.whitelistedKeyIds,
-                           blacklisted: evt.value.blacklistedKeyIDs };
-          }
+          const linkedKeys = getKeyIdsLinkedToSession(
+            initializationData,
+            sessionInfo.record,
+            options.singleLicensePer,
+            sessionInfo.source === MediaKeySessionLoadingType.Created,
+            evt.value.whitelistedKeyIds,
+            evt.value.blacklistedKeyIDs);
 
           sessionInfo.record.associateKeyIds(linkedKeys.whitelisted);
           sessionInfo.record.associateKeyIds(linkedKeys.blacklisted);
@@ -1053,22 +1046,46 @@ interface IAttachedMediaKeysData {
 }
 
 /**
- * Returns information on all keys - explicit or implicit - that are linked to
- * a loaded license.
+ * Returns set of all usable and unusable keys - explicit or implicit - that are
+ * linked to a `MediaKeySession`.
  *
  * In the RxPlayer, there is a concept of "explicit" key ids, which are key ids
  * found in a license whose status can be known through the `keyStatuses`
  * property from a `MediaKeySession`, and of "implicit" key ids, which are key
  * ids which were expected to be in a fetched license, but apparently weren't.
- * @param {Object} initializationData
- * @param {string|undefined} singleLicensePer
- * @param {Array.<Uint8Array>} usableKeyIds
- * @param {Array.<Uint8Array>} unusableKeyIds
- * @returns {Object}
+ *
+ * @param {Object} initializationData - Initialization data object used to make
+ * the request for the current license.
+ * @param {Object} keySessionRecord - The `KeySessionRecord` associated with the
+ * session that has been loaded. It might give supplementary information on
+ * keys implicitly linked to the license.
+ * @param {string|undefined} singleLicensePer - Setting allowing to indicate the
+ * scope a given license should have.
+ * @param {boolean} isCurrentLicense - If `true` the license has been fetched
+ * especially for the current content.
+ *
+ * Knowing this allows to determine that if decryption keys that should have
+ * been referenced in the fetched license (according to the `singleLicensePer`
+ * setting) are missing, then the keys surely must have been voluntarly
+ * removed from the license.
+ *
+ * If it is however set to `false`, it means that the license is an older
+ * license that might have been linked to another content, thus we cannot make
+ * that assumption.
+ * @param {Array.<Uint8Array>} usableKeyIds - Key ids that are present in the
+ * license and can be used.
+ * @param {Array.<Uint8Array>} unusableKeyIds - Key ids that are present in the
+ * license yet cannot be used.
+ * @returns {Object} - Returns an object with the following properties:
+ *   - `whitelisted`: Array of key ids for keys that are known to be usable
+ *   - `blacklisted`: Array of key ids for keys that are considered unusable.
+ *     The qualities linked to those keys should not be played.
  */
-function getFetchedLicenseKeysInfo(
+function getKeyIdsLinkedToSession(
   initializationData : IProcessedProtectionData,
+  keySessionRecord : KeySessionRecord,
   singleLicensePer : undefined | "init-data" | "content" | "periods",
+  isCurrentLicense : boolean,
   usableKeyIds : Uint8Array[],
   unusableKeyIds : Uint8Array[]
 ) : { whitelisted : Uint8Array[];
@@ -1081,6 +1098,19 @@ function getFetchedLicenseKeysInfo(
   const associatedKeyIds = [...usableKeyIds,
                             ...unusableKeyIds];
 
+  // Add all key ids associated to the `KeySessionRecord` yet not in
+  // `usableKeyIds` nor in `unusableKeyIds`
+  const allKnownKeyIds = keySessionRecord.getAssociatedKeyIds();
+  for (const kid of allKnownKeyIds) {
+    if (!associatedKeyIds.some(ak => areKeyIdsEqual(ak, kid))) {
+      if (log.hasLevel("DEBUG")) {
+        log.debug("DRM: KeySessionRecord's key missing in the license, blacklisting it",
+                  bytesToHex(kid));
+      }
+      associatedKeyIds.push(kid);
+    }
+  }
+
   if (singleLicensePer !== undefined && singleLicensePer !== "init-data") {
     // We want to add the current key ids in the blacklist if it is
     // not already there.
@@ -1102,11 +1132,15 @@ function getFetchedLicenseKeysInfo(
         return !associatedKeyIds.some(k => areKeyIdsEqual(k, expected));
       });
       if (missingKeyIds.length > 0) {
+        if (log.hasLevel("DEBUG")) {
+          log.debug("DRM: init data keys missing in the license, blacklisting them",
+                    missingKeyIds.map(m => bytesToHex(m)).join(", "));
+        }
         associatedKeyIds.push(...missingKeyIds) ;
       }
     }
 
-    if (content !== undefined) {
+    if (isCurrentLicense && content !== undefined) {
       if (singleLicensePer === "content") {
         // Put it in a Set to automatically filter out duplicates (by ref)
         const contentKeys = new Set<Uint8Array>();

package/src/core/init/content_time_boundaries_observer.ts

@@ -73,7 +73,7 @@ export default function ContentTimeBoundariesObserver(
 
   // trigger warnings when the wanted time is before or after the manifest's
   // segments
-  const outOfManifest$ = playbackObserver.observe(true).pipe(
+  const outOfManifest$ = playbackObserver.getReference().asObservable().pipe(
     filterMap<IContentTimeObserverPlaybackObservation, IWarningEvent, null>((
       { position }
     ) => {

package/src/core/init/create_stream_playback_observer.ts

@@ -14,13 +14,11 @@
  * limitations under the License.
  */
 
-import {
-  combineLatest as observableCombineLatest,
-  map,
-  Observable,
-} from "rxjs";
 import Manifest from "../../manifest";
-import { IReadOnlySharedReference } from "../../utils/reference";
+import createSharedReference, {
+  IReadOnlySharedReference,
+} from "../../utils/reference";
+import { CancellationSignal } from "../../utils/task_canceller";
 import {
   IPlaybackObservation,
   IReadOnlyPlaybackObserver,
@@ -47,7 +45,7 @@ export interface IStreamPlaybackObserverArguments {
  * @param {Object} manifest
  * @param {Object} playbackObserver
  * @param {Object} args
- * @returns {Observable}
+ * @returns {Object}
  */
 export default function createStreamPlaybackObserver(
   manifest : Manifest,
@@ -58,47 +56,71 @@ export default function createStreamPlaybackObserver(
     speed,
     startTime } : IStreamPlaybackObserverArguments
 ) : IReadOnlyPlaybackObserver<IStreamOrchestratorPlaybackObservation> {
-  return playbackObserver.deriveReadOnlyObserver(function mapObservable(
-    observation$ : Observable<IPlaybackObservation>
-  ) : Observable<IStreamOrchestratorPlaybackObservation> {
-    return observableCombineLatest([observation$, speed.asObservable()]).pipe(
-      map(([observation, lastSpeed]) => {
-        let pendingPosition : number | undefined;
-        if (!initialSeekPerformed.getValue()) {
-          pendingPosition = startTime;
-        } else if (!manifest.isDynamic || manifest.isLastPeriodKnown) {
-          // HACK: When the position is actually further than the maximum
-          // position for a finished content, we actually want to be loading
-          // the last segment before ending.
-          // For now, this behavior is implicitely forced by making as if we
-          // want to seek one second before the period's end (despite never
-          // doing it).
-          const lastPeriod = manifest.periods[manifest.periods.length - 1];
-          if (lastPeriod !== undefined &&
-              lastPeriod.end !== undefined &&
-              observation.position > lastPeriod.end)
-          {
-            pendingPosition = lastPeriod.end - 1;
-          }
+  return playbackObserver.deriveReadOnlyObserver(function transform(
+    observationRef : IReadOnlySharedReference<IPlaybackObservation>,
+    cancellationSignal : CancellationSignal
+  ) : IReadOnlySharedReference<IStreamOrchestratorPlaybackObservation> {
+    const newRef = createSharedReference(constructStreamPlaybackObservation());
+
+    speed.onUpdate(emitStreamPlaybackObservation, {
+      clearSignal: cancellationSignal,
+      emitCurrentValue: false,
+    });
+
+    observationRef.onUpdate(emitStreamPlaybackObservation, {
+      clearSignal: cancellationSignal,
+      emitCurrentValue: false,
+    });
+
+    cancellationSignal.register(() => {
+      newRef.finish();
+    });
+
+    return newRef;
+
+    function constructStreamPlaybackObservation() {
+      const observation = observationRef.getValue();
+      const lastSpeed = speed.getValue();
+      let pendingPosition : number | undefined;
+      if (!initialSeekPerformed.getValue()) {
+        pendingPosition = startTime;
+      } else if (!manifest.isDynamic || manifest.isLastPeriodKnown) {
+        // HACK: When the position is actually further than the maximum
+        // position for a finished content, we actually want to be loading
+        // the last segment before ending.
+        // For now, this behavior is implicitely forced by making as if we
+        // want to seek one second before the period's end (despite never
+        // doing it).
+        const lastPeriod = manifest.periods[manifest.periods.length - 1];
+        if (lastPeriod !== undefined &&
+            lastPeriod.end !== undefined &&
+            observation.position > lastPeriod.end)
+        {
+          pendingPosition = lastPeriod.end - 1;
         }
+      }
+
+      return {
+        // TODO more exact according to the current Adaptation chosen?
+        maximumPosition: manifest.getMaximumSafePosition(),
+        position: {
+          last: observation.position,
+          pending: pendingPosition,
+        },
+        duration: observation.duration,
+        paused: {
+          last: observation.paused,
+          pending: initialPlayPerformed.getValue()  ? undefined :
+                   !autoPlay === observation.paused ? undefined :
+                                                      !autoPlay,
+        },
+        readyState: observation.readyState,
+        speed: lastSpeed,
+      };
+    }
 
-        return {
-          // TODO more exact according to the current Adaptation chosen?
-          maximumPosition: manifest.getMaximumSafePosition(),
-          position: {
-            last: observation.position,
-            pending: pendingPosition,
-          },
-          duration: observation.duration,
-          paused: {
-            last: observation.paused,
-            pending: initialPlayPerformed.getValue()  ? undefined :
-                     !autoPlay === observation.paused ? undefined :
-                                                        !autoPlay,
-          },
-          readyState: observation.readyState,
-          speed: lastSpeed,
-        };
-      }));
+    function emitStreamPlaybackObservation() {
+      newRef.setValue(constructStreamPlaybackObservation());
+    }
   });
 }

package/src/core/init/initial_seek_and_play.ts

@@ -83,7 +83,7 @@ export function waitUntilPlayable(
 
 /**
  * Try to play content then handle autoplay errors.
- * @param {HTMLMediaElement} - mediaElement
+ * @param {HTMLMediaElement} mediaElement
  * @returns {Observable}
  */
 function autoPlay(
@@ -161,12 +161,12 @@ export default function initialSeekAndPlay(
   const seekAndPlay$ = seek$.pipe(
     mergeMap(() : Observable<IWarningEvent | undefined> => {
       if (!shouldValidateMetadata() || mediaElement.duration > 0) {
-        return waitUntilPlayable(playbackObserver.observe(true));
+        return waitUntilPlayable(playbackObserver.getReference().asObservable());
       } else {
         const error = new MediaError("MEDIA_ERR_NOT_LOADED_METADATA",
                                      "Cannot load automatically: your browser " +
                                      "falsely announced having loaded the content.");
-        return waitUntilPlayable(playbackObserver.observe(true))
+        return waitUntilPlayable(playbackObserver.getReference().asObservable())
           .pipe(startWith(EVENTS.warning(error)));
       }
     }),

package/src/core/init/initialize_directfile.ts

@@ -158,7 +158,7 @@ export default function initializeDirectfileContent({
   // through a throwing Observable.
   const mediaError$ = throwOnMediaError(mediaElement);
 
-  const observation$ = playbackObserver.observe(true);
+  const observation$ = playbackObserver.getReference().asObservable();
 
   // Set the speed set by the user on the media element while pausing a
   // little longer while the buffer is empty.

package/src/core/init/load_on_media_source.ts

@@ -125,7 +125,7 @@ export default function createMediaSourceLoader(
                                                           startTime: initialTime,
                                                           mustAutoPlay: autoPlay });
 
-    const observation$ = playbackObserver.observe(true);
+    const observation$ = playbackObserver.getReference().asObservable();
     const streamEvents$ = initialPlayPerformed.asObservable().pipe(
       filter((hasPlayed) => hasPlayed),
       mergeMap(() => streamEventsEmitter(manifest, mediaElement, observation$)));

package/src/core/init/stall_avoider.ts

@@ -139,7 +139,7 @@ export default function StallAvoider(
    * order (first ordered by Period's start, then by bufferType in any order.
    */
   const discontinuitiesStore$ = discontinuityUpdate$.pipe(
-    withLatestFrom(playbackObserver.observe(true)),
+    withLatestFrom(playbackObserver.getReference().asObservable()),
     scan(
       (discontinuitiesStore, [evt, observation]) =>
         updateDiscontinuitiesStore(discontinuitiesStore, evt, observation),
@@ -179,7 +179,7 @@ export default function StallAvoider(
    * Period handled by that stream to unlock the situation.
    */
   const unlock$ = lockedStream$.pipe(
-    withLatestFrom(playbackObserver.observe(true)),
+    withLatestFrom(playbackObserver.getReference().asObservable()),
     tap(([lockedStreamEvt, observation]) => {
       // TODO(PaulB) also skip when the user's wanted speed is set to `0`, as we
       // might not want to seek in that case?
@@ -211,7 +211,7 @@ export default function StallAvoider(
     ignoreElements()
   );
 
-  const stall$ = playbackObserver.observe(true).pipe(
+  const stall$ = playbackObserver.getReference().asObservable().pipe(
     withLatestFrom(discontinuitiesStore$),
     map(([observation, discontinuitiesStore]) => {
       const { buffered,
@@ -279,12 +279,15 @@ export default function StallAvoider(
         if (ignoredStallTimeStamp === null) {
           ignoredStallTimeStamp = now;
         }
-        if (isSeekingApproximate &&
-            observation.position < lastSeekingPosition &&
-            now - ignoredStallTimeStamp < FORCE_DISCONTINUITY_SEEK_DELAY)
-        {
-          return { type: "stalled" as const,
-                   value: stalledReason };
+        if (isSeekingApproximate && observation.position < lastSeekingPosition) {
+          log.debug("Init: the device appeared to have seeked back by itself.");
+          if (now - ignoredStallTimeStamp < FORCE_DISCONTINUITY_SEEK_DELAY) {
+            return { type: "stalled" as const,
+                     value: stalledReason };
+          } else {
+            log.warn("Init: ignored stall for too long, checking discontinuity",
+                     now - ignoredStallTimeStamp);
+          }
         }
         lastSeekingPosition = null;
       }

package/src/core/stream/adaptation/create_representation_estimator.ts

@@ -70,12 +70,12 @@ export default function getRepresentationEstimate(
   updateRepresentationsReference();
   manifest.addEventListener("decipherabilityUpdate", updateRepresentationsReference);
   const unregisterCleanUp = cancellationSignal.register(cleanUp);
-  const [ estimateRef,
-          abrCallbacks ] = representationEstimator(content,
-                                                   currentRepresentation,
-                                                   representations,
-                                                   playbackObserver,
-                                                   cancellationSignal);
+  const { estimates: estimateRef,
+          callbacks: abrCallbacks } = representationEstimator(content,
+                                                              currentRepresentation,
+                                                              representations,
+                                                              playbackObserver,
+                                                              cancellationSignal);
   return { abrCallbacks, estimateRef };
 
   function updateRepresentationsReference() : void {

package/src/core/stream/orchestrator/stream_orchestrator.ts

@@ -142,7 +142,7 @@ export default function StreamOrchestrator(
                                 Infinity;
       return BufferGarbageCollector({
         segmentBuffer,
-        currentTime$: playbackObserver.observe(true)
+        currentTime$: playbackObserver.getReference().asObservable()
           .pipe(map(o => o.position.pending ?? o.position.last)),
         maxBufferBehind$: maxBufferBehind.asObservable().pipe(
           map(val => Math.min(val, defaultMaxBehind))),
@@ -264,7 +264,8 @@ export default function StreamOrchestrator(
 
     // Restart the current Stream when the wanted time is in another period
     // than the ones already considered
-    const restartStreamsWhenOutOfBounds$ = playbackObserver.observe(true).pipe(
+    const observation$ = playbackObserver.getReference().asObservable();
+    const restartStreamsWhenOutOfBounds$ = observation$.pipe(
       filterMap<
         IStreamOrchestratorPlaybackObservation,
         Period,
@@ -329,7 +330,7 @@ export default function StreamOrchestrator(
           // to reduce the risk of race conditions where the next observation
           // was going to be emitted synchronously.
           nextTickObs().pipe(ignoreElements()),
-          playbackObserver.observe(true).pipe(
+          playbackObserver.getReference().asObservable().pipe(
             take(1),
             mergeMap((observation) => {
               const shouldAutoPlay = !(observation.paused.pending ??
@@ -399,7 +400,7 @@ export default function StreamOrchestrator(
     const destroyNextStreams$ = new Subject<void>();
 
     // Emits when the current position goes over the end of the current Stream.
-    const endOfCurrentStream$ = playbackObserver.observe(true)
+    const endOfCurrentStream$ = playbackObserver.getReference().asObservable()
       .pipe(filter(({ position }) =>
         basePeriod.end != null &&
                     (position.pending ?? position.last) >= basePeriod.end));

package/src/core/stream/period/create_empty_adaptation_stream.ts

@@ -48,7 +48,7 @@ export default function createEmptyAdaptationStream(
   const { period } = content;
   let hasFinishedLoading = false;
   const wantedBufferAhead$ = wantedBufferAhead.asObservable();
-  const observation$ = playbackObserver.observe(true);
+  const observation$ = playbackObserver.getReference().asObservable();
   return observableCombineLatest([observation$,
                                   wantedBufferAhead$]).pipe(
     mergeMap(([observation, wba]) => {

package/src/core/stream/period/period_stream.ts

@@ -42,7 +42,10 @@ import Manifest, {
 import { IAudioTrackSwitchingMode } from "../../../public_types";
 import objectAssign from "../../../utils/object_assign";
 import { getLeftSizeOfRange } from "../../../utils/ranges";
-import { IReadOnlySharedReference } from "../../../utils/reference";
+import createSharedReference, {
+  IReadOnlySharedReference,
+} from "../../../utils/reference";
+import { CancellationSignal } from "../../../utils/task_canceller";
 import WeakMapMemory from "../../../utils/weak_map_memory";
 import { IRepresentationEstimator } from "../../adaptive";
 import { IReadOnlyPlaybackObserver } from "../../api";
@@ -357,18 +360,34 @@ function createAdaptationStreamPlaybackObserver(
   initialPlaybackObserver : IReadOnlyPlaybackObserver<IPeriodStreamPlaybackObservation>,
   segmentBuffer : SegmentBuffer
 ) : IReadOnlyPlaybackObserver<IAdaptationStreamPlaybackObservation> {
-  return initialPlaybackObserver.deriveReadOnlyObserver(
-    (observation$) => observation$.pipe(map(mapObservation)),
-    mapObservation
-  );
+  return initialPlaybackObserver.deriveReadOnlyObserver(function transform(
+    observationRef : IReadOnlySharedReference<IPeriodStreamPlaybackObservation>,
+    cancellationSignal : CancellationSignal
+  ) : IReadOnlySharedReference<IAdaptationStreamPlaybackObservation> {
+    const newRef = createSharedReference(constructAdaptationStreamPlaybackObservation());
+
+    observationRef.onUpdate(emitAdaptationStreamPlaybackObservation, {
+      clearSignal: cancellationSignal,
+      emitCurrentValue: false,
+    });
+
+    cancellationSignal.register(() => {
+      newRef.finish();
+    });
+
+    return newRef;
+
+    function constructAdaptationStreamPlaybackObservation(
+    ) : IAdaptationStreamPlaybackObservation {
+      const baseObservation = observationRef.getValue();
+      const buffered = segmentBuffer.getBufferedRanges();
+      const bufferGap = getLeftSizeOfRange(buffered, baseObservation.position.last);
+      return objectAssign({}, baseObservation, { bufferGap });
+    }
+
+    function emitAdaptationStreamPlaybackObservation() {
+      newRef.setValue(constructAdaptationStreamPlaybackObservation());
+    }
+  });
 
-  function mapObservation(
-    baseObservation : IPeriodStreamPlaybackObservation
-  ) : IAdaptationStreamPlaybackObservation {
-    const buffered = segmentBuffer.getBufferedRanges();
-    return objectAssign({},
-                        baseObservation,
-                        { bufferGap: getLeftSizeOfRange(buffered,
-                                                        baseObservation.position.last) });
-  }
 }

package/src/core/stream/reload_after_switch.ts

@@ -62,7 +62,7 @@ export default function reloadAfterSwitch(
   // It can happen when `reloadAfterSwitch` is called as a side-effect of the
   // same event that triggers the playback observation to be emitted.
   return nextTickObs().pipe(
-    mergeMap(() => playbackObserver.observe(true)),
+    mergeMap(() => playbackObserver.getReference().asObservable()),
     map((observation) => {
       const currentTime = playbackObserver.getCurrentTime();
       const pos = currentTime + deltaPos;

package/src/core/stream/representation/append_segment_to_buffer.ts

@@ -61,7 +61,7 @@ export default function appendSegmentToBuffer<T>(
         throw new MediaError("BUFFER_APPEND_ERROR", reason);
       }
 
-      return playbackObserver.observe(true).pipe(
+      return playbackObserver.getReference().asObservable().pipe(
         take(1),
         mergeMap((observation) => {
           const currentPos = observation.position.pending ??

package/src/core/stream/representation/representation_stream.ts

@@ -166,7 +166,7 @@ export default function RepresentationStream<TSegmentDataType>({
 
   /** Observable emitting the stream "status" and filling `lastSegmentQueue`. */
   const status$ = observableCombineLatest([
-    playbackObserver.observe(true),
+    playbackObserver.getReference().asObservable(),
     bufferGoal$,
     maxBufferSize$,
     terminate$.pipe(take(1),

package/src/utils/reference.ts

@@ -57,11 +57,26 @@ import { CancellationSignal } from "./task_canceller";
  * those use cases makes the intent of the corresponding code clearer.
  */
 export interface ISharedReference<T> {
-  /** Get the last set value for this shared reference. */
+  /**
+   * Get the last set value for this shared reference.
+   * @returns {*}
+   */
   getValue() : T;
 
-  /** Update the value of this shared reference. */
+  /**
+   * Update the value of this shared reference.
+   * @param {*} newVal
+   */
   setValue(newVal : T) : void;
+
+  /**
+   * Update the value of this shared reference only if the value changed.
+   *
+   * Note that this function only performs a strict equality reference through
+   * the "===" operator. Different objects that are structurally the same will
+   * thus be considered different.
+   * @param {*} newVal
+   */
   setValueIfChanged(newVal : T) : void;
 
   /**
@@ -72,25 +87,6 @@ export interface ISharedReference<T> {
    * @returns {Observable}
    */
   asObservable(skipCurrentValue? : boolean) : Observable<T>;
-  /**
-   * Triggers a callback each time this reference's value is updated.
-   *
-   * Can be given several options as argument:
-   *   - clearSignal: When the attach `CancellationSignal` emits, the given
-   *     callback will not be called anymore on reference updates.
-   *   - emitCurrentValue: If `true`, the callback will be called directly and
-   *     synchronously on this call with its current value.
-   * @param {Function} cb
-   * @param {Object} [options]
-   */
-  onUpdate(
-    cb : (val : T) => void,
-    options? : {
-      clearSignal?: CancellationSignal;
-      emitCurrentValue?: boolean;
-    },
-  ) : void;
-
   /**
    * Allows to register a callback to be called each time the value inside the
    * reference is updated.
@@ -105,11 +101,10 @@ export interface ISharedReference<T> {
   onUpdate(
     cb : (val : T) => void,
     options? : {
-      clearSignal?: CancellationSignal;
-      emitCurrentValue?: boolean;
+      clearSignal?: CancellationSignal | undefined;
+      emitCurrentValue?: boolean | undefined;
     },
   ) : void;
-
   /**
    * Indicate that no new values will be emitted.
    * Allows to automatically close all Observables generated from this shared
@@ -217,15 +212,15 @@ export function createSharedReference<T>(initialValue : T) : ISharedReference<T>
 
     /**
      * Update the value of this shared reference.
-     * @param {*}
+     * @param {*} newVal
      */
     setValue(newVal : T) : void {
       if (isFinished) {
         if (__ENVIRONMENT__.CURRENT_ENV === __ENVIRONMENT__.DEV as number) {
-          throw new Error("Finished shared references cannot be updated");
-        } else {
-          return;
+          /* eslint-disable-next-line no-console */
+          console.error("Finished shared references cannot be updated");
         }
+        return;
       }
       value = newVal;
 
@@ -244,6 +239,10 @@ export function createSharedReference<T>(initialValue : T) : ISharedReference<T>
       }
     },
 
+    /**
+     * Update the value of this shared reference only if it changed.
+     * @param {*} newVal
+     */
     setValueIfChanged(newVal : T) : void {
       if (newVal !== value) {
         this.setValue(newVal);
@@ -345,14 +344,27 @@ export function createSharedReference<T>(initialValue : T) : ISharedReference<T>
           if (!cbObj.hasBeenCleared) {
             cbObj.complete();
           }
+          cbObj.hasBeenCleared = true;
         } catch (_) {
           /* nothing */
         }
       }
+      cbs.length = 0;
     },
   };
 }
 
+/**
+ * Create a new `ISharedReference` based on another one by mapping over its
+ * referenced value each time it is updated.
+ * @param {Object} originalRef - The Original `ISharedReference` you wish to map
+ * over.
+ * @param {Function} mappingFn - The mapping function which will receives
+ * `originalRef`'s value and outputs this new reference's value.
+ * @param {Object | undefined} [cancellationSignal] - Optionally, a
+ * `CancellationSignal` which will finish that reference when it emits.
+ * @returns {Object} - The new, mapped, reference.
+ */
 export function createMappedReference<T, U>(
   originalRef : IReadOnlySharedReference<T>,
   mappingFn : (x : T) => U,