feat(request-builder): allow message parameters to be fully specified…

… without sending the message

This change reworks the `RequestBuilder` API so that URI, HTTP method, and content can be specified without forcing the request to be sent.

This is a breaking API change to `RequestBuilder`. To update code, replaces uses of `.get(uri)`, `.post(uri, content)`, etc. with `.asGet().withUri(uri).send()`, `.asPost().withUri(uri).withContent(content).send()`.

Fixes aurelia#29

src/http-client.js

@@ -54,10 +54,17 @@ export class HttpClient {
    * Returns a new RequestBuilder for this HttpClient instance that can be used to build and send HTTP requests.
    *
    * @method createRequest
+   * @param uri The target URI.
    * @type RequestBuilder
    */
-  createRequest(){
-    return new RequestBuilder(this);
+  createRequest(uri){
+    let builder = new RequestBuilder(this);
+
+    if(uri) {
+      builder.withUri(uri);
+    }
+
+    return builder;
   }
 
   /**
@@ -108,7 +115,7 @@ export class HttpClient {
    * @return {Promise} A cancellable promise object.
    */
   delete(uri){
-    return this.createRequest().delete(uri);
+    return this.createRequest(uri).asDelete().send();
   }
 
   /**
@@ -119,7 +126,7 @@ export class HttpClient {
    * @return {Promise} A cancellable promise object.
    */
   get(uri){
-    return this.createRequest().get(uri);
+    return this.createRequest(uri).asGet().send();
   }
 
   /**
@@ -130,19 +137,18 @@ export class HttpClient {
    * @return {Promise} A cancellable promise object.
    */
   head(uri){
-    return this.createRequest().head(uri);
+    return this.createRequest(uri).asHead().send();
   }
 
   /**
    * Sends a JSONP request.
    *
    * @method jsonp
    * @param {String} uri The target URI.
-   * @param {String} [callbackParameterName=jsoncallback] The target Javascript expression to invoke.
    * @return {Promise} A cancellable promise object.
    */
   jsonp(uri, callbackParameterName='jsoncallback'){
-    return this.createRequest().jsonp(uri, callbackParameterName);
+    return this.createRequest(uri).withJsonpParameter(callbackParameterName).send();
   }
 
   /**
@@ -153,7 +159,7 @@ export class HttpClient {
    * @return {Promise} A cancellable promise object.
    */
   options(uri){
-    return this.createRequest().options(uri);
+    return this.createRequest(uri).asOptions().send();
   }
 
   /**
@@ -165,7 +171,7 @@ export class HttpClient {
    * @return {Promise} A cancellable promise object.
    */
   put(uri, content){
-    return this.createRequest().put(uri, content);
+    return this.createRequest(uri).asPut().withContent(content).send();
   }
 
   /**
@@ -177,7 +183,7 @@ export class HttpClient {
    * @return {Promise} A cancellable promise object.
    */
   patch(uri, content){
-    return this.createRequest().patch(uri, content);
+    return this.createRequest(uri).asPatch().withContent(content).send();
   }
 
   /**
@@ -189,6 +195,6 @@ export class HttpClient {
    * @return {Promise} A cancellable promise object.
    */
   post(uri, content){
-    return this.createRequest().post(uri, content);
+    return this.createRequest(uri).asPost().withContent(content).send();
   }
 }

src/request-builder.js

@@ -12,6 +12,7 @@ export class RequestBuilder {
 	constructor (client) {
 		this.client = client;
 		this.transformers = client.requestTransformers.slice(0);
+		this.useJsonp = false;
 	}
 
 	/**
@@ -30,105 +31,77 @@ export class RequestBuilder {
 	}
 
 	/**
-	* Sends an HTTP DELETE request.
+	* Sends the request.
 	*
-	* @method delete
-	* @param {String} uri The target URI.
+	* @method send
 	* @return {Promise} A cancellable promise object.
 	*/
-	delete(uri){
-		var message = new HttpRequestMessage('DELETE', uri);
+	send(){
+		let message = this.useJsonp ? new JSONPRequestMessage() : new HttpRequestMessage();
 		return this.client.send(message, this.transformers);
 	}
+}
 
-	/**
-	* Sends an HTTP GET request.
-	*
-	* @method get
-	* @param {String} uri The target URI.
-	* @return {Promise} A cancellable promise object.
-	*/
-	get(uri){
-		var message = new HttpRequestMessage('GET', uri);
-		return this.client.send(message, this.transformers);
-	}
+RequestBuilder.addHelper('asDelete', function(){
+	return function(client, processor, message){
+		message.method = 'DELETE';
+	};
+});
 
-	/**
-	* Sends an HTTP HEAD request.
-	*
-	* @method head
-	* @param {String} uri The target URI.
-	* @return {Promise} A cancellable promise object.
-	*/
-	head(uri){
-		var message = new HttpRequestMessage('HEAD', uri);
-		return this.client.send(message, this.transformers);
-	}
+RequestBuilder.addHelper('asGet', function(){
+	return function(client, processor, message){
+		message.method = 'GET';
+	};
+});
 
-	/**
-	* Sends a JSONP request.
-	*
-	* @method jsonp
-	* @param {String} uri The target URI.
-	* @param {String} [callbackParameterName=jsoncallback] The target Javascript expression to invoke.
-	* @return {Promise} A cancellable promise object.
-	*/
-	jsonp(uri, callbackParameterName='jsoncallback'){
-		var message = new JSONPRequestMessage(uri, callbackParameterName);
-		return this.client.send(message, this.transformers);
-	}
+RequestBuilder.addHelper('asHead', function(){
+	return function(client, processor, message){
+		message.method = 'HEAD';
+	};
+});
 
-	/**
-	* Sends an HTTP OPTIONS request.
-	*
-	* @method options
-	* @param {String} uri The target URI.
-	* @return {Promise} A cancellable promise object.
-	*/
-	options(uri){
-		var message = new HttpRequestMessage('OPTIONS', uri);
-		return this.client.send(message, this.transformers);
-	}
+RequestBuilder.addHelper('asOptions', function(){
+	return function(client, processor, message){
+		message.method = 'OPTIONS';
+	};
+});
 
-	/**
-	* Sends an HTTP PUT request.
-	*
-	* @method put
-	* @param {String} uri The target URI.
-	* @param {Object} uri The request payload.
-	* @return {Promise} A cancellable promise object.
-	*/
-	put(uri, content){
-		var message = new HttpRequestMessage('PUT', uri, content);
-		return this.client.send(message, this.transformers);
-	}
+RequestBuilder.addHelper('asPatch', function(){
+	return function(client, processor, message){
+		message.method = 'PATCH';
+	};
+});
 
-	/**
-	* Sends an HTTP PATCH request.
-	*
-	* @method patch
-	* @param {String} uri The target URI.
-	* @param {Object} uri The request payload.
-	* @return {Promise} A cancellable promise object.
-	*/
-	patch(uri, content){
-		var message = new HttpRequestMessage('PATCH', uri, content);
-		return this.client.send(message, this.transformers);
-	}
+RequestBuilder.addHelper('asPost', function(){
+	return function(client, processor, message){
+		message.method = 'POST';
+	};
+});
 
-	/**
-	* Sends an HTTP POST request.
-	*
-	* @method post
-	* @param {String} uri The target URI.
-	* @param {Object} uri The request payload.
-	* @return {Promise} A cancellable promise object.
-	*/
-	post(uri, content){
-		var message = new HttpRequestMessage('POST', uri, content);
-		return this.client.send(message, this.transformers);
-	}
-}
+RequestBuilder.addHelper('asPut', function(){
+	return function(client, processor, message){
+		message.method = 'PUT';
+	};
+});
+
+RequestBuilder.addHelper('withJsonpParameter', function(jsonpParameterName){
+	this.useJsonp = true;
+	return function(client, processor, message){
+		message.jsonpParameterName =  jsonpParameterName;
+	};
+});
+
+RequestBuilder.addHelper('withUri', function(uri){
+	return function(client, processor, message){
+		message.uri = uri;
+	};
+});
+
+RequestBuilder.addHelper('withContent', function(content){
+	return function(client, processor, message){
+		message.content = content;
+	};
+});
 
 RequestBuilder.addHelper('withBaseUrl', function(baseUrl){
 	return function(client, processor, message){

test/http-client.spec.js

@@ -125,9 +125,11 @@ describe('http client', () => {
             x.withHeader('Content-Type', 'application/json');
           });
 
-        client.createRequest()
+        client.createRequest('some/cool/path')
+          .asPut()
+          .withContent(content)
           .withReplacer(['firstName'])
-          .put('some/cool/path', content);
+          .send();
 
         var request = jasmine.Ajax.requests.mostRecent();
 
@@ -229,9 +231,11 @@ describe('http client', () => {
             x.withHeader('Content-Type', 'application/json');
           });
 
-        client.createRequest()
+        client.createRequest('some/cool/path')
+          .asPatch()
+          .withContent(content)
           .withReplacer(['firstName'])
-          .patch('some/cool/path', content);
+          .send();
 
         var request = jasmine.Ajax.requests.mostRecent();
 
@@ -333,9 +337,11 @@ describe('http client', () => {
             x.withHeader('Content-Type', 'application/json');
           });
 
-        client.createRequest()
+        client.createRequest('some/cool/path')
+          .asPost()
+          .withContent(content)
           .withReplacer(['firstName'])
-          .post('some/cool/path', content);
+          .send();
 
         var request = jasmine.Ajax.requests.mostRecent();
 
@@ -562,9 +568,10 @@ describe('http client', () => {
       var client = new HttpClient();
       var callback = function(){};
 
-      client.createRequest()
+      client.createRequest('some/cool/url')
+        .asGet()
         .withProgressCallback(callback)
-        .get('some/cool/url');
+        .send();
 
       var response = jasmine.Ajax.requests.mostRecent();
       expect(response.upload.onprogress).toBe(callback);