From 44a4f2d507cf3e745dd4e6333eea1795caa78729 Mon Sep 17 00:00:00 2001 From: pmartin Date: Fri, 23 Dec 2016 18:47:01 +0100 Subject: [PATCH 1/3] docs(operators): examples for catch operator --- src/operator/catch.ts | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/src/operator/catch.ts b/src/operator/catch.ts index d24c8267f2..7f6ac169e2 100644 --- a/src/operator/catch.ts +++ b/src/operator/catch.ts @@ -7,6 +7,45 @@ import { subscribeToResult } from '../util/subscribeToResult'; /** * Catches errors on the observable to be handled by returning a new observable or throwing an error. + * + * @example Returns a different Observable in case of error + * + * let primary$ = Observable.of(1, 2, 3, 4, 5); + * let secondary$ = Observable.of('I', 'II', 'III', 'IV', 'V'); + * + * primary$ + * .map(n => { + * if (n == 4) + * throw 'four!'; + * return n; + * }) + * .catch(err => secondary$) + * .subscribe(x => console.log(x)); // -> 1, 2, 3, I, II, III, IV, V + * + * @example "Tries" the Observable again in case of error + * + * Observable.of(1, 2, 3, 4, 5) + * .map(n => { + * if (n === 4) + * throw 'four!'; + * return n; + * }) + * .catch((err, caught) => caught) + * .take(30) + * .subscribe(x => console.log(x)); // 1, 2, 3, 1, 2, 3, ... + * + * @example Throws a new error when the source Observable throws an error + * + * Observable.of(1, 2, 3, 4, 5) + * .map(n => { + * if (n == 4) + * throw 'four!'; + * return n; + * }) + * .catch(err => { throw 'error in source. Details: ' + err; }) + * .subscribe(x => console.log(x), + * err => console.log(err)); -> 1, 2, 3, error in source. Details: four! + * * @param {function} selector a function that takes as arguments `err`, which is the error, and `caught`, which * is the source observable, in case you'd like to "retry" that observable by returning it again. Whatever observable * is returned by the `selector` will be used to continue the observable chain. From 8348549147dfe44baba658f8adfc6a922e6ac944 Mon Sep 17 00:00:00 2001 From: Jay Phelps Date: Thu, 26 Jan 2017 17:55:36 -0800 Subject: [PATCH 2/3] docs(catch): minor changes to indention and wording --- src/operator/catch.ts | 60 ++++++++++++++++++++++++------------------- 1 file changed, 33 insertions(+), 27 deletions(-) diff --git a/src/operator/catch.ts b/src/operator/catch.ts index 7f6ac169e2..ab7aeed5d3 100644 --- a/src/operator/catch.ts +++ b/src/operator/catch.ts @@ -8,43 +8,49 @@ import { subscribeToResult } from '../util/subscribeToResult'; /** * Catches errors on the observable to be handled by returning a new observable or throwing an error. * - * @example Returns a different Observable in case of error + * @example Continues with a different Observable when there's an error * - * let primary$ = Observable.of(1, 2, 3, 4, 5); - * let secondary$ = Observable.of('I', 'II', 'III', 'IV', 'V'); - * - * primary$ - * .map(n => { - * if (n == 4) - * throw 'four!'; - * return n; - * }) - * .catch(err => secondary$) - * .subscribe(x => console.log(x)); // -> 1, 2, 3, I, II, III, IV, V + * Observable.of(1, 2, 3, 4, 5) + * .map(n => { + * if (n == 4) { + * throw 'four!'; + * } + * return n; + * }) + * .catch(err => Observable.of('I', 'II', 'III', 'IV', 'V')) + * .subscribe(x => console.log(x)); // -> 1, 2, 3, I, II, III, IV, V * - * @example "Tries" the Observable again in case of error + * @example Retries the caught source Observable again in case of error, similar to retry() operator * * Observable.of(1, 2, 3, 4, 5) - * .map(n => { - * if (n === 4) - * throw 'four!'; - * return n; - * }) - * .catch((err, caught) => caught) - * .take(30) - * .subscribe(x => console.log(x)); // 1, 2, 3, 1, 2, 3, ... + * .map(n => { + * if (n === 4) { + * throw 'four!'; + * } + * return n; + * }) + * .catch((err, caught) => caught) + * .take(30) + * .subscribe(x => console.log(x)); + * // 1, 2, 3, 1, 2, 3, ... * * @example Throws a new error when the source Observable throws an error * * Observable.of(1, 2, 3, 4, 5) * .map(n => { - * if (n == 4) - * throw 'four!'; - * return n; + * if (n == 4) { + * throw 'four!'; + * } + * return n; + * }) + * .catch(err => { + * throw 'error in source. Details: ' + err; * }) - * .catch(err => { throw 'error in source. Details: ' + err; }) - * .subscribe(x => console.log(x), - * err => console.log(err)); -> 1, 2, 3, error in source. Details: four! + * .subscribe( + * x => console.log(x), + * err => console.log(err) + * ); + * // 1, 2, 3, error in source. Details: four! * * @param {function} selector a function that takes as arguments `err`, which is the error, and `caught`, which * is the source observable, in case you'd like to "retry" that observable by returning it again. Whatever observable From d6b796750619ff2edf455ad51ba5db6796ce56b7 Mon Sep 17 00:00:00 2001 From: Jay Phelps Date: Thu, 26 Jan 2017 17:59:22 -0800 Subject: [PATCH 3/3] docs(catch): include marble diagram --- src/operator/catch.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/operator/catch.ts b/src/operator/catch.ts index ab7aeed5d3..f6e4fe74ab 100644 --- a/src/operator/catch.ts +++ b/src/operator/catch.ts @@ -8,6 +8,8 @@ import { subscribeToResult } from '../util/subscribeToResult'; /** * Catches errors on the observable to be handled by returning a new observable or throwing an error. * + * + * * @example Continues with a different Observable when there's an error * * Observable.of(1, 2, 3, 4, 5) @@ -18,7 +20,8 @@ import { subscribeToResult } from '../util/subscribeToResult'; * return n; * }) * .catch(err => Observable.of('I', 'II', 'III', 'IV', 'V')) - * .subscribe(x => console.log(x)); // -> 1, 2, 3, I, II, III, IV, V + * .subscribe(x => console.log(x)); + * // 1, 2, 3, I, II, III, IV, V * * @example Retries the caught source Observable again in case of error, similar to retry() operator *