Elgato_dark/angular
1
0
Fork 0
mirror of https://github.com/angular/angular synced 2026-05-24 09:28:37 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
angular/aio/content/guide/comparing-observables.md

138 lines
15 KiB
Markdown
Raw Normal View History

docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
# Observables compared to other techniques
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
You can often use observables instead of promises to deliver values asynchronously.
Similarly, observables can take the place of event handlers.
Finally, because observables deliver multiple values, you can use them where you might otherwise build and operate on arrays.
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
Observables behave somewhat differently from the alternative techniques in each of these situations, but offer some significant advantages.
Here are detailed comparisons of the differences.
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
## Observables compared to promises
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
Observables are often compared to promises.
Here are some key differences:
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: Migrate Observables guides & code examples to standalone (#51516) None of the guide pages mentions ngModules. Only `observables-in-angular` needed conversion to Standalone. However, some of the guide pages reflect old versions of RxJS, including signatures that are no longer valid. These have been corrected. More significantly, *the existing guide is pretty bad at explaining RxJS and its usage*. It was written (by me I think) in the very early days of Angular and Angular RxJS instruction. I've taught numerous "RxJS in Angular" classes since and learned from that experience what does and does not work with students. There was neither the time nor the charter to completely overhaul this guide. But this commit attempts to remove what flops with students and to bring the teaching closer to what seems more effectively. I hope reviewers agree that my revisions are an improvement. **Revised Overview** The overview doc, `observables.md`, had a few errors (ex: `next` is NOT REQUIRED) and deprecated patterns (you now must pass the Observer object to `subscribe`). More importantly, it was wildly overcomplicated and scary, especially when it got into multi-casting. Moved the multi-casting section to "RxJS Library" and rewrote it (with working example) for simplicity and context. I made other changes in an effort to make this an overview that is more comprehensive and more clear. I paid particular attention to the "Basic usage and terms" section. Finally, I relocated the "Naming conventions for observables" section here from `rx-library`. This is the section that describes the dollar-sign convention. It made more sense for it to be here. **Revised "RxJS Library" page and code** *RxJS no longer supports chaining* and hasn't for a very long time. Removed note in `rx-library.md` that suggested you could use operator chaining. The RxJS `pipe` discussion in the "Operators" section was just weird. Almost no one calls the `pipe` function. We certainly should *start* there. We should start with how people actually use operators - by adding them to the argument list of the `Observable.pipe()` method. I kept the original `pipe` function example but subordinated it in a "callout". Most readers will (and should) ignore it. `Subject` is a *critically important RxJS mechanism for creating custom observables*. It was completely missing from the list of observable creators on this guide page. So I added it to the "Observable creation functions" section of the guide and wrote an accompanying `MessageService` code sample (see the new `rx-library/app/` folder). The `MessageService` is a pretty common pattern in Angular apps - far more common than creating an observable from a counter or an event, two of the creation patterns currently on this page. This new section also afforded an opportunity to show how RxJS helps with building loosely coupled applications. We will soon be talking about Signals. Many will wonder whether and when they should still use RxJS. At least a partial answer is that RxJS is really good at progressively combining and enhancing streams of data as they cross component boundaries. Of course you can pass signals around; but they are not as rich in transformers as RxJS. This is where RxJS shines. **Revised "Comparing observables"** The Promises section in `comparing-observables.md` had many errors and misleading remarks. The comparison of error handling was especially egregious; the code example for that was nonsense. The "Chain" sub-section was really about transforming values. It also failed to demonstrate chaining promise `.then`s. Reworked these sub-sections and improved the code samples to match. PR Close #51516
2023-08-25 09:06:52 +00:00
* Observable execution is deferred; computation does not start until subscription.
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
Promises execute immediately on creation.
This makes observables useful for defining recipes that can be run whenever you need the result.
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
* Observables provide many values.
Promises provide one.
This makes observables useful for getting multiple values over time.
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: Migrate Observables guides & code examples to standalone (#51516) None of the guide pages mentions ngModules. Only `observables-in-angular` needed conversion to Standalone. However, some of the guide pages reflect old versions of RxJS, including signatures that are no longer valid. These have been corrected. More significantly, *the existing guide is pretty bad at explaining RxJS and its usage*. It was written (by me I think) in the very early days of Angular and Angular RxJS instruction. I've taught numerous "RxJS in Angular" classes since and learned from that experience what does and does not work with students. There was neither the time nor the charter to completely overhaul this guide. But this commit attempts to remove what flops with students and to bring the teaching closer to what seems more effectively. I hope reviewers agree that my revisions are an improvement. **Revised Overview** The overview doc, `observables.md`, had a few errors (ex: `next` is NOT REQUIRED) and deprecated patterns (you now must pass the Observer object to `subscribe`). More importantly, it was wildly overcomplicated and scary, especially when it got into multi-casting. Moved the multi-casting section to "RxJS Library" and rewrote it (with working example) for simplicity and context. I made other changes in an effort to make this an overview that is more comprehensive and more clear. I paid particular attention to the "Basic usage and terms" section. Finally, I relocated the "Naming conventions for observables" section here from `rx-library`. This is the section that describes the dollar-sign convention. It made more sense for it to be here. **Revised "RxJS Library" page and code** *RxJS no longer supports chaining* and hasn't for a very long time. Removed note in `rx-library.md` that suggested you could use operator chaining. The RxJS `pipe` discussion in the "Operators" section was just weird. Almost no one calls the `pipe` function. We certainly should *start* there. We should start with how people actually use operators - by adding them to the argument list of the `Observable.pipe()` method. I kept the original `pipe` function example but subordinated it in a "callout". Most readers will (and should) ignore it. `Subject` is a *critically important RxJS mechanism for creating custom observables*. It was completely missing from the list of observable creators on this guide page. So I added it to the "Observable creation functions" section of the guide and wrote an accompanying `MessageService` code sample (see the new `rx-library/app/` folder). The `MessageService` is a pretty common pattern in Angular apps - far more common than creating an observable from a counter or an event, two of the creation patterns currently on this page. This new section also afforded an opportunity to show how RxJS helps with building loosely coupled applications. We will soon be talking about Signals. Many will wonder whether and when they should still use RxJS. At least a partial answer is that RxJS is really good at progressively combining and enhancing streams of data as they cross component boundaries. Of course you can pass signals around; but they are not as rich in transformers as RxJS. This is where RxJS shines. **Revised "Comparing observables"** The Promises section in `comparing-observables.md` had many errors and misleading remarks. The comparison of error handling was especially egregious; the code example for that was nonsense. The "Chain" sub-section was really about transforming values. It also failed to demonstrate chaining promise `.then`s. Reworked these sub-sections and improved the code samples to match. PR Close #51516
2023-08-25 09:06:52 +00:00
* Observable values can be transformed with operators as well as in the subscription. The rich variety of RxJS operators observables enables complex transformations that can be passed around to other parts of the system, without causing the work to be executed prematurely.
Promises have `.then()` clauses which can transform values but only after the work is done.
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: Migrate Observables guides & code examples to standalone (#51516) None of the guide pages mentions ngModules. Only `observables-in-angular` needed conversion to Standalone. However, some of the guide pages reflect old versions of RxJS, including signatures that are no longer valid. These have been corrected. More significantly, *the existing guide is pretty bad at explaining RxJS and its usage*. It was written (by me I think) in the very early days of Angular and Angular RxJS instruction. I've taught numerous "RxJS in Angular" classes since and learned from that experience what does and does not work with students. There was neither the time nor the charter to completely overhaul this guide. But this commit attempts to remove what flops with students and to bring the teaching closer to what seems more effectively. I hope reviewers agree that my revisions are an improvement. **Revised Overview** The overview doc, `observables.md`, had a few errors (ex: `next` is NOT REQUIRED) and deprecated patterns (you now must pass the Observer object to `subscribe`). More importantly, it was wildly overcomplicated and scary, especially when it got into multi-casting. Moved the multi-casting section to "RxJS Library" and rewrote it (with working example) for simplicity and context. I made other changes in an effort to make this an overview that is more comprehensive and more clear. I paid particular attention to the "Basic usage and terms" section. Finally, I relocated the "Naming conventions for observables" section here from `rx-library`. This is the section that describes the dollar-sign convention. It made more sense for it to be here. **Revised "RxJS Library" page and code** *RxJS no longer supports chaining* and hasn't for a very long time. Removed note in `rx-library.md` that suggested you could use operator chaining. The RxJS `pipe` discussion in the "Operators" section was just weird. Almost no one calls the `pipe` function. We certainly should *start* there. We should start with how people actually use operators - by adding them to the argument list of the `Observable.pipe()` method. I kept the original `pipe` function example but subordinated it in a "callout". Most readers will (and should) ignore it. `Subject` is a *critically important RxJS mechanism for creating custom observables*. It was completely missing from the list of observable creators on this guide page. So I added it to the "Observable creation functions" section of the guide and wrote an accompanying `MessageService` code sample (see the new `rx-library/app/` folder). The `MessageService` is a pretty common pattern in Angular apps - far more common than creating an observable from a counter or an event, two of the creation patterns currently on this page. This new section also afforded an opportunity to show how RxJS helps with building loosely coupled applications. We will soon be talking about Signals. Many will wonder whether and when they should still use RxJS. At least a partial answer is that RxJS is really good at progressively combining and enhancing streams of data as they cross component boundaries. Of course you can pass signals around; but they are not as rich in transformers as RxJS. This is where RxJS shines. **Revised "Comparing observables"** The Promises section in `comparing-observables.md` had many errors and misleading remarks. The comparison of error handling was especially egregious; the code example for that was nonsense. The "Chain" sub-section was really about transforming values. It also failed to demonstrate chaining promise `.then`s. Reworked these sub-sections and improved the code samples to match. PR Close #51516
2023-08-25 09:06:52 +00:00
* Observables and Promises handle errors differently with roughly comparable efficacy.
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: Migrate Observables guides & code examples to standalone (#51516) None of the guide pages mentions ngModules. Only `observables-in-angular` needed conversion to Standalone. However, some of the guide pages reflect old versions of RxJS, including signatures that are no longer valid. These have been corrected. More significantly, *the existing guide is pretty bad at explaining RxJS and its usage*. It was written (by me I think) in the very early days of Angular and Angular RxJS instruction. I've taught numerous "RxJS in Angular" classes since and learned from that experience what does and does not work with students. There was neither the time nor the charter to completely overhaul this guide. But this commit attempts to remove what flops with students and to bring the teaching closer to what seems more effectively. I hope reviewers agree that my revisions are an improvement. **Revised Overview** The overview doc, `observables.md`, had a few errors (ex: `next` is NOT REQUIRED) and deprecated patterns (you now must pass the Observer object to `subscribe`). More importantly, it was wildly overcomplicated and scary, especially when it got into multi-casting. Moved the multi-casting section to "RxJS Library" and rewrote it (with working example) for simplicity and context. I made other changes in an effort to make this an overview that is more comprehensive and more clear. I paid particular attention to the "Basic usage and terms" section. Finally, I relocated the "Naming conventions for observables" section here from `rx-library`. This is the section that describes the dollar-sign convention. It made more sense for it to be here. **Revised "RxJS Library" page and code** *RxJS no longer supports chaining* and hasn't for a very long time. Removed note in `rx-library.md` that suggested you could use operator chaining. The RxJS `pipe` discussion in the "Operators" section was just weird. Almost no one calls the `pipe` function. We certainly should *start* there. We should start with how people actually use operators - by adding them to the argument list of the `Observable.pipe()` method. I kept the original `pipe` function example but subordinated it in a "callout". Most readers will (and should) ignore it. `Subject` is a *critically important RxJS mechanism for creating custom observables*. It was completely missing from the list of observable creators on this guide page. So I added it to the "Observable creation functions" section of the guide and wrote an accompanying `MessageService` code sample (see the new `rx-library/app/` folder). The `MessageService` is a pretty common pattern in Angular apps - far more common than creating an observable from a counter or an event, two of the creation patterns currently on this page. This new section also afforded an opportunity to show how RxJS helps with building loosely coupled applications. We will soon be talking about Signals. Many will wonder whether and when they should still use RxJS. At least a partial answer is that RxJS is really good at progressively combining and enhancing streams of data as they cross component boundaries. Of course you can pass signals around; but they are not as rich in transformers as RxJS. This is where RxJS shines. **Revised "Comparing observables"** The Promises section in `comparing-observables.md` had many errors and misleading remarks. The comparison of error handling was especially egregious; the code example for that was nonsense. The "Chain" sub-section was really about transforming values. It also failed to demonstrate chaining promise `.then`s. Reworked these sub-sections and improved the code samples to match. PR Close #51516
2023-08-25 09:06:52 +00:00
The following sections explore these points in greater detail.
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
### Creation and subscription
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
* Observables are not executed until a consumer subscribes.
docs: Migrate Observables guides & code examples to standalone (#51516) None of the guide pages mentions ngModules. Only `observables-in-angular` needed conversion to Standalone. However, some of the guide pages reflect old versions of RxJS, including signatures that are no longer valid. These have been corrected. More significantly, *the existing guide is pretty bad at explaining RxJS and its usage*. It was written (by me I think) in the very early days of Angular and Angular RxJS instruction. I've taught numerous "RxJS in Angular" classes since and learned from that experience what does and does not work with students. There was neither the time nor the charter to completely overhaul this guide. But this commit attempts to remove what flops with students and to bring the teaching closer to what seems more effectively. I hope reviewers agree that my revisions are an improvement. **Revised Overview** The overview doc, `observables.md`, had a few errors (ex: `next` is NOT REQUIRED) and deprecated patterns (you now must pass the Observer object to `subscribe`). More importantly, it was wildly overcomplicated and scary, especially when it got into multi-casting. Moved the multi-casting section to "RxJS Library" and rewrote it (with working example) for simplicity and context. I made other changes in an effort to make this an overview that is more comprehensive and more clear. I paid particular attention to the "Basic usage and terms" section. Finally, I relocated the "Naming conventions for observables" section here from `rx-library`. This is the section that describes the dollar-sign convention. It made more sense for it to be here. **Revised "RxJS Library" page and code** *RxJS no longer supports chaining* and hasn't for a very long time. Removed note in `rx-library.md` that suggested you could use operator chaining. The RxJS `pipe` discussion in the "Operators" section was just weird. Almost no one calls the `pipe` function. We certainly should *start* there. We should start with how people actually use operators - by adding them to the argument list of the `Observable.pipe()` method. I kept the original `pipe` function example but subordinated it in a "callout". Most readers will (and should) ignore it. `Subject` is a *critically important RxJS mechanism for creating custom observables*. It was completely missing from the list of observable creators on this guide page. So I added it to the "Observable creation functions" section of the guide and wrote an accompanying `MessageService` code sample (see the new `rx-library/app/` folder). The `MessageService` is a pretty common pattern in Angular apps - far more common than creating an observable from a counter or an event, two of the creation patterns currently on this page. This new section also afforded an opportunity to show how RxJS helps with building loosely coupled applications. We will soon be talking about Signals. Many will wonder whether and when they should still use RxJS. At least a partial answer is that RxJS is really good at progressively combining and enhancing streams of data as they cross component boundaries. Of course you can pass signals around; but they are not as rich in transformers as RxJS. This is where RxJS shines. **Revised "Comparing observables"** The Promises section in `comparing-observables.md` had many errors and misleading remarks. The comparison of error handling was especially egregious; the code example for that was nonsense. The "Chain" sub-section was really about transforming values. It also failed to demonstrate chaining promise `.then`s. Reworked these sub-sections and improved the code samples to match. PR Close #51516
2023-08-25 09:06:52 +00:00
The `subscribe()` initiates the observable's behavior which may execute synchronously or asynchronously and could produce one, many or no values over time.
For "unicast" observables, if you call `subscribe` again, you get a new observable execution with its own production of values.
Calling `subscribe` on a "multicast" observable (e.g., `Subject` or an observable with the `shareReplay` operator) simply adds another *subscriber* to the already running observable.
The `subscribe` call is the end-of-the-line. You cannot continue to manipulate values after `subscribe(...)`.
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
<code-example header="src/observables.ts (observable)" path="comparing-observables/src/observables.ts" region="observable"></code-example>
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: Migrate Observables guides & code examples to standalone (#51516) None of the guide pages mentions ngModules. Only `observables-in-angular` needed conversion to Standalone. However, some of the guide pages reflect old versions of RxJS, including signatures that are no longer valid. These have been corrected. More significantly, *the existing guide is pretty bad at explaining RxJS and its usage*. It was written (by me I think) in the very early days of Angular and Angular RxJS instruction. I've taught numerous "RxJS in Angular" classes since and learned from that experience what does and does not work with students. There was neither the time nor the charter to completely overhaul this guide. But this commit attempts to remove what flops with students and to bring the teaching closer to what seems more effectively. I hope reviewers agree that my revisions are an improvement. **Revised Overview** The overview doc, `observables.md`, had a few errors (ex: `next` is NOT REQUIRED) and deprecated patterns (you now must pass the Observer object to `subscribe`). More importantly, it was wildly overcomplicated and scary, especially when it got into multi-casting. Moved the multi-casting section to "RxJS Library" and rewrote it (with working example) for simplicity and context. I made other changes in an effort to make this an overview that is more comprehensive and more clear. I paid particular attention to the "Basic usage and terms" section. Finally, I relocated the "Naming conventions for observables" section here from `rx-library`. This is the section that describes the dollar-sign convention. It made more sense for it to be here. **Revised "RxJS Library" page and code** *RxJS no longer supports chaining* and hasn't for a very long time. Removed note in `rx-library.md` that suggested you could use operator chaining. The RxJS `pipe` discussion in the "Operators" section was just weird. Almost no one calls the `pipe` function. We certainly should *start* there. We should start with how people actually use operators - by adding them to the argument list of the `Observable.pipe()` method. I kept the original `pipe` function example but subordinated it in a "callout". Most readers will (and should) ignore it. `Subject` is a *critically important RxJS mechanism for creating custom observables*. It was completely missing from the list of observable creators on this guide page. So I added it to the "Observable creation functions" section of the guide and wrote an accompanying `MessageService` code sample (see the new `rx-library/app/` folder). The `MessageService` is a pretty common pattern in Angular apps - far more common than creating an observable from a counter or an event, two of the creation patterns currently on this page. This new section also afforded an opportunity to show how RxJS helps with building loosely coupled applications. We will soon be talking about Signals. Many will wonder whether and when they should still use RxJS. At least a partial answer is that RxJS is really good at progressively combining and enhancing streams of data as they cross component boundaries. Of course you can pass signals around; but they are not as rich in transformers as RxJS. This is where RxJS shines. **Revised "Comparing observables"** The Promises section in `comparing-observables.md` had many errors and misleading remarks. The comparison of error handling was especially egregious; the code example for that was nonsense. The "Chain" sub-section was really about transforming values. It also failed to demonstrate chaining promise `.then`s. Reworked these sub-sections and improved the code samples to match. PR Close #51516
2023-08-25 09:06:52 +00:00
* Promises execute immediately when they are created. There is no deferred execution and, therefore, no equivalent to `subscribe()`.
A promise is always asynchronous and can produce at most one value.
There is no way to restart a promise and it retains its result value for the life of the promise.
You can chain additional `then` clauses to a promise.
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
<code-example header="src/promises.ts (promise)" path="comparing-observables/src/promises.ts" region="promise"></code-example>
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: Migrate Observables guides & code examples to standalone (#51516) None of the guide pages mentions ngModules. Only `observables-in-angular` needed conversion to Standalone. However, some of the guide pages reflect old versions of RxJS, including signatures that are no longer valid. These have been corrected. More significantly, *the existing guide is pretty bad at explaining RxJS and its usage*. It was written (by me I think) in the very early days of Angular and Angular RxJS instruction. I've taught numerous "RxJS in Angular" classes since and learned from that experience what does and does not work with students. There was neither the time nor the charter to completely overhaul this guide. But this commit attempts to remove what flops with students and to bring the teaching closer to what seems more effectively. I hope reviewers agree that my revisions are an improvement. **Revised Overview** The overview doc, `observables.md`, had a few errors (ex: `next` is NOT REQUIRED) and deprecated patterns (you now must pass the Observer object to `subscribe`). More importantly, it was wildly overcomplicated and scary, especially when it got into multi-casting. Moved the multi-casting section to "RxJS Library" and rewrote it (with working example) for simplicity and context. I made other changes in an effort to make this an overview that is more comprehensive and more clear. I paid particular attention to the "Basic usage and terms" section. Finally, I relocated the "Naming conventions for observables" section here from `rx-library`. This is the section that describes the dollar-sign convention. It made more sense for it to be here. **Revised "RxJS Library" page and code** *RxJS no longer supports chaining* and hasn't for a very long time. Removed note in `rx-library.md` that suggested you could use operator chaining. The RxJS `pipe` discussion in the "Operators" section was just weird. Almost no one calls the `pipe` function. We certainly should *start* there. We should start with how people actually use operators - by adding them to the argument list of the `Observable.pipe()` method. I kept the original `pipe` function example but subordinated it in a "callout". Most readers will (and should) ignore it. `Subject` is a *critically important RxJS mechanism for creating custom observables*. It was completely missing from the list of observable creators on this guide page. So I added it to the "Observable creation functions" section of the guide and wrote an accompanying `MessageService` code sample (see the new `rx-library/app/` folder). The `MessageService` is a pretty common pattern in Angular apps - far more common than creating an observable from a counter or an event, two of the creation patterns currently on this page. This new section also afforded an opportunity to show how RxJS helps with building loosely coupled applications. We will soon be talking about Signals. Many will wonder whether and when they should still use RxJS. At least a partial answer is that RxJS is really good at progressively combining and enhancing streams of data as they cross component boundaries. Of course you can pass signals around; but they are not as rich in transformers as RxJS. This is where RxJS shines. **Revised "Comparing observables"** The Promises section in `comparing-observables.md` had many errors and misleading remarks. The comparison of error handling was especially egregious; the code example for that was nonsense. The "Chain" sub-section was really about transforming values. It also failed to demonstrate chaining promise `.then`s. Reworked these sub-sections and improved the code samples to match. PR Close #51516
2023-08-25 09:06:52 +00:00
<a id="chaining"></a>
### Transformations
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: Migrate Observables guides & code examples to standalone (#51516) None of the guide pages mentions ngModules. Only `observables-in-angular` needed conversion to Standalone. However, some of the guide pages reflect old versions of RxJS, including signatures that are no longer valid. These have been corrected. More significantly, *the existing guide is pretty bad at explaining RxJS and its usage*. It was written (by me I think) in the very early days of Angular and Angular RxJS instruction. I've taught numerous "RxJS in Angular" classes since and learned from that experience what does and does not work with students. There was neither the time nor the charter to completely overhaul this guide. But this commit attempts to remove what flops with students and to bring the teaching closer to what seems more effectively. I hope reviewers agree that my revisions are an improvement. **Revised Overview** The overview doc, `observables.md`, had a few errors (ex: `next` is NOT REQUIRED) and deprecated patterns (you now must pass the Observer object to `subscribe`). More importantly, it was wildly overcomplicated and scary, especially when it got into multi-casting. Moved the multi-casting section to "RxJS Library" and rewrote it (with working example) for simplicity and context. I made other changes in an effort to make this an overview that is more comprehensive and more clear. I paid particular attention to the "Basic usage and terms" section. Finally, I relocated the "Naming conventions for observables" section here from `rx-library`. This is the section that describes the dollar-sign convention. It made more sense for it to be here. **Revised "RxJS Library" page and code** *RxJS no longer supports chaining* and hasn't for a very long time. Removed note in `rx-library.md` that suggested you could use operator chaining. The RxJS `pipe` discussion in the "Operators" section was just weird. Almost no one calls the `pipe` function. We certainly should *start* there. We should start with how people actually use operators - by adding them to the argument list of the `Observable.pipe()` method. I kept the original `pipe` function example but subordinated it in a "callout". Most readers will (and should) ignore it. `Subject` is a *critically important RxJS mechanism for creating custom observables*. It was completely missing from the list of observable creators on this guide page. So I added it to the "Observable creation functions" section of the guide and wrote an accompanying `MessageService` code sample (see the new `rx-library/app/` folder). The `MessageService` is a pretty common pattern in Angular apps - far more common than creating an observable from a counter or an event, two of the creation patterns currently on this page. This new section also afforded an opportunity to show how RxJS helps with building loosely coupled applications. We will soon be talking about Signals. Many will wonder whether and when they should still use RxJS. At least a partial answer is that RxJS is really good at progressively combining and enhancing streams of data as they cross component boundaries. Of course you can pass signals around; but they are not as rich in transformers as RxJS. This is where RxJS shines. **Revised "Comparing observables"** The Promises section in `comparing-observables.md` had many errors and misleading remarks. The comparison of error handling was especially egregious; the code example for that was nonsense. The "Chain" sub-section was really about transforming values. It also failed to demonstrate chaining promise `.then`s. Reworked these sub-sections and improved the code samples to match. PR Close #51516
2023-08-25 09:06:52 +00:00
* Developers can transform values both in the *subscription* and in piped *operators*. There are large number of RxJS operators to suit many complex scenarios, including numerous ways to combine and split observables.
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: Migrate Observables guides & code examples to standalone (#51516) None of the guide pages mentions ngModules. Only `observables-in-angular` needed conversion to Standalone. However, some of the guide pages reflect old versions of RxJS, including signatures that are no longer valid. These have been corrected. More significantly, *the existing guide is pretty bad at explaining RxJS and its usage*. It was written (by me I think) in the very early days of Angular and Angular RxJS instruction. I've taught numerous "RxJS in Angular" classes since and learned from that experience what does and does not work with students. There was neither the time nor the charter to completely overhaul this guide. But this commit attempts to remove what flops with students and to bring the teaching closer to what seems more effectively. I hope reviewers agree that my revisions are an improvement. **Revised Overview** The overview doc, `observables.md`, had a few errors (ex: `next` is NOT REQUIRED) and deprecated patterns (you now must pass the Observer object to `subscribe`). More importantly, it was wildly overcomplicated and scary, especially when it got into multi-casting. Moved the multi-casting section to "RxJS Library" and rewrote it (with working example) for simplicity and context. I made other changes in an effort to make this an overview that is more comprehensive and more clear. I paid particular attention to the "Basic usage and terms" section. Finally, I relocated the "Naming conventions for observables" section here from `rx-library`. This is the section that describes the dollar-sign convention. It made more sense for it to be here. **Revised "RxJS Library" page and code** *RxJS no longer supports chaining* and hasn't for a very long time. Removed note in `rx-library.md` that suggested you could use operator chaining. The RxJS `pipe` discussion in the "Operators" section was just weird. Almost no one calls the `pipe` function. We certainly should *start* there. We should start with how people actually use operators - by adding them to the argument list of the `Observable.pipe()` method. I kept the original `pipe` function example but subordinated it in a "callout". Most readers will (and should) ignore it. `Subject` is a *critically important RxJS mechanism for creating custom observables*. It was completely missing from the list of observable creators on this guide page. So I added it to the "Observable creation functions" section of the guide and wrote an accompanying `MessageService` code sample (see the new `rx-library/app/` folder). The `MessageService` is a pretty common pattern in Angular apps - far more common than creating an observable from a counter or an event, two of the creation patterns currently on this page. This new section also afforded an opportunity to show how RxJS helps with building loosely coupled applications. We will soon be talking about Signals. Many will wonder whether and when they should still use RxJS. At least a partial answer is that RxJS is really good at progressively combining and enhancing streams of data as they cross component boundaries. Of course you can pass signals around; but they are not as rich in transformers as RxJS. This is where RxJS shines. **Revised "Comparing observables"** The Promises section in `comparing-observables.md` had many errors and misleading remarks. The comparison of error handling was especially egregious; the code example for that was nonsense. The "Chain" sub-section was really about transforming values. It also failed to demonstrate chaining promise `.then`s. Reworked these sub-sections and improved the code samples to match. PR Close #51516
2023-08-25 09:06:52 +00:00
<code-example header="src/observables.ts (operators and multiple values)" path="comparing-observables/src/observables.ts" region="operators"></code-example>
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: Migrate Observables guides & code examples to standalone (#51516) None of the guide pages mentions ngModules. Only `observables-in-angular` needed conversion to Standalone. However, some of the guide pages reflect old versions of RxJS, including signatures that are no longer valid. These have been corrected. More significantly, *the existing guide is pretty bad at explaining RxJS and its usage*. It was written (by me I think) in the very early days of Angular and Angular RxJS instruction. I've taught numerous "RxJS in Angular" classes since and learned from that experience what does and does not work with students. There was neither the time nor the charter to completely overhaul this guide. But this commit attempts to remove what flops with students and to bring the teaching closer to what seems more effectively. I hope reviewers agree that my revisions are an improvement. **Revised Overview** The overview doc, `observables.md`, had a few errors (ex: `next` is NOT REQUIRED) and deprecated patterns (you now must pass the Observer object to `subscribe`). More importantly, it was wildly overcomplicated and scary, especially when it got into multi-casting. Moved the multi-casting section to "RxJS Library" and rewrote it (with working example) for simplicity and context. I made other changes in an effort to make this an overview that is more comprehensive and more clear. I paid particular attention to the "Basic usage and terms" section. Finally, I relocated the "Naming conventions for observables" section here from `rx-library`. This is the section that describes the dollar-sign convention. It made more sense for it to be here. **Revised "RxJS Library" page and code** *RxJS no longer supports chaining* and hasn't for a very long time. Removed note in `rx-library.md` that suggested you could use operator chaining. The RxJS `pipe` discussion in the "Operators" section was just weird. Almost no one calls the `pipe` function. We certainly should *start* there. We should start with how people actually use operators - by adding them to the argument list of the `Observable.pipe()` method. I kept the original `pipe` function example but subordinated it in a "callout". Most readers will (and should) ignore it. `Subject` is a *critically important RxJS mechanism for creating custom observables*. It was completely missing from the list of observable creators on this guide page. So I added it to the "Observable creation functions" section of the guide and wrote an accompanying `MessageService` code sample (see the new `rx-library/app/` folder). The `MessageService` is a pretty common pattern in Angular apps - far more common than creating an observable from a counter or an event, two of the creation patterns currently on this page. This new section also afforded an opportunity to show how RxJS helps with building loosely coupled applications. We will soon be talking about Signals. Many will wonder whether and when they should still use RxJS. At least a partial answer is that RxJS is really good at progressively combining and enhancing streams of data as they cross component boundaries. Of course you can pass signals around; but they are not as rich in transformers as RxJS. This is where RxJS shines. **Revised "Comparing observables"** The Promises section in `comparing-observables.md` had many errors and misleading remarks. The comparison of error handling was especially egregious; the code example for that was nonsense. The "Chain" sub-section was really about transforming values. It also failed to demonstrate chaining promise `.then`s. Reworked these sub-sections and improved the code samples to match. PR Close #51516
2023-08-25 09:06:52 +00:00
* Promises do not have an equivalent to `subscribe()`. You can transform the emitted value of a promise through one or more `.then` clauses. Promises have a small set of combiners (e.g., `all`, `any`, `race`).
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: Migrate Observables guides & code examples to standalone (#51516) None of the guide pages mentions ngModules. Only `observables-in-angular` needed conversion to Standalone. However, some of the guide pages reflect old versions of RxJS, including signatures that are no longer valid. These have been corrected. More significantly, *the existing guide is pretty bad at explaining RxJS and its usage*. It was written (by me I think) in the very early days of Angular and Angular RxJS instruction. I've taught numerous "RxJS in Angular" classes since and learned from that experience what does and does not work with students. There was neither the time nor the charter to completely overhaul this guide. But this commit attempts to remove what flops with students and to bring the teaching closer to what seems more effectively. I hope reviewers agree that my revisions are an improvement. **Revised Overview** The overview doc, `observables.md`, had a few errors (ex: `next` is NOT REQUIRED) and deprecated patterns (you now must pass the Observer object to `subscribe`). More importantly, it was wildly overcomplicated and scary, especially when it got into multi-casting. Moved the multi-casting section to "RxJS Library" and rewrote it (with working example) for simplicity and context. I made other changes in an effort to make this an overview that is more comprehensive and more clear. I paid particular attention to the "Basic usage and terms" section. Finally, I relocated the "Naming conventions for observables" section here from `rx-library`. This is the section that describes the dollar-sign convention. It made more sense for it to be here. **Revised "RxJS Library" page and code** *RxJS no longer supports chaining* and hasn't for a very long time. Removed note in `rx-library.md` that suggested you could use operator chaining. The RxJS `pipe` discussion in the "Operators" section was just weird. Almost no one calls the `pipe` function. We certainly should *start* there. We should start with how people actually use operators - by adding them to the argument list of the `Observable.pipe()` method. I kept the original `pipe` function example but subordinated it in a "callout". Most readers will (and should) ignore it. `Subject` is a *critically important RxJS mechanism for creating custom observables*. It was completely missing from the list of observable creators on this guide page. So I added it to the "Observable creation functions" section of the guide and wrote an accompanying `MessageService` code sample (see the new `rx-library/app/` folder). The `MessageService` is a pretty common pattern in Angular apps - far more common than creating an observable from a counter or an event, two of the creation patterns currently on this page. This new section also afforded an opportunity to show how RxJS helps with building loosely coupled applications. We will soon be talking about Signals. Many will wonder whether and when they should still use RxJS. At least a partial answer is that RxJS is really good at progressively combining and enhancing streams of data as they cross component boundaries. Of course you can pass signals around; but they are not as rich in transformers as RxJS. This is where RxJS shines. **Revised "Comparing observables"** The Promises section in `comparing-observables.md` had many errors and misleading remarks. The comparison of error handling was especially egregious; the code example for that was nonsense. The "Chain" sub-section was really about transforming values. It also failed to demonstrate chaining promise `.then`s. Reworked these sub-sections and improved the code samples to match. PR Close #51516
2023-08-25 09:06:52 +00:00
<code-example header="src/promises.ts (chained .then)" path="comparing-observables/src/promises.ts" region="chain"></code-example>
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
### Cancellation
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
* Observable subscriptions are cancellable.
Unsubscribing removes the listener from receiving further values, and notifies the subscriber function to cancel work.
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
<code-example header="src/observables.ts (unsubscribe)" path="comparing-observables/src/observables.ts" region="unsubscribe"></code-example>
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
* Promises are not cancellable.
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
### Error handling
docs: Migrate Observables guides & code examples to standalone (#51516) None of the guide pages mentions ngModules. Only `observables-in-angular` needed conversion to Standalone. However, some of the guide pages reflect old versions of RxJS, including signatures that are no longer valid. These have been corrected. More significantly, *the existing guide is pretty bad at explaining RxJS and its usage*. It was written (by me I think) in the very early days of Angular and Angular RxJS instruction. I've taught numerous "RxJS in Angular" classes since and learned from that experience what does and does not work with students. There was neither the time nor the charter to completely overhaul this guide. But this commit attempts to remove what flops with students and to bring the teaching closer to what seems more effectively. I hope reviewers agree that my revisions are an improvement. **Revised Overview** The overview doc, `observables.md`, had a few errors (ex: `next` is NOT REQUIRED) and deprecated patterns (you now must pass the Observer object to `subscribe`). More importantly, it was wildly overcomplicated and scary, especially when it got into multi-casting. Moved the multi-casting section to "RxJS Library" and rewrote it (with working example) for simplicity and context. I made other changes in an effort to make this an overview that is more comprehensive and more clear. I paid particular attention to the "Basic usage and terms" section. Finally, I relocated the "Naming conventions for observables" section here from `rx-library`. This is the section that describes the dollar-sign convention. It made more sense for it to be here. **Revised "RxJS Library" page and code** *RxJS no longer supports chaining* and hasn't for a very long time. Removed note in `rx-library.md` that suggested you could use operator chaining. The RxJS `pipe` discussion in the "Operators" section was just weird. Almost no one calls the `pipe` function. We certainly should *start* there. We should start with how people actually use operators - by adding them to the argument list of the `Observable.pipe()` method. I kept the original `pipe` function example but subordinated it in a "callout". Most readers will (and should) ignore it. `Subject` is a *critically important RxJS mechanism for creating custom observables*. It was completely missing from the list of observable creators on this guide page. So I added it to the "Observable creation functions" section of the guide and wrote an accompanying `MessageService` code sample (see the new `rx-library/app/` folder). The `MessageService` is a pretty common pattern in Angular apps - far more common than creating an observable from a counter or an event, two of the creation patterns currently on this page. This new section also afforded an opportunity to show how RxJS helps with building loosely coupled applications. We will soon be talking about Signals. Many will wonder whether and when they should still use RxJS. At least a partial answer is that RxJS is really good at progressively combining and enhancing streams of data as they cross component boundaries. Of course you can pass signals around; but they are not as rich in transformers as RxJS. This is where RxJS shines. **Revised "Comparing observables"** The Promises section in `comparing-observables.md` had many errors and misleading remarks. The comparison of error handling was especially egregious; the code example for that was nonsense. The "Chain" sub-section was really about transforming values. It also failed to demonstrate chaining promise `.then`s. Reworked these sub-sections and improved the code samples to match. PR Close #51516
2023-08-25 09:06:52 +00:00
* Observable execution errors can be handled with the `catchError()` operator or in the `subscribe`.
`catchError` can put the observable back on the normal path where it continues to produce values or it can rethrow the error. An uncaught error unsubscribes all subscribers.
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
<code-example header="src/observables.ts (error)" path="comparing-observables/src/observables.ts" region="error"></code-example>
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: Migrate Observables guides & code examples to standalone (#51516) None of the guide pages mentions ngModules. Only `observables-in-angular` needed conversion to Standalone. However, some of the guide pages reflect old versions of RxJS, including signatures that are no longer valid. These have been corrected. More significantly, *the existing guide is pretty bad at explaining RxJS and its usage*. It was written (by me I think) in the very early days of Angular and Angular RxJS instruction. I've taught numerous "RxJS in Angular" classes since and learned from that experience what does and does not work with students. There was neither the time nor the charter to completely overhaul this guide. But this commit attempts to remove what flops with students and to bring the teaching closer to what seems more effectively. I hope reviewers agree that my revisions are an improvement. **Revised Overview** The overview doc, `observables.md`, had a few errors (ex: `next` is NOT REQUIRED) and deprecated patterns (you now must pass the Observer object to `subscribe`). More importantly, it was wildly overcomplicated and scary, especially when it got into multi-casting. Moved the multi-casting section to "RxJS Library" and rewrote it (with working example) for simplicity and context. I made other changes in an effort to make this an overview that is more comprehensive and more clear. I paid particular attention to the "Basic usage and terms" section. Finally, I relocated the "Naming conventions for observables" section here from `rx-library`. This is the section that describes the dollar-sign convention. It made more sense for it to be here. **Revised "RxJS Library" page and code** *RxJS no longer supports chaining* and hasn't for a very long time. Removed note in `rx-library.md` that suggested you could use operator chaining. The RxJS `pipe` discussion in the "Operators" section was just weird. Almost no one calls the `pipe` function. We certainly should *start* there. We should start with how people actually use operators - by adding them to the argument list of the `Observable.pipe()` method. I kept the original `pipe` function example but subordinated it in a "callout". Most readers will (and should) ignore it. `Subject` is a *critically important RxJS mechanism for creating custom observables*. It was completely missing from the list of observable creators on this guide page. So I added it to the "Observable creation functions" section of the guide and wrote an accompanying `MessageService` code sample (see the new `rx-library/app/` folder). The `MessageService` is a pretty common pattern in Angular apps - far more common than creating an observable from a counter or an event, two of the creation patterns currently on this page. This new section also afforded an opportunity to show how RxJS helps with building loosely coupled applications. We will soon be talking about Signals. Many will wonder whether and when they should still use RxJS. At least a partial answer is that RxJS is really good at progressively combining and enhancing streams of data as they cross component boundaries. Of course you can pass signals around; but they are not as rich in transformers as RxJS. This is where RxJS shines. **Revised "Comparing observables"** The Promises section in `comparing-observables.md` had many errors and misleading remarks. The comparison of error handling was especially egregious; the code example for that was nonsense. The "Chain" sub-section was really about transforming values. It also failed to demonstrate chaining promise `.then`s. Reworked these sub-sections and improved the code samples to match. PR Close #51516
2023-08-25 09:06:52 +00:00
* Promise errors can be handled with a `.catch()` or in the second argument of a `.then()`.
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
<code-example header="src/promises.ts (error)" path="comparing-observables/src/promises.ts" region="error"></code-example>
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
### Cheat sheet
The following code snippets illustrate how the same kind of operation is defined using observables and promises.
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
| Operation | Observable | Promise |
|:--- |:--- |:--- |
| Creation | <code-example format="typescript" hideCopy language="typescript"> new Observable((observer) =&gt; { &NewLine;&nbsp; observer.next(123); &NewLine;}); </code-example> | <code-example format="typescript" hideCopy language="typescript"> new Promise((resolve, reject) =&gt; { &NewLine;&nbsp; resolve(123); &NewLine;}); </code-example> |
| Transform | <code-example format="typescript" hideCopy language="typescript"> obs.pipe(map((value) =&gt; value &ast; 2));</pre> | <code-example format="typescript" hideCopy language="typescript"> promise.then((value) =&gt; value &ast; 2);</code-example> |
| Subscribe | <code-example format="typescript" hideCopy language="typescript"> sub = obs.subscribe((value) =&gt; { &NewLine;&nbsp; console.log(value) &NewLine;});</code-example> | <code-example format="typescript" hideCopy language="typescript"> promise.then((value) =&gt; { &NewLine;&nbsp; console.log(value); &NewLine;}); </code-example> |
| Unsubscribe | <code-example format="typescript" hideCopy language="typescript"> sub.unsubscribe();</code-example> | Implied by promise resolution. |
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
## Observables compared to events API
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
Observables are very similar to event handlers that use the events API.
Both techniques define notification handlers, and use them to process multiple values delivered over time.
Subscribing to an observable is equivalent to adding an event listener.
One significant difference is that you can configure an observable to transform an event before passing the event to the handler.
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
Using observables to handle events and asynchronous operations can have the advantage of greater consistency in contexts such as HTTP requests.
Here are some code samples that illustrate how the same kind of operation is defined using observables and the events API.
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
| | Observable | Events API |
|:--- |:--- |:--- |
| Creation &amp; cancellation | <code-example format="typescript" hideCopy language="typescript"> // Setup &NewLine;const clicks&dollar; = fromEvent(buttonEl, 'click'); &NewLine;// Begin listening &NewLine;const subscription = clicks&dollar; &NewLine;&nbsp; .subscribe(e =&gt; console.log('Clicked', e)) &NewLine;// Stop listening &NewLine;subscription.unsubscribe(); </code-example> | <code-example format="typescript" hideCopy language="typescript">function handler(e) { &NewLine;&nbsp; console.log('Clicked', e); &NewLine;} &NewLine;// Setup &amp; begin listening &NewLine;button.addEventListener('click', handler); &NewLine;// Stop listening &NewLine;button.removeEventListener('click', handler); </code-example> |
| Subscription | <code-example format="typescript" hideCopy language="typescript">observable.subscribe(() =&gt; { &NewLine;&nbsp; // notification handlers here &NewLine;});</code-example> | <code-example format="typescript" hideCopy language="typescript">element.addEventListener(eventName, (event) =&gt; { &NewLine;&nbsp; // notification handler here &NewLine;}); </code-example> |
| Configuration | Listen for keystrokes, but provide a stream representing the value in the input. <code-example format="typescript" hideCopy language="typescript"> fromEvent(inputEl, 'keydown').pipe( &NewLine;&nbsp; map(e =&gt; e.target.value) &NewLine;); </code-example> | Does not support configuration. <code-example format="typescript" hideCopy language="typescript"> element.addEventListener(eventName, (event) =&gt; { &NewLine;&nbsp; // Cannot change the passed Event into another &NewLine;&nbsp; // value before it gets to the handler &NewLine;}); </code-example> |
docs(aio): add Observable and Rx docs (#21423) PR Close #21423
2018-01-09 19:31:41 +00:00
## Observables compared to arrays
docs: improve markdown (#45325) The purpose of the changes is to clean all markdown to match a single pedantic style. * To ensure all changes in style are properly separated. * To ensure all styled content aligns to nearest 4-character-tab. * To ensure all code blocks use the Angular `<code-example>` or `<code-tab>` elements. * To ensure all markdown exists outside of html tags. * To ensure all images use the Angular style for `<img>` elements. * To ensure that all smart punctuation is replaced or removed. ```text ’, ’, “, ”, –, —, … ``` * To ensure all content does not conflict with the following reserved characters. ```text @, $, *, &, #, |, <, >, ``` * To ensure all content displays using html entities. The following changes were made to files in the following directory. ```text aio/content ``` The target files were markdown files. The list of excluded files: ```text .browserslistrc, .css, .conf, .editorconfig, .gitignore, .html, .js, .json, .sh, .svg, .ts, .txt, .xlf, ``` PR Close #45325
2022-03-10 16:48:09 +00:00
An observable produces values over time.
An array is created as a static set of values.
In a sense, observables are asynchronous where arrays are synchronous.
In the following examples, <code>&rarr;</code> implies asynchronous value delivery.
| Values | Observable | Array |
|:--- |:--- |:--- |
| Given | <code-example format="typescript" hideCopy language="typescript"> obs: &rarr;1&rarr;2&rarr;3&rarr;5&rarr;7 </code-example> <code-example format="typescript" hideCopy language="typescript"> obsB: &rarr;'a'&rarr;'b'&rarr;'c' </code-example> | <code-example format="typescript" hideCopy language="typescript"> arr: [1, 2, 3, 5, 7] </code-example> <code-example format="typescript" hideCopy language="typescript"> arrB: ['a', 'b', 'c'] </code-example> |
| `concat()` | <code-example format="typescript" hideCopy language="typescript"> concat(obs, obsB) </code-example> <code-example format="typescript" hideCopy language="typescript"> &rarr;1&rarr;2&rarr;3&rarr;5&rarr;7&rarr;'a'&rarr;'b'&rarr;'c' </code-example> | <code-example format="typescript" hideCopy language="typescript"> arr.concat(arrB) </code-example> <code-example format="typescript" hideCopy language="typescript"> [1,2,3,5,7,'a','b','c'] </code-example> |
| `filter()` | <code-example format="typescript" hideCopy language="typescript"> obs.pipe(filter((v) =&gt; v&gt;3)) </code-example> <code-example format="typescript" hideCopy language="typescript"> &rarr;5&rarr;7 </code-example> | <code-example format="typescript" hideCopy language="typescript"> arr.filter((v) =&gt; v&gt;3) </code-example> <code-example format="typescript" hideCopy language="typescript"> [5, 7] </code-example> |
| `find()` | <code-example format="typescript" hideCopy language="typescript"> obs.pipe(find((v) =&gt; v&gt;3)) </code-example> <code-example format="typescript" hideCopy language="typescript"> &rarr;5 </code-example> | <code-example format="typescript" hideCopy language="typescript"> arr.find((v) =&gt; v&gt;3) </code-example> <code-example format="typescript" hideCopy language="typescript"> 5 </code-example> |
| `findIndex()` | <code-example format="typescript" hideCopy language="typescript"> obs.pipe(findIndex((v) =&gt; v&gt;3)) </code-example> <code-example format="typescript" hideCopy language="typescript"> &rarr;3 </code-example> | <code-example format="typescript" hideCopy language="typescript"> arr.findIndex((v) =&gt; v&gt;3) </code-example> <code-example format="typescript" hideCopy language="typescript"> 3 </code-example> |
| `forEach()` | <code-example format="typescript" hideCopy language="typescript"> obs.pipe(tap((v) =&gt; { &NewLine; &nbsp; console.log(v); &NewLine; })) &NewLine; 1 &NewLine; 2 &NewLine; 3 &NewLine; 5 &NewLine; 7 </code-example> | <code-example format="typescript" hideCopy language="typescript"> arr.forEach((v) =&gt; { &NewLine; &nbsp; console.log(v); &NewLine; }) &NewLine; 1 &NewLine; 2 &NewLine; 3 &NewLine; 5 &NewLine; 7 </code-example> |
| `map()` | <code-example format="typescript" hideCopy language="typescript"> obs.pipe(map((v) =&gt; -v)) </code-example> <code-example format="typescript" hideCopy language="typescript"> &rarr;-1&rarr;-2&rarr;-3&rarr;-5&rarr;-7 </code-example> | <code-example format="typescript" hideCopy language="typescript"> arr.map((v) =&gt; -v) </code-example> <code-example format="typescript" hideCopy language="typescript"> [-1, -2, -3, -5, -7] </code-example> |
| `reduce()` | <code-example format="typescript" hideCopy language="typescript"> obs.pipe(reduce((s,v)=&gt; s+v, 0)) </code-example> <code-example format="typescript" hideCopy language="typescript"> &rarr;18 </code-example> | <code-example format="typescript" hideCopy language="typescript"> arr.reduce((s,v) =&gt; s+v, 0) </code-example> <code-example format="typescript" hideCopy language="typescript"> 18 </code-example> |
<!-- links -->
<!-- external links -->
<!-- end links -->
docs: Migrate Observables guides & code examples to standalone (#51516) None of the guide pages mentions ngModules. Only `observables-in-angular` needed conversion to Standalone. However, some of the guide pages reflect old versions of RxJS, including signatures that are no longer valid. These have been corrected. More significantly, *the existing guide is pretty bad at explaining RxJS and its usage*. It was written (by me I think) in the very early days of Angular and Angular RxJS instruction. I've taught numerous "RxJS in Angular" classes since and learned from that experience what does and does not work with students. There was neither the time nor the charter to completely overhaul this guide. But this commit attempts to remove what flops with students and to bring the teaching closer to what seems more effectively. I hope reviewers agree that my revisions are an improvement. **Revised Overview** The overview doc, `observables.md`, had a few errors (ex: `next` is NOT REQUIRED) and deprecated patterns (you now must pass the Observer object to `subscribe`). More importantly, it was wildly overcomplicated and scary, especially when it got into multi-casting. Moved the multi-casting section to "RxJS Library" and rewrote it (with working example) for simplicity and context. I made other changes in an effort to make this an overview that is more comprehensive and more clear. I paid particular attention to the "Basic usage and terms" section. Finally, I relocated the "Naming conventions for observables" section here from `rx-library`. This is the section that describes the dollar-sign convention. It made more sense for it to be here. **Revised "RxJS Library" page and code** *RxJS no longer supports chaining* and hasn't for a very long time. Removed note in `rx-library.md` that suggested you could use operator chaining. The RxJS `pipe` discussion in the "Operators" section was just weird. Almost no one calls the `pipe` function. We certainly should *start* there. We should start with how people actually use operators - by adding them to the argument list of the `Observable.pipe()` method. I kept the original `pipe` function example but subordinated it in a "callout". Most readers will (and should) ignore it. `Subject` is a *critically important RxJS mechanism for creating custom observables*. It was completely missing from the list of observable creators on this guide page. So I added it to the "Observable creation functions" section of the guide and wrote an accompanying `MessageService` code sample (see the new `rx-library/app/` folder). The `MessageService` is a pretty common pattern in Angular apps - far more common than creating an observable from a counter or an event, two of the creation patterns currently on this page. This new section also afforded an opportunity to show how RxJS helps with building loosely coupled applications. We will soon be talking about Signals. Many will wonder whether and when they should still use RxJS. At least a partial answer is that RxJS is really good at progressively combining and enhancing streams of data as they cross component boundaries. Of course you can pass signals around; but they are not as rich in transformers as RxJS. This is where RxJS shines. **Revised "Comparing observables"** The Promises section in `comparing-observables.md` had many errors and misleading remarks. The comparison of error handling was especially egregious; the code example for that was nonsense. The "Chain" sub-section was really about transforming values. It also failed to demonstrate chaining promise `.then`s. Reworked these sub-sections and improved the code samples to match. PR Close #51516
2023-08-25 09:06:52 +00:00
@reviewed 2023-08-25
Reference in a new issue Copy permalink