docs(Http): add docs for Http lib

Fixes angular#2442

Author: jeffbcross

docs/public-docs-package/index.js

@@ -10,8 +10,9 @@ module.exports = new Package('angular-public', [basePackage])
     'angular2/core.ts',
     'angular2/di.ts',
     'angular2/directives.ts',
+    'angular2/http.ts',
     'angular2/forms.ts',
-    'angular2/router.js',
+    'angular2/router.ts',
     'angular2/test.ts',
     'angular2/pipes.ts'
   ];

modules/angular2/angular2.ts

@@ -4,6 +4,7 @@ export * from './annotations';
 export * from './directives';
 export * from './forms';
 export * from './di';
+export * from './http';
 export {Observable, EventEmitter} from 'angular2/src/facade/async';
 export * from 'angular2/src/render/api';
 export {DomRenderer, DOCUMENT_TOKEN} from 'angular2/src/render/dom/dom_renderer';

modules/angular2/http.dart

@@ -0,0 +1 @@
+library angular2.http;

modules/angular2/http.ts

@@ -1,10 +1,41 @@
+/**
+ * @module
+ * @public
+ * @description
+ * The http module provides services to perform http requests. To get started, see the {@link Http}
+ * class.
+ */
 import {bind, Binding} from 'angular2/di';
 import {Http, HttpFactory} from './src/http/http';
-import {XHRBackend} from 'angular2/src/http/backends/xhr_backend';
+import {XHRBackend, XHRConnection} from 'angular2/src/http/backends/xhr_backend';
 import {BrowserXHR} from 'angular2/src/http/backends/browser_xhr';
-import {BaseRequestOptions} from 'angular2/src/http/base_request_options';
+import {BaseRequestOptions, RequestOptions} from 'angular2/src/http/base_request_options';
 
-export {Http};
+export {MockConnection, MockBackend} from 'angular2/src/http/backends/mock_backend';
+export {Request} from 'angular2/src/http/static_request';
+export {Response} from 'angular2/src/http/static_response';
+
+export {Http, XHRBackend, XHRConnection, BaseRequestOptions, RequestOptions, HttpFactory};
+export {IHttp} from 'angular2/src/http/interfaces';
+export {Headers} from 'angular2/src/http/headers';
+
+/**
+ * Provides a basic set of injectables to use the {@link Http} service in any application.
+ *
+ * #Example
+ *
+ * ```
+ * import {httpInjectables, Http} from 'angular2/http';
+ * @Component({selector: 'http-app', appInjector: [httpInjectables]})
+ * @View({template: '{{data}}'})
+ * class MyApp {
+ *   constructor(http:Http) {
+ *     http.request('data.txt').subscribe(res => this.data = res.text());
+ *   }
+ * }
+ * ```
+ *
+ */
 export var httpInjectables: List<any> = [
   bind(BrowserXHR)
       .toValue(BrowserXHR),

modules/angular2/src/http/backends/mock_backend.ts

@@ -2,31 +2,40 @@ import {Injectable} from 'angular2/di';
 import {Request} from 'angular2/src/http/static_request';
 import {Response} from 'angular2/src/http/static_response';
 import {ReadyStates} from 'angular2/src/http/enums';
+import {Connection, ConnectionBackend} from 'angular2/src/http/interfaces';
 import * as Rx from 'rx';
 
 /**
- * Connection represents a request and response for an underlying transport, like XHR or mock.
- * The mock implementation contains helper methods to respond to connections within tests.
- * API subject to change and expand.
+ *
+ * Connection class used by MockBackend
+ *
+ * This class is typically not instantiated directly, but instances can be retrieved by subscribing
+ *to the `connections` Observable of
+ * {@link MockBackend} in order to mock responses to requests.
+ *
  **/
-export class Connection {
+export class MockConnection implements Connection {
+  // TODO Name `readyState` should change to be more generic, and states could be made to be more
+  // descriptive than XHR states.
   /**
-   * Observer to call on download progress, if provided in config.
-   **/
-  downloadObserver: Rx.Observer<Response>;
+   * Describes the state of the connection, based on `XMLHttpRequest.readyState`, but with
+   * additional states. For example, state 5 indicates an aborted connection.
+   */
+  readyState: ReadyStates;
 
   /**
-   * TODO
-   * Name `readyState` should change to be more generic, and states could be made to be more
-   * descriptive than XHR states.
-   **/
-
-  readyState: ReadyStates;
+   * {@link Request} instance used to create the connection.
+   */
   request: Request;
+
+  /**
+   * [RxJS
+   * Observable](https://github.com/Reactive-Extensions/RxJS/blob/master/doc/api/core/observable.md)
+   * of {@link Response}. Can be subscribed to in order to be notified when a response is available.
+   */
   response: Rx.Subject<Response>;
 
   constructor(req: Request) {
-    // State
     if (Rx.hasOwnProperty('default')) {
       this.response = new ((<any>Rx).default.Rx.Subject)();
     } else {
@@ -38,15 +47,29 @@ export class Connection {
     this.dispose = this.dispose.bind(this);
   }
 
+  /**
+   * Changes the `readyState` of the connection to a custom state of 5 (cancelled).
+   */
   dispose() {
     if (this.readyState !== ReadyStates.DONE) {
       this.readyState = ReadyStates.CANCELLED;
     }
   }
 
   /**
-   * Called after a connection has been established.
-   **/
+   * Sends a mock response to the connection. This response is the value that is emitted to the
+   * `Observable` returned by {@link Http}.
+   *
+   * #Example
+   *
+   * ```
+   * var connection;
+   * backend.connections.subscribe(c => connection = c);
+   * http.request('data.json').subscribe(res => console.log(res.text()));
+   * connection.mockRespond(new Response('fake response')); //logs 'fake response'
+   * ```
+   *
+   */
   mockRespond(res: Response) {
     if (this.readyState >= ReadyStates.DONE) {
       throw new Error('Connection has already been resolved');
@@ -56,13 +79,24 @@ export class Connection {
     this.response.onCompleted();
   }
 
+  /**
+   * Not yet implemented!
+   *
+   * Sends the provided {@link Response} to the `downloadObserver` of the `Request`
+   * associated with this connection.
+   */
   mockDownload(res: Response) {
-    this.downloadObserver.onNext(res);
-    if (res.bytesLoaded === res.totalBytes) {
-      this.downloadObserver.onCompleted();
-    }
+    // this.request.downloadObserver.onNext(res);
+    // if (res.bytesLoaded === res.totalBytes) {
+    //   this.request.downloadObserver.onCompleted();
+    // }
   }
 
+  // TODO(jeffbcross): consider using Response type
+  /**
+   * Emits the provided error object as an error to the {@link Response} observable returned
+   * from {@link Http}.
+   */
   mockError(err?) {
     // Matches XHR semantics
     this.readyState = ReadyStates.DONE;
@@ -71,35 +105,135 @@ export class Connection {
   }
 }
 
+/**
+ * A mock backend for testing the {@link Http} service.
+ *
+ * This class can be injected in tests, and should be used to override bindings
+ * to other backends, such as {@link XHRBackend}.
+ *
+ * #Example
+ *
+ * ```
+ * import {MockBackend, DefaultOptions, Http} from 'angular2/http';
+ * it('should get some data', inject([AsyncTestCompleter], (async) => {
+ *   var connection;
+ *   var injector = Injector.resolveAndCreate([
+ *     MockBackend,
+ *     bind(Http).toFactory((backend, defaultOptions) => {
+ *       return new Http(backend, defaultOptions)
+ *     }, [MockBackend, DefaultOptions])]);
+ *   var http = injector.get(Http);
+ *   var backend = injector.get(MockBackend);
+ *   //Assign any newly-created connection to local variable
+ *   backend.connections.subscribe(c => connection = c);
+ *   http.request('data.json').subscribe((res) => {
+ *     expect(res.text()).toBe('awesome');
+ *     async.done();
+ *   });
+ *   connection.mockRespond(new Response('awesome'));
+ * }));
+ * ```
+ *
+ * This method only exists in the mock implementation, not in real Backends.
+ **/
 @Injectable()
-export class MockBackend {
-  connections: Rx.Subject<Connection>;
-  connectionsArray: Array<Connection>;
-  pendingConnections: Rx.Observable<Connection>;
+export class MockBackend implements ConnectionBackend {
+  /**
+   * [RxJS
+   * Subject](https://github.com/Reactive-Extensions/RxJS/blob/master/doc/api/subjects/subject.md)
+   * of {@link MockConnection} instances that have been created by this backend. Can be subscribed
+   * to in order to respond to connections.
+   *
+   * #Example
+   *
+   * ```
+   * import {MockBackend, Http, BaseRequestOptions} from 'angular2/http';
+   * import {Injector} from 'angular2/di';
+   *
+   * it('should get a response', () => {
+   *   var connection; //this will be set when a new connection is emitted from the backend.
+   *   var text; //this will be set from mock response
+   *   var injector = Injector.resolveAndCreate([
+   *     MockBackend,
+   *     bind(Http).toFactory(backend, options) {
+   *       return new Http(backend, options);
+   *     }, [MockBackend, BaseRequestOptions]]);
+   *   var backend = injector.get(MockBackend);
+   *   var http = injector.get(Http);
+   *   backend.connections.subscribe(c => connection = c);
+   *   http.request('something.json').subscribe(res => {
+   *     text = res.text();
+   *   });
+   *   connection.mockRespond(new Response('Something'));
+   *   expect(text).toBe('Something');
+   * });
+   * ```
+   *
+   * This property only exists in the mock implementation, not in real Backends.
+   */
+  connections: Rx.Subject<MockConnection>;
+
+  /**
+   * An array representation of `connections`. This array will be updated with each connection that
+   * is created by this backend.
+   *
+   * This property only exists in the mock implementation, not in real Backends.
+   */
+  connectionsArray: Array<MockConnection>;
+  /**
+   * [Observable](https://github.com/Reactive-Extensions/RxJS/blob/master/doc/api/core/observable.md)
+   * of {@link MockConnection} instances that haven't yet been resolved (i.e. with a `readyState`
+   * less than 4). Used internally to verify that no connections are pending via the
+   * `verifyNoPendingRequests` method.
+   *
+   * This property only exists in the mock implementation, not in real Backends.
+   */
+  pendingConnections: Rx.Observable<MockConnection>;
   constructor() {
+    var Observable;
     this.connectionsArray = [];
     if (Rx.hasOwnProperty('default')) {
       this.connections = new (<any>Rx).default.Rx.Subject();
+      Observable = (<any>Rx).default.Rx.Observable;
     } else {
-      this.connections = new Rx.Subject<Connection>();
+      this.connections = new Rx.Subject<MockConnection>();
+      Observable = Rx.Observable;
     }
     this.connections.subscribe(connection => this.connectionsArray.push(connection));
-    this.pendingConnections = this.connections.filter((c) => c.readyState < ReadyStates.DONE);
+    this.pendingConnections =
+        Observable.fromArray(this.connectionsArray).filter((c) => c.readyState < ReadyStates.DONE);
   }
 
+  /**
+   * Checks all connections, and raises an exception if any connection has not received a response.
+   *
+   * This method only exists in the mock implementation, not in real Backends.
+   */
   verifyNoPendingRequests() {
     let pending = 0;
     this.pendingConnections.subscribe((c) => pending++);
     if (pending > 0) throw new Error(`${pending} pending connections to be resolved`);
   }
 
+  /**
+   * Can be used in conjunction with `verifyNoPendingRequests` to resolve any not-yet-resolve
+   * connections, if it's expected that there are connections that have not yet received a response.
+   *
+   * This method only exists in the mock implementation, not in real Backends.
+   */
   resolveAllConnections() { this.connections.subscribe((c) => c.readyState = 4); }
 
+  /**
+   * Creates a new {@link MockConnection}. This is equivalent to calling `new
+   * MockConnection()`, except that it also will emit the new `Connection` to the `connections`
+   * observable of this `MockBackend` instance. This method will usually only be used by tests
+   * against the framework itself, not by end-users.
+   */
   createConnection(req: Request) {
     if (!req || !(req instanceof Request)) {
       throw new Error(`createConnection requires an instance of Request, got ${req}`);
     }
-    let connection = new Connection(req);
+    let connection = new MockConnection(req);
     this.connections.onNext(connection);
     return connection;
   }

modules/angular2/src/http/backends/xhr_backend.ts

@@ -7,8 +7,21 @@ import {Injectable} from 'angular2/di';
 import {BrowserXHR} from './browser_xhr';
 import * as Rx from 'rx';
 
+/**
+ * Creates connections using `XMLHttpRequest`. Given a fully-qualified
+ * request, an `XHRConnection` will immediately create an `XMLHttpRequest` object and send the
+ * request.
+ *
+ * This class would typically not be created or interacted with directly inside applications, though
+ * the {@link MockConnection} may be interacted with in tests.
+ */
 export class XHRConnection implements Connection {
   request: Request;
+  /**
+   * Response
+   * [Subject](https://github.com/Reactive-Extensions/RxJS/blob/master/doc/api/subjects/subject.md)
+   * which emits a single {@link Response} value on load event of `XMLHttpRequest`.
+   */
   response: Rx.Subject<Response>;
   readyState: ReadyStates;
   private _xhr;
@@ -20,6 +33,7 @@ export class XHRConnection implements Connection {
       this.response = new Rx.Subject<Response>();
     }
     this._xhr = new NativeConstruct();
+    // TODO(jeffbcross): implement error listening/propagation
     this._xhr.open(RequestMethods[req.method], req.url);
     this._xhr.addEventListener(
         'load',
@@ -28,9 +42,38 @@ export class XHRConnection implements Connection {
     this._xhr.send(this.request.text());
   }
 
+  /**
+   * Calls abort on the underlying XMLHttpRequest.
+   */
   dispose(): void { this._xhr.abort(); }
 }
 
+/**
+ * Creates {@link XHRConnection} instances.
+ *
+ * This class would typically not be used by end users, but could be
+ * overridden if a different backend implementation should be used,
+ * such as in a node backend.
+ *
+ * #Example
+ *
+ * ```
+ * import {Http, MyNodeBackend, httpInjectables, BaseRequestOptions} from 'angular2/http';
+ * @Component({
+ *   appInjector: [
+ *     httpInjectables,
+ *     bind(Http).toFactory((backend, options) => {
+ *       return new Http(backend, options);
+ *     }, [MyNodeBackend, BaseRequestOptions])]
+ * })
+ * class MyComponent {
+ *   constructor(http:Http) {
+ *     http('people.json').subscribe(res => this.people = res.json());
+ *   }
+ * }
+ * ```
+ *
+ **/
 @Injectable()
 export class XHRBackend implements ConnectionBackend {
   constructor(private _NativeConstruct: BrowserXHR) {}