superagent 2.2.0 → 2.3.0

package/History.md

@@ -1,3 +1,12 @@
+# 2.3.0
+
+ * Enabled `.field()` to handle objects (Affan Shahid)
+ * Added authentication with client certificates (terusus)
+ * Added `.catch()` for more Promise-like interface (Maxim Samoilov, Kornel Lesiński)
+ * Silenced errors from incomplete gzip streams for compatibility with web browsers (Kornel Lesiński)
+ * Fixed `event.direction` in uploads (Kornel Lesiński)
+ * Fixed returned value of overwritten response object's `on()` method (Juan Dopazo)
+
 # 2.2.0
 
  * Added `timedout` property to node Request instance (Alexander Pope)

package/Readme.md

@@ -18,7 +18,7 @@ component:
 $ component install visionmedia/superagent
 ```
 
-Works with [browserify](https://github.com/substack/node-browserify) and should work with [webpack](https://github.com/visionmedia/superagent/wiki/Superagent-for-Webpack)
+Works with [browserify](https://github.com/substack/node-browserify) and should work with [webpack](https://github.com/visionmedia/superagent/wiki/SuperAgent-for-Webpack)
 
 ```js
 request
@@ -46,7 +46,7 @@ Even though IE9 is supported, a polyfill for `window.FormData` is required for `
 
 # Plugins
 
-Superagent is easily extended via plugins.
+SuperAgent is easily extended via plugins.
 
 ```js
 var nocache = require('superagent-no-cache');
@@ -68,18 +68,17 @@ Existing plugins:
  * [superagent-suffix](https://github.com/timneutkens1/superagent-suffix) - suffix URLs with a given path
  * [superagent-mock](https://github.com/M6Web/superagent-mock) - simulate HTTP calls by returning data fixtures based on the requested URL
  * [superagent-mocker](https://github.com/shuvalov-anton/superagent-mocker) — simulate REST API
- * [superagent-cache](https://github.com/jpodwys/superagent-cache) - superagent with built-in, flexible caching
+ * [superagent-cache](https://github.com/jpodwys/superagent-cache) - SuperAgent with built-in, flexible caching (compatible with SuperAgent `1.x`)
  * [superagent-jsonapify](https://github.com/alex94puchades/superagent-jsonapify) - A lightweight [json-api](http://jsonapi.org/format/) client addon for superagent
  * [superagent-serializer](https://github.com/zzarcon/superagent-serializer) - Converts server payload into different cases
- * [superagent-promise-plugin](https://github.com/jomaxx/superagent-promise-plugin) - Shims req.end to return a promise when executed with no callback.
  * [superagent-use](https://github.com/koenpunt/superagent-use) - A client addon to apply plugins to all requests.
  * [superagent-httpbackend](https://www.npmjs.com/package/superagent-httpbackend) - stub out requests using AngularJS' $httpBackend syntax
  * [superagent-throttle](https://github.com/leviwheatcroft/superagent-throttle) - queues and intelligently throttles requests
- * [superagent-charset](https://github.com/magicdawn/superagent-charset) - add charset support for node's superagent
+ * [superagent-charset](https://github.com/magicdawn/superagent-charset) - add charset support for node's SuperAgent
 
 Please prefix your plugin with `superagent-*` so that it can easily be found by others.
 
-For superagent extensions such as couchdb and oauth visit the [wiki](https://github.com/visionmedia/superagent/wiki).
+For SuperAgent extensions such as couchdb and oauth visit the [wiki](https://github.com/visionmedia/superagent/wiki).
 
 ## Running node tests
 
@@ -119,7 +118,7 @@ Edit tests and refresh your browser. You do not have to restart the test runner.
 
 **npm (for browser standalone)** When we publish versions to npm, we run `make superagent.js` which generates the standalone `superagent.js` file via `browserify`, and this file is included in the package published to npm (but this file is never checked into the git repository). If users want to install via npm but serve a single `.js` file directly to the browser, the `node_modules/superagent/superagent.js` is a standalone browserified file ready to go for that purpose. It is not minified.
 
-**npm (for browserify)** is handled via the `package.json` `browser` field which allows users to install superagent via npm, reference it from their browser code with `require('superagent')`, and then build their own application bundle via `browserify`, which will use `lib/client.js` as the superagent entrypoint.
+**npm (for browserify)** is handled via the `package.json` `browser` field which allows users to install SuperAgent via npm, reference it from their browser code with `require('superagent')`, and then build their own application bundle via `browserify`, which will use `lib/client.js` as the SuperAgent entrypoint.
 
 **bower** is configured via the `bower.json` file. Bower installs files directly from git/github without any transformation.
 

package/docs/index.md

@@ -1,7 +1,7 @@
 
 # SuperAgent
 
- Super Agent is light-weight progressive ajax API crafted for flexibility, readability, and a low learning curve after being frustrated with many of the existing request APIs. It also works with Node.js!
+ SuperAgent is light-weight progressive ajax API crafted for flexibility, readability, and a low learning curve after being frustrated with many of the existing request APIs. It also works with Node.js!
 
      request
        .post('/api/pet')
@@ -46,7 +46,7 @@ ES6 promises are supported. Instead of `.end()` you can call `.then()`:
 
        });
 
-  __DELETE__, __HEAD__, __POST__, __PUT__ and other __HTTP__ verbs may also be used, simply change the method name:
+  __DELETE__, __HEAD__, __PATCH__, __POST__, and __PUT__ requests can also be used, simply change the method name:
 
     request
       .head('/favicon.ico')
@@ -199,7 +199,7 @@ You can also use the `.query()` method for HEAD requests. The following will pro
 
 ## Serializing request body
 
-Superagent will automatically serialize JSON and forms. If you want to send the payload in a custom format, you can replace the built-in serialization with `.serialize()` method.
+SuperAgent will automatically serialize JSON and forms. If you want to send the payload in a custom format, you can replace the built-in serialization with `.serialize()` method.
 
 ## Setting Accept
 
@@ -227,7 +227,7 @@ In a similar fashion to the `.type()` method it is also possible to set the Acce
 
 ## Parsing response bodies
 
-  Super Agent will parse known response-body data for you, currently supporting `application/x-www-form-urlencoded`, `application/json`, and `multipart/form-data`.
+  SuperAgent will parse known response-body data for you, currently supporting `application/x-www-form-urlencoded`, `application/json`, and `multipart/form-data`.
 
   You can set a custom parser (that takes precedence over built-in parsers) with the `.buffer(true).parse(fn)` method. If response buffering is not enabled (`.buffer(false)`) then the `response` event will be emitted without waiting for the body parser to finish, so `response.body` won't be available.
 
@@ -365,7 +365,7 @@ In a similar fashion to the `.type()` method it is also possible to set the Acce
 
 ## Multipart requests
 
-  Super Agent is also great for _building_ multipart requests for which it provides methods `.attach()` and `.field()`.
+  SuperAgent is also great for _building_ multipart requests for which it provides methods `.attach()` and `.field()`.
 
 ### Attaching files
 
@@ -454,23 +454,23 @@ Your callback function will always be passed two arguments: error and response.
 
 ## Promise and Generator support
 
-Superagent's request is a "thenable" object that's compatible with JavaScript promises and `async`/`await` syntax.
+SuperAgent's request is a "thenable" object that's compatible with JavaScript promises and `async`/`await` syntax.
 
-Libraries like [co](https://github.com/tj/co) or a web framework like [koa](https://github.com/koajs/koa) can `yield` on any superagent method:
+Libraries like [co](https://github.com/tj/co) or a web framework like [koa](https://github.com/koajs/koa) can `yield` on any SuperAgent method:
 
     var res = yield request
       .get('http://local')
       .auth('tobi', 'learnboost')
 
-Note that superagent expects the global `Promise` object to be present. You'll need a polyfill to use promises in Internet Explorer or Node.js 0.10.
+Note that SuperAgent expects the global `Promise` object to be present. You'll need a polyfill to use promises in Internet Explorer or Node.js 0.10.
 
 
 ## Browser and node versions
 
-Superagent has two implementations: one for web browsers (using XHR) and one for Node.JS (using core http module). By default Browserify and WebPack will pick the browser version.
+SuperAgent has two implementations: one for web browsers (using XHR) and one for Node.JS (using core http module). By default Browserify and WebPack will pick the browser version.
 
 If want to use WebPack to compile code for Node.JS, you *must* specify [node target](webpack.github.io/docs/configuration.html#target) in its configuration.
 
 ### Using browser version in electron
 
-[Electron](http://electron.atom.io/) developers report if you would prefer to use the browser version of superagent instead of the Node version, you can `require('superagent/superagent')`. Your requests will now show up in the Chrome developer tools Network tab. Note this environment is not covered by automated test suite and not officially supported.
+[Electron](http://electron.atom.io/) developers report if you would prefer to use the browser version of SuperAgent instead of the Node version, you can `require('superagent/superagent')`. Your requests will now show up in the Chrome developer tools Network tab. Note this environment is not covered by automated test suite and not officially supported.

package/lib/client.js

@@ -773,24 +773,24 @@ Request.prototype.end = function(fn){
   };
 
   // progress
-  var handleProgress = function(e){
+  var handleProgress = function(direction, e) {
     if (e.total > 0) {
       e.percent = e.loaded / e.total * 100;
     }
-    e.direction = 'download';
+    e.direction = direction;
     self.emit('progress', e);
-  };
-  if (this.hasListeners('progress')) {
-    xhr.onprogress = handleProgress;
   }
-  try {
-    if (xhr.upload && this.hasListeners('progress')) {
-      xhr.upload.onprogress = handleProgress;
+  if (this.hasListeners('progress')) {
+    try {
+      xhr.onprogress = handleProgress.bind(null, 'download');
+      if (xhr.upload) {
+        xhr.upload.onprogress = handleProgress.bind(null, 'upload');
+      }
+    } catch(e) {
+      // Accessing xhr.upload fails in IE from a web worker, so just pretend it doesn't exist.
+      // Reported here:
+      // https://connect.microsoft.com/IE/feedback/details/837245/xmlhttprequest-upload-throws-invalid-argument-when-used-from-web-worker-context
     }
-  } catch(e) {
-    // Accessing xhr.upload fails in IE from a web worker, so just pretend it doesn't exist.
-    // Reported here:
-    // https://connect.microsoft.com/IE/feedback/details/837245/xmlhttprequest-upload-throws-invalid-argument-when-used-from-web-worker-context
   }
 
   // timeout

package/lib/node/agent.js

@@ -6,7 +6,7 @@
 var CookieJar = require('cookiejar').CookieJar;
 var CookieAccess = require('cookiejar').CookieAccessInfo;
 var parse = require('url').parse;
-var request = require('./index');
+var request = require('../..');
 var methods = require('methods');
 
 /**
@@ -23,7 +23,11 @@ module.exports = Agent;
 
 function Agent(options) {
   if (!(this instanceof Agent)) return new Agent(options);
-  if (options) this._ca = options.ca;
+  if (options) {
+    this._ca = options.ca;
+    this._key = options.key;
+    this._cert = options.cert;
+  }
   this.jar = new CookieJar;
 }
 
@@ -70,6 +74,8 @@ methods.forEach(function(method){
   Agent.prototype[name] = function(url, fn){
     var req = request(method, url);
     req.ca(this._ca);
+    req.key(this._key);
+    req.cert(this._cert);
 
     req.on('response', this._saveCookies.bind(this));
     req.on('redirect', this._saveCookies.bind(this));

package/lib/node/index.js

@@ -489,6 +489,32 @@ Request.prototype.ca = function(cert){
   return this;
 };
 
+/**
+ * Set the client certificate key option for https request.
+ *
+ * @param {Buffer | String} cert
+ * @return {Request} for chaining
+ * @api public
+ */
+
+Request.prototype.key = function(cert){
+  this._key = cert;
+  return this;
+};
+
+/**
+ * Set the client certificate option for https request.
+ *
+ * @param {Buffer | String} cert
+ * @return {Request} for chaining
+ * @api public
+ */
+
+Request.prototype.cert = function(cert){
+  this._cert = cert;
+  return this;
+};
+
 /**
  * Return an http[s] request.
  *
@@ -514,6 +540,8 @@ Request.prototype.request = function(){
   options.path = url.pathname;
   options.host = url.hostname;
   options.ca = this._ca;
+  options.key = this._key;
+  options.cert = this._cert;
   options.agent = this._agent;
 
   // initiate request

package/lib/node/utils.js

@@ -83,6 +83,10 @@ exports.unzip = function(req, res){
   stream.req = req;
 
   unzip.on('error', function(err){
+    if (err && err.code === 'Z_BUF_ERROR') { // unexpected end of file is ignored by browsers and curl
+      stream.emit('end');
+      return;
+    }
     stream.emit('error', err);
   });
 
@@ -119,6 +123,7 @@ exports.unzip = function(req, res){
     } else {
       _on.call(res, type, fn);
     }
+    return this;
   };
 };
 

package/lib/request-base.js

@@ -77,6 +77,10 @@ exports.then = function then(resolve, reject) {
   return this._fullfilledPromise.then(resolve, reject);
 }
 
+exports.catch = function(cb) {
+  return this.then(undefined, cb);
+};
+
 /**
  * Allow for extension
  */
@@ -166,21 +170,42 @@ exports.unset = function(field){
 };
 
 /**
- * Write the field `name` and `val` for "multipart/form-data"
- * request bodies.
+ * Write the field `name` and `val`, or multiple fields with one object
+ * for "multipart/form-data" request bodies.
  *
  * ``` js
  * request.post('/upload')
  *   .field('foo', 'bar')
  *   .end(callback);
+ *
+ * request.post('/upload')
+ *   .field({ foo: 'bar', baz: 'qux' })
+ *   .end(callback);
  * ```
  *
- * @param {String} name
+ * @param {String|Object} name
  * @param {String|Blob|File|Buffer|fs.ReadStream} val
  * @return {Request} for chaining
  * @api public
  */
 exports.field = function(name, val) {
+
+  // name should be either a string or an object.
+  if (null === name ||  undefined === name) {
+    throw new Error('.field(name, val) name can not be empty');
+  }
+
+  if (isObject(name)) {
+    for (var key in name) {
+      this.field(key, name[key]);
+    }
+    return this;
+  }
+
+  // val should be defined now
+  if (null === val || undefined === val) {
+    throw new Error('.field(name, val) val can not be empty');
+  }
   this._getFormData().append(name, val);
   return this;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superagent",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "elegant & feature rich browser / node HTTP with a fluent API",
   "scripts": {
     "prepublish": "make all",

package/superagent.js

@@ -93,6 +93,10 @@ exports.then = function then(resolve, reject) {
   return this._fullfilledPromise.then(resolve, reject);
 }
 
+exports.catch = function(cb) {
+  return this.then(undefined, cb);
+};
+
 /**
  * Allow for extension
  */
@@ -182,21 +186,42 @@ exports.unset = function(field){
 };
 
 /**
- * Write the field `name` and `val` for "multipart/form-data"
- * request bodies.
+ * Write the field `name` and `val`, or multiple fields with one object
+ * for "multipart/form-data" request bodies.
  *
  * ``` js
  * request.post('/upload')
  *   .field('foo', 'bar')
  *   .end(callback);
+ *
+ * request.post('/upload')
+ *   .field({ foo: 'bar', baz: 'qux' })
+ *   .end(callback);
  * ```
  *
- * @param {String} name
+ * @param {String|Object} name
  * @param {String|Blob|File|Buffer|fs.ReadStream} val
  * @return {Request} for chaining
  * @api public
  */
 exports.field = function(name, val) {
+
+  // name should be either a string or an object.
+  if (null === name ||  undefined === name) {
+    throw new Error('.field(name, val) name can not be empty');
+  }
+
+  if (isObject(name)) {
+    for (var key in name) {
+      this.field(key, name[key]);
+    }
+    return this;
+  }
+
+  // val should be defined now
+  if (null === val || undefined === val) {
+    throw new Error('.field(name, val) val can not be empty');
+  }
   this._getFormData().append(name, val);
   return this;
 };
@@ -1337,24 +1362,24 @@ Request.prototype.end = function(fn){
   };
 
   // progress
-  var handleProgress = function(e){
+  var handleProgress = function(direction, e) {
     if (e.total > 0) {
       e.percent = e.loaded / e.total * 100;
     }
-    e.direction = 'download';
+    e.direction = direction;
     self.emit('progress', e);
-  };
-  if (this.hasListeners('progress')) {
-    xhr.onprogress = handleProgress;
   }
-  try {
-    if (xhr.upload && this.hasListeners('progress')) {
-      xhr.upload.onprogress = handleProgress;
+  if (this.hasListeners('progress')) {
+    try {
+      xhr.onprogress = handleProgress.bind(null, 'download');
+      if (xhr.upload) {
+        xhr.upload.onprogress = handleProgress.bind(null, 'upload');
+      }
+    } catch(e) {
+      // Accessing xhr.upload fails in IE from a web worker, so just pretend it doesn't exist.
+      // Reported here:
+      // https://connect.microsoft.com/IE/feedback/details/837245/xmlhttprequest-upload-throws-invalid-argument-when-used-from-web-worker-context
     }
-  } catch(e) {
-    // Accessing xhr.upload fails in IE from a web worker, so just pretend it doesn't exist.
-    // Reported here:
-    // https://connect.microsoft.com/IE/feedback/details/837245/xmlhttprequest-upload-throws-invalid-argument-when-used-from-web-worker-context
   }
 
   // timeout