diff --git a/src/internal/Observable.ts b/src/internal/Observable.ts index c410e92697..41737d6e57 100644 --- a/src/internal/Observable.ts +++ b/src/internal/Observable.ts @@ -231,10 +231,95 @@ export class Observable implements Subscribable { } } + /** + * Subscribes to and nexts out each value of from the observable, passing values + * to the supplied next handler. Useful for async-await + * + * ### Example + * + * ```javascript + * async function foo() { + * console.log('start logging'); + * await interval(1000).pipe(take(3)) + * .forEach(x => console.log(x)); + * console.log('done logging'); + * } + * + * foo(); + * + * // Logs + * // "start logging" + * // 0 + * // 1 + * // 2 + * // "done logging" + * ``` + * @param next a handler for each value emitted by the observable + * @returns A promise that resolves when the observable completes or rejects if the + * observable errors. + */ + forEach(next: (value: T) => void): Promise; + + /** + * Subscribes to and nexts out each value of from the observable, passing values + * to the supplied next handler. The subscription may be cancelled with a provided + * subscription. When the provided subscription is unsubscribed, the operation is cancelled + * and the returned promise will reject with "Observable forEach unsubscribed" so that + * it can be handled in a try-catch block in async-await. + * + * ### Example + * + * ```js + * async function foo() { + * + * async function foo() { + * console.log('start logging'); + * + * const cancel = new Subscription(); + * setTimeout(() => cancel.unsubscribe(), 2500); + * + * try { + * await interval(1000).pipe(take(3)) + * .forEach(x => console.log(x), cancel); + * } catch (err) { + * console.log("ERROR: " + err.message); + * } + * + * console.log('done logging'); + * } + * + * foo(); + * + * // Logs + * // "start logging" + * // 0 + * // 1 + * // "ERROR: Observable forEach unsubscribed" + * // "done logging" + * } + * + * ``` + * + * @param next a handler for each value emitted by the observable + * @param cancelSubs a {@link Subscription} used like a cancellation token, that, + * when unsubscribed, will reject the returned promise with an error + * @returns A promise that resolves when the observable completes or rejects if the + * observable errors or is unsubscribed. + */ + forEach(next: (value: T) => void, cancelSubs: Subscription): Promise; + + /** + * Nexts out each value from the observable to the `next` handler, and returns a promise, + * created from a specified promise constructor that resolves on Observable completion, or + * rejects if there's an error. + * @deprecated use {@link config} to configure the Promise Constructor if you need to configure promises. + */ + forEach(next: (value: T) => void, promiseCtor: PromiseConstructorLike): Promise; + /** * @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 + * @param {PromiseConstructorLike|Subscription} [promiseCtorOrSubscription] a constructor function used to instantiate the Promise * @return {Promise} a promise that either resolves on observable completion or * rejects with the handled error */