From def4127bf1ef825a077c24504be9e4f1f1131937 Mon Sep 17 00:00:00 2001 From: Sonu Kapoor Date: Tue, 10 Dec 2019 09:34:32 -0500 Subject: [PATCH] fix(docs-infra): convert hard-coded `comparing-observables` examples into a proper mini-app (#34327) Previously, the examples in the `comparing-observables` guide were hard-coded. This made it impossible to test them and verify they are correct. This commit fixes this by converting them into a proper mini-app. In a subsequent commit, tests will be added to verify that the source code works as expected (and guard against regressions). Fixes #31024 PR Close #34327 --- .github/CODEOWNERS | 1 + .../comparing-observables/src/observables.ts | 40 +++++++ .../comparing-observables/src/promises.ts | 25 +++++ aio/content/guide/comparing-observables.md | 100 +++++++++--------- 4 files changed, 117 insertions(+), 49 deletions(-) create mode 100644 aio/content/examples/comparing-observables/src/observables.ts create mode 100644 aio/content/examples/comparing-observables/src/promises.ts diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 8aa92729d5..70b1c295a2 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -867,6 +867,7 @@ testing/** @angular/fw-test /aio/content/guide/observables.md @angular/fw-docs-observables @angular/framework-global-approvers @angular/framework-global-approvers-for-docs-only-changes /aio/content/examples/observables/** @angular/fw-docs-observables @angular/framework-global-approvers @angular/framework-global-approvers-for-docs-only-changes /aio/content/guide/comparing-observables.md @angular/fw-docs-observables @angular/framework-global-approvers @angular/framework-global-approvers-for-docs-only-changes +/aio/content/examples/comparing-observables/** @angular/fw-docs-observables @angular/framework-global-approvers @angular/framework-global-approvers-for-docs-only-changes /aio/content/guide/observables-in-angular.md @angular/fw-docs-observables @angular/framework-global-approvers @angular/framework-global-approvers-for-docs-only-changes /aio/content/examples/observables-in-angular/** @angular/fw-docs-observables @angular/framework-global-approvers @angular/framework-global-approvers-for-docs-only-changes /aio/content/guide/practical-observable-usage.md @angular/fw-docs-observables @angular/framework-global-approvers @angular/framework-global-approvers-for-docs-only-changes diff --git a/aio/content/examples/comparing-observables/src/observables.ts b/aio/content/examples/comparing-observables/src/observables.ts new file mode 100644 index 0000000000..f0e8c1a138 --- /dev/null +++ b/aio/content/examples/comparing-observables/src/observables.ts @@ -0,0 +1,40 @@ +import { map } from 'rxjs/operators'; +import { Observable } from 'rxjs'; + +// #docregion observable + +// declare a publishing operation +const observable = new Observable(observer => { + // Subscriber fn... +}); + +// initiate execution +observable.subscribe(() => { + // observer handles notifications +}); + +// #enddocregion observable + +// #docregion unsubscribe + +const subscription = observable.subscribe(() => { + // observer handles notifications +}); + +subscription.unsubscribe(); + +// #enddocregion unsubscribe + +// #docregion error + +observable.subscribe(() => { + throw Error('my error'); +}); + +// #enddocregion error + +// #docregion chain + +observable.pipe(map(v => 2 * v)); + +// #enddocregion chain diff --git a/aio/content/examples/comparing-observables/src/promises.ts b/aio/content/examples/comparing-observables/src/promises.ts new file mode 100644 index 0000000000..0ad68d99da --- /dev/null +++ b/aio/content/examples/comparing-observables/src/promises.ts @@ -0,0 +1,25 @@ +// #docregion promise +// initiate execution +const promise = new Promise((resolve, reject) => { + // Executer fn... +}); + +promise.then(value => { + // handle result here +}); + +// #enddocregion promise + +// #docregion chain + +promise.then(v => 2 * v); + +// #enddocregion chain + +// #docregion error + +promise.then(() => { + throw Error('my error'); +}); + +// #enddocregion error diff --git a/aio/content/guide/comparing-observables.md b/aio/content/guide/comparing-observables.md index 8179e43bfb..c3402b1644 100644 --- a/aio/content/guide/comparing-observables.md +++ b/aio/content/guide/comparing-observables.md @@ -21,48 +21,47 @@ Observables are often compared to promises. Here are some key differences: * Observables are not executed until a consumer subscribes. The `subscribe()` executes the defined behavior once, and it can be called again. Each subscription has its own computation. Resubscription causes recomputation of values. - -// declare a publishing operation -new Observable((observer) => { subscriber_fn }); -// initiate execution -observable.subscribe(() => { - // observer handles notifications -}); - + + * Promises execute immediately, and just once. The computation of the result is initiated when the promise is created. There is no way to restart work. All `then` clauses (subscriptions) share the same computation. - -// initiate execution -new Promise((resolve, reject) => { executer_fn }); -// handle return value -promise.then((value) => { - // handle result here -}); - + + ### Chaining * Observables differentiate between transformation function such as a map and subscription. Only subscription activates the subscriber function to start computing the values. - -observable.pipe(map((v) => 2*v)); - + + * Promises do not differentiate between the last `.then` clauses (equivalent to subscription) and intermediate `.then` clauses (equivalent to map). - -promise.then((v) => 2*v); - + + ### Cancellation * Observable subscriptions are cancellable. Unsubscribing removes the listener from receiving further values, and notifies the subscriber function to cancel work. - -const sub = obs.subscribe(...); -sub.unsubscribe(); - + + * Promises are not cancellable. @@ -70,19 +69,19 @@ sub.unsubscribe(); * Observable execution errors are delivered to the subscriber's error handler, and the subscriber automatically unsubscribes from the observable. - -obs.subscribe(() => { - throw Error('my error'); -}); - + + * Promises push errors to the child promises. - -promise.then(() => { - throw Error('my error'); -}); - + + ### Cheat sheet @@ -100,14 +99,16 @@ The following code snippets illustrate how the same kind of operation is defined Creation - 
new Observable((observer) => {
-    observer.next(123);
-  });
+ 
+new Observable((observer) => {
+  observer.next(123);
+});
- 
new Promise((resolve, reject) => {
-    resolve(123);
-  });
+ 
+new Promise((resolve, reject) => {
+  resolve(123);
+});
@@ -118,14 +119,16 @@ The following code snippets illustrate how the same kind of operation is defined Subscribe - 
sub = obs.subscribe((value) => {
-    console.log(value)
-  });
+ 
+sub = obs.subscribe((value) => {
+  console.log(value)
+});
- 
promise.then((value) => {
-    console.log(value);
-  });
+ 
+promise.then((value) => {
+  console.log(value);
+});
@@ -165,7 +168,6 @@ subscription.unsubscribe(); 
function handler(e) {
   console.log(‘Clicked’, e);
 }
-
 // Setup & begin listening
 button.addEventListener(‘click’, handler);
 // Stop listening