docs(rxjs): [WIP] Ward's contributions

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

@@ -2,6 +2,7 @@
 // #docregion
 import { Component, OnInit } from '@angular/core';
 import { EventAggregatorService } from './event-aggregator.service';
+import { ObservablePrinciples }   from './observable-principles';
 
 @Component({
   selector: 'my-app',
@@ -19,12 +20,17 @@ import { EventAggregatorService } from './event-aggregator.service';
   `
 })
 export class AppComponent implements OnInit {
-  constructor(private eventService: EventAggregatorService) {}
+  constructor(
+    private eventService: EventAggregatorService,
+    private principles: ObservablePrinciples) {}
 
   ngOnInit() {
     this.eventService.add({
       type: 'init',
       message: 'Application Initialized'
     });
+
+    this.principles.callFunctionalExamples();
+    this.principles.callPromiseExamples();
   }
 }

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

@@ -12,6 +12,7 @@ import { MessageLogComponent }        from './message-log.component';
 import { LoadingComponent }           from './loading.component';
 import { AddHeroComponent }           from './add-hero.component';
 
+import { ObservablePrinciples }       from './observable-principles';
 import { LoadingService }             from './loading.service';
 import { HeroService }                from './hero.service';
 
@@ -40,6 +41,7 @@ import { InMemoryDataService }  from './in-memory-data.service';
     AddHeroComponent
   ],
   providers: [
+    ObservablePrinciples,
     HeroService,
     LoadingService,
     EventAggregatorService

public/docs/_examples/rxjs/ts/src/app/observable-principles.ts

@@ -0,0 +1,133 @@
+// Demonstrate Observable principles discussed in the doc
+// #docplaster
+import { Injectable } from '@angular/core';
+import { Http } from '@angular/http';
+
+import { Observable } from 'rxjs/Observable';
+
+import 'rxjs/add/observable/fromPromise';
+import 'rxjs/add/observable/interval';
+
+import 'rxjs/add/operator/do';
+import 'rxjs/add/operator/filter';
+import 'rxjs/add/operator/map';
+import 'rxjs/add/operator/take';
+import 'rxjs/add/operator/toPromise';
+
+import { Hero } from './hero';
+import { InMemoryDataService }  from './in-memory-data.service';
+import { EventAggregatorService } from './event-aggregator.service';
+
+
+@Injectable()
+export class ObservablePrinciples {
+  private heroesUrl = 'api/heroes';
+
+  constructor(
+    private http: Http,
+    private eventService: EventAggregatorService) { }
+
+  functionalArray() {
+    // #docregion functional-array
+    // double the odd numbers in the array.
+    const numbers = [0, 1, 2, 3, 4, 5];
+    return numbers.filter(n => n % 2 === 1).map(n => n * 2);
+    // #enddocregion functional-array
+  }
+
+  functionalEvents() {
+    // #docregion functional-events
+    // double the next odd integer every tick ... forever.
+    const numbers = Observable.interval(0);
+    return numbers.filter(n => n % 2 === 1).map(n => n * 2);
+    // #enddocregion functional-events
+  }
+
+  /**
+   * Call the functional array and event example methods
+   * and write their results to the EventAggregatorService
+   * for display in AppComponent.
+   */
+  callFunctionalExamples() {
+
+    this.eventService.add({
+      type: 'array',
+      message: `array of numbers: ${this.functionalArray()}`}
+    );
+
+    // Stop after 3
+    this.functionalEvents().take(3).subscribe(
+      result => this.eventService.add({
+        type: 'number stream',
+        message: `stream of numbers: ${result}`}
+      )
+    );
+  }
+
+ /////////////////
+
+ /**
+  * A `fromPromise` example that converts the `Promise` result
+  * of the `fetch` API into an Observable of heroes.
+  */
+  fetchHeroes(): Observable<Hero[]> {
+
+  // #docregion fromPromise
+    // JavaScript fetch returns a Promise
+    let promise = fetch(this.heroesUrl)
+      .then(resp => resp.json() as Promise<Hero[]>)
+      .then(heroes => { console.log(heroes); return heroes; });
+
+    // return an Observable
+    return Observable.fromPromise(promise);
+  // #enddocregion fromPromise
+  }
+
+ /**
+  * A `toPromise` example that converts the `Observable` result
+  * of the Angular `http` API into a Promise of heroes.
+  */
+  getHeroes(): Promise<Hero[]> {
+
+  // #docregion toPromise
+    // Angular http.get returns an Observable
+    let observable = this.http.get(this.heroesUrl)
+      .map(resp => resp.json().data as Hero[])
+      .do(heroes => console.log(heroes));
+
+    // return a Promise
+    return observable.toPromise();
+  // #enddocregion toPromise
+  }
+
+  /**
+   * Call the fromPromise and toPromise example methods
+   * and write their results to the EventAggregatorService
+   * for display in AppComponent.
+   */
+  callPromiseExamples() {
+
+    this.fetchHeroes()
+      .subscribe(
+        heroes => this.eventService.add({type: 'fetch', message: 'fetched heroes'}),
+        error => this.eventService.add({type: 'fetch', message: 'fetchHeroes failed'})
+      );
+
+    this.getHeroes()
+      .then(
+        heroes => this.eventService.add({type: 'get', message: 'got heroes'}),
+        error => this.eventService.add({type: 'get', message: 'getHeroes failed'})
+      );
+  }
+}
+
+// Fake the JavaScript fetch API (https://fetch.spec.whatwg.org/) because
+// don't want to add another polyfill for browsers that don't support fetch
+// and it's not important for this example.
+function fetch(url: string) {
+   const heroes = new InMemoryDataService().createDb().heroes;
+   const resp = { json: () => Promise.resolve(heroes) as Promise<any>};
+   return new Promise<typeof resp>(resolve => {
+      setTimeout(() => resolve(resp), 500); // respond after half second
+   });
+}

public/docs/_examples/rxjs/ts/src/heroes.json

@@ -0,0 +1,12 @@
+[
+  {"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"}
+]

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

@@ -1,6 +1,8 @@
-// #docregion
 import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
 
 import { AppModule } from './app/app.module';
 
-platformBrowserDynamic().bootstrapModule(AppModule);
+// #docregion promise
+platformBrowserDynamic().bootstrapModule(AppModule)
+  .then(() => console.log('The app was bootstrapped.'));
+// #enddocregion promise

public/docs/ts/latest/guide/_data.json

@@ -169,7 +169,7 @@
 
   "rxjs": {
     "title": "RxJS in Angular",
-    "intro": "Using Observables to manage application streams."
+    "intro": "Using Observables to manage asynchronous application events."
   },
 
   "security": {

public/docs/ts/latest/guide/change-log.jade

@@ -5,6 +5,9 @@ block includes
   The Angular documentation is a living document with continuous improvements.
   This log calls attention to recent significant changes.
 
+  ## NEW: _RxJS in Angular_ guide (2017-03-13)
+  The new [_Rxjs in Angular_](rxjs.htm) guide explains why and how to use RxJS `Observables` to handle asynchronous application events.
+
   ## NEW: Downloadable examples for each guide (2017-02-28)
   Now you can download the sample code for any guide and run it locally.
   Look for the new download links next to the "live example" links.