docs(tutorial): Adding a comprehensive tutorial on RxJS, done as I usually teach it. #5592

benlesh · 2020-07-16T00:02:17Z

Starting to add a series of documents outlining the basics of how to use RxJS. Still a lot more to go.

This, effectively, is how I teach RxJS to people.

This adds:

Subscription
Unsubscription

Also:

Additional detail provided in UnsubscriptionError docs.

NOTES:

I still need to go back through and add appropriate URLs to the links that are in the markdown files. (GL) means it is a glossary link, and (API) means it is a link to an API resource doc.

Description:

Related issue (if exists):

niklas-wortmann · 2020-07-16T06:36:03Z

I was planning a slightly different strategy for a tutorial section in the docs. IMO a tutorial should be very task-driven, like the tour of heroes where you end up with an application without knowing anything about RxJS. This tutorial might be a little bit intimidating for newcomers as they probably have to look up several words and it also requires some understanding of javascript in general. The content of this pr is absolutely amazing, but IMO this should rather go into https://rxjs.dev/guide/subscription.
My intention was to work out a practical example as a tutorial for people to go through that doesn't need any background knowledge. The guide section was intended for quality content that is not directly related to API stuff but more on a meta-layer.
I am super happy to discuss this idea with everyone to reach a consensus on this one.

Btw. in #5419 I initiated a restructuring of the guide section by doing a split in "beginners" and "advanced" content. IMO it would be good to apply this style on this document too

benlesh · 2020-07-16T23:08:10Z

@niklas-wortmann We don't need to call this a "tutorial". I just couldn't think of a better name right off.

This is more of a brain dump of everything and anything I know about RxJS (within reason) in the order I'd tell it.

benlesh · 2020-07-16T23:10:10Z

Also, @niklas-wortmann, I'm very sorry I didn't see your other PR. This is just something I've wanted to do for ages. I've finally gotten around to doing it. I appreciate any feedback you can give, but it's really important to me that this lands. (It goes along with the glossary work, etc)

niklas-wortmann · 2020-07-17T08:42:10Z

I discussed with @benlesh offline that this pr might replace the whole guide section. This is the current draft I will think about the proper place to present this in the docs.

jnizet · 2020-07-18T09:58:22Z

docs_app/content/tutorial/2-unsubscribing.md

+
+- Calls to [`subscribe`](API) return a [`Subscription`](API) object.
+- Calling [`unsubscribe`](API) on the [`Subscription`](API) object notifies the [producer](GL) to stop sending values, and triggers the [teardown](GL) of any underlying resources the [producer](GL) has registered for teardown.
+- Failure to [unsubscribe](GL) from asynchronous observables will result in unnecessary resource use, and even memory leaks.


Shouldn't that be balanced by saying that a completion or an error automatically unsubscribes? In my experience with Angular, most observables (HTTP, Form, ActivatedRoute observables) are short-lived and guaranteed to complete or error.

jnizet · 2020-07-18T10:08:45Z

docs_app/content/tutorial/3-creating-an-observable.md

+const firehose$ = new Observable(subscriber => {
+    let n = 0;
+    while (true) {
+        subscriber.notify(n++);


Shouldn't that be subscriber.next(n++)?

jnizet · 2020-07-18T10:09:39Z

docs_app/content/tutorial/3-creating-an-observable.md

+    // This check will prevent this loop from running forever
+    // as long as there is a `take`, etc.
+    while (!subscriber.closed) {
+        subscriber.notify(n++);


Shouldn't that be subscriber.next(n++)?

jnizet · 2020-07-18T10:14:19Z

docs_app/content/tutorial/3-creating-an-observable.md

+Synchronously, when a subscriber has called `complete` or `error`, or when a consumer has [unsubscribed](GL), there is a flag property on [`Subscriber`](API) called [`closed`](API) that will be flipped to `true`. This is useful for checking whether to continue things like synchronous loops. (NOTE: That you do _NOT_ have to check `closed` every time before calling `next`, `error`, or `complete`, RxJS does an internal check there for you).
+
+```ts
+// BAD: this is going to lock your thread on subscribe!


I'm confused. This seems like the way to fix the above bad example, but it's still commented as BAD. Also, the previous paragraph says that you do not have to check closed before calling next, but this example precisely does that.

DeborahK · 2020-07-19T18:34:24Z

docs_app/content/tutorial/1-subscribing.md

+
+## Overview
+
+Chances are, the first time you encounter an [Observable](API), it is because you have had one returned to you by some other API. In this case, the most helpful thing for you to know is how to get values from the observable, and the semantics of [subscription](GL)


Missing period.

DeborahK · 2020-07-19T18:39:57Z

docs_app/content/tutorial/1-subscribing.md

+
+> The first thing to know is, an observable doesn't "do" anything.
+
+An observable, in fact, is _not_ a "stream". An observable is a template for [subscription](GL), through which your code (the [consumer](GL)), will tell a [producer](GL) to start pushing values to it by subscribing to an observable, creating a [subscription](GL).


Consider making these two sentences: "An observable is a template for a subscription. Subscribing to the observable creates the subscription, through which your code (the consumer), will tell a producer to start pushing values to it." This makes the text a little easier to digest.

DeborahK · 2020-07-19T18:44:25Z

docs_app/content/tutorial/1-subscribing.md

+});
+```
+
+The most basic form of subscription is to subscribe to the observable with a single function as the argument to [`subscribe`](API). This will execute the observable's initialization function and create the [subscription](GL).


"the observable's initialization function" has not been discussed previously. Should that be covered before here? Described in more detail here? Or removed from here to stick with a more simplistic discussion of this at this point and discussed in detail later?

DeborahK · 2020-07-19T18:57:15Z

docs_app/content/tutorial/1-subscribing.md

+})
+```
+
+An `Observer` is a type, basically any object with a `next`, `error`, and `complete` method on it. A "partial observer" is any object with at least one of those methods. It is a way to pass these three handlers to the subscription so that a [producer](GL) can notify your code (the [consumer](GL)). `next` is called when the producer pushes a value to the consumer. `error` is called when the producer has encountered an error and must stop sending values, and `complete` is called  when the producer has pushed all values to the consumer, and will push no more.


Wording: Sometimes words like "it" and "this" can be difficult to match back up to what it's referencing, especially when covering complex topics. Consider instead of "It is a way..." to go with "The Observer object provides a way ..." or something similar.

DeborahK · 2020-07-19T19:09:45Z

docs_app/content/tutorial/1-subscribing.md

+All unhandled errors will be rethrown in a different call context. This is done for a variety of reasons, but what is important to know is: Even if your observable is totally synchronous, an error from your observable _cannot be caught_ by wrapping the [`subscribe`](API) call in a `try-catch` block.
+
+
+### Handled Errors


Should this be ## instead of ### so it's at the same level as "Unhandled Errors"?

DeborahK · 2020-07-19T19:16:52Z

docs_app/content/tutorial/1-subscribing.md

+})
+```
+
+An `Observer` is a type, basically any object with a `next`, `error`, and `complete` method on it. A "partial observer" is any object with at least one of those methods. It is a way to pass these three handlers to the subscription so that a [producer](GL) can notify your code (the [consumer](GL)). `next` is called when the producer pushes a value to the consumer. `error` is called when the producer has encountered an error and must stop sending values, and `complete` is called  when the producer has pushed all values to the consumer, and will push no more.


Concepts: The term "callback" is used in the Handled Errors section. Consider introducing the term here. Something like: "The next, error, and complete methods are often called callback functions because they are "called back" when an action occurs." inserted before "next is called when ..."

DeborahK · 2020-07-19T19:25:25Z

docs_app/content/tutorial/2-unsubscribing.md

+- Calls to [`subscribe`](API) return a [`Subscription`](API) object.
+- Calling [`unsubscribe`](API) on the [`Subscription`](API) object notifies the [producer](GL) to stop sending values, and triggers the [teardown](GL) of any underlying resources the [producer](GL) has registered for teardown.
+- Failure to [unsubscribe](GL) from asynchronous observables will result in unnecessary resource use, and even memory leaks.
+- Any errors that occur during teardown will be collected and rethrown as an [`UnsubscriptoinError`](API).


Misspelling: UnsubscriptoinError

DeborahK · 2020-07-19T19:33:30Z

docs_app/content/tutorial/2-unsubscribing.md

+
+## Overview
+
+Just as you need to know how to start getting values from your observable, you must also need to know how to tell the [producer](GL) to stop sending values, and perhaps more importantly, to [teardown](GL) and free up resources.


Minor: Consider changing this: "you must also need to know" to this "you must also know".

DeborahK · 2020-07-19T19:34:55Z

docs_app/content/tutorial/2-unsubscribing.md

+
+## Subscriptions
+
+All calls to [`subscribe`](API) return a [`Subscription`](API) object. In order to end your [subscription](GL) and tell the [producer](GL) to stop sending values and [teardown](API), you must call [`unsubscribe`](API).


Minor: Consider changing "In order to end..." to "To end ..."

DeborahK · 2020-07-19T19:37:38Z

docs_app/content/tutorial/2-unsubscribing.md

+
+All calls to [`subscribe`](API) return a [`Subscription`](API) object. In order to end your [subscription](GL) and tell the [producer](GL) to stop sending values and [teardown](API), you must call [`unsubscribe`](API).
+
+When [`unsubscribe`](API) is called, it will synchronously trigger the [teardown](GL) of the entire [stream](GL) and all underlying [producers](GL) from [cold](GL) sources. This means from that exact moment on, no values can be [nexted](GL), and you cannot be [notified](GL) of any errors or completions.


Haven't previously introduced the concept of "cold" sources. Is there another way to say that so that concept doesn't need to be introduced here?

DeborahK · 2020-07-19T19:40:07Z

docs_app/content/tutorial/2-unsubscribing.md

+
+When [`unsubscribe`](API) is called, it will synchronously trigger the [teardown](GL) of the entire [stream](GL) and all underlying [producers](GL) from [cold](GL) sources. This means from that exact moment on, no values can be [nexted](GL), and you cannot be [notified](GL) of any errors or completions.
+
+By the time the [`unsubscribe`](API) call returns, an attempt to [teardown](GL) has completed.


I'm unclear on this wording: "an attempt to teardown has completed". Should this be "any attempt ..." Or just "all teardown is complete"?

DeborahK · 2020-07-19T19:42:47Z

docs_app/content/tutorial/2-unsubscribing.md

+        console.error(error);
+    }
+}
+```


Consider adding a section on "When Unsubscribe is Not Needed" (or similar) that details the additional items suggested for the TLDR: That an error automatically unsubscribes and that any Observable that completes will automatically be unsubscribed. And consider including examples.

DeborahK · 2020-07-19T19:48:41Z

docs_app/content/tutorial/3-creating-an-observable.md

+
+## TLDR:
+
+- You should probably use a provided [creation function](API).


These TLDR sections are great!

Consider re-wording the first two items to be more clear on the recommendation:

"Use a provided creation function to create an Observable"

"Only create an Observable with the new Observable constructor if no creation function will suffice"

DeborahK · 2020-07-19T19:51:25Z

docs_app/content/tutorial/3-creating-an-observable.md

+- The constructor wraps an initialization function that will be executed synchronously every time you call [`subscribe`](API).
+- The initialization function gives you a [`Subscriber`](API) instance to push [notifications](GL) to [consumers](GL).
+- The initialization function is expected to return [teardown](GL) logic, which is either a `() => void`, [`Subscription`](API), or `void` (if there is no teardown to be done).
+- When `complete` or `error` are called on the [`Subscriber`] provided by the initialization function, it will execute the provided [teardown](GL) as soon as possible.


Should this: [Subscriber] be this: Subscriber in the last bullet?

DeborahK · 2020-07-19T19:54:06Z

docs_app/content/tutorial/3-creating-an-observable.md

+
+## Overview
+
+Besides consuming observables, another thing you'll likely need to do is create new observables. Creating an observable is relatively straight forward, as it is effectively wrapping a function to be executed later with some guarantees. But more importantly, RxJS provides a host of observable [creation functions](API) that create observables for you in tested ways.


Consider elaborating on this point: "as it is effectively wrapping a function to be executed later with some guarantees" What does that mean, exactly? When later is it executed (on creation I presume)? And what types of guarantees?

DeborahK · 2020-07-19T19:56:23Z

docs_app/content/tutorial/3-creating-an-observable.md

+## Creation Functions
+
+A creation function, in RxJS terms, is simply a standalone function provided by RxJS that takes some arguments and returns an [`Observable`](API). There are many examples of these creation functions, but the most common are:
+


I assume these will all link to examples, but consider adding at least one example here anyway ... maybe the of (and if space permits one of the more async-ish ones like interval) ... so the reader can get an idea of what these look like without having to link off somewhere else.

DeborahK · 2020-07-19T20:03:31Z

docs_app/content/tutorial/3-creating-an-observable.md

+
+It is highly recommended that you try to use these functions to create your observable. They are well tested, and used in a huge number of projects, and can generally be composed to create most observables you need.
+
+## Observable Construction


This section gets quite technical rather quickly and this is still pretty early on in the reader's journey.

Consider leaving this introduction paragraph on Observable Construction, so the reader knows there is an alternative. Maybe mention it gets complex. But then move all of the remaining content to a separate section much later in this document and linking to that here. That prevents a reader newer to these concepts from getting lost and stopping at this point.

DeborahK · 2020-07-20T16:15:11Z

docs_app/content/tutorial/4-what-is-an-operator.md

+
+## TLDR:
+
+- Observables are a container for a collection of values over time.


In Chapter 1 the text is: "An observable, in fact, is not a "stream". An observable is a template for subscription..." To prevent confusion, is there a way to bring these two definitions together? Maybe add this line also to Chapter 1 under "Overview"? Something like "You can think of Observables as a container for a collection of values over time."

DeborahK · 2020-08-12T00:16:53Z

docs_app/content/tutorial/1001-but-rxjs-is-hard.md

@@ -0,0 +1,108 @@
+# ???. But RxJS Is Hard
+
+We understand. Believe me. But maybe you're not seeing the real value of what RxJS offers, which is the [`Observable`](API) type itself. There are many [benefits to using observables](1000-why-observables.md), and you don't have to use [operators](GL) at all to get those benefits.


Consider leaving off the "but maybe ..." sentence as it may be construed to be condescending.

DeborahK · 2020-08-12T00:18:50Z

docs_app/content/tutorial/1001-but-rxjs-is-hard.md

+        <ul><li *ngFor="let item of data">{{item}}<li></ul>
+    `
+})
+const SomeComponent {


And even though it's pseudo code, consider going with export class to more closely match the React example.

DeborahK · 2020-08-12T00:20:59Z

docs_app/content/tutorial/1001-but-rxjs-is-hard.md

+
+**Plain DOM Manipulation**
+
+Presented for those who don't quite follow the Angular or React examples above.


consider changing "who don't quite follow" to "who may not be interested in" to not sound condescending.

DeborahK · 2020-08-12T00:23:51Z

docs_app/content/tutorial/1001-but-rxjs-is-hard.md

+If this is the case, I'd recommend using an online playground/sandbox app like [Stackblitz](https://stackblitz.com), or [Codesandbox](https://codesandbox.io), et al, and importing `rxjs` and just playing with it.
+
+### Recommendations for playing with operators:
+


Links to a few sample stackblitz examples could be useful here, giving readers a starting point.

DeborahK · 2020-08-12T00:43:52Z

docs_app/content/guide2/index.md

+2. [Unsubscribing](2-unsubscribing.md)
+3. [Creating An Observable](3-creating-an-observable.md)
+4. [What Is An Operator?](4-what-is-an-operator.md)
+5. [Implementing Operators](5-implementing-operators.md)


Consider moving this section down as it is a bit more complex and implementing ones own operators is not a common "starter" task.

jnizet

I really liked what I read, as usual. 👍

jnizet · 2020-08-12T06:00:23Z

docs_app/content/tutorial/9-writing-readable-rxjs.md

+The next developer will have a hard time **understanding** your code if they lack one or both of these things:
+
+1. Context around why the code is doing what it is doing.
+2. Knowledge of what the abstractions your using do.


your -> you're

jnizet · 2020-08-12T06:01:34Z

docs_app/content/tutorial/9-writing-readable-rxjs.md

+
+## Break Your Code Up
+
+You wouldn't write a "mega function" in most cases, don't write "mega observables". Observables are effectively functions. As functions don't do anything until you call the, observables don't do anything until you _subscribe_ to them. When you're building an observable by chaining operators together, what you're doing is effectively writing a function by adding lines of code to it, so to speak. Very long functions can be hard to understand because they can be hard to follow. Variable declarations can slowly move away from where they are used over the evolution of the code, and the local variable context gets cluttered with names that can start to conflict with one another.


you call the -> you call them

jnizet · 2020-08-12T06:02:46Z

docs_app/content/tutorial/9-writing-readable-rxjs.md

+
+You wouldn't write a "mega function" in most cases, don't write "mega observables". Observables are effectively functions. As functions don't do anything until you call the, observables don't do anything until you _subscribe_ to them. When you're building an observable by chaining operators together, what you're doing is effectively writing a function by adding lines of code to it, so to speak. Very long functions can be hard to understand because they can be hard to follow. Variable declarations can slowly move away from where they are used over the evolution of the code, and the local variable context gets cluttered with names that can start to conflict with one another.
+
+The very nature of reactive programming with observables is that each piece is processed as an individual "step". Every operator returns a new observable. This means that you can break single "mega observable" into smaller observables. This can help with unit testing, in particular.


break single -> break a single

jnizet · 2020-08-12T06:08:29Z

docs_app/content/tutorial/9-writing-readable-rxjs.md

+
+## RxJS Names Are Challenging
+
+Normally, with abstractions, ideally, the abstractions have names that clearly convey what they are doing under the hood and possibly even their use case. Unfortunately, RxJS is a little rough around the edges in this area. Many of our names were inherited from a more than 10-year history dating back to a port from DotNet's Rx implementation. While we have been able to try to change and standardize some of the names (`mergeMap` or `exhaustMap`, for example), there are still some names that exist that don't make much sense to outsiders, such as `BehaviorSubject`. The obvious thing to do would seem to be rename these things in RxJS to names that make more sense. However, given the wide use and momentum of the library, these sorts of changes are costly, take a long time to execute, and just don't make sense at that sort of scale.


Normally, with abstractions, ideally, the abstractions have names

This sounds weird to me. I'd rephrase as

Ideally, abstractions have names

jnizet · 2020-08-12T06:12:24Z

docs_app/content/tutorial/9-writing-readable-rxjs.md

+
+## Using Custom Operators To Improve Readability
+
+Since pipeable operators were introduced in RxJS 5.5, we have had the ability to quickly and easily create custom operators using simple functional concepts. One of the key advantages to this the ability to create operators that are really wrapping other operators with names that concisely convey what the code is doing.


One of the key advantages to this is the ability (missing is)

jnizet · 2020-08-12T06:32:33Z

docs_app/content/tutorial/9-writing-readable-rxjs.md

+
+### Quick Note On "Finnish Notation" ($ suffix)
+
+Adding a `$` suffix to variable names pointing to observable instances is something that started long ago with [Andre Staltz](https://twitter.com/andrestaltz), and continues to be widely practiced today. The RxJS team, does not "officially" think this practice is required or even "better" than not doing so. We have found it advantageous to use Finnish Notation in our documentation because it clearly calls out which variables are observables, and let's face it, we have a lot of documentation on this site that involve important variables that are observables.


The RxJS team, does not -> the RxJS team does not

jnizet · 2020-08-12T06:34:40Z

docs_app/content/tutorial/9-writing-readable-rxjs.md

+
+```ts
+/**
+ * This is an operator used on an observable of save button clicks in our checkout component,


I would end the sentence and start a new one after "component".

jnizet · 2020-08-12T06:39:52Z

docs_app/content/guide2/index.md

+
+## Overview
+
+This section is a guide to how to approach RxJS concepts and how to address common issues while learning and using this library. The goal is to go into as much detail as possible or necessary in as many aspects of RxJS as possible while also trying to provide a quick high-level overview of the concepts.


"a guide to how to" sounds weird to me. "a guide on how to" maybe?

jnizet · 2020-08-12T06:47:49Z

docs_app/content/guide2/2-unsubscribing.md

+
+### NO NEED to unsubscribe:
+
+- **Subscriptions that should stay active for the life of your server/web document**. If it needs to stay up for as long as the host environment is open, then there is no need to tear it down. **HOWEVER**. If you have a web application that can be mounted and unmounted, you will want to unsubscribe from all subscriptions owned by that web application. Otherwise, when unmounting the app it will leave it subscriptions active and hang onto resources.


leave it subscriptions -> leave its subscriptions

jnizet · 2020-08-12T06:50:46Z

docs_app/content/guide2/2-unsubscribing.md

+
+- **Subscriptions that should stay active for the life of your server/web document**. If it needs to stay up for as long as the host environment is open, then there is no need to tear it down. **HOWEVER**. If you have a web application that can be mounted and unmounted, you will want to unsubscribe from all subscriptions owned by that web application. Otherwise, when unmounting the app it will leave it subscriptions active and hang onto resources.
+- **Subscriptions that you know will complete that are delivering a value you always want to get**. For example, if you're loading some expensive to calculate data that you know you're going to use eventually, and you don't want to get it twice, you might choose to allow an observable to run to completion, even if the original consuming code no longer cares about the value.
+- **Synchronous observables**. By the time you get the `Subscription` back from a synchronous observable, it is already `complete`, and it as already torndown. There is no need to keep the `Subscription` in memory or unsubscribe from it later (It won't hurt much if you do, but it's unnecessary). Examples of these are things like the result of [`of`](API), [`from`](API), [`range`](API), et al.


it as already -> it has already

DeborahK · 2020-08-12T21:00:38Z

docs_app/content/guide2/index.md

+2. [Unsubscribing](2-unsubscribing.md)
+3. [Creating An Observable](3-creating-an-observable.md)
+4. [What Is An Operator?](4-what-is-an-operator.md)
+5. [Implementing Operators](5-implementing-operators.md)


Consider adding a section or multiple sections here introducing some of the other operators with their best practices similar to the "Flattening Operations" section.

DeborahK · 2020-08-12T21:02:15Z