feat(forEach): deprecating passing promise constructor

- Adds documentation
- Deprecates promise constructor

Author: benlesh

src/internal/Observable.ts

@@ -231,10 +231,95 @@ export class Observable<T> implements Subscribable<T> {
     }
   }
 
+  /**
+   * 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<void>;
+
+  /**
+   * 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<void>;
+
+  /**
+   * 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<void>;
+
   /**
    * @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
    */