rx-player
Version:
Canal+ HTML5 Video Player
215 lines • 8.75 kB
TypeScript
/**
* Copyright 2015 CANAL+ Group
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import type { CancellationSignal } from "./task_canceller";
/**
* A value behind a shared reference, meaning that any update to its value from
* anywhere can be retrieved from any other parts of the code in possession of
* the same `SharedReference`.
*
* @example
* ```ts
* const myVal = 1;
* const myRef : SharedReference<number> = new SharedReference(1);
*
* function setValTo2(num : number) {
* num = 2;
* }
*
* function setRefTo2(num : SharedReference<number>) {
* num.setValue(2);
* }
*
* setValTo2(myVal);
* console.log(myVal); // output: 1
*
* myRef.onUpdate((val) => {
* console.log(val); // outputs first synchronously `1`, then `2`
* }, { emitCurrentValue: true });
*
* setRefTo2(myRef);
* console.log(myRef.getValue()); // output: 2
*
* myRef.listen((val) => {
* console.log(val); // outputs only `2`
* }, { emitCurrentValue: true });
* ```
*
* This type was added because we found that the usage of an explicit type for
* those use cases makes the intent of the corresponding code clearer.
*/
declare class SharedReference<T> {
/** Current value referenced by this `SharedReference`. */
private _value;
/**
* Attributes each linked to a single registered callbacks which listen to the
* referenced value's updates.
*
* Contains the following properties:
* - `trigger`: Function which will be called with the new reference's value
* once it changes
* - `complete`: Allows to clean-up the listener, will be called once the
* reference is finished.
* - `hasBeenCleared`: becomes `true` when the reference is
* removed from the `cbs` array.
* Adding this property allows to detect when a previously-added
* listener has since been removed e.g. as a side-effect during a
* function call.
* - `complete`: Callback to call when the current Reference is "finished".
*/
private _listeners;
/**
* Set to `true` when this `SharedReference` is finished in which case it
* cannot be updated nor emit values anymore.
*/
private _isFinished;
/**
* Callbacks triggered when the `SharedReference` is finished.
*/
private _onFinishCbs;
/**
* Store a reference to the callback allowing to finish the `SharedReference`
* on some event. Allows to remove the logic when it's not needed anymore.
*/
private _deregisterCancellation;
/**
* Create a `SharedReference` object encapsulating the mutable `initialValue`
* value of type T.
* @param {*} initialValue
* @param {Object|undefined} [cancelSignal] - If set, the created shared
* reference will be automatically "finished" once that signal emits.
* Finished references won't be able to update their value anymore, and will
* also automatically have their listeners (callbacks linked to value change)
* removed - as they cannot be triggered anymore, thus providing a security
* against memory leaks.
*/
constructor(initialValue: T, cancelSignal?: CancellationSignal);
/**
* Returns the current value of this shared reference.
* @returns {*}
*/
getValue(): T;
/**
* 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;
/**
* Allows to register a callback to be called each time the value inside the
* reference is updated.
* @param {Function} cb - Callback to be called each time the reference is
* updated. Takes as first argument its new value and in second argument a
* callback allowing to unregister the callback.
* @param {Object} params
* @param {Object} params.clearSignal - Allows to provide a CancellationSignal
* which will unregister the callback when it emits.
* @param {boolean|undefined} [params.emitCurrentValue] - If `true`, the
* callback will also be immediately called with the current value.
*/
onUpdate(cb: (val: T, stopListening: () => void) => void, params: {
clearSignal: CancellationSignal;
emitCurrentValue?: boolean | undefined;
}): void;
/**
* Variant of `onUpdate` which will only call the callback once, once the
* value inside the reference is different from `undefined`.
* The callback is called synchronously if the value already isn't set to
* `undefined`.
*
* This method can be used as a lighter weight alternative to `onUpdate` when
* just waiting that the stored value becomes defined.
* As such, it is an explicit equivalent to something like:
* ```js
* myReference.onUpdate((newVal, stopListening) => {
* if (newVal !== undefined) {
* stopListening();
*
* // ... do the logic
* }
* }, { emitCurrentValue: true });
* ```
* @param {Function} cb - Callback to be called each time the reference is
* updated. Takes the new value in argument.
* @param {Object} params
* @param {Object} params.clearSignal - Allows to provide a
* CancellationSignal which will unregister the callback when it emits.
*/
waitUntilDefined(cb: (val: Exclude<T, undefined>) => void, params: {
clearSignal: CancellationSignal;
}): void;
/**
* Allows to register a callback for when the Shared Reference is "finished".
*
* This function is mostly there for implementing operators on the shared
* reference and isn't meant to be used by regular code, hence it being
* prefixed by `_`.
* @param {Function} cb - Callback to be called once the reference is
* finished.
* @param {Object} onFinishCancelSignal - Allows to provide a
* CancellationSignal which will unregister the callback when it emits.
*/
_onFinished(cb: () => void, onFinishCancelSignal: CancellationSignal): () => void;
/**
* Indicate that no new values will be emitted.
* Allows to automatically free all listeners linked to this reference.
*/
finish(): void;
}
/**
* A `SharedReference` which can only be read and not updated.
*
* Because a `SharedReference` is structurally compatible to a
* `IReadOnlySharedReference`, and because of TypeScript variance rules, it can
* be upcasted into a `IReadOnlySharedReference` at any time to make it clear in
* the code that some logic is not supposed to update the referenced value.
*
* @example
* ```ts
* const myReference : SharedReference<number> = new SharedReference(4);
*
* function shouldOnlyReadIt(roRef : IReadOnlySharedReference<number>) {
* console.log("current value:", roRef.getValue());
* }
*
* shouldOnlyReadIt(myReference); // output: "current value: 4"
*
* myReference.setValue(12);
* shouldOnlyReadIt(myReference); // output: "current value: 12"
* ```
*/
export type IReadOnlySharedReference<T> = Pick<SharedReference<T>, "getValue" | "onUpdate" | "waitUntilDefined" | "_onFinished">;
/**
* Create a new `SharedReference` based on another one by mapping over its
* referenced value each time it is updated and finishing once it finishes.
* @param {Object} originalRef - The Original `SharedReference` 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} 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 SharedReference;
//# sourceMappingURL=reference.d.ts.map