docs(http): add docs and examples for ResponseOptions

This commit is contained in:
Jeff Cross 2015-09-22 15:50:49 -07:00
parent ae3713ef95
commit 662a585fc2
1 changed files with 63 additions and 5 deletions

View File

@ -5,20 +5,53 @@ import {ResponseTypes} from './enums';
import {ResponseOptionsArgs} from './interfaces'; import {ResponseOptionsArgs} from './interfaces';
/** /**
* Creates a response options object similar to the * Creates a response options object to be optionally provided when instantiating a
* [ResponseInit](https://fetch.spec.whatwg.org/#responseinit) description
* in the Fetch
* Spec to be optionally provided when instantiating a
* {@link Response}. * {@link Response}.
* *
* All values are null by default. * This class is based on the `ResponseInit` description in the [Fetch
* Spec](https://fetch.spec.whatwg.org/#responseinit).
*
* All values are null by default. Typical defaults can be found in the
* {@link BaseResponseOptions} class, which sub-classes `ResponseOptions`.
*
* This class may be used in tests to build {@link Response Responses} for
* mock responses (see {@link MockBackend}).
*
* ### Example ([live demo](http://plnkr.co/edit/P9Jkk8e8cz6NVzbcxEsD?p=preview))
*
* ```typescript
* import {ResponseOptions, Response} from 'angular2/http';
*
* var options = new ResponseOptions({
* body: '{"name":"Jeff"}'
* });
* var res = new Response(options);
*
* console.log('res.json():', res.json()); // Object {name: "Jeff"}
* ```
*/ */
export class ResponseOptions { export class ResponseOptions {
// TODO: ArrayBuffer | FormData | Blob // TODO: ArrayBuffer | FormData | Blob
/**
* String or Object representing the body of the {@link Response}.
*/
body: string | Object; body: string | Object;
/**
* Http {@link http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html status code}
* associated with the response.
*/
status: number; status: number;
/**
* Response {@link Headers headers}
*/
headers: Headers; headers: Headers;
/**
* @private
*/
statusText: string; statusText: string;
/**
* @private
*/
type: ResponseTypes; type: ResponseTypes;
url: string; url: string;
constructor({body, status, headers, statusText, type, url}: ResponseOptionsArgs = {}) { constructor({body, status, headers, statusText, type, url}: ResponseOptionsArgs = {}) {
@ -30,6 +63,31 @@ export class ResponseOptions {
this.url = isPresent(url) ? url : null; this.url = isPresent(url) ? url : null;
} }
/**
* Creates a copy of the `ResponseOptions` instance, using the optional input as values to
* override
* existing values. This method will not change the values of the instance on which it is being
* called.
*
* This may be useful when sharing a base `ResponseOptions` object inside tests,
* where certain properties may change from test to test.
*
* Example ([live demo](http://plnkr.co/edit/1lXquqFfgduTFBWjNoRE?p=preview))
*
* ```typescript
* import {ResponseOptions, Response} from 'angular2/http';
*
* var options = new ResponseOptions({
* body: {name: 'Jeff'}
* });
* var res = new Response(options.merge({
* url: 'https://google.com'
* }));
* console.log('options.url:', options.url); // null
* console.log('res.json():', res.json()); // Object {name: "Jeff"}
* console.log('res.url:', res.url); // https://google.com
* ```
*/
merge(options?: ResponseOptionsArgs): ResponseOptions { merge(options?: ResponseOptionsArgs): ResponseOptions {
return new ResponseOptions({ return new ResponseOptions({
body: isPresent(options) && isPresent(options.body) ? options.body : this.body, body: isPresent(options) && isPresent(options.body) ? options.body : this.body,