feat(docs): add Observable and Rx docs #21423

jasonaden · 2018-01-09T19:32:24Z

This PR adds documentation to Angular.io for Observables and the basics of RxJS. The intention behind this documentation is to give an introduction to Observable as a type. It also introduces just enough Rx to work with an Angular application. For example, Rx Observable creation utilities and operators used through the pipe function/method.

This doc intentionally avoids more complex discussions such as higher order Observables (this may be added later), hot and cold Observables, marble diagrams, etc. For topics like these (and more), developers should see the RxJS documentation directly.

Some sections are currently incomplete: testing, common operators, and some of the Practical Usage page. Additionally, the examples need to be moved out so they are runnable.

Current preview available at https://pr21423-0412f81.ngbuilds.io/guide/observables

matpag · 2018-01-09T21:13:03Z

aio/content/guide/comparing-observables.md

+});
+chaining
+observable.map((v) => 2*v);
+Observables differentiate between transformation function such as a map and subscription. Only subscription activase the subscribe Function to start computing the values.


typo activase

matpag · 2018-01-09T21:18:56Z

aio/content/guide/observables-in-angular.md

+
+Angular provides an EventEmitter class that’s used when publishing values from a Component through the `@Output()` decorator. Angular’s EventEmitter class extends from Observable, but adds a method `emit()` so it can send arbitrary values. Calling the `emit()` function will cause any subscribed Observers’ `next()` method to be called with the same value.
+
+The example on the [EventEmitter0(https://angular.io/api/core/EventEmitter)] docs page is a good example of it’s usage:


typo EventEmitter0 (and the link reference is broken)

matpag · 2018-01-09T21:25:58Z

aio/content/guide/observables.md

+
+Use the Observable constructor to create an Observable stream of any type. The constructor takes as its argument a Subscriber function to run when the Observable’s `subscribe()` method executes. A subscriber function receives an Observer, and can publish values to the Observer's `next()` method.
+
+For example, to create an Observable equivalent to the `Observable.of(1, 2, 3)` above, you could so something like this:


matpag · 2018-01-09T21:31:28Z

aio/content/guide/practical-observable-usage.md

+
+## Exponential backoff
+
+Exponential backoff is a technique where you retry an API after failure, making the time in between retries longer after each consecutive failure, with a maximum number of retries after which the request is considered to have failed.  This can be quite complex to implement with Promises and other methods of tracking AJAX calls, but with Observables it is very easy:


double space between ... to have failed. This can be ...

matpag · 2018-01-09T21:33:33Z

aio/content/guide/practical-observable-usage.md

+
+To illustrate how and when to unsubscribe, consider a component named `HeroCounterComponent` that performs the simple task of increasing a total of heroes. The counter runs as long as the component is active in the view. Once the component is destroyed, you no longer want to listen for any changes coming from the Observable counter, so you can use the ngOnDestroy lifecycle hook to unsubscribe from the Observable counter and clean up its resources.
+
+Disposing of a single subscription when your component is destroyed is very manageable, but as you use more Observables, managing multiple subscriptions can get unwieldy.  One way to manage them is to use operators that cause a stream to complete, which in turn causes the unsubscription logic to run. For example, the  `takeUntil` operator  listens for one or more supplied Observables to complete, then notifies the source Observable to complete.


double space between ...can get unwieldy. One way to...
And in For example, the takeUntil operator listens part

matpag · 2018-01-09T21:35:47Z

aio/content/guide/practical-observable-usage.md

+
+Disposing of a single subscription when your component is destroyed is very manageable, but as you use more Observables, managing multiple subscriptions can get unwieldy.  One way to manage them is to use operators that cause a stream to complete, which in turn causes the unsubscription logic to run. For example, the  `takeUntil` operator  listens for one or more supplied Observables to complete, then notifies the source Observable to complete.
+
+A typical Observable creates a new, independent execution for each subscribed observer. To illustrate managing a number of subscriptions, we can create a _multicasting_ Observable that keeps a list of subscribers, and broadcasts its values to all of them. Then we  can update the hero counter example to use the `takeUntil` operator to manage multiple subscribers.


double space between Then we can update

matpag · 2018-01-09T21:37:01Z

aio/content/guide/practical-observable-usage.md

+
+A typical Observable creates a new, independent execution for each subscribed observer. To illustrate managing a number of subscriptions, we can create a _multicasting_ Observable that keeps a list of subscribers, and broadcasts its values to all of them. Then we  can update the hero counter example to use the `takeUntil` operator to manage multiple subscribers.
+
+> NOTE: RxJS defines a multicasting Observable called a  Subject, which keeps a list of registered observers, and notifies all observers each time a new value is emitted.


double space between Observable called a Subject,

matpag · 2018-01-09T21:40:10Z

aio/content/guide/practical-observable-usage.md

+
+When the `onDestroy` Observable completes, the counter Observable also completes and stops producing values. This approach scales up, allowing a single Observable to trigger completion across multiple subscriptions.
+
+** CODE SAMPLE NEEDED. EXAMPLE [HERE](https://gist.github.com/alxhub/4c55e39b572c4cdcbb369fb3598cc92c).**


Is this intentional or the code sample should be reported?
There are a lot more ** EXAMPLE HERE ** comments in the doc, so this intentional probably, sorry for reporting that

matpag · 2018-01-09T21:50:04Z

aio/content/guide/practical-observable-usage.md

+
+As with other services, you'll import the `EventAggregatorService` and MessageLogComponent and add it to the AppModule providers and declarations arrays respectively.
+
+To see your message bus in action, you'll import and inject the `EventAggregatorService` in the AppComponent and add an event when the Application starts and add the message-log component to the AppComponenttemplate.


AppComponenttemplate not fully PascalCase

matpag · 2018-01-09T21:57:54Z

aio/content/guide/testing-observables.md

+
+# Testing Observable Services
+
+First, let's look at the sharing data with a stream example. You want to verify the functionality of the service including its initial state, and that new entries are added into the stream each time the add method is used. If you're familiar with Angular's TestBed, this is a normal setup. You use the TestBed to setup the configure a testing module include the necessary providers, and use the TestBed.get() method to get a new instance of the EventAggregatorService before each test run.


You use the TestBed to setup the configure a testing module include the necessary providers is this sentence correct?

mary-poppins · 2018-01-09T22:05:29Z

You can preview 97f0ce4 at https://pr21423-97f0ce4.ngbuilds.io/.

mary-poppins · 2018-01-10T01:28:29Z

You can preview fb88455 at https://pr21423-fb88455.ngbuilds.io/.

jasonaden · 2018-01-11T19:43:16Z

aio/content/guide/observables.md

+
+A handler for receiving Observable notifications implements the Observer interface. It is an object that defines callback methods to handle the three types of notifications that an Observable can send:
+
+| Notification Types |


Formatting needs to be fixed on this table.

jasonaden · 2018-01-11T19:46:33Z

aio/content/guide/comparing-observables.md

+
+Observables are often compared to Promises. They both deliver values asynchronously, so what’s the difference? Unlike Promise, Observable delivers many values over time and is cancellable. Some of the other differences are described in the following table.
+
+<table>


These tables format nicely on Github, but not on Angular.io. Need to adjust the formatting so they display correctly.

Observables do not deliver values asynchronously. In fact, they can but they often do not and that's pretty darned important.

IMO, relating Observables to Promises only leads to confusion. They're completely different things: like a screwdriver and a hammer. You can get a screw into a piece of wood with both (handle one-time async events), but that's about as similar as they get.

ngbot · 2018-01-16T15:43:25Z

Hello? Don't want to hassle you. Sure you're busy. But this PR has some merge conflicts that you probably ought to resolve.
That is... if you want it to be merged someday...

mary-poppins · 2018-01-16T16:59:33Z

You can preview 0412f81 at https://pr21423-0412f81.ngbuilds.io/.

mhevery · 2018-01-16T19:51:23Z

aio/content/guide/observables.md

+| error | Optional. A handler for an error notification. An error halts execution of the Observable instance. |
+| complete | Optional. A handler for the execution-complete notification. Delayed values can continue to be delivered to the next handler after execution is complete. |
+
+An observer object can define any combination of these handlers. If you don't supply a handler for a notification type, the observer ignores notifications of that type.


I think a quick example pseudo code would be useful here.
Also should you say something along the lines of: Most of the time one does not need to create observables one only subscribes to them or uses composition methods to compose observables?

mhevery · 2018-01-16T19:53:35Z

aio/content/guide/observables.md

+
+## Subscribing
+
+An Observable object begins publishing values only when someone subscribes to it. You subscribe by calling the subscribe() method of an Observable instance, passing an Observer to receive the notifications.


Should Observer be in back ticks since it is a type?

mhevery · 2018-01-16T19:53:58Z

aio/content/guide/observables.md

+
+An Observable object begins publishing values only when someone subscribes to it. You subscribe by calling the subscribe() method of an Observable instance, passing an Observer to receive the notifications.
+
+> In order to show how subscribing works, we need to create a new Observable. There is an Observable constructor that you use to create customized Observable instances, but for illustration, we can use some static methods on the Observable class that create simple Observables of frequently used types:


Observable in back ticks

mhevery · 2018-01-16T20:04:46Z

aio/content/guide/rx-library.md

+### Observable from a Promise
+
+```
+import { fromPromise } from 'rxjs/observable/fromPromise;


missing' before ;

mhevery · 2018-01-16T20:05:23Z

aio/content/guide/rx-library.md

+### Observable from a Counter
+
+```
+// Observable that will publish a value on an interval


probably should add imporf for interval

mhevery · 2018-01-16T21:54:22Z

aio/content/guide/common-operators.md

@@ -0,0 +1,38 @@
+# Common Operators
+
+RxJS provides many operators (over 150 of them!), but only a handful are used frequently. Here is a list of common operators with simple examples to show their usage. These examples are largely derived from the [RxJS 5 Operators By Example](https://github.com/btroncone/learn-rxjs/blob/master/operators/complete.md) page:


Text says that there are examples, but no examples are listed.

mhevery · 2018-01-16T21:56:28Z

aio/content/guide/practical-observable-usage.md

+```
+
+## Managing Subscriptions
+


what is the plan with TBD here?

Removed for MVP of the docs

mhevery · 2018-01-16T21:56:57Z

aio/content/guide/testing-observables.md

@@ -0,0 +1,3 @@
+# Testing
+
+TBD. Original content [here](https://docs.google.com/document/d/1gGP5sqWNCHAWWV_GLdZQ1XyMO4K-CHksUxux0BFtVxk/edit#heading=h.ohqykkhzdhb2).


Removed for MVP of the docs. Will work in some of the testing guide from previous PR.

mhevery · 2018-01-16T22:02:22Z

aio/content/guide/comparing-observables.md

+  <tr>
+    <td>Configuration</td>
+    <td>
+<pre>fromEvent(inputEl, ‘keydown).pipe(


missing trailing back tick on keydown

mhevery · 2018-01-16T22:03:21Z

aio/content/guide/comparing-observables.md

+      <p>Configured to listen for keystrokes, but provide a stream representing the value in the input.</p>
+    </td>
+    <td>
+<pre>element.addEventListener(eventName, (event) => {


eventName should be 'keydown' for consistency

wardbell · 2018-01-17T07:24:30Z

@jasonaden FYI ... PR #20697 update to Testing guide teaches techniques for testing observable APIs. Those techniques include an intro to marble testing. There may be a cross-ref opportunity once that PR lands.

googlebot · 2018-01-23T18:43:11Z

So there's good news and bad news.

👍 The good news is that everyone that needs to sign a CLA (the pull request submitter and all commit authors) have done so. Everything is all good there.

😕 The bad news is that it appears that one or more commits were authored by someone other than the pull request submitter. We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that here in the pull request.

Note to project maintainer: This is a terminal state, meaning the cla/google commit status will not change from this State. It's up to you to confirm consent of the commit author(s) and merge this pull request when appropriate.

jenniferfell · 2018-02-09T19:23:26Z

@jbogarthyde I added you as a reviewer. When you're happy with the doc content, please approve as a reviewer. Thx.

jenniferfell · 2018-02-12T22:15:10Z

These seem to be the answers to my questions above:

Q1: Judy sent a slack saying the content looks good to her, so that's done.
Q2: ?
Q3: Travis issues appear to be with formatting in example files. @jasonaden ?

jenniferfell

I found a couple typos (missing or extra letters). Capitalization of all titles and headings should be sentence caps. Most of the rest are also minor suggestions for clarity or style at the sentence level. I didn't make any structural recommendations at this time. Comments that begin "Recommend:" are optional.

jenniferfell · 2018-02-14T22:54:14Z

aio/content/guide/observables.md

+
+Observables provide support for passing messages between publishers and subscribers in your application. Observables offer significant benefits over other techniques for event handling, asynchronous programming, and handling multiple values.
+
+Observables are declarative &mdash; that is, you define a function for publishing values, but it is not executed until a consumer subscribes to it. The subscribed consumer then receives notifications until the function completes, or they unsubscribe.


No spaces around em-dashes. https://developers.google.com/style/dashes

jenniferfell · 2018-02-14T22:55:02Z

aio/content/guide/observables.md

+
+Observables provide support for passing messages between publishers and subscribers in your application. Observables offer significant benefits over other techniques for event handling, asynchronous programming, and handling multiple values.
+
+Observables are declarative &mdash; that is, you define a function for publishing values, but it is not executed until a consumer subscribes to it. The subscribed consumer then receives notifications until the function completes, or they unsubscribe.


Mismatched subject-verb. Recommend: The subscribed consumers then receives notifications until the function completes, or until they unsubscribe.

jenniferfell · 2018-02-14T22:57:37Z

aio/content/guide/observables.md

+
+Observables are declarative &mdash; that is, you define a function for publishing values, but it is not executed until a consumer subscribes to it. The subscribed consumer then receives notifications until the function completes, or they unsubscribe.
+
+An Observable can deliver multiple values of any type &mdash; literals, messages, or events, depending on the context. The API for receiving values is the same whether the values are delivered synchronously or asynchronously. Because setup and teardown logic are both handled by the Observable, your application code only needs to worry about subscribing to consume values, and when done, unsubscribing. Whether the stream was keystrokes, an HTTP response, or an interval timer, the interface for listening to values and stopping listening is the same.


Global:

Why is Observable always capitalized? Seems like this should be a regular noun, lowercase.

Doc is inconsistent: observer object, observer, Observer. I prefer observer or observer object.

I see that RxJS capitalizes Observables. That's unfortunate, because it's just a thing like "car." It's not a specific trademarked thing (Toyota), nor is it a specific code construct that must be capitalized. I'm fine either way I guess.

It should be Observer where we are referring to it as interface. observer or observer object should be fine in other uses.

jenniferfell · 2018-02-14T23:03:31Z

aio/content/guide/observables.md

+
+Sometimes, instead of starting an independent execution for each subscriber, you want each subscription to get the same values -- even if values have already started emitting. This might be the case with something like an Observable of clicks on the document object. You might not want to register multiple listeners on the document, but instead re-use the first listener and send values out to each subscriber.
+
+This is called “multicasting”. When creating an Observable you should determine how you want that Observable to be used and whether or not you want to multicast it’s values. Changing the Observable above to be multicasted could look something like this:


Above: "This is known as multicasting." Implies that multicasting is the act of broadcasting to a list of subscribers in a single execution.
Here: "This is called multicasting." Implies that multicasting is specifically re-using a listener to send values out to a set of subscribers.
Recommendation: Define "multicasting" once near the beginning. "Multicasting is...." Then clean up the second "This is multicasting" to fit. For example, "Multicasting is achieved by re-using a listener..."

jenniferfell · 2018-02-14T23:04:36Z

aio/content/guide/observables.md

+
+Sometimes, instead of starting an independent execution for each subscriber, you want each subscription to get the same values -- even if values have already started emitting. This might be the case with something like an Observable of clicks on the document object. You might not want to register multiple listeners on the document, but instead re-use the first listener and send values out to each subscriber.
+
+This is called “multicasting”. When creating an Observable you should determine how you want that Observable to be used and whether or not you want to multicast it’s values. Changing the Observable above to be multicasted could look something like this:


Replace "it's values" with "its values"

jenniferfell · 2018-02-15T00:54:24Z

aio/content/guide/observables.md

+
+## Multicasting
+
+One feature of Observables is they don’t do anything until a subscription happens. In the previous examples, you can see that no event handlers are wired up and no values delivered until you subscribe to the Observable. But what happens when there are two subscriptions? A typical Observable creates a new, independent execution for each subscribed observer. If you have an Observable that keeps a list of subscribers, it can broadcast its values to all of them. This is known as multicasting.


Is this what you're trying to emphasize? "A typical Observable creates a new, independent execution for each subscribed observer. When an observer subscribes, the Observable wires up an event handler and delivers values to that observer. When a second observer subscribes, the Observable then wires up a new event handler and delivers values to that second observer in a separate execution. Multicasting is the practice of broadcasting to a list of multiple subscribers in a single execution. It's awesome because..." [everyone gets same values at the same time, everyone gets same values, event handling is centralized, ???]

jenniferfell · 2018-02-15T00:56:04Z

aio/content/guide/observables.md

+
+One feature of Observables is they don’t do anything until a subscription happens. In the previous examples, you can see that no event handlers are wired up and no values delivered until you subscribe to the Observable. But what happens when there are two subscriptions? A typical Observable creates a new, independent execution for each subscribed observer. If you have an Observable that keeps a list of subscribers, it can broadcast its values to all of them. This is known as multicasting.
+
+Let’s look at an example, similar to the one above that counts from 1 to 3. But in this example we’ll introduce a 1 second delay between each number being emitted:


Better not to start sentence with "But."
"This example introduces a one-second delay after each number emitted."

jenniferfell · 2018-02-15T00:59:21Z

aio/content/guide/rx-library.md

+
+Reactive programming is an asynchronous programming paradigm concerned with data streams and the propagation of change ([Wikipedia](https://en.wikipedia.org/wiki/Reactive_programming)). RxJS (Reactive Extensions for JavaScript) is a library for reactive programming using Observables that makes it easier to compose asynchronous or callback-based code ([RxJS Docs](http://reactivex.io/rxjs/)).
+
+RxJS provides an implementation of the Observable type, which is needed until Observable becomes part of the language and until browsers support it. But the most important parts of the library are utility functions for creating and working with Observables. These utility functions can be used for:


Recommend simplifying: RxJS provides an implementation of the Observable type, which is needed until Observable becomes part of the JavaScript language and until browsers support it. The library also provides utility functions for creating and working with Observables.

jenniferfell · 2018-02-15T01:02:09Z

aio/content/guide/practical-observable-usage.md

+
+## Exponential backoff
+
+Exponential backoff is a technique where you retry an API after failure, making the time in between retries longer after each consecutive failure, with a maximum number of retries after which the request is considered to have failed. This can be quite complex to implement with Promises and other methods of tracking AJAX calls. With Observables, it is very easy:


"...is a technique in which you..."

jenniferfell · 2018-02-15T01:06:12Z

aio/content/guide/rx-library.md

+
+## Naming conventions for Observables
+
+Because Angular applications are mostly written in TypeScript, you will typically know when a variable is an Observable. While the Angular framework generally does not employ a naming convention for Observables, in online examples and applications, you will often see Observables named with a trailing “$” sign.


Recommend not using "while" unless you mean time. Also can "generally does not employ" be simplified?

"Although the Angular framework does not enforce a naming convention for Observables, you will often see Observables named with a trailing dollar sign ("$")."

jenniferfell · 2018-02-15T01:54:12Z

aio/content/guide/rx-library.md

+
+Operators are functions that build on the Observables foundation to enable sophisticated manipulation of collections. For example, RxJS defines operators for operations such as `map()`, `filter()`, `concat()`, and `flatMap()`.
+
+An operator takes configuration options, and returns another function which takes a source Observable. When executing this returned function, the operator observes the source Observable’s emitted values, transforms them, and returns a new Observable of those transformed values. Here is a simple example:


There should be a comma before which, but that creates some complex parsing.
"An operator takes configuration options, and it returns another function, which takes a source Observable."
"Operators take configuration options, and they return a function that takes a source Observable."

spottedmahn · 2018-02-23T21:49:53Z

Thanks for creating the documentation, it looks great!

I didn't see anything about unsubscribing from observables though. Did I miss it?

Reference issue 22410

jasonaden · 2018-02-26T17:24:22Z

@spottedmahn Good question. No, this doc doesn't immediately cover that. And we will have to follow up with another addition to the docs. Similarly with testing. I think it'll be good to get this doc out since it should be useful now, rather than waiting to add more content.

I assigned your referenced issue to myself so I can grab it in an upcoming sprint.

ngbot · 2018-02-26T17:24:45Z

I see that you just added the PR action: merge label, but the following checks are still failing:
     missing required label: "PR target: *"
     status "ci/circleci: lint" is pending
     status "ci/circleci: build" is pending
     status "continuous-integration/travis-ci/pr" is pending
     1 pending code review

If you want your PR to be merged, it has to pass all the CI checks.

If you can't get the PR to a green state due to flakes or broken master, please try rebasing to master and/or restarting the CI job. If that fails and you believe that the issue is not due to your change, please contact the caretaker and ask for help.

mary-poppins · 2018-02-26T17:28:41Z

You can preview 31ee194 at https://pr21423-31ee194.ngbuilds.io/.

Addressed comments. She is on vacation so hard to get approval.

mary-poppins · 2018-02-26T18:21:07Z

You can preview 4f314f6 at https://pr21423-4f314f6.ngbuilds.io/.

jenniferfell · 2018-02-26T18:21:13Z

I'm here. :-) I took a quick look. Extra file and title caps are resolved. I didn't recheck every copy edit. LTGM.

PR Close #21423

PR Close angular#21423

angular-automatic-lock-bot · 2019-09-13T09:21:10Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

googlebot added the cla: yes label Jan 9, 2018

matpag reviewed Jan 9, 2018

View reviewed changes

jasonaden force-pushed the docs_observables branch from 4099e47 to 97f0ce4 Compare January 9, 2018 21:58

jasonaden requested a review from petebacondarwin January 9, 2018 22:35

kara added the comp: docs label Jan 9, 2018

jasonaden force-pushed the docs_observables branch from 97f0ce4 to fb88455 Compare January 10, 2018 01:19

jasonaden commented Jan 11, 2018

View reviewed changes

jasonaden requested review from alxhub and robwormald January 11, 2018 19:46

gkalpak force-pushed the docs_observables branch from fb88455 to 0412f81 Compare January 16, 2018 16:52

mhevery reviewed Jan 16, 2018

View reviewed changes

ocombe added the aio: preview label Jan 17, 2018

googlebot added cla: no and removed cla: yes labels Jan 23, 2018

jasonaden removed the cla: no label Jan 23, 2018

jenniferfell requested a review from jbogarthyde February 9, 2018 19:22

jenniferfell previously requested changes Feb 15, 2018

View reviewed changes

jenniferfell reviewed Feb 15, 2018

View reviewed changes

ericmartinezr mentioned this pull request Feb 23, 2018

Documentation for RxJS Unsubscribing #22410

Closed

docs(aio): add Observable and Rx docs

31ee194

jasonaden force-pushed the docs_observables branch from 21b2d4f to 31ee194 Compare February 26, 2018 17:20

jasonaden removed request for petebacondarwin, robwormald, alxhub and jbogarthyde February 26, 2018 17:22

jasonaden added action: merge The PR is ready for merge by the caretaker target: patch This PR is targeted for the next patch release labels Feb 26, 2018

fixup! docs(aio): add Observable and Rx docs

4f314f6

jenniferfell approved these changes Feb 26, 2018

View reviewed changes

alexeagle pushed a commit that referenced this pull request Feb 27, 2018

docs(aio): add Observable and Rx docs (#21423)

f2fa7a2

PR Close #21423

alexeagle closed this in 79656e7 Feb 27, 2018

smdunn pushed a commit to smdunn/angular that referenced this pull request Feb 28, 2018

docs(aio): add Observable and Rx docs (angular#21423)

c02a80e

PR Close angular#21423

leo6104 pushed a commit to leo6104/angular that referenced this pull request Mar 25, 2018

docs(aio): add Observable and Rx docs (angular#21423)

c404d3e

PR Close angular#21423

angular-automatic-lock-bot bot locked and limited conversation to collaborators Sep 13, 2019


		Angular provides an EventEmitter class that’s used when publishing values from a Component through the `@Output()` decorator. Angular’s EventEmitter class extends from Observable, but adds a method `emit()` so it can send arbitrary values. Calling the `emit()` function will cause any subscribed Observers’ `next()` method to be called with the same value.

		The example on the [EventEmitter0(https://angular.io/api/core/EventEmitter)] docs page is a good example of it’s usage:


		Use the Observable constructor to create an Observable stream of any type. The constructor takes as its argument a Subscriber function to run when the Observable’s `subscribe()` method executes. A subscriber function receives an Observer, and can publish values to the Observer's `next()` method.

		For example, to create an Observable equivalent to the `Observable.of(1, 2, 3)` above, you could so something like this:


		## Exponential backoff

		Exponential backoff is a technique where you retry an API after failure, making the time in between retries longer after each consecutive failure, with a maximum number of retries after which the request is considered to have failed. This can be quite complex to implement with Promises and other methods of tracking AJAX calls, but with Observables it is very easy:


		To illustrate how and when to unsubscribe, consider a component named `HeroCounterComponent` that performs the simple task of increasing a total of heroes. The counter runs as long as the component is active in the view. Once the component is destroyed, you no longer want to listen for any changes coming from the Observable counter, so you can use the ngOnDestroy lifecycle hook to unsubscribe from the Observable counter and clean up its resources.

		Disposing of a single subscription when your component is destroyed is very manageable, but as you use more Observables, managing multiple subscriptions can get unwieldy. One way to manage them is to use operators that cause a stream to complete, which in turn causes the unsubscription logic to run. For example, the `takeUntil` operator listens for one or more supplied Observables to complete, then notifies the source Observable to complete.


		Disposing of a single subscription when your component is destroyed is very manageable, but as you use more Observables, managing multiple subscriptions can get unwieldy. One way to manage them is to use operators that cause a stream to complete, which in turn causes the unsubscription logic to run. For example, the `takeUntil` operator listens for one or more supplied Observables to complete, then notifies the source Observable to complete.

		A typical Observable creates a new, independent execution for each subscribed observer. To illustrate managing a number of subscriptions, we can create a _multicasting_ Observable that keeps a list of subscribers, and broadcasts its values to all of them. Then we can update the hero counter example to use the `takeUntil` operator to manage multiple subscribers.


		A typical Observable creates a new, independent execution for each subscribed observer. To illustrate managing a number of subscriptions, we can create a _multicasting_ Observable that keeps a list of subscribers, and broadcasts its values to all of them. Then we can update the hero counter example to use the `takeUntil` operator to manage multiple subscribers.

		> NOTE: RxJS defines a multicasting Observable called a Subject, which keeps a list of registered observers, and notifies all observers each time a new value is emitted.


		When the `onDestroy` Observable completes, the counter Observable also completes and stops producing values. This approach scales up, allowing a single Observable to trigger completion across multiple subscriptions.

		CODE SAMPLE NEEDED. EXAMPLE [HERE](https://gist.github.com/alxhub/4c55e39b572c4cdcbb369fb3598cc92c).


		As with other services, you'll import the `EventAggregatorService` and MessageLogComponent and add it to the AppModule providers and declarations arrays respectively.

		To see your message bus in action, you'll import and inject the `EventAggregatorService` in the AppComponent and add an event when the Application starts and add the message-log component to the AppComponenttemplate.


		# Testing Observable Services

		First, let's look at the sharing data with a stream example. You want to verify the functionality of the service including its initial state, and that new entries are added into the stream each time the add method is used. If you're familiar with Angular's TestBed, this is a normal setup. You use the TestBed to setup the configure a testing module include the necessary providers, and use the TestBed.get() method to get a new instance of the EventAggregatorService before each test run.


		A handler for receiving Observable notifications implements the Observer interface. It is an object that defines callback methods to handle the three types of notifications that an Observable can send:

		\| Notification Types \|


		Observables are often compared to Promises. They both deliver values asynchronously, so what’s the difference? Unlike Promise, Observable delivers many values over time and is cancellable. Some of the other differences are described in the following table.

		<table>


		## Subscribing

		An Observable object begins publishing values only when someone subscribes to it. You subscribe by calling the subscribe() method of an Observable instance, passing an Observer to receive the notifications.


		An Observable object begins publishing values only when someone subscribes to it. You subscribe by calling the subscribe() method of an Observable instance, passing an Observer to receive the notifications.

		> In order to show how subscribing works, we need to create a new Observable. There is an Observable constructor that you use to create customized Observable instances, but for illustration, we can use some static methods on the Observable class that create simple Observables of frequently used types:

		@@ -0,0 +1,38 @@
		# Common Operators

		RxJS provides many operators (over 150 of them!), but only a handful are used frequently. Here is a list of common operators with simple examples to show their usage. These examples are largely derived from the [RxJS 5 Operators By Example](https://github.com/btroncone/learn-rxjs/blob/master/operators/complete.md) page:

		@@ -0,0 +1,3 @@
		# Testing

		TBD. Original content [here](https://docs.google.com/document/d/1gGP5sqWNCHAWWV_GLdZQ1XyMO4K-CHksUxux0BFtVxk/edit#heading=h.ohqykkhzdhb2).


		Observables provide support for passing messages between publishers and subscribers in your application. Observables offer significant benefits over other techniques for event handling, asynchronous programming, and handling multiple values.

		Observables are declarative — that is, you define a function for publishing values, but it is not executed until a consumer subscribes to it. The subscribed consumer then receives notifications until the function completes, or they unsubscribe.


		Observables are declarative — that is, you define a function for publishing values, but it is not executed until a consumer subscribes to it. The subscribed consumer then receives notifications until the function completes, or they unsubscribe.

		An Observable can deliver multiple values of any type — literals, messages, or events, depending on the context. The API for receiving values is the same whether the values are delivered synchronously or asynchronously. Because setup and teardown logic are both handled by the Observable, your application code only needs to worry about subscribing to consume values, and when done, unsubscribing. Whether the stream was keystrokes, an HTTP response, or an interval timer, the interface for listening to values and stopping listening is the same.


		Sometimes, instead of starting an independent execution for each subscriber, you want each subscription to get the same values -- even if values have already started emitting. This might be the case with something like an Observable of clicks on the document object. You might not want to register multiple listeners on the document, but instead re-use the first listener and send values out to each subscriber.

		This is called “multicasting”. When creating an Observable you should determine how you want that Observable to be used and whether or not you want to multicast it’s values. Changing the Observable above to be multicasted could look something like this:


		## Multicasting

		One feature of Observables is they don’t do anything until a subscription happens. In the previous examples, you can see that no event handlers are wired up and no values delivered until you subscribe to the Observable. But what happens when there are two subscriptions? A typical Observable creates a new, independent execution for each subscribed observer. If you have an Observable that keeps a list of subscribers, it can broadcast its values to all of them. This is known as multicasting.


		One feature of Observables is they don’t do anything until a subscription happens. In the previous examples, you can see that no event handlers are wired up and no values delivered until you subscribe to the Observable. But what happens when there are two subscriptions? A typical Observable creates a new, independent execution for each subscribed observer. If you have an Observable that keeps a list of subscribers, it can broadcast its values to all of them. This is known as multicasting.

		Let’s look at an example, similar to the one above that counts from 1 to 3. But in this example we’ll introduce a 1 second delay between each number being emitted:

feat(docs): add Observable and Rx docs #21423

feat(docs): add Observable and Rx docs #21423

Conversation

jasonaden commented Jan 9, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

matpag Jan 9, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

matpag Jan 9, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

matpag Jan 9, 2018 • edited Loading

Choose a reason for hiding this comment

matpag Jan 9, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

matpag Jan 9, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mary-poppins commented Jan 9, 2018

mary-poppins commented Jan 10, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ngbot bot commented Jan 16, 2018

mary-poppins commented Jan 16, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wardbell commented Jan 17, 2018

googlebot commented Jan 23, 2018

jenniferfell commented Feb 9, 2018

jenniferfell commented Feb 12, 2018

jenniferfell left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

spottedmahn commented Feb 23, 2018

jasonaden commented Feb 26, 2018

ngbot bot commented Feb 26, 2018

mary-poppins commented Feb 26, 2018

mary-poppins commented Feb 26, 2018

jenniferfell commented Feb 26, 2018

angular-automatic-lock-bot bot commented Sep 13, 2019

jasonaden commented Jan 9, 2018 •

edited

Loading

matpag Jan 9, 2018 •

edited

Loading

matpag Jan 9, 2018 •

edited

Loading

matpag Jan 9, 2018 •

edited

Loading

matpag Jan 9, 2018 •

edited

Loading

matpag Jan 9, 2018 •

edited

Loading


		Reactive programming is an asynchronous programming paradigm concerned with data streams and the propagation of change ([Wikipedia](https://en.wikipedia.org/wiki/Reactive_programming)). RxJS (Reactive Extensions for JavaScript) is a library for reactive programming using Observables that makes it easier to compose asynchronous or callback-based code ([RxJS Docs](http://reactivex.io/rxjs/)).

		RxJS provides an implementation of the Observable type, which is needed until Observable becomes part of the language and until browsers support it. But the most important parts of the library are utility functions for creating and working with Observables. These utility functions can be used for:


		## Naming conventions for Observables

		Because Angular applications are mostly written in TypeScript, you will typically know when a variable is an Observable. While the Angular framework generally does not employ a naming convention for Observables, in online examples and applications, you will often see Observables named with a trailing “$” sign.


		Operators are functions that build on the Observables foundation to enable sophisticated manipulation of collections. For example, RxJS defines operators for operations such as `map()`, `filter()`, `concat()`, and `flatMap()`.

		An operator takes configuration options, and returns another function which takes a source Observable. When executing this returned function, the operator observes the source Observable’s emitted values, transforms them, and returns a new Observable of those transformed values. Here is a simple example: