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

package/CHANGELOG.md

@@ -1,27 +1,28 @@
 # Changelog
 
-## v3.28.0-dev.2022061700 (2022-06-17)
+## v3.28.0
 
 ### Features
 
   - Add `label` to audio, video and text track APIs (such as `getAvailableAudioTracks`) which gives a human-readable description of the corresponding track, if available in the Manifest [#1105, #1109]
   - Automatically set the LogLevel to `"DEBUG"` if a global `__RX_PLAYER_DEBUG_MODE__` constant is set to `true`, to simplify debugging [#1115]
-  - TTML: Add support for percent based thickness for textOutline in TTML Subtitles [#1108]
 
 ### Bug fixes
 
   - Use the first **compatible** codec of the current AdaptationSet when creating a SourceBuffer [#1094]
   - DASH/DRM: Fix potential infinite rebuffering when a KID is not anounced in the MPD [#1113]
+  - DRM: Fix quality fallback when loading a content whose license has been cached under an extended `singleLicensePer` setting and when starting (and staying) with a quality whose key id is not in it [#1133]
   - DASH: Avoid infinite loop due to rounding errors while parsing multi-Periods MPDs [#1111, #1110]
+  - After a `RELOADING` state, stay in `PAUSED` if the media element was paused synchronously before the side-effect which triggered the reloading (usually coming from the API) was perform [#1132]
   - Fix issue with `maxVideoBufferSize` setting which could lead to too much data being buffered [#1125]
   - Prevent possibility of requests loops and infinite rebuffering when a pushed segment is always completely and immediately garbage collected by the browser [#1123]
   - DASH: Fix issues that could arise if a segment is calculated to start at a negative position [#1122]
   - DASH: Fix possibility of wrong segments being requested when a SegmentTimeline in a given Period (whose Period@end is set) had an S@r set to `-1` at its end [#1098]
   - DASH: If the first `<S>` has its S@t attribute not set, make as if it is set to `0` [#1118]
-  - Reload in the paused state when the action that lead to reloading was performed directly as the RxPlayer went into the `PAUSED` state [#1132]
 
 ### Other improvements
 
+  - TTML: Add support for percent based thickness for textOutline in TTML Subtitles [#1108]
   - If seeking after the last potential position, load last segments before ending [#1097]
   - The duration set on the media element is now only relative to the current chosen tracks (it was previously relative to all potential track). This allows to seek later when switching e.g. to a longer video track [#1102]
   - Errors coming from an HTMLMediaElement now have the browser's error message if it exists [#1112]

package/VERSION

@@ -1 +1 @@
-3.28.0-dev.2022061700
+3.28.0-dev.2022062000

package/appveyor.yml

@@ -1,6 +1,6 @@
 # Test against the latest version of this Node.js version
 environment:
-  nodejs_version: "12"
+  nodejs_version: "16"
 
 branches:
   only:

package/dist/_esm5.processed/core/adaptive/adaptive_representation_selector.d.ts

@@ -23,8 +23,10 @@ import { IPendingRequestStoreBegin, IPendingRequestStoreProgress } from "./utils
 /**
  * Select the most adapted Representation according to the network and buffer
  * metrics it receives.
+ *
  * @param {Object} options - Initial configuration (see type definition)
- * @returns {Object} - Interface allowing to select a Representation
+ * @returns {Object} - Interface allowing to select a Representation.
+ * @see IRepresentationEstimator
  */
 export default function createAdaptiveRepresentationSelector(options: IAdaptiveRepresentationSelectorArguments): IRepresentationEstimator;
 /**
@@ -175,11 +177,7 @@ export interface IABRFiltersObject {
      */
     width?: number;
 }
-/**
- * Callbacks returned by `getEstimateReference`.
- * Those needs to be called as soon as the corresponding events to obtain
- * coherent Representation estimates.
- */
+/** Callbacks returned by `getEstimateReference`. */
 export interface IRepresentationEstimatorCallbacks {
     /** Callback to call when a segment has been completely pushed to the buffer. */
     addedSegment(val: IAddedSegmentCallbackPayload): void;
@@ -303,14 +301,37 @@ export interface IRepresentationEstimatorArguments {
  * Type of the function returned by `createAdaptiveRepresentationSelector`,
  * allowing to estimate the most adapted `Representation`.
  */
-export declare type IRepresentationEstimator = (context: {
+export declare type IRepresentationEstimator = (
+/** Information on the content for which a Representation will be chosen */
+context: {
     manifest: Manifest;
     period: Period;
     adaptation: Adaptation;
-}, currentRepresentation: IReadOnlySharedReference<Representation | null>, representations: IReadOnlySharedReference<Representation[]>, playbackObserver: IReadOnlyPlaybackObserver<IRepresentationEstimatorPlaybackObservation>, cancellationSignal: CancellationSignal) => [
-    IReadOnlySharedReference<IABREstimate>,
-    IRepresentationEstimatorCallbacks
-];
+}, 
+/** Reference emitting the Representation currently loaded. */
+currentRepresentation: IReadOnlySharedReference<Representation | null>, 
+/** Reference emitting the list of available Representations to choose from. */
+representations: IReadOnlySharedReference<Representation[]>, 
+/** Regularly emits playback conditions */
+playbackObserver: IReadOnlyPlaybackObserver<IRepresentationEstimatorPlaybackObservation>, 
+/**
+ * After this `CancellationSignal` emits, resources will be disposed and
+ * estimates will stop to be emitted.
+ */
+stopAllEstimates: CancellationSignal) => IRepresentationEstimatorResponse;
+/** Value returned by an `IRepresentationEstimator` */
+export interface IRepresentationEstimatorResponse {
+    /**
+     * Regularly produces estimates of the best Representation to play (from the
+     * list given).
+     */
+    estimates: IReadOnlySharedReference<IABREstimate>;
+    /**
+     * Callback which need to be called as soon as the corresponding events to
+     * obtain accurate Representation estimates.
+     */
+    callbacks: IRepresentationEstimatorCallbacks;
+}
 /** Arguments received by `createAdaptiveRepresentationSelector`. */
 export interface IAdaptiveRepresentationSelectorArguments {
     /** Initial bitrate chosen, per type (minimum if not set) */

package/dist/_esm5.processed/core/adaptive/adaptive_representation_selector.js

@@ -32,8 +32,10 @@ import selectOptimalRepresentation from "./utils/select_optimal_representation";
 /**
  * Select the most adapted Representation according to the network and buffer
  * metrics it receives.
+ *
  * @param {Object} options - Initial configuration (see type definition)
- * @returns {Object} - Interface allowing to select a Representation
+ * @returns {Object} - Interface allowing to select a Representation.
+ * @see IRepresentationEstimator
  */
 export default function createAdaptiveRepresentationSelector(options) {
     /**
@@ -45,17 +47,16 @@ export default function createAdaptiveRepresentationSelector(options) {
     /**
      * Returns Object emitting Representation estimates as well as callbacks
      * allowing to helping it produce them.
+     *
+     * @see IRepresentationEstimator
      * @param {Object} context
-     * @param {Object} currentRepresentation - Reference emitting the
-     * Representation currently loaded.
-     * @param {Object} representations - Reference emitting the list of available
-     * Representations to choose from.
-     * @param {Object} playbackObserver - Emits regularly playback conditions
-     * @param {Object} cancellationSignal - After this `CancellationSignal` emits,
-     * estimates will stop to be emitted.
+     * @param {Object} currentRepresentation
+     * @param {Object} representations
+     * @param {Object} playbackObserver
+     * @param {Object} stopAllEstimates
      * @returns {Array.<Object>}
      */
-    return function getEstimates(context, currentRepresentation, representations, playbackObserver, cancellationSignal) {
+    return function getEstimates(context, currentRepresentation, representations, playbackObserver, stopAllEstimates) {
         var type = context.adaptation.type;
         var bandwidthEstimator = _getBandwidthEstimator(type);
         var manualBitrate = takeFirstSet(manualBitrates[type], createSharedReference(-1));
@@ -66,7 +67,7 @@ export default function createAdaptiveRepresentationSelector(options) {
             limitWidth: takeFirstSet(throttlers.limitWidth[type], createSharedReference(undefined)),
             throttleBitrate: takeFirstSet(throttlers.throttleBitrate[type], throttlers.throttle[type], createSharedReference(Infinity)),
         };
-        return getEstimateReference({ bandwidthEstimator: bandwidthEstimator, context: context, currentRepresentation: currentRepresentation, filters: filters, initialBitrate: initialBitrate, manualBitrate: manualBitrate, minAutoBitrate: minAutoBitrate, maxAutoBitrate: maxAutoBitrate, playbackObserver: playbackObserver, representations: representations, lowLatencyMode: lowLatencyMode }, cancellationSignal);
+        return getEstimateReference({ bandwidthEstimator: bandwidthEstimator, context: context, currentRepresentation: currentRepresentation, filters: filters, initialBitrate: initialBitrate, manualBitrate: manualBitrate, minAutoBitrate: minAutoBitrate, maxAutoBitrate: maxAutoBitrate, playbackObserver: playbackObserver, representations: representations, lowLatencyMode: lowLatencyMode }, stopAllEstimates);
     };
     /**
      * Returns interface allowing to estimate network throughtput for a given type.
@@ -100,10 +101,10 @@ export default function createAdaptiveRepresentationSelector(options) {
  *     events to help it doing those estimates.
  *
  * @param {Object} args
- * @param {Object} cancellationSignal
+ * @param {Object} stopAllEstimates
  * @returns {Array.<Object>}
  */
-function getEstimateReference(_a, cancellationSignal) {
+function getEstimateReference(_a, stopAllEstimates) {
     var bandwidthEstimator = _a.bandwidthEstimator, context = _a.context, currentRepresentation = _a.currentRepresentation, filters = _a.filters, initialBitrate = _a.initialBitrate, lowLatencyMode = _a.lowLatencyMode, manualBitrate = _a.manualBitrate, maxAutoBitrate = _a.maxAutoBitrate, minAutoBitrate = _a.minAutoBitrate, playbackObserver = _a.playbackObserver, representationsRef = _a.representations;
     var scoreCalculator = new RepresentationScoreCalculator();
     var networkAnalyzer = new NetworkAnalyzer(initialBitrate !== null && initialBitrate !== void 0 ? initialBitrate : 0, lowLatencyMode);
@@ -121,15 +122,12 @@ function getEstimateReference(_a, cancellationSignal) {
      * This TaskCanceller is used both for restarting estimates with a new
      * configuration and to cancel them altogether.
      */
-    var currentEstimatesCanceller = new TaskCanceller();
-    cancellationSignal.register(function () {
-        currentEstimatesCanceller.cancel();
-    });
+    var currentEstimatesCanceller = new TaskCanceller({ cancelOn: stopAllEstimates });
     // Create `ISharedReference` on which estimates will be emitted.
     var estimateRef = createEstimateReference(manualBitrate.getValue(), representationsRef.getValue(), currentEstimatesCanceller.signal);
-    manualBitrate.onUpdate(restartEstimatesProductionFromCurrentConditions, { clearSignal: currentEstimatesCanceller.signal });
-    representationsRef.onUpdate(restartEstimatesProductionFromCurrentConditions, { clearSignal: currentEstimatesCanceller.signal });
-    return [estimateRef, callbacks];
+    manualBitrate.onUpdate(restartEstimatesProductionFromCurrentConditions, { clearSignal: stopAllEstimates });
+    representationsRef.onUpdate(restartEstimatesProductionFromCurrentConditions, { clearSignal: stopAllEstimates });
+    return { estimates: estimateRef, callbacks: callbacks };
     function createEstimateReference(manualBitrateVal, representations, innerCancellationSignal) {
         if (manualBitrateVal >= 0) {
             // A manual bitrate has been set. Just choose Representation according to it.
@@ -319,7 +317,7 @@ function getEstimateReference(_a, cancellationSignal) {
         var manualBitrateVal = manualBitrate.getValue();
         var representations = representationsRef.getValue();
         currentEstimatesCanceller.cancel();
-        currentEstimatesCanceller = new TaskCanceller();
+        currentEstimatesCanceller = new TaskCanceller({ cancelOn: stopAllEstimates });
         var newRef = createEstimateReference(manualBitrateVal, representations, currentEstimatesCanceller.signal);
         newRef.onUpdate(function onNewEstimate(newEstimate) {
             estimateRef.setValue(newEstimate);

package/dist/_esm5.processed/core/api/public_api.js

@@ -88,7 +88,7 @@ var Player = /** @class */ (function (_super) {
         // Workaround to support Firefox autoplay on FF 42.
         // See: https://bugzilla.mozilla.org/show_bug.cgi?id=1194624
         videoElement.preload = "auto";
-        _this.version = /* PLAYER_VERSION */ "3.28.0-dev.2022061700";
+        _this.version = /* PLAYER_VERSION */ "3.28.0-dev.2022062000";
         _this.log = log;
         _this.state = "STOPPED";
         _this.videoElement = videoElement;
@@ -2295,5 +2295,5 @@ var Player = /** @class */ (function (_super) {
     };
     return Player;
 }(EventEmitter));
-Player.version = /* PLAYER_VERSION */ "3.28.0-dev.2022061700";
+Player.version = /* PLAYER_VERSION */ "3.28.0-dev.2022062000";
 export default Player;

package/dist/_esm5.processed/core/decrypt/content_decryptor.js

@@ -428,18 +428,7 @@ var ContentDecryptor = /** @class */ (function (_super) {
                                         _this.trigger("warning", evt.value);
                                         return;
                                 }
-                                var linkedKeys;
-                                if (sessionInfo.source === "created-session" /* 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 };
-                                }
+                                var linkedKeys = getKeyIdsLinkedToSession(initializationData, sessionInfo.record, options.singleLicensePer, sessionInfo.source === "created-session" /* MediaKeySessionLoadingType.Created */, evt.value.whitelistedKeyIds, evt.value.blacklistedKeyIDs);
                                 sessionInfo.record.associateKeyIds(linkedKeys.whitelisted);
                                 sessionInfo.record.associateKeyIds(linkedKeys.blacklisted);
                                 sessionInfo.keyStatuses = { whitelisted: linkedKeys.whitelisted,
@@ -758,26 +747,63 @@ export var ContentDecryptorState;
     ContentDecryptorState[ContentDecryptorState["Disposed"] = 4] = "Disposed";
 })(ContentDecryptorState || (ContentDecryptorState = {}));
 /**
- * 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(initializationData, singleLicensePer, usableKeyIds, unusableKeyIds) {
+function getKeyIdsLinkedToSession(initializationData, keySessionRecord, singleLicensePer, isCurrentLicense, usableKeyIds, unusableKeyIds) {
     var _a;
     /**
      * Every key id associated with the MediaKeySession, starting with
      * whitelisted ones.
      */
     var associatedKeyIds = __spreadArray(__spreadArray([], usableKeyIds, true), unusableKeyIds, true);
+    // Add all key ids associated to the `KeySessionRecord` yet not in
+    // `usableKeyIds` nor in `unusableKeyIds`
+    var allKnownKeyIds = keySessionRecord.getAssociatedKeyIds();
+    var _loop_2 = function (kid) {
+        if (!associatedKeyIds.some(function (ak) { return areKeyIdsEqual(ak, kid); })) {
+            if (log.hasLevel("DEBUG")) {
+                log.debug("DRM: KeySessionRecord's key missing in the license, blacklisting it", bytesToHex(kid));
+            }
+            associatedKeyIds.push(kid);
+        }
+    };
+    for (var _i = 0, allKnownKeyIds_1 = allKnownKeyIds; _i < allKnownKeyIds_1.length; _i++) {
+        var kid = allKnownKeyIds_1[_i];
+        _loop_2(kid);
+    }
     if (singleLicensePer !== undefined && singleLicensePer !== "init-data") {
         // We want to add the current key ids in the blacklist if it is
         // not already there.
@@ -798,24 +824,27 @@ function getFetchedLicenseKeysInfo(initializationData, singleLicensePer, usableK
                 return !associatedKeyIds.some(function (k) { return 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(function (m) { return bytesToHex(m); }).join(", "));
+                }
                 associatedKeyIds.push.apply(associatedKeyIds, missingKeyIds);
             }
         }
-        if (content !== undefined) {
+        if (isCurrentLicense && content !== undefined) {
             if (singleLicensePer === "content") {
                 // Put it in a Set to automatically filter out duplicates (by ref)
                 var contentKeys = new Set();
                 var manifest = content.manifest;
-                for (var _i = 0, _b = manifest.periods; _i < _b.length; _i++) {
-                    var period = _b[_i];
+                for (var _b = 0, _c = manifest.periods; _b < _c.length; _b++) {
+                    var period = _c[_b];
                     addKeyIdsFromPeriod(contentKeys, period);
                 }
                 mergeKeyIdSetIntoArray(contentKeys, associatedKeyIds);
             }
             else if (singleLicensePer === "periods") {
                 var manifest = content.manifest;
-                for (var _c = 0, _d = manifest.periods; _c < _d.length; _c++) {
-                    var period = _d[_c];
+                for (var _d = 0, _e = manifest.periods; _d < _e.length; _d++) {
+                    var period = _e[_d];
                     var periodKeys = new Set();
                     addKeyIdsFromPeriod(periodKeys, period);
                     if (((_a = initializationData.content) === null || _a === void 0 ? void 0 : _a.period.id) === period.id) {
@@ -823,16 +852,16 @@ function getFetchedLicenseKeysInfo(initializationData, singleLicensePer, usableK
                     }
                     else {
                         var periodKeysArr = Array.from(periodKeys);
-                        var _loop_2 = function (kid) {
+                        var _loop_3 = function (kid) {
                             var isFound = associatedKeyIds.some(function (k) { return areKeyIdsEqual(k, kid); });
                             if (isFound) {
                                 mergeKeyIdSetIntoArray(periodKeys, associatedKeyIds);
                                 return "break";
                             }
                         };
-                        for (var _e = 0, periodKeysArr_3 = periodKeysArr; _e < periodKeysArr_3.length; _e++) {
-                            var kid = periodKeysArr_3[_e];
-                            var state_2 = _loop_2(kid);
+                        for (var _f = 0, periodKeysArr_3 = periodKeysArr; _f < periodKeysArr_3.length; _f++) {
+                            var kid = periodKeysArr_3[_f];
+                            var state_2 = _loop_3(kid);
                             if (state_2 === "break")
                                 break;
                         }
@@ -847,7 +876,7 @@ function getFetchedLicenseKeysInfo(initializationData, singleLicensePer, usableK
 }
 function mergeKeyIdSetIntoArray(set, arr) {
     var setArr = Array.from(set.values());
-    var _loop_3 = function (kid) {
+    var _loop_4 = function (kid) {
         var isFound = arr.some(function (k) { return areKeyIdsEqual(k, kid); });
         if (!isFound) {
             arr.push(kid);
@@ -855,7 +884,7 @@ function mergeKeyIdSetIntoArray(set, arr) {
     };
     for (var _i = 0, setArr_1 = setArr; _i < setArr_1.length; _i++) {
         var kid = setArr_1[_i];
-        _loop_3(kid);
+        _loop_4(kid);
     }
 }
 function addKeyIdsFromPeriod(set, period) {

package/dist/_esm5.processed/core/stream/adaptation/create_representation_estimator.js

@@ -39,7 +39,7 @@ export default function getRepresentationEstimate(content, representationEstimat
     updateRepresentationsReference();
     manifest.addEventListener("decipherabilityUpdate", updateRepresentationsReference);
     var unregisterCleanUp = cancellationSignal.register(cleanUp);
-    var _a = representationEstimator(content, currentRepresentation, representations, playbackObserver, cancellationSignal), estimateRef = _a[0], abrCallbacks = _a[1];
+    var _a = representationEstimator(content, currentRepresentation, representations, playbackObserver, cancellationSignal), estimateRef = _a.estimates, abrCallbacks = _a.callbacks;
     return { abrCallbacks: abrCallbacks, estimateRef: estimateRef };
     function updateRepresentationsReference() {
         /** Representations for which a `RepresentationStream` can be created. */

package/dist/_esm5.processed/utils/reference.d.ts

@@ -52,10 +52,24 @@ 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;
     /**
      * Returns an Observable which synchronously emits the current value (unless
@@ -65,21 +79,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.
@@ -160,5 +159,16 @@ export interface IReadOnlySharedReference<T> {
  * @returns {Observable}
  */
 export declare function createSharedReference<T>(initialValue: T): ISharedReference<T>;
+/**
+ * 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 declare function createMappedReference<T, U>(originalRef: IReadOnlySharedReference<T>, mappingFn: (x: T) => U, cancellationSignal?: CancellationSignal): IReadOnlySharedReference<U>;
 export default createSharedReference;

package/dist/_esm5.processed/utils/reference.js

@@ -53,7 +53,7 @@ export function createSharedReference(initialValue) {
         },
         /**
          * Update the value of this shared reference.
-         * @param {*}
+         * @param {*} newVal
          */
         setValue: function (newVal) {
             if (isFinished) {
@@ -81,6 +81,10 @@ export function createSharedReference(initialValue) {
                 }
             }
         },
+        /**
+         * Update the value of this shared reference only if it changed.
+         * @param {*} newVal
+         */
         setValueIfChanged: function (newVal) {
             if (newVal !== value) {
                 this.setValue(newVal);
@@ -181,6 +185,17 @@ export function createSharedReference(initialValue) {
         },
     };
 }
+/**
+ * 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(originalRef, mappingFn, cancellationSignal) {
     var newRef = createSharedReference(mappingFn(originalRef.getValue()));
     originalRef.onUpdate(function mapOriginalReference(x) {