feat(forEach): deprecating passing promise constructor

- Adds documentation
- Deprecates promise constructor

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
  */