Recommendation clarification for Observables

Description

I would like to ask the core developers to clarify/expand the following sentence in the documentation for Observables: “They are used frequently in Angular and are the recommended technique for event handling, asynchronous programming, and handling multiple values.”.

Problem: asynchronous programming here is a little bit wide. In some cases it might be interpreted as “do not use promises at all” [1][2]. As this is an official documentation and people who start to dive into angular tend to read documentation as a single truth, I would like to reduce a number interpretations.

important: this issue is not about observables vs promises.

---

[1]: as for some people…

1. learning two concepts (promises/observables) is irrational as they can concentrate on a single concept (but as angular recommends to use observables, the choice is obvious);
2. async and await aren’t in a comfort zone;
3. who has never worked with event driven APIs (example: node.js) (to get a feel for the difference in these concepts) is not clear when to use promises as the observable is more powerful (read: rxjs) and with canceling.

[2]: which is not the case according the angular codebase itself where we can find promises.

---

Proposal

1. Add a new clarification describing why/when promises should (not) be used and (one of) a. To remove asynchronous programming from the mentioned paragraph. b. Keep asynchronous programming
2. Or remove the recommendation part completely (and are the recommended technique for event handling, asynchronous programming, and handling multiple values.).
3. Replace “the recommended technique” with “a technique”.

URL:

https://angular.io/guide/observables

Similars

• When to use Observables and Promises in Angular
• When to use Promise over observable? and so on.

[kkamkou]

Angular chooses to use them over promises…

If you dig in the core module you’ll find the usage of promises. My assumption is that angular uses both of them in context.

Nevertheless, removing “the recommended technique” would decrease a number of interpretations: “Observables provide support for passing messages between parts of your application. They are used frequently in Angular and are a technique for event handling, asynchronous programming, and handling multiple values.”

[Airblader]

I think that Angular’s documentation on observables should be limited to describing what they are (since they’re used in the framework) and, possibly, why Angular chooses to use them over promises. But it shouldn’t say »and this is how we recommend you deal with things in your application«.

Given that the only thing I slightly disagree with in the sentence you’re quoting is the phrase “the recommended technique”, it could be replaced with “a technique”.