123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296 |
- import { root } from './util/root';
- import { toSubscriber } from './util/toSubscriber';
- import { observable as Symbol_observable } from './symbol/observable';
- import { pipeFromArray } from './util/pipe';
- /**
- * A representation of any set of values over any amount of time. This is the most basic building block
- * of RxJS.
- *
- * @class Observable<T>
- */
- export class Observable {
- /**
- * @constructor
- * @param {Function} 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._isScalar = false;
- if (subscribe) {
- this._subscribe = subscribe;
- }
- }
- /**
- * Creates a new Observable, with this Observable as the source, and the passed
- * operator defined as the new observable's operator.
- * @method lift
- * @param {Operator} operator the operator defining the operation to take on the observable
- * @return {Observable} a new observable with the Operator applied
- */
- lift(operator) {
- const observable = new Observable();
- observable.source = this;
- observable.operator = operator;
- return observable;
- }
- /**
- * 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 a {@link create} static factory, but most of the time it is
- * a library implementation, which defines what and when will be emitted by an Observable. This means that calling
- * `subscribe` is actually the moment when Observable starts its work, not when it is created, as it is often
- * 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
- * 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, that if `error` method is not provided, all errors will
- * be left uncaught.
- *
- * 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 first function is equivalent
- * of a `next` method, second of an `error` method and third of a `complete` method. Just as in case of Observer,
- * if you do not need to listen for something, you can omit a function, preferably by passing `undefined` or `null`,
- * since `subscribe` recognizes these functions by where they were placed in function call. When it comes
- * to `error` function, just as before, if not provided, errors emitted by an Observable will be thrown.
- *
- * Whatever 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 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 {@link Scheduler}.
- *
- * @example <caption>Subscribe with an Observer</caption>
- * 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);
- * }
- * };
- *
- * Rx.Observable.of(1, 2, 3) // Synchronously emits 1, 2, 3 and then completes.
- * .subscribe(sumObserver);
- *
- * // Logs:
- * // "Adding: 1"
- * // "Adding: 2"
- * // "Adding: 3"
- * // "Sum equals: 6"
- *
- *
- * @example <caption>Subscribe with functions</caption>
- * let sum = 0;
- *
- * Rx.Observable.of(1, 2, 3)
- * .subscribe(
- * function(value) {
- * console.log('Adding: ' + value);
- * sum = sum + value;
- * },
- * undefined,
- * function() {
- * console.log('Sum equals: ' + sum);
- * }
- * );
- *
- * // Logs:
- * // "Adding: 1"
- * // "Adding: 2"
- * // "Adding: 3"
- * // "Sum equals: 6"
- *
- *
- * @example <caption>Cancel a subscription</caption>
- * const subscription = Rx.Observable.interval(1000).subscribe(
- * num => console.log(num),
- * undefined,
- * () => console.log('completed!') // Will not be called, even
- * ); // when cancelling subscription
- *
- *
- * setTimeout(() => {
- * subscription.unsubscribe();
- * console.log('unsubscribed!');
- * }, 2500);
- *
- * // Logs:
- * // 0 after 1s
- * // 1 after 2s
- * // "unsubscribed!" after 2.5s
- *
- *
- * @param {Observer|Function} observerOrNext (optional) Either an observer with methods to be called,
- * or the first of three possible handlers, which is the handler for each value emitted from the subscribed
- * Observable.
- * @param {Function} error (optional) A handler for a terminal event resulting from an error. If no error handler is provided,
- * the error will be thrown as unhandled.
- * @param {Function} complete (optional) A handler for a terminal event resulting from successful completion.
- * @return {ISubscription} a subscription reference to the registered handlers
- * @method subscribe
- */
- subscribe(observerOrNext, error, complete) {
- const { operator } = this;
- const sink = toSubscriber(observerOrNext, error, complete);
- if (operator) {
- operator.call(sink, this.source);
- }
- else {
- sink.add(this.source || !sink.syncErrorThrowable ? this._subscribe(sink) : this._trySubscribe(sink));
- }
- if (sink.syncErrorThrowable) {
- sink.syncErrorThrowable = false;
- if (sink.syncErrorThrown) {
- throw sink.syncErrorValue;
- }
- }
- return sink;
- }
- _trySubscribe(sink) {
- try {
- return this._subscribe(sink);
- }
- catch (err) {
- sink.syncErrorThrown = true;
- sink.syncErrorValue = err;
- sink.error(err);
- }
- }
- /**
- * @method forEach
- * @param {Function} next a handler for each value emitted by the observable
- * @param {PromiseConstructor} [PromiseCtor] a constructor function used to instantiate the Promise
- * @return {Promise} a promise that either resolves on observable completion or
- * rejects with the handled error
- */
- forEach(next, PromiseCtor) {
- if (!PromiseCtor) {
- if (root.Rx && root.Rx.config && root.Rx.config.Promise) {
- PromiseCtor = root.Rx.config.Promise;
- }
- else if (root.Promise) {
- PromiseCtor = root.Promise;
- }
- }
- if (!PromiseCtor) {
- throw new Error('no Promise impl found');
- }
- return new PromiseCtor((resolve, reject) => {
- // Must be declared in a separate statement to avoid a RefernceError when
- // accessing subscription below in the closure due to Temporal Dead Zone.
- let subscription;
- subscription = this.subscribe((value) => {
- if (subscription) {
- // if there is a subscription, then we can surmise
- // the next handling is asynchronous. Any errors thrown
- // need to be rejected explicitly and unsubscribe must be
- // called manually
- try {
- next(value);
- }
- catch (err) {
- reject(err);
- subscription.unsubscribe();
- }
- }
- else {
- // if there is NO subscription, then we're getting a nexted
- // value synchronously during subscription. We can just call it.
- // If it errors, Observable's `subscribe` will ensure the
- // unsubscription logic is called, then synchronously rethrow the error.
- // After that, Promise will trap the error and send it
- // down the rejection path.
- next(value);
- }
- }, reject, resolve);
- });
- }
- /** @deprecated internal use only */ _subscribe(subscriber) {
- return this.source.subscribe(subscriber);
- }
- /**
- * An interop point defined by the es7-observable spec https://github.com/zenparsing/es-observable
- * @method Symbol.observable
- * @return {Observable} this instance of the observable
- */
- [Symbol_observable]() {
- return this;
- }
- /* tslint:enable:max-line-length */
- /**
- * Used to stitch together functional operators into a chain.
- * @method pipe
- * @return {Observable} the Observable result of all of the operators having
- * been called in the order they were passed in.
- *
- * @example
- *
- * import { map, filter, scan } from 'rxjs/operators';
- *
- * Rx.Observable.interval(1000)
- * .pipe(
- * filter(x => x % 2 === 0),
- * map(x => x + x),
- * scan((acc, x) => acc + x)
- * )
- * .subscribe(x => console.log(x))
- */
- pipe(...operations) {
- if (operations.length === 0) {
- return this;
- }
- return pipeFromArray(operations)(this);
- }
- /* tslint:enable:max-line-length */
- toPromise(PromiseCtor) {
- if (!PromiseCtor) {
- if (root.Rx && root.Rx.config && root.Rx.config.Promise) {
- PromiseCtor = root.Rx.config.Promise;
- }
- else if (root.Promise) {
- PromiseCtor = root.Promise;
- }
- }
- if (!PromiseCtor) {
- throw new Error('no Promise impl found');
- }
- return new PromiseCtor((resolve, reject) => {
- let value;
- this.subscribe((x) => value = x, (err) => reject(err), () => resolve(value));
- });
- }
- }
- // 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 cold Observable by calling the Observable constructor
- * @static true
- * @owner Observable
- * @method create
- * @param {Function} subscribe? the subscriber function to be passed to the Observable constructor
- * @return {Observable} a new cold observable
- */
- Observable.create = (subscribe) => {
- return new Observable(subscribe);
- };
- //# sourceMappingURL=Observable.js.map
|