docs(rxjs): Added developer guide on Observables

Author: brandonroberts

public/docs/_examples/rxjs/e2e-spec.ts

@@ -0,0 +1,12 @@
+'use strict'; // necessary for es6 output in node
+
+import { browser
+/*, element, by, ElementFinder*/
+} from 'protractor';
+
+describe('RxJS', function () {
+
+  beforeAll(function () {
+    browser.get('');
+  });
+});

public/docs/_examples/rxjs/ts/app/app-routing.module.ts

@@ -0,0 +1,19 @@
+// #docplaster
+// #docregion
+import { NgModule }             from '@angular/core';
+import { RouterModule, Routes } from '@angular/router';
+import { HomeComponent }        from './home.component';
+import { HeroDetailComponent }  from './hero-detail.component';
+import { HeroSearchComponent }  from './hero-search.component';
+
+const appRoutes: Routes = [
+  { path: '', component: HomeComponent },
+  { path: 'hero/search', component: HeroSearchComponent },
+  { path: 'hero/:id', component: HeroDetailComponent }
+];
+
+@NgModule({
+  imports: [RouterModule.forRoot(appRoutes)],
+  exports: [RouterModule]
+})
+export class AppRoutingModule {}

public/docs/_examples/rxjs/ts/app/app.component.ts

@@ -0,0 +1,15 @@
+// #docplaster
+// #docregion
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'my-app',
+  template: `
+    <h1 class="title">RxJS in Angular</h1>
+
+    <router-outlet></router-outlet>
+    <loading-component></loading-component>
+  `
+})
+export class AppComponent {
+}

public/docs/_examples/rxjs/ts/app/app.module.ts

@@ -0,0 +1,52 @@
+// #docregion
+import { NgModule }             from '@angular/core';
+import { BrowserModule }        from '@angular/platform-browser';
+import { HttpModule }           from '@angular/http';
+import { ReactiveFormsModule } from '@angular/forms';
+
+import { AppComponent }               from './app.component';
+import { AppRoutingModule }           from './app-routing.module';
+import { HomeComponent }              from './home.component';
+import { HeroesReadyComponent }       from './heroes-ready.component';
+import { CounterComponent }           from './counter.component';
+import { FormFieldComponent }         from './form-field.component';
+import { LoadingComponent }           from './loading.component';
+import { HeroSearchComponent }        from './hero-search.component';
+import { HeroDetailComponent }        from './hero-detail.component';
+import { HeroListComponent }          from './hero-list.component';
+
+import { LoadingService }             from './loading.service';
+import { HeroService }                from './hero.service';
+
+// Imports for loading & configuring the in-memory web api
+import { InMemoryWebApiModule } from 'angular-in-memory-web-api';
+import { InMemoryDataService }  from './in-memory-data.service';
+
+@NgModule({
+  imports: [
+    BrowserModule,
+    HttpModule,
+    AppRoutingModule,
+    ReactiveFormsModule,
+    InMemoryWebApiModule.forRoot(InMemoryDataService)
+  ],
+  declarations: [
+    AppComponent,
+    HomeComponent,
+    HeroesReadyComponent,
+    CounterComponent,
+    FormFieldComponent,
+    LoadingComponent,
+    HeroSearchComponent,
+    HeroDetailComponent,
+    HeroListComponent
+  ],
+  providers: [
+    HeroService,
+    LoadingService
+  ],
+  bootstrap: [ AppComponent ]
+})
+export class AppModule {
+}
+// #enddocregion

public/docs/_examples/rxjs/ts/app/counter.component.1.ts

@@ -0,0 +1,33 @@
+// #docplaster
+// #docregion
+import { Component, OnInit, OnDestroy } from '@angular/core';
+import { Subject } from 'rxjs/Subject';
+import { Subscription } from 'rxjs/Subscription';
+
+@Component({
+  selector: 'counter-component',
+  template: `
+    <p>
+      Hero Counter: {{ count }}
+
+      <button (click)="increment()">Increment</button>
+    </p>
+  `
+})
+export class CounterComponent implements OnInit, OnDestroy {
+  count: number = 0;
+  counter$ = new Subject();
+  sub: Subscription;
+
+  ngOnInit() {
+    this.sub = this.counter$.subscribe();
+  }
+
+  increment() {
+    this.counter$.next(this.count++);
+  }
+
+  ngOnDestroy() {
+    this.sub.unsubscribe();
+  }
+}

public/docs/_examples/rxjs/ts/app/counter.component.ts

@@ -0,0 +1,33 @@
+// #docplaster
+// #docregion
+import 'rxjs/add/operator/takeUntil';
+import { Component, OnInit, OnDestroy } from '@angular/core';
+import { Subject } from 'rxjs/Subject';
+
+@Component({
+  selector: 'counter-component',
+  template: `
+    <p>
+      Counter: {{ count }}
+
+      <button (click)="increment()">Increment</button>
+    </p>
+  `
+})
+export class CounterComponent implements OnInit, OnDestroy {
+  count: number = 0;
+  counter$ = new Subject();
+  destroy$: Subject<any> = new Subject();
+
+  ngOnInit() {
+    this.counter$.takeUntil(this.destroy$).subscribe();
+  }
+
+  increment() {
+    this.counter$.next(this.count++);
+  }
+
+  ngOnDestroy() {
+    this.destroy$.next();
+  }
+}

public/docs/_examples/rxjs/ts/app/event-aggregator.service.ts

@@ -0,0 +1,27 @@
+import { Injectable } from '@angular/core';
+import { BehaviorSubject } from 'rxjs/BehaviorSubject';
+
+export interface Event {
+  type: string;
+  message: string;
+}
+
+@Injectable()
+export class EventAggregatorService {
+  _events: Event[];
+  events$: BehaviorSubject<Event[]> = new BehaviorSubject<any>([]);
+
+  add(event: Event) {
+    this._events.push(event);
+    this.next();
+  }
+
+  clear() {
+    this._events = [];
+    this.next();
+  }
+
+  next() {
+    this.events$.next(this._events);
+  }
+}

public/docs/_examples/rxjs/ts/app/form-field.component.ts

@@ -0,0 +1,26 @@
+// #docplaster
+// #docregion
+import 'rxjs/add/observable/of';
+import 'rxjs/add/observable/fromEvent';
+import { Component, OnInit, ViewChild, ElementRef } from '@angular/core';
+import { Observable } from 'rxjs/Observable';
+
+@Component({
+  selector: 'form-field-component',
+  template: `
+    <h3>Observable Form Field</h3>
+    <p>
+      <input type="text" #name>
+      <span *ngIf="blurred$ | async">Blurred</span>
+    </p>
+  `
+})
+export class FormFieldComponent implements OnInit {
+  @ViewChild('name', { read: ElementRef }) name: ElementRef;
+
+  blurred$: Observable<boolean>;
+
+  ngOnInit() {
+    this.blurred$ = Observable.fromEvent(this.name.nativeElement, 'blur');
+  }
+}

public/docs/_examples/rxjs/ts/app/hero-detail.component.ts

@@ -0,0 +1,59 @@
+// #docplaster
+// #docregion
+import 'rxjs/add/observable/of';
+import 'rxjs/add/operator/map';
+import 'rxjs/add/operator/do';
+import 'rxjs/add/operator/filter';
+import { Component, OnInit } from '@angular/core';
+import { ActivatedRoute, Params } from '@angular/router';
+import { HeroService } from './hero.service';
+import { Hero } from './hero';
+import { Observable } from 'rxjs/Observable';
+
+@Component({
+  template: `
+    <div *ngIf="loading">
+      Loading Hero...
+    </div>
+    <div *ngIf="loaded && hero">
+      <h3>HEROES</h3>
+      <div>
+        <label>Id: </label>{{ hero.id }}
+      </div>
+      <div>
+        <label>Name: </label>
+        <input placeholder="name" [value]="hero.name"/>
+      </div>
+    </div>
+    <div *ngIf="loaded && !hero">
+      No hero found
+    </div>
+  `
+})
+export class HeroDetailComponent implements OnInit {
+  hero: Hero;
+  loading: boolean = true;
+  loaded: boolean;
+
+  constructor(
+    private heroService: HeroService,
+    private route: ActivatedRoute
+  ) {}
+
+  ngOnInit() {
+    this.route.params
+      .do(() => {
+        this.loading = true;
+        this.loaded = false;
+      })
+      .switchMap((params: Params) =>
+        this.heroService.getHero(params['id'])
+          .catch(() => Observable.of(null))
+      )
+      .do(() => {
+        this.loading = false;
+        this.loaded = true;
+      })
+      .subscribe(hero => this.hero = hero);
+  }
+}

public/docs/_examples/rxjs/ts/app/hero-list.component.1.ts

@@ -0,0 +1,31 @@
+// #docplaster
+// #docregion
+import { Component, OnInit }   from '@angular/core';
+
+import { HeroService }   from './hero.service';
+import { Hero }   from './hero';
+
+@Component({
+  selector: 'hero-list',
+  template: `
+    <h2>HEROES</h2>
+    <ul class="items">
+      <li *ngFor="let hero of heroes">
+        <span class="badge">{{ hero.id }}</span> {{ hero.name }}
+      </li>
+    </ul>
+  `
+})
+export class HeroListComponent implements OnInit {
+  heroes: Hero[];
+
+  constructor(
+    private service: HeroService
+  ) {}
+
+  ngOnInit() {
+    this.service.getHeroes()
+      .subscribe(heroes => this.heroes = heroes);
+  }
+}
+// #enddocregion

public/docs/_examples/rxjs/ts/app/hero-list.component.ts

@@ -0,0 +1,32 @@
+// #docplaster
+// #docregion
+import { Component, OnInit }   from '@angular/core';
+
+import { HeroService }   from './hero.service';
+import { Hero }   from './hero';
+
+@Component({
+  selector: 'hero-list',
+  template: `
+    <h2>HEROES</h2>
+    <ul class="items">
+      <li *ngFor="let hero of heroes">
+        <span class="badge">{{ hero.id }}</span> {{ hero.name }}
+      </li>
+    </ul>
+  `
+})
+export class HeroListComponent implements OnInit {
+  heroes: Hero[];
+
+  constructor(
+    private service: HeroService
+  ) {}
+
+  ngOnInit() {
+    this.service.getHeroes()
+      .toPromise()
+      .then(heroes => this.heroes = heroes);
+  }
+}
+// #enddocregion

public/docs/_examples/rxjs/ts/app/hero-search.component.css

@@ -0,0 +1,16 @@
+/* #docregion */
+.search-result{
+  border-bottom: 1px solid gray;
+  border-left: 1px solid gray;
+  border-right: 1px solid gray;
+  width:195px;
+  height: 20px;
+  padding: 5px;
+  background-color: white;
+  cursor: pointer;
+}
+
+.search-box{
+  width: 200px;
+  height: 20px;
+}

public/docs/_examples/rxjs/ts/app/hero-search.component.html

@@ -0,0 +1,12 @@
+<!-- #docregion -->
+<div id="search-component">
+  <h4>Hero Search</h4>
+  <form [formGroup]="form">
+    <input formControlName="searchTerms" class="search-box" />
+  </form>
+  <div>
+    <div *ngFor="let hero of heroes | async" class="search-result">
+      <a [routerLink]="['/hero', hero.id]">{{ hero.name }}</a>
+    </div>
+  </div>
+</div>

public/docs/_examples/rxjs/ts/app/hero-search.component.ts

@@ -0,0 +1,67 @@
+// #docplaster
+// #docregion
+import 'rxjs/add/operator/debounceTime';
+import 'rxjs/add/operator/distinctUntilChanged';
+import 'rxjs/add/operator/do';
+import 'rxjs/add/operator/filter';
+import 'rxjs/add/operator/switchMap';
+import 'rxjs/add/observable/merge';
+import { Component, OnInit, OnDestroy }   from '@angular/core';
+import { FormBuilder, FormGroup }         from '@angular/forms';
+import { Router, ActivatedRoute, Params } from '@angular/router';
+import { Observable }                     from 'rxjs/Observable';
+import { Subject }                        from 'rxjs/Subject';
+
+import { HeroService } from './hero.service';
+import { Hero } from './hero';
+
+@Component({
+  moduleId: module.id,
+  selector: 'hero-search',
+  templateUrl: 'hero-search.component.html',
+  styleUrls: [ 'hero-search.component.css' ]
+})
+export class HeroSearchComponent implements OnInit, OnDestroy {
+  heroes$: Observable<Hero[]>;
+  destroy$: Subject<any> = new Subject();
+  form: FormGroup;
+
+  constructor(
+    private heroService: HeroService,
+    private formBuilder: FormBuilder,
+    private route: ActivatedRoute,
+    private router: Router
+  ) {}
+
+  ngOnInit(): void {
+    this.form = this.formBuilder.group({
+      searchTerms: ['']
+    });
+
+    const searchTerms$: Observable<string> = this.form.valueChanges
+      .debounceTime(300)
+      .map(model => model.searchTerms);
+
+    const querySearch$: Observable<string> = this.route.queryParams
+      .map((params: Params) => params['q'])
+      .do(searchTerms => this.form.patchValue({
+        searchTerms
+      }));
+
+    this.heroes$ = Observable.merge(searchTerms$, querySearch$)
+      .distinctUntilChanged()
+      .takeUntil(this.destroy$)
+      .do(q => this.router.navigate(['./'], { queryParams: { q }, relativeTo: this.route }))
+      .switchMap(term => term
+        ? this.heroService.search(term)
+        : Observable.of<Hero[]>([])
+      )
+      .catch(error => {
+        return Observable.of<Hero[]>([]);
+      });
+  }
+
+  ngOnDestroy() {
+    this.destroy$.next();
+  }
+}

public/docs/_examples/rxjs/ts/app/hero.service.ts

@@ -0,0 +1,57 @@
+// #docplaster
+// #docregion
+import 'rxjs/add/operator/map';
+import 'rxjs/add/operator/delay';
+import 'rxjs/add/operator/catch';
+import 'rxjs/add/operator/toPromise';
+import 'rxjs/add/observable/throw';
+import { Injectable }    from '@angular/core';
+import { Http, Response } from '@angular/http';
+import { Observable }    from 'rxjs/Observable';
+
+import { Hero } from './hero';
+
+@Injectable()
+export class HeroService {
+  private heroesUrl = 'api/heroes';
+
+  constructor(private http: Http) { }
+
+  getHeroes(): Observable<Hero[]> {
+    return this.http.get(this.heroesUrl)
+      .map(response => response.json().data as Hero[]);
+  }
+
+  getHeroesNow(): Promise<Hero[]> {
+    return this.http.get(this.heroesUrl)
+      .map(response => response.json().data as Hero[])
+      .toPromise();
+  }
+
+  getHeroesSlowly(): Observable<Hero[]> {
+    return this.getHeroes().delay(3000);
+  }
+
+  getHero(id: number): Observable<Hero> {
+    const url = `${this.heroesUrl}/${id}`;
+    return this.http.get(url)
+      .map(response => response.json().data as Hero)
+      .catch(this.handleError);
+  }
+
+  getHeroesFailed() {
+    return this.getHeroes().map(() => {
+      throw new Error('I failed');
+    });
+  }
+
+  search(term: string): Observable<Hero[]> {
+    return this.http
+               .get(`app/heroes/?name=${term}`)
+               .map((r: Response) => r.json().data as Hero[]);
+  }
+
+  private handleError(error: any): Observable<any> {
+    return Observable.throw(error);
+  }
+}

public/docs/_examples/rxjs/ts/app/hero.ts

@@ -0,0 +1,4 @@
+export class Hero {
+  id: number;
+  name: string;
+}

public/docs/_examples/rxjs/ts/app/heroes-ready.component.1.ts

@@ -0,0 +1,30 @@
+// #docplaster
+// #docregion
+import { Component, OnInit } from '@angular/core';
+import { Observable } from 'rxjs/Observable';
+import { Observer } from 'rxjs/Observer';
+
+@Component({
+  selector: 'heroes-ready',
+  template: `
+    <p>
+      Heroes Ready: {{ counter }}
+
+      <button (click)="increment()">Increment</button>
+    </p>
+  `
+})
+export class HeroesReadyComponent implements OnInit {
+  counter: number = 0;
+  counter$: Observable<number>;
+
+  ngOnInit() {
+    this.counter$ = Observable.create((observer: Observer<number>) => {
+      observer.next(this.counter++);
+    });
+  }
+
+  increment() {
+    this.counter$.subscribe(count => console.log(count));
+  }
+}

public/docs/_examples/rxjs/ts/app/heroes-ready.component.2.ts

@@ -0,0 +1,34 @@
+// #docplaster
+// #docregion
+import { Component, OnInit } from '@angular/core';
+import { Observable } from 'rxjs/Observable';
+import { Observer } from 'rxjs/Observer';
+
+@Component({
+  selector: 'heroes-ready',
+  template: `
+    <p>
+      Heroes Ready: {{ counter }}
+
+      <button (click)="increment()">Increment</button>
+    </p>
+  `
+})
+export class HeroesReadyComponent implements OnInit {
+  counter: number = 0;
+  counter$: Observable<number>;
+
+  ngOnInit() {
+    this.counter$ = Observable.create((observer: Observer<number>) => {
+      this.counter++;
+      observer.next(this.counter);
+      this.counter++;
+      observer.next(this.counter);
+      observer.error('test');
+    });
+  }
+
+  increment() {
+    this.counter$.subscribe(count => console.log(count), () => console.log('error'));
+  }
+}

public/docs/_examples/rxjs/ts/app/heroes-ready.component.3.ts

@@ -0,0 +1,34 @@
+// #docplaster
+// #docregion
+import { Component, OnInit } from '@angular/core';
+import { Observable } from 'rxjs/Observable';
+import { Observer } from 'rxjs/Observer';
+
+@Component({
+  selector: 'heroes-ready',
+  template: `
+    <p>
+      Heroes Ready: {{ counter }}
+
+      <button (click)="increment()">Increment</button>
+    </p>
+  `
+})
+export class HeroesReadyComponent implements OnInit {
+  counter: number = 0;
+  counter$: Observable<number>;
+
+  ngOnInit() {
+    this.counter$ = Observable.create((observer: Observer<number>) => {
+      this.counter++;
+      observer.next(this.counter);
+      this.counter++;
+      observer.next(this.counter);
+      observer.complete();
+    });
+  }
+
+  increment() {
+    this.counter$.subscribe(count => console.log(count), () => {}, () => console.log('done'));
+  }
+}

public/docs/_examples/rxjs/ts/app/heroes-ready.component.ts

@@ -0,0 +1,34 @@
+// #docplaster
+// #docregion
+import { Component, OnInit } from '@angular/core';
+import { Observable } from 'rxjs/Observable';
+import { Observer } from 'rxjs/Observer';
+
+@Component({
+  selector: 'heroes-ready',
+  template: `
+    <p>
+      Heroes Ready: {{ counter }}
+
+      <button (click)="increment()">Increment</button>
+    </p>
+  `
+})
+export class HeroesReadyComponent implements OnInit {
+  counter: number = 0;
+  counter$: Observable<number>;
+
+  ngOnInit() {
+    this.counter$ = Observable.create((observer: Observer<number>) => {
+      this.counter++;
+      observer.next(this.counter);
+      this.counter++;
+      observer.next(this.counter);
+      observer.error('test');
+    });
+  }
+
+  increment() {
+    this.counter$.subscribe(count => console.log(count));
+  }
+}

public/docs/_examples/rxjs/ts/app/home.component.ts

@@ -0,0 +1,13 @@
+import { Component } from '@angular/core';
+
+@Component({
+  template: `
+    <heroes-ready></heroes-ready>
+    <counter-component></counter-component>
+    <form-field-component></form-field-component>
+    <hero-list></hero-list>
+  `
+})
+export class HomeComponent {
+
+}

public/docs/_examples/rxjs/ts/app/in-memory-data.service.ts

@@ -0,0 +1,19 @@
+// #docregion , init
+import { InMemoryDbService } from 'angular-in-memory-web-api';
+export class InMemoryDataService implements InMemoryDbService {
+  createDb() {
+    let heroes = [
+      {id: 1, name: 'Mr. Nice'},
+      {id: 2, name: 'Narco'},
+      {id: 3, name: 'Bombasto'},
+      {id: 4, name: 'Celeritas'},
+      {id: 5, name: 'Magneta'},
+      {id: 6, name: 'RubberMan'},
+      {id: 7, name: 'Dynama'},
+      {id: 8, name: 'Dr IQ'},
+      {id: 9, name: 'Magma'},
+      {id: 10, name: 'Tornado'}
+    ];
+    return {heroes};
+  }
+}

public/docs/_examples/rxjs/ts/app/loading.component.ts

@@ -0,0 +1,22 @@
+import { Component, OnInit } from '@angular/core';
+
+import { LoadingService } from './loading.service';
+
+@Component({
+  selector: 'loading-component',
+  template: `
+    <div [class.loading]="loading" *ngIf="loading">LOADING</div>
+  `
+})
+export class LoadingComponent implements OnInit {
+  loading: boolean;
+
+  constructor(private loadingService: LoadingService) {}
+
+  ngOnInit() {
+    this.loadingService.loading$.subscribe(loading => {
+      console.log(loading);
+      this.loading = loading;
+    });
+  }
+}

public/docs/_examples/rxjs/ts/app/loading.service.ts

@@ -0,0 +1,20 @@
+import 'rxjs/add/operator/map';
+import { Injectable } from '@angular/core';
+import { Router, Event, RoutesRecognized, NavigationStart } from '@angular/router';
+import { Observable } from 'rxjs/Observable';
+
+@Injectable()
+export class LoadingService {
+  loading$: Observable<boolean>;
+
+  constructor(private router: Router) {
+    this.loading$ = this.router.events.map((event: Event) => {
+      if ( event instanceof NavigationStart || event instanceof RoutesRecognized) {
+        return true;
+      } else {
+        // return false for NavigationEnd, NavigationError and NavigationCancel events
+        return false;
+      }
+    });
+  }
+}

public/docs/_examples/rxjs/ts/app/main.ts

@@ -0,0 +1,6 @@
+// #docregion
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+
+import { AppModule } from './app.module';
+
+platformBrowserDynamic().bootstrapModule(AppModule);

public/docs/_examples/rxjs/ts/example-config.json

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<!-- #docregion -->
+<html>
+  <head>
+    <!-- Set the base href -->
+    <base href="/">
+    <title>RxJS Observables</title>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <link rel="stylesheet" href="styles.css">
+
+    <!-- Polyfills for older browsers -->
+    <script src="node_modules/core-js/client/shim.min.js"></script>
+
+    <script src="node_modules/zone.js/dist/zone.js"></script>
+    <script src="node_modules/reflect-metadata/Reflect.js"></script>
+    <script src="node_modules/systemjs/dist/system.src.js"></script>
+
+    <script src="systemjs.config.js"></script>
+    <script>
+      System.import('app')
+            .catch(function(err){ console.error(err); });
+    </script>
+  </head>
+
+  <body>
+    <my-app>loading...</my-app>
+  </body>
+
+</html>
+<!-- #enddocregion -->

public/docs/_examples/rxjs/ts/index.html

@@ -0,0 +1,9 @@
+{
+  "description": "RxJS",
+  "files":[
+    "!**/*.d.ts",
+    "!**/*.js",
+    "!**/*.[0-9].*"
+  ],
+  "tags": ["rxjs", "observable"]
+}

public/docs/_examples/rxjs/ts/plnkr.json

@@ -0,0 +1,182 @@
+block includes
+  include ../_util-fns
+
+:marked
+  **Observables** provided by the Reactive Extensions for Javascript (RxJS) library provide applications with an extensive API
+  for handling asynchronous and event-based values produced over time.
+
+  An application is made up of many different streams of information. Whether it be user input into
+  a form, navigating from one route another, making an HTTP request to fetch some data, updating the application view with
+  new data as its received, or many other examples, each of these events happen over time. Observables provide a interface to
+  handle the many different sources of events and help to transform these events as they flow throughout an application.
+
+  This guide will serve as an introductory chapter to Observables, common uses cases for Observables in an Angular application
+  and how Observables are used and provided by the Angular framework.
+
+  ## Table of Contents
+  * [The Observable](#definition "")
+  * [Observables and Promises](#promises "")
+  * [Observable Lifecycle](#lifecycle "")
+  * [Observer](#lifecycle "")
+  * [Subscriptions](#subscriptions "")
+  * [Creating Observables](#creating "")
+  * [Operators](#transforming "")
+  * [Error Handling](#error-handling "")
+  * [Framework APIs](#apis "")
+  * [Impact on Change Detection](#change-detection "")
+  * [Further Reading](#reading "")
+
+:marked
+  The Observable: a function at its core
+
+  An Observable, simply put, is a specific type of function with a specific purpose. Its a function that accepts an `Observer` to produce values and
+  returns a function for cancellation. It represents an action that can be performed. This action may be performed right now, or at some point
+  in the future.
+
+  An action can be anything, from simply "return a constant" to "make an HTTP request". Here’s a simple "action" function that increments a counter
+  and returns the new value.
+
+  // Example of simple counter
+
+  The same functionality can be produced with an Observable. Observables don't return values directly, as they can be produced synchronously asynchronously.
+  An Observer is used by an Observable to consume its produced values.
+
+  // Example of observable counter
+
+  There is a key difference between these two examples. In the first counter example, the results of the action were produced when the function was called.
+  In the Observable counter, the Observable was created, with the [Observer](https://en.wikipedia.org/wiki/Observer_pattern) to produce values and the value incremented but the action hasn't been performed yet.
+  It represents an action we've defined, but it hasn't been executed.
+
+  // Example of subscribing to observable counter
+
+  Observable streams are **cold** or **lazy** by nature, meaning that until you invoke them, they will not produce
+  any values. Invoking an Observable is done using the `subscribe` method, which makes the Observable **hot** and calls the observer's method to produce
+  values. The `subscribe` function also returns an object with an `unsubscribe` from an Observable and no longer receive the values it produces.
+
+  // Example of unsubscribing
+
+  Managing the lifecycle of an Observable will be discussed later in the chapter.
+
+:marked
+  Observables and Promises: More different than alike
+
+  RxJS and Observables have been around for a long time, and they aren't the first concept of handling asynchronous events. Before Observables became more prevalent,
+  the `Promise` was the primary way of handling asynchronous events. Promises and Observables share some similarities as they both handle asynchronous events,
+  both implement a function to handle execution and error handling, but they are more different then alike.
+
+  Promises
+  * Produce a one-time value
+  * Can be composed
+  * Are always resolved/rejected asynchronously
+  * Are always multicast to multiple receivers
+
+  Observables
+  * Produce a number of values over time
+  * Can be composed
+  * Resolve synchronously/asynchronously
+  * Multicast when needed
+
+  The strength of Observables is producing and handling values over time, which is something a Promise wasn't designed to do. Observables also provide mechanisms
+  for easy cancellation, retrying upon failure and transformations. Observables include a rich library of operators, along with the extensibility to provide a more powerful
+  tool to handle the various streams of events in an application. So does this mean Promises are no longer needed? Absolutely not. Promises will continue to serve a purpose as the right tool for the job in some situations.
+  The good news is Observables support conversion to a Promise for instances where a one-off value needs to be produced without managing the lifecycle
+  of an Observable.
+
+:marked
+  Observable Anatomy: Next, Error, and Complete
+
+  Even though an Observable is a function that performs an action, it has a lifecycle. An Observable has 3 types of notifications it produces through its
+  lifetime: `next`, `error`, and `complete`.
+
+  The `next` is called whenever the observable produces a new value, notifying the Observer
+  that some value was produced. The `next` Observables may produce a single value, or multiple values over time. These values can be a number, string, object
+
+
+  Let's modify the HeroesReadyComponent to produce two values when subscribed.
+
+  // Example of Observable that produces 2 values
+
+  When click the `increment` button this time and subscribes to the Observable, the counter will be incremented twice and produce two values.
+
+  Whenever an Observable produces an error, it uses the `error` event. An error event can only happen once during the invocation of an Observable action.
+
+  // Example of Observable that errors
+
+  The Observable notifies its Observer through that an error has occurred.
+
+  Observables can also notify observers of completion. A completion event signals that no more values will be produced by the Observable. Like the error event,
+  a completion event can only happen once.
+
+  // Example of Observable that produces values, then completes
+
+:marked
+  Observer: The Observable's Consumer
+  An Observer is provided to an Observable to consume its values produced. An observer provides callbacks for the notification types produced by an Observable: `next`,
+  `error`, and `complete`.
+
+  An Observer is provided to an Observable through the `subscribe` method in 2 ways
+
+  * As a single object containing 3 callbacks for each notification.
+  * As 3 arguments in the subscribe method for each notification
+
+  // Example of single object and logging out each notification
+
+  // Example of 3 arguments to subscribe method
+
+:marked
+  Subscription: Maintaining of resources
+
+  As mentioned earlier, an Observable is not invoked until its `subscribed` to. This starts the execution of the Observable to produce values or events to an Observer.
+  This subscription is an allocation of resources for the action performed by the Observable. Naturally, you want to clean up resources used by the Observable when
+  finished with its execution. Each time an Observable is subscribed, it returns a `Subscription`. The `Subscription` is an object that handles the resources provided
+  by the Observable, along with the `unsubscribe`. The `unsubscribe` method provided by the `Subscription` disposes of the resources allocated by the Observable.
+
+  // Example of unsubscribing
+
+  As a general rule and good practice, resources that are allocated and used must be cleaned up, and the Observable subscription is no different. Angular provides
+  APIs that manage Observable lifecycles without the need to unsubscribe, but for those Observables you create, cleanup of resources is a must to protect against
+  memory leaks and other unwanted side effects.
+
+  // Example of unsubscribe in ngOnDestroy
+
+  In this example, only one subscription is used and disposed of. Managing multiple subscriptions using the `unsubscribe` method
+  has the potential to get unwieldy. You'll learn about different ways to to end subscriptions of multiple Observables later in the chapter.
+
+  // Example of unsubscribe using a Subject
+
+:marked
+  Operators: Observable functions
+
+  The Observable prototype contains many `operators`, which are methods that perform an operation. Operators are **pure functions**
+  that are stateless. Stateless operators are less error-prone as they are provided an Observable, in which an operation is performed on,
+  and return a new Observable, without modifying the original Observable. The Observable prototype comes with a minimal set of operators by default,
+  with a large set of operators that can be added. Operators are also used to (create Observable instances) from existing events.
+
+  There are different ways to access the operators provided by RxJS: By patching the Observable prototype or by importing the operator functions directly.
+  Each operator only needs to be patched on the prototype once, but where you choose to patch the Observable requires consideration. We'll examine a
+  few options below:
+
+  // Example of importing entire rxjs/Rx library
+
+  By importing `rxjs/Rx`, the **entire** set of RxJS operators are added to the Observable prototype. In most cases, you will only use a subset of
+  the available operators and adding the entire set increases the overall bundle size of your application. This is
+  only recommended for sample apps, and in testing environments.
+
+  // Example of patching the Observable prototype
+
+  Since minimizing bundle size is a recommended practice, you should only import the operators you need, where you need them.
+  This approach includes importing operators multiple times in different files, but safeguards against using operators
+  without having patched the Observable prototype first. Since feature areas can be loaded lazily, this also allows you the benefit
+  of keeping certain operators in separate bundles and only loaded them when needed.
+
+  // Example of importing operators directly
+
+  // Note about tree-shaking when pat
+
+  NOTE: Operators patched onto the Observable prototype that are unused will not be tree-shaken.
+
+  Operators can also be directly imported and used without patching the Observable prototype. This is the
+  recommended option for third-party libraries, staying with the approach to only import what you need. It
+  is also more suited for tree-shaking when bundling your Angular application.
+
+:marked