Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(guides): add observable and subscription instructions #4134

Merged
merged 1 commit into from
Sep 14, 2018
Merged

docs(guides): add observable and subscription instructions #4134

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 51 additions & 35 deletions doc/observable.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,10 @@ Observables are lazy Push collections of multiple values. They fill the missing

**Example.** The following is an Observable that pushes the values `1`, `2`, `3` immediately (synchronously) when subscribed, and the value `4` after one second has passed since the subscribe call, then completes:

```js
var observable = Rx.Observable.create(function (observer) {
```ts
import { Observable } from 'rxjs';

const observable = Observable.create(function (observer) {
observer.next(1);
observer.next(2);
observer.next(3);
Expand All @@ -23,8 +25,10 @@ var observable = Rx.Observable.create(function (observer) {

To invoke the Observable and see these values, we need to *subscribe* to it:

```js
var observable = Rx.Observable.create(function (observer) {
```ts
import { Observable } from 'rxjs';

const observable = Observable.create(function (observer) {
observer.next(1);
observer.next(2);
observer.next(3);
Expand Down Expand Up @@ -90,15 +94,15 @@ Contrary to popular claims, Observables are not like EventEmitters nor are they

Consider the following:

```js
```ts
function foo() {
console.log('Hello');
return 42;
}

var x = foo.call(); // same as foo()
const x = foo.call(); // same as foo()
console.log(x);
var y = foo.call(); // same as foo()
const y = foo.call(); // same as foo()
console.log(y);
```

Expand All @@ -113,8 +117,10 @@ We expect to see as output:

You can write the same behavior above, but with Observables:

```js
var foo = Rx.Observable.create(function (observer) {
```ts
import { Observable } from 'rxjs';

const foo = Observable.create(function (observer) {
console.log('Hello');
observer.next(42);
});
Expand Down Expand Up @@ -142,7 +148,6 @@ This happens because both functions and Observables are lazy computations. If yo

Some people claim that Observables are asynchronous. That is not true. If you surround a function call with logs, like this:

<!-- skip-example -->
```js
console.log('before');
console.log(foo.call());
Expand All @@ -160,7 +165,6 @@ You will see the output:

And this is the same behavior with Observables:

<!-- skip-example -->
```js
console.log('before');
foo.subscribe(function (x) {
Expand Down Expand Up @@ -194,8 +198,10 @@ function foo() {

Functions can only return one value. Observables, however, can do this:

```js
var foo = Rx.Observable.create(function (observer) {
```ts
import { Observable } from 'rxjs';

const foo = Observable.create(function (observer) {
console.log('Hello');
observer.next(42);
observer.next(100); // "return" another value
Expand All @@ -222,8 +228,10 @@ With synchronous output:

But you can also "return" values asynchronously:

```js
var foo = Rx.Observable.create(function (observer) {
```ts
import { Observable } from 'rxjs';

const foo = Observable.create(function (observer) {
console.log('Hello');
observer.next(42);
observer.next(100);
Expand Down Expand Up @@ -259,7 +267,7 @@ Conclusion:

## Anatomy of an Observable

Observables are **created** using `Rx.Observable.create` or a creation operator, are **subscribed** to with an Observer, **execute** to deliver `next` / `error` / `complete` notifications to the Observer, and their execution may be **disposed**. These four aspects are all encoded in an Observable instance, but some of these aspects are related to other types, like Observer and Subscription.
Observables are **created** using `Observable.create` or a creation operator, are **subscribed** to with an Observer, **execute** to deliver `next` / `error` / `complete` notifications to the Observer, and their execution may be **disposed**. These four aspects are all encoded in an Observable instance, but some of these aspects are related to other types, like Observer and Subscription.

Core Observable concerns:
- **Creating** Observables
Expand All @@ -269,13 +277,15 @@ Core Observable concerns:

### Creating Observables

`Rx.Observable.create` is an alias for the `Observable` constructor, and it takes one argument: the `subscribe` function.
`Observable.create` is an alias for the `Observable` constructor, and it takes one argument: the `subscribe` function.

The following example creates an Observable to emit the string `'hi'` every second to an Observer.

```js
var observable = Rx.Observable.create(function subscribe(observer) {
var id = setInterval(() => {
```ts
import { Observable } from 'rxjs';

const observable = Observable.create(function subscribe(observer) {
const id = setInterval(() => {
observer.next('hi')
}, 1000);
});
Expand All @@ -289,8 +299,7 @@ In the example above, the `subscribe` function is the most important piece to de

The Observable `observable` in the example can be *subscribed* to, like this:

<!-- skip-example -->
```js
```ts
observable.subscribe(x => console.log(x));
```

Expand Down Expand Up @@ -326,8 +335,10 @@ next*(error|complete)?

The following is an example of an Observable execution that delivers three Next notifications, then completes:

```js
var observable = Rx.Observable.create(function subscribe(observer) {
```ts
import { Observable } from 'rxjs';

const observable = Observable.create(function subscribe(observer) {
observer.next(1);
observer.next(2);
observer.next(3);
Expand All @@ -337,8 +348,10 @@ var observable = Rx.Observable.create(function subscribe(observer) {

Observables strictly adhere to the Observable Contract, so the following code would not deliver the Next notification `4`:

```js
var observable = Rx.Observable.create(function subscribe(observer) {
```ts
import { Observable } from 'rxjs';

const observable = Observable.create(function subscribe(observer) {
observer.next(1);
observer.next(2);
observer.next(3);
Expand All @@ -349,8 +362,10 @@ var observable = Rx.Observable.create(function subscribe(observer) {

It is a good idea to wrap any code in `subscribe` with `try`/`catch` block that will deliver an Error notification if it catches an exception:

```js
var observable = Rx.Observable.create(function subscribe(observer) {
```ts
import { Observable } from 'rxjs';

const observable = Observable.create(function subscribe(observer) {
try {
observer.next(1);
observer.next(2);
Expand All @@ -368,16 +383,17 @@ Because Observable Executions may be infinite, and it's common for an Observer t

When `observable.subscribe` is called, the Observer gets attached to the newly created Observable execution. This call also returns an object, the `Subscription`:

<!-- skip-example -->
```js
var subscription = observable.subscribe(x => console.log(x));
```ts
const subscription = observable.subscribe(x => console.log(x));
```

The Subscription represents the ongoing execution, and has a minimal API which allows you to cancel that execution. Read more about the [`Subscription` type here](./overview.html#subscription). With `subscription.unsubscribe()` you can cancel the ongoing execution:
The Subscription represents the ongoing execution, and has a minimal API which allows you to cancel that execution. Read more about the [`Subscription` type here](./subscription). With `subscription.unsubscribe()` you can cancel the ongoing execution:

```js
var observable = Rx.Observable.from([10, 20, 30]);
var subscription = observable.subscribe(x => console.log(x));
```ts
import { Observable } from 'rxjs';

const observable = Observable.from([10, 20, 30]);
const subscription = observable.subscribe(x => console.log(x));
// Later:
subscription.unsubscribe();
```
Expand Down
20 changes: 12 additions & 8 deletions doc/subscription.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,11 @@

**What is a Subscription?** A Subscription is an object that represents a disposable resource, usually the execution of an Observable. A Subscription has one important method, `unsubscribe`, that takes no argument and just disposes the resource held by the subscription. In previous versions of RxJS, Subscription was called "Disposable".

```js
var observable = Rx.Observable.interval(1000);
var subscription = observable.subscribe(x => console.log(x));
```ts
import { interval } from 'rxjs';

const observable = interval(1000);
const subscription = observable.subscribe(x => console.log(x));
// Later:
// This cancels the ongoing Observable execution which
// was started by calling subscribe with an Observer.
Expand All @@ -15,12 +17,14 @@ subscription.unsubscribe();

Subscriptions can also be put together, so that a call to an `unsubscribe()` of one Subscription may unsubscribe multiple Subscriptions. You can do this by "adding" one subscription into another:

```js
var observable1 = Rx.Observable.interval(400);
var observable2 = Rx.Observable.interval(300);
```ts
import { interval } from 'rxjs';

const observable1 = interval(400);
const observable2 = interval(300);

var subscription = observable1.subscribe(x => console.log('first: ' + x));
var childSubscription = observable2.subscribe(x => console.log('second: ' + x));
const subscription = observable1.subscribe(x => console.log('first: ' + x));
const childSubscription = observable2.subscribe(x => console.log('second: ' + x));

subscription.add(childSubscription);

Expand Down
Loading