123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487 |
- import { Operator } from './Operator';
- import { SafeSubscriber, Subscriber } from './Subscriber';
- import { isSubscription, Subscription } from './Subscription';
- import { TeardownLogic, OperatorFunction, Subscribable, Observer } from './types';
- import { observable as Symbol_observable } from './symbol/observable';
- import { pipeFromArray } from './util/pipe';
- import { config } from './config';
- import { isFunction } from './util/isFunction';
- import { errorContext } from './util/errorContext';
- /**
- * A representation of any set of values over any amount of time. This is the most basic building block
- * of RxJS.
- */
- export class Observable<T> implements Subscribable<T> {
- /**
- * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.
- */
- source: Observable<any> | undefined;
- /**
- * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.
- */
- operator: Operator<any, T> | undefined;
- /**
- * @param subscribe The function that is called when the Observable is
- * initially subscribed to. This function is given a Subscriber, to which new values
- * can be `next`ed, or an `error` method can be called to raise an error, or
- * `complete` can be called to notify of a successful completion.
- */
- constructor(subscribe?: (this: Observable<T>, subscriber: Subscriber<T>) => TeardownLogic) {
- if (subscribe) {
- this._subscribe = subscribe;
- }
- }
- // HACK: Since TypeScript inherits static properties too, we have to
- // fight against TypeScript here so Subject can have a different static create signature
- /**
- * Creates a new Observable by calling the Observable constructor
- * @param subscribe the subscriber function to be passed to the Observable constructor
- * @return A new observable.
- * @deprecated Use `new Observable()` instead. Will be removed in v8.
- */
- static create: (...args: any[]) => any = <T>(subscribe?: (subscriber: Subscriber<T>) => TeardownLogic) => {
- return new Observable<T>(subscribe);
- };
- /**
- * Creates a new Observable, with this Observable instance as the source, and the passed
- * operator defined as the new observable's operator.
- * @param operator the operator defining the operation to take on the observable
- * @return A new observable with the Operator applied.
- * @deprecated Internal implementation detail, do not use directly. Will be made internal in v8.
- * If you have implemented an operator using `lift`, it is recommended that you create an
- * operator by simply returning `new Observable()` directly. See "Creating new operators from
- * scratch" section here: https://rxjs.dev/guide/operators
- */
- lift<R>(operator?: Operator<T, R>): Observable<R> {
- const observable = new Observable<R>();
- observable.source = this;
- observable.operator = operator;
- return observable;
- }
- subscribe(observerOrNext?: Partial<Observer<T>> | ((value: T) => void)): Subscription;
- /** @deprecated Instead of passing separate callback arguments, use an observer argument. Signatures taking separate callback arguments will be removed in v8. Details: https://rxjs.dev/deprecations/subscribe-arguments */
- subscribe(next?: ((value: T) => void) | null, error?: ((error: any) => void) | null, complete?: (() => void) | null): Subscription;
- /**
- * Invokes an execution of an Observable and registers Observer handlers for notifications it will emit.
- *
- * <span class="informal">Use it when you have all these Observables, but still nothing is happening.</span>
- *
- * `subscribe` is not a regular operator, but a method that calls Observable's internal `subscribe` function. It
- * might be for example a function that you passed to Observable's constructor, but most of the time it is
- * a library implementation, which defines what will be emitted by an Observable, and when it be will emitted. This means
- * that calling `subscribe` is actually the moment when Observable starts its work, not when it is created, as it is often
- * the thought.
- *
- * Apart from starting the execution of an Observable, this method allows you to listen for values
- * that an Observable emits, as well as for when it completes or errors. You can achieve this in two
- * of the following ways.
- *
- * The first way is creating an object that implements {@link Observer} interface. It should have methods
- * defined by that interface, but note that it should be just a regular JavaScript object, which you can create
- * yourself in any way you want (ES6 class, classic function constructor, object literal etc.). In particular, do
- * not attempt to use any RxJS implementation details to create Observers - you don't need them. Remember also
- * that your object does not have to implement all methods. If you find yourself creating a method that doesn't
- * do anything, you can simply omit it. Note however, if the `error` method is not provided and an error happens,
- * it will be thrown asynchronously. Errors thrown asynchronously cannot be caught using `try`/`catch`. Instead,
- * use the {@link onUnhandledError} configuration option or use a runtime handler (like `window.onerror` or
- * `process.on('error)`) to be notified of unhandled errors. Because of this, it's recommended that you provide
- * an `error` method to avoid missing thrown errors.
- *
- * The second way is to give up on Observer object altogether and simply provide callback functions in place of its methods.
- * This means you can provide three functions as arguments to `subscribe`, where the first function is equivalent
- * of a `next` method, the second of an `error` method and the third of a `complete` method. Just as in case of an Observer,
- * if you do not need to listen for something, you can omit a function by passing `undefined` or `null`,
- * since `subscribe` recognizes these functions by where they were placed in function call. When it comes
- * to the `error` function, as with an Observer, if not provided, errors emitted by an Observable will be thrown asynchronously.
- *
- * You can, however, subscribe with no parameters at all. This may be the case where you're not interested in terminal events
- * and you also handled emissions internally by using operators (e.g. using `tap`).
- *
- * Whichever style of calling `subscribe` you use, in both cases it returns a Subscription object.
- * This object allows you to call `unsubscribe` on it, which in turn will stop the work that an Observable does and will clean
- * up all resources that an Observable used. Note that cancelling a subscription will not call `complete` callback
- * provided to `subscribe` function, which is reserved for a regular completion signal that comes from an Observable.
- *
- * Remember that callbacks provided to `subscribe` are not guaranteed to be called asynchronously.
- * It is an Observable itself that decides when these functions will be called. For example {@link of}
- * by default emits all its values synchronously. Always check documentation for how given Observable
- * will behave when subscribed and if its default behavior can be modified with a `scheduler`.
- *
- * #### Examples
- *
- * Subscribe with an {@link guide/observer Observer}
- *
- * ```ts
- * import { of } from 'rxjs';
- *
- * const sumObserver = {
- * sum: 0,
- * next(value) {
- * console.log('Adding: ' + value);
- * this.sum = this.sum + value;
- * },
- * error() {
- * // We actually could just remove this method,
- * // since we do not really care about errors right now.
- * },
- * complete() {
- * console.log('Sum equals: ' + this.sum);
- * }
- * };
- *
- * of(1, 2, 3) // Synchronously emits 1, 2, 3 and then completes.
- * .subscribe(sumObserver);
- *
- * // Logs:
- * // 'Adding: 1'
- * // 'Adding: 2'
- * // 'Adding: 3'
- * // 'Sum equals: 6'
- * ```
- *
- * Subscribe with functions ({@link deprecations/subscribe-arguments deprecated})
- *
- * ```ts
- * import { of } from 'rxjs'
- *
- * let sum = 0;
- *
- * of(1, 2, 3).subscribe(
- * value => {
- * console.log('Adding: ' + value);
- * sum = sum + value;
- * },
- * undefined,
- * () => console.log('Sum equals: ' + sum)
- * );
- *
- * // Logs:
- * // 'Adding: 1'
- * // 'Adding: 2'
- * // 'Adding: 3'
- * // 'Sum equals: 6'
- * ```
- *
- * Cancel a subscription
- *
- * ```ts
- * import { interval } from 'rxjs';
- *
- * const subscription = interval(1000).subscribe({
- * next(num) {
- * console.log(num)
- * },
- * complete() {
- * // Will not be called, even when cancelling subscription.
- * console.log('completed!');
- * }
- * });
- *
- * setTimeout(() => {
- * subscription.unsubscribe();
- * console.log('unsubscribed!');
- * }, 2500);
- *
- * // Logs:
- * // 0 after 1s
- * // 1 after 2s
- * // 'unsubscribed!' after 2.5s
- * ```
- *
- * @param observerOrNext Either an {@link Observer} with some or all callback methods,
- * or the `next` handler that is called for each value emitted from the subscribed Observable.
- * @param error A handler for a terminal event resulting from an error. If no error handler is provided,
- * the error will be thrown asynchronously as unhandled.
- * @param complete A handler for a terminal event resulting from successful completion.
- * @return A subscription reference to the registered handlers.
- */
- subscribe(
- observerOrNext?: Partial<Observer<T>> | ((value: T) => void) | null,
- error?: ((error: any) => void) | null,
- complete?: (() => void) | null
- ): Subscription {
- const subscriber = isSubscriber(observerOrNext) ? observerOrNext : new SafeSubscriber(observerOrNext, error, complete);
- errorContext(() => {
- const { operator, source } = this;
- subscriber.add(
- operator
- ? // We're dealing with a subscription in the
- // operator chain to one of our lifted operators.
- operator.call(subscriber, source)
- : source
- ? // If `source` has a value, but `operator` does not, something that
- // had intimate knowledge of our API, like our `Subject`, must have
- // set it. We're going to just call `_subscribe` directly.
- this._subscribe(subscriber)
- : // In all other cases, we're likely wrapping a user-provided initializer
- // function, so we need to catch errors and handle them appropriately.
- this._trySubscribe(subscriber)
- );
- });
- return subscriber;
- }
- /** @internal */
- protected _trySubscribe(sink: Subscriber<T>): TeardownLogic {
- try {
- return this._subscribe(sink);
- } catch (err) {
- // We don't need to return anything in this case,
- // because it's just going to try to `add()` to a subscription
- // above.
- sink.error(err);
- }
- }
- /**
- * Used as a NON-CANCELLABLE means of subscribing to an observable, for use with
- * APIs that expect promises, like `async/await`. You cannot unsubscribe from this.
- *
- * **WARNING**: Only use this with observables you *know* will complete. If the source
- * observable does not complete, you will end up with a promise that is hung up, and
- * potentially all of the state of an async function hanging out in memory. To avoid
- * this situation, look into adding something like {@link timeout}, {@link take},
- * {@link takeWhile}, or {@link takeUntil} amongst others.
- *
- * #### Example
- *
- * ```ts
- * import { interval, take } from 'rxjs';
- *
- * const source$ = interval(1000).pipe(take(4));
- *
- * async function getTotal() {
- * let total = 0;
- *
- * await source$.forEach(value => {
- * total += value;
- * console.log('observable -> ' + value);
- * });
- *
- * return total;
- * }
- *
- * getTotal().then(
- * total => console.log('Total: ' + total)
- * );
- *
- * // Expected:
- * // 'observable -> 0'
- * // 'observable -> 1'
- * // 'observable -> 2'
- * // 'observable -> 3'
- * // 'Total: 6'
- * ```
- *
- * @param next A handler for each value emitted by the observable.
- * @return A promise that either resolves on observable completion or
- * rejects with the handled error.
- */
- forEach(next: (value: T) => void): Promise<void>;
- /**
- * @param next a handler for each value emitted by the observable
- * @param promiseCtor a constructor function used to instantiate the Promise
- * @return a promise that either resolves on observable completion or
- * rejects with the handled error
- * @deprecated Passing a Promise constructor will no longer be available
- * in upcoming versions of RxJS. This is because it adds weight to the library, for very
- * little benefit. If you need this functionality, it is recommended that you either
- * polyfill Promise, or you create an adapter to convert the returned native promise
- * to whatever promise implementation you wanted. Will be removed in v8.
- */
- forEach(next: (value: T) => void, promiseCtor: PromiseConstructorLike): Promise<void>;
- forEach(next: (value: T) => void, promiseCtor?: PromiseConstructorLike): Promise<void> {
- promiseCtor = getPromiseCtor(promiseCtor);
- return new promiseCtor<void>((resolve, reject) => {
- const subscriber = new SafeSubscriber<T>({
- next: (value) => {
- try {
- next(value);
- } catch (err) {
- reject(err);
- subscriber.unsubscribe();
- }
- },
- error: reject,
- complete: resolve,
- });
- this.subscribe(subscriber);
- }) as Promise<void>;
- }
- /** @internal */
- protected _subscribe(subscriber: Subscriber<any>): TeardownLogic {
- return this.source?.subscribe(subscriber);
- }
- /**
- * An interop point defined by the es7-observable spec https://github.com/zenparsing/es-observable
- * @return This instance of the observable.
- */
- [Symbol_observable]() {
- return this;
- }
- /* tslint:disable:max-line-length */
- pipe(): Observable<T>;
- pipe<A>(op1: OperatorFunction<T, A>): Observable<A>;
- pipe<A, B>(op1: OperatorFunction<T, A>, op2: OperatorFunction<A, B>): Observable<B>;
- pipe<A, B, C>(op1: OperatorFunction<T, A>, op2: OperatorFunction<A, B>, op3: OperatorFunction<B, C>): Observable<C>;
- pipe<A, B, C, D>(
- op1: OperatorFunction<T, A>,
- op2: OperatorFunction<A, B>,
- op3: OperatorFunction<B, C>,
- op4: OperatorFunction<C, D>
- ): Observable<D>;
- pipe<A, B, C, D, E>(
- op1: OperatorFunction<T, A>,
- op2: OperatorFunction<A, B>,
- op3: OperatorFunction<B, C>,
- op4: OperatorFunction<C, D>,
- op5: OperatorFunction<D, E>
- ): Observable<E>;
- pipe<A, B, C, D, E, F>(
- op1: OperatorFunction<T, A>,
- op2: OperatorFunction<A, B>,
- op3: OperatorFunction<B, C>,
- op4: OperatorFunction<C, D>,
- op5: OperatorFunction<D, E>,
- op6: OperatorFunction<E, F>
- ): Observable<F>;
- pipe<A, B, C, D, E, F, G>(
- op1: OperatorFunction<T, A>,
- op2: OperatorFunction<A, B>,
- op3: OperatorFunction<B, C>,
- op4: OperatorFunction<C, D>,
- op5: OperatorFunction<D, E>,
- op6: OperatorFunction<E, F>,
- op7: OperatorFunction<F, G>
- ): Observable<G>;
- pipe<A, B, C, D, E, F, G, H>(
- op1: OperatorFunction<T, A>,
- op2: OperatorFunction<A, B>,
- op3: OperatorFunction<B, C>,
- op4: OperatorFunction<C, D>,
- op5: OperatorFunction<D, E>,
- op6: OperatorFunction<E, F>,
- op7: OperatorFunction<F, G>,
- op8: OperatorFunction<G, H>
- ): Observable<H>;
- pipe<A, B, C, D, E, F, G, H, I>(
- op1: OperatorFunction<T, A>,
- op2: OperatorFunction<A, B>,
- op3: OperatorFunction<B, C>,
- op4: OperatorFunction<C, D>,
- op5: OperatorFunction<D, E>,
- op6: OperatorFunction<E, F>,
- op7: OperatorFunction<F, G>,
- op8: OperatorFunction<G, H>,
- op9: OperatorFunction<H, I>
- ): Observable<I>;
- pipe<A, B, C, D, E, F, G, H, I>(
- op1: OperatorFunction<T, A>,
- op2: OperatorFunction<A, B>,
- op3: OperatorFunction<B, C>,
- op4: OperatorFunction<C, D>,
- op5: OperatorFunction<D, E>,
- op6: OperatorFunction<E, F>,
- op7: OperatorFunction<F, G>,
- op8: OperatorFunction<G, H>,
- op9: OperatorFunction<H, I>,
- ...operations: OperatorFunction<any, any>[]
- ): Observable<unknown>;
- /* tslint:enable:max-line-length */
- /**
- * Used to stitch together functional operators into a chain.
- *
- * ## Example
- *
- * ```ts
- * import { interval, filter, map, scan } from 'rxjs';
- *
- * interval(1000)
- * .pipe(
- * filter(x => x % 2 === 0),
- * map(x => x + x),
- * scan((acc, x) => acc + x)
- * )
- * .subscribe(x => console.log(x));
- * ```
- *
- * @return The Observable result of all the operators having been called
- * in the order they were passed in.
- */
- pipe(...operations: OperatorFunction<any, any>[]): Observable<any> {
- return pipeFromArray(operations)(this);
- }
- /* tslint:disable:max-line-length */
- /** @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise */
- toPromise(): Promise<T | undefined>;
- /** @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise */
- toPromise(PromiseCtor: typeof Promise): Promise<T | undefined>;
- /** @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise */
- toPromise(PromiseCtor: PromiseConstructorLike): Promise<T | undefined>;
- /* tslint:enable:max-line-length */
- /**
- * Subscribe to this Observable and get a Promise resolving on
- * `complete` with the last emission (if any).
- *
- * **WARNING**: Only use this with observables you *know* will complete. If the source
- * observable does not complete, you will end up with a promise that is hung up, and
- * potentially all of the state of an async function hanging out in memory. To avoid
- * this situation, look into adding something like {@link timeout}, {@link take},
- * {@link takeWhile}, or {@link takeUntil} amongst others.
- *
- * @param [promiseCtor] a constructor function used to instantiate
- * the Promise
- * @return A Promise that resolves with the last value emit, or
- * rejects on an error. If there were no emissions, Promise
- * resolves with undefined.
- * @deprecated Replaced with {@link firstValueFrom} and {@link lastValueFrom}. Will be removed in v8. Details: https://rxjs.dev/deprecations/to-promise
- */
- toPromise(promiseCtor?: PromiseConstructorLike): Promise<T | undefined> {
- promiseCtor = getPromiseCtor(promiseCtor);
- return new promiseCtor((resolve, reject) => {
- let value: T | undefined;
- this.subscribe(
- (x: T) => (value = x),
- (err: any) => reject(err),
- () => resolve(value)
- );
- }) as Promise<T | undefined>;
- }
- }
- /**
- * Decides between a passed promise constructor from consuming code,
- * A default configured promise constructor, and the native promise
- * constructor and returns it. If nothing can be found, it will throw
- * an error.
- * @param promiseCtor The optional promise constructor to passed by consuming code
- */
- function getPromiseCtor(promiseCtor: PromiseConstructorLike | undefined) {
- return promiseCtor ?? config.Promise ?? Promise;
- }
- function isObserver<T>(value: any): value is Observer<T> {
- return value && isFunction(value.next) && isFunction(value.error) && isFunction(value.complete);
- }
- function isSubscriber<T>(value: any): value is Subscriber<T> {
- return (value && value instanceof Subscriber) || (isObserver(value) && isSubscription(value));
- }
|