superagent 3.8.2 → 3.8.3

package/History.md

@@ -1,3 +1,16 @@
+
+# 3.8.3 (2018-04-29)
+
+ * Add flags for 201 & 422 responses (Nikhil Fadnis)
+ * Emit progress event while uploading Node `Buffer` via send method (Sergey Akhalkov)
+ * Fixed setting correct cookies for redirects (Damien Clark)
+ * Replace .catch with ['catch'] for IE9 Support (Miguel Stevens)
+
+# 3.8.2 (2017-12-09)
+
+ * Fixed handling of exceptions thrown from callbacks
+ * Stricter matching of `+json` MIME types.
+
 # 3.8.1 (2017-11-08)
 
  * Clear authorization header on cross-domain redirect

package/Readme.md

@@ -70,6 +70,7 @@ Existing plugins:
  * [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-verbose-errors](https://github.com/jcoreio/superagent-verbose-errors) - include response body in error messages for failed requests
 
 Please prefix your plugin with `superagent-*` so that it can easily be found by others.
 

package/docs/index.md

@@ -8,12 +8,8 @@ SuperAgent is light-weight progressive ajax API crafted for flexibility, readabi
        .send({ name: 'Manny', species: 'cat' })
        .set('X-API-Key', 'foobar')
        .set('Accept', 'application/json')
-       .end(function(err, res){
-         if (err || !res.ok) {
-           alert('Oh no! error');
-         } else {
-           alert('yay got ' + JSON.stringify(res.body));
-         }
+       .then(function(res) {
+          alert('yay got ' + JSON.stringify(res.body));
        });
 
 ## Test documentation
@@ -22,27 +18,32 @@ The following [test documentation](docs/test.html) was generated with [Mocha's](
 
 ## Request basics
 
-A request can be initiated by invoking the appropriate method on the `request` object, then calling `.end()` to send the request. For example a simple __GET__ request:
+A request can be initiated by invoking the appropriate method on the `request` object, then calling `.then()` (or `.end()` [or `await`](#promise-and-generator-support)) to send the request. For example a simple __GET__ request:
 
      request
        .get('/search')
-       .end(function(err, res){
-
+       .then(function(res) {
+          // res.body, res.headers, res.status
+       })
+       .catch(function(err) {
+          // err.message, err.response
        });
 
-A method string may also be passed:
+HTTP method may also be passed as a string:
 
-    request('GET', '/search').end(callback);
+    request('GET', '/search').then(success, failure);
 
-ES6 promises are supported. *Instead* of `.end()` you can call `.then()`:
+Old-style callbacks are also supported. *Instead of* `.then()` you can call `.end()`:
 
-    request('GET', '/search').then(success, failure);
+    request('GET', '/search').end(function(err, res){
+      if (res.ok) {}
+    });
 
-The __Node__ client may also provide absolute URLs. In browsers absolute URLs won't work unless the server implements [CORS](#cors).
+Absolute URLs can be used. In web browsers absolute URLs work only if the server implements [CORS](#cors).
 
      request
        .get('http://example.com/search')
-       .end(function(err, res){
+       .then(function(res) {
 
        });
 
@@ -52,7 +53,7 @@ The __Node__ client supports making requests to [Unix Domain Sockets](http://en.
      //          Use `%2F` as `/` in SOCKET_PATH
      request
        .get('http+unix://%2Fabsolute%2Fpath%2Fto%2Funix.sock/search')
-       .end(function(err, res){
+       .then(res => {
 
        });
 
@@ -60,13 +61,13 @@ __DELETE__, __HEAD__, __PATCH__, __POST__, and __PUT__ requests can also be used
 
     request
       .head('/favicon.ico')
-      .end(function(err, res){
+      .then(function(res) {
 
       });
 
 __DELETE__ can be also called as `.del()` for compatibility with old IE where `delete` is a reserved word.
 
-  The HTTP method defaults to __GET__, so if you wish, the following is valid:
+The HTTP method defaults to __GET__, so if you wish, the following is valid:
 
      request('/search', function(err, res){
 
@@ -80,14 +81,14 @@ Setting header fields is simple, invoke `.set()` with a field name and value:
        .get('/search')
        .set('API-Key', 'foobar')
        .set('Accept', 'application/json')
-       .end(callback);
+       .then(callback);
 
 You may also pass an object to set several fields in a single call:
 
      request
        .get('/search')
        .set({ 'API-Key': 'foobar', Accept: 'application/json' })
-       .end(callback);
+       .then(callback);
 
 ## `GET` requests
 
@@ -98,7 +99,7 @@ The `.query()` method accepts objects, which when used with the __GET__ method w
        .query({ query: 'Manny' })
        .query({ range: '1..5' })
        .query({ order: 'desc' })
-       .end(function(err, res){
+       .then(function(res) {
 
        });
 
@@ -107,7 +108,7 @@ Or as a single object:
     request
       .get('/search')
       .query({ query: 'Manny', range: '1..5', order: 'desc' })
-      .end(function(err, res){
+      .then(function(res) {
 
       });
 
@@ -116,7 +117,7 @@ The `.query()` method accepts strings as well:
       request
         .get('/querystring')
         .query('search=Manny&range=1..5')
-        .end(function(err, res){
+        .then(function(res) {
 
         });
 
@@ -126,7 +127,7 @@ Or joined:
         .get('/querystring')
         .query('search=Manny')
         .query('range=1..5')
-        .end(function(err, res){
+        .then(function(res) {
 
         });
 
@@ -137,7 +138,7 @@ You can also use the `.query()` method for HEAD requests. The following will pro
       request
         .head('/users')
         .query({ email: 'joe@smith.com' })
-        .end(function(err, res){
+        .then(function(res) {
 
         });
 
@@ -148,20 +149,20 @@ A typical JSON __POST__ request might look a little like the following, where we
       request.post('/user')
         .set('Content-Type', 'application/json')
         .send('{"name":"tj","pet":"tobi"}')
-        .end(callback)
+        .then(callback)
 
 Since JSON is undoubtedly the most common, it's the _default_! The following example is equivalent to the previous.
 
       request.post('/user')
         .send({ name: 'tj', pet: 'tobi' })
-        .end(callback)
+        .then(callback)
 
 Or using multiple `.send()` calls:
 
       request.post('/user')
         .send({ name: 'tj' })
         .send({ pet: 'tobi' })
-        .end(callback)
+        .then(callback)
 
 By default sending strings will set the `Content-Type` to `application/x-www-form-urlencoded`,
   multiple calls will be concatenated with `&`, here resulting in `name=tj&pet=tobi`:
@@ -169,7 +170,7 @@ By default sending strings will set the `Content-Type` to `application/x-www-for
       request.post('/user')
         .send('name=tj')
         .send('pet=tobi')
-        .end(callback);
+        .then(callback);
 
 SuperAgent formats are extensible, however by default "json" and "form" are supported. To send the data as `application/x-www-form-urlencoded` simply invoke `.type()` with "form", where the default is "json". This request will __POST__ the body "name=tj&pet=tobi".
 
@@ -177,13 +178,13 @@ SuperAgent formats are extensible, however by default "json" and "form" are supp
         .type('form')
         .send({ name: 'tj' })
         .send({ pet: 'tobi' })
-        .end(callback)
+        .then(callback)
 
 Sending a [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData/FormData) object is also supported. The following example will __POST__ the content of the HTML form identified by id="myForm":
 
       request.post('/user')
         .send(new FormData(document.getElementById('myForm')))
-        .end(callback)
+        .then(callback)
 
 ## Setting the `Content-Type`
 
@@ -207,8 +208,28 @@ simply the extension name such as "xml", "json", "png", etc:
 
 ## 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.
+You can setup automatic serialization for other types as well:
+
+```js
+request.serialize['application/xml'] = function (obj) {
+    return 'string generated from obj';
+};
+
+//going forward, all requests with a Content-type of
+//'application/xml' will be automatically serialized
+```
+If you want to send the payload in a custom format, you can replace
+the built-in serialization with the `.serialize()` method on a per-request basis:
 
+```js
+request
+    .post('/user')
+    .send({foo: 'bar'})
+    .serialize(function serializer(obj) {
+        return 'string generated from obj';
+    });
+```
 ## Retrying requests
 
 When given the `.retry()` method, SuperAgent will automatically retry requests, if they fail in a way that is transient or could be due to a flaky Internet connection.
@@ -217,8 +238,9 @@ This method has two optional arguments: number of retries (default 3) and a call
 
      request
        .get('http://example.com/search')
-       .retry(2)
-       .end(callback);
+       .retry(2) // or:
+       .retry(2, callback)
+       .then(finished);
 
 Use `.retry()` only with requests that are *idempotent* (i.e. multiple requests reaching the server won't cause undesirable side effects like duplicate purchases).
 
@@ -248,7 +270,7 @@ If you are calling Facebook's API, be sure to send an `Accept: application/json`
       .query({ format: 'json' })
       .query({ dest: '/login' })
       .send({ post: 'data', here: 'wahoo' })
-      .end(callback);
+      .then(callback);
 
 By default the query string is not assembled in any particular order. An asciibetically-sorted query string can be enabled with `req.sortQuery()`. You may also provide a custom sorting comparison function with `req.sortQuery(myComparisonFn)`. The comparison function should take 2 arguments and return a negative/zero/positive integer.
 
@@ -258,7 +280,7 @@ By default the query string is not assembled in any particular order. An asciibe
    .query('name=Nick')
    .query('search=Manny')
    .sortQuery()
-   .end(callback)
+   .then(callback)
 
  // customized sort function
  request.get('/user')
@@ -267,7 +289,7 @@ By default the query string is not assembled in any particular order. An asciibe
    .sortQuery(function(a, b){
      return a.length - b.length;
    })
-   .end(callback)
+   .then(callback)
 ```
 
 ## TLS options
@@ -289,7 +311,7 @@ request
   .post('/client-auth')
   .key(key)
   .cert(cert)
-  .end(callback);
+  .then(callback);
 ```
 
 ```js
@@ -298,12 +320,32 @@ var ca = fs.readFileSync('ca.cert.pem');
 request
   .post('https://localhost/private-ca-server')
   .ca(ca)
-  .end(callback);
+  .then(res => {});
 ```
 
 ## Parsing response bodies
 
-SuperAgent 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 setup
+automatic parsing for other response-body data as well:
+
+```js
+//browser
+request.parse['application/xml'] = function (str) {
+    return {'object': 'parsed from str'};
+};
+
+//node
+request.parse['application/xml'] = function (res, cb) {
+    //parse response text and set res.body here
+
+    cb(null, res);
+};
+
+//going forward, responses of type 'application/xml'
+//will be parsed automatically
+```
 
 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.
 
@@ -414,8 +456,10 @@ You should use both `deadline` and `response` timeouts. This way you can use a s
         response: 5000,  // Wait 5 seconds for the server to start sending,
         deadline: 60000, // but allow 1 minute for the file to finish loading.
       })
-      .end(function(err, res){
-        if (err.timeout) { /* timed out! */ }
+      .then(res => {
+          /* responded in time */
+        }, err => {
+          if (err.timeout) { /* timed out! */ } else { /* other error */ }
       });
 
 Timeout errors have a `.timeout` property.
@@ -427,12 +471,12 @@ In both Node and browsers auth available via the `.auth()` method:
     request
       .get('http://local')
       .auth('tobi', 'learnboost')
-      .end(callback);
+      .then(callback);
 
 
 In the _Node_ client Basic auth can be in the URL as "user:pass":
 
-    request.get('http://tobi:learnboost@local').end(callback);
+    request.get('http://tobi:learnboost@local').then(callback);
 
 By default only `Basic` auth is used. In browser you can add `{type:'auto'}` to enable all methods built-in in the browser (Digest, NTLM, etc.):
 
@@ -445,7 +489,7 @@ By default up to 5 redirects will be followed, however you may specify this with
     request
       .get('/some.png')
       .redirects(2)
-      .end(callback);
+      .then(callback);
 
 ## Agents for global state
 
@@ -464,7 +508,7 @@ In browsers cookies are managed automatically by the browser, so the `.agent()`
 
 ### Default options for multiple requests
 
-Regular request methods (`.use()`, `.set()`, `.auth()`) called on the agent will be used as defaults for all requests made by that agent.
+Regular request methods called on the agent will be used as defaults for all requests made by that agent.
 
     const agent = request.agent()
       .use(plugin)
@@ -473,9 +517,13 @@ Regular request methods (`.use()`, `.set()`, `.auth()`) called on the agent will
     await agent.get('/with-plugin-and-auth');
     await agent.get('/also-with-plugin-and-auth');
 
+The complete list of methods that the agent can use to set defaults is: `use`, `on`, `once`, `set`, `query`, `type`, `accept`, `auth`, `withCredentials`, `sortQuery`, `retry`, `ok`, `redirects`, `timeout`, `buffer`, `serialize`, `parse`, `ca`, `key`, `pfx`, `cert`.
+
 ## Piping data
 
-The Node client allows you to pipe data to and from the request. For example piping a file's contents as the request:
+The Node client allows you to pipe data to and from the request. Please note that `.pipe()` is used **instead of** `.end()`/`.then()` methods.
+
+For example piping a file's contents as the request:
 
     const request = require('superagent');
     const fs = require('fs');
@@ -493,19 +541,19 @@ Or piping the response to a file:
     const req = request.get('/some.json');
     req.pipe(stream);
 
-Note that you should **NOT** attempt to pipe the result of `.end()` or the `Response` object:
+ It's not possible to mix pipes and callbacks or promises. Note that you should **NOT** attempt to pipe the result of `.end()` or the `Response` object:
 
     // Don't do either of these:
     const stream = getAWritableStream();
     const req = request
       .get('/some.json')
-      // this pipes garbage to the stream and fails in unexpected ways
-      .end((err, response) => response.pipe(stream))
+      // BAD: this pipes garbage to the stream and fails in unexpected ways
+      .end((err, this_does_not_work) => this_does_not_work.pipe(stream))
     const req = request
       .get('/some.json')
       .end()
-      // this is also unsupported, .pipe calls .end for you.
-      .pipe(stream);
+      // BAD: this is also unsupported, .pipe calls .end for you.
+      .pipe(nope_its_too_late);
 
 In a [future version](https://github.com/visionmedia/superagent/issues/1188) of superagent, improper calls to `pipe()` will fail.
 
@@ -519,7 +567,7 @@ When you use `.field()` or `.attach()` you can't use `.send()` and you *must not
 
 To send a file use `.attach(name, [file], [options])`. You can attach multiple files by calling `.attach` multiple times. The arguments are:
 
- * `name` — filed name in the form.
+ * `name` — field name in the form.
  * `file` — either string with file path or `Blob`/`Buffer` object.
  * `options` — (optional) either string with custom file name or `{filename: string}` object. In Node also `{contentType: 'mime/type'}` is supported. In browser create a `Blob` with an appropriate type instead.
 
@@ -530,7 +578,7 @@ To send a file use `.attach(name, [file], [options])`. You can attach multiple f
       .attach('image1', 'path/to/felix.jpeg')
       .attach('image2', imageBuffer, 'luna.jpeg')
       .field('caption', 'My cats')
-      .end(callback);
+      .then(callback);
 
 ### Field values
 
@@ -542,7 +590,7 @@ Much like form fields in HTML, you can set field values with `.field(name, value
        .field('user[email]', 'tobi@learnboost.com')
        .field('friends[]', ['loki', 'jane'])
        .attach('image', 'path/to/tobi.png')
-       .end(callback);
+       .then(callback);
 
 ## Compression
 
@@ -563,7 +611,7 @@ The `.withCredentials()` method enables the ability to send cookies from the ori
     request
       .get('http://api.example.com:4001/')
       .withCredentials()
-      .then(function(res){
+      .then(function(res) {
         assert.equal(200, res.status);
         assert.equal('tobi', res.text);
       })
@@ -575,7 +623,7 @@ Your callback function will always be passed two arguments: error and response.
     request
      .post('/upload')
      .attach('image', 'path/to/tobi.png')
-     .end(function(err, res){
+     .then(function(res) {
 
      });
 
@@ -585,7 +633,7 @@ An "error" event is also emitted, with you can listen for:
       .post('/upload')
       .attach('image', 'path/to/tobi.png')
       .on('error', handle)
-      .end(function(err, res){
+      .then(function(res) {
 
       });
 
@@ -629,7 +677,9 @@ SuperAgent fires `progress` events on upload and download of large files.
 
 ## Promise and Generator support
 
-SuperAgent's request is a "thenable" object that's compatible with JavaScript promises and `async`/`await` syntax. Do not call `.end()` if you're using promises.
+SuperAgent's request is a "thenable" object that's compatible with JavaScript promises and `async`/`await` syntax.
+
+If you're using promises, **do not** call `.end()` or `.pipe()`. Any use of `.then()` or `await` disables all other ways of using the request.
 
 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:
 

package/lib/client.js

@@ -186,7 +186,7 @@ request.types = {
 
 request.serialize = {
   'application/x-www-form-urlencoded': serialize,
-  'application/json': JSON.stringify,
+  'application/json': JSON.stringify
 };
 
 /**
@@ -200,7 +200,7 @@ request.serialize = {
 
 request.parse = {
   'application/x-www-form-urlencoded': parseString,
-  'application/json': JSON.parse,
+  'application/json': JSON.parse
 };
 
 /**

package/lib/node/index.js

@@ -25,6 +25,7 @@ const zlib = require('zlib');
 const util = require('util');
 const pkg = require('../../package.json');
 const RequestBase = require('../request-base');
+const CookieJar = require('cookiejar');
 
 function request(method, url) {
   // callback
@@ -654,15 +655,24 @@ Request.prototype.request = function(){
   if (this.username && this.password) {
     this.auth(this.username, this.password);
   }
-
-  // add cookies
-  if (this.cookies) req.setHeader('Cookie', this.cookies);
-
   for (const key in this.header) {
     if (this.header.hasOwnProperty(key))
       req.setHeader(key, this.header[key]);
   }
 
+  // add cookies
+  if (this.cookies) {
+    if(this.header.hasOwnProperty('cookie')) {
+      // merge
+      const tmpJar = new CookieJar.CookieJar();
+      tmpJar.setCookies(this.header.cookie.split(';'));
+      tmpJar.setCookies(this.cookies.split(';'));
+      req.setHeader('Cookie',tmpJar.getCookies(CookieJar.CookieAccessInfo.All).toValueString());
+    } else {
+      req.setHeader('Cookie', this.cookies);
+    }
+  }
+
   return req;
 };
 
@@ -942,6 +952,47 @@ Request.prototype._end = function() {
 
   this.emit('request', this);
 
+  const getProgressMonitor = () => {
+    const lengthComputable = true;
+    const total = req.getHeader('Content-Length');
+    let loaded = 0;
+
+    const progress = new Stream.Transform();
+    progress._transform = (chunk, encoding, cb) => {
+      loaded += chunk.length;
+      this.emit('progress', {
+        direction: 'upload',
+        lengthComputable,
+        loaded,
+        total,
+      });
+      cb(null, chunk);
+    };
+    return progress;
+  };
+
+  const bufferToChunks = (buffer) => {
+    const chunkSize = 16 * 1024; // default highWaterMark value
+    const chunking = new Stream.Readable();
+    const totalLength = buffer.length;
+    const remainder = totalLength % chunkSize;
+    const cutoff = totalLength - remainder;
+
+    for (let i = 0; i < cutoff; i += chunkSize) {
+      const chunk = buffer.slice(i, i + chunkSize);
+      chunking.push(chunk);
+    }
+
+    if (remainder > 0) {
+      const remainderBuffer = buffer.slice(-remainder);
+      chunking.push(remainderBuffer);
+    }
+
+    chunking.push(null); // no more data
+
+    return chunking;
+  }
+
   // if a FormData instance got created, then we send that as the request body
   const formData = this._formData;
   if (formData) {
@@ -961,27 +1012,11 @@ Request.prototype._end = function() {
       if ('number' == typeof length) {
         req.setHeader('Content-Length', length);
       }
-
-      const getProgressMonitor = () => {
-        const lengthComputable = true;
-        const total = req.getHeader('Content-Length');
-        let loaded = 0;
-
-        const progress = new Stream.Transform();
-        progress._transform = (chunk, encoding, cb) => {
-          loaded += chunk.length;
-          this.emit('progress', {
-            direction: 'upload',
-            lengthComputable,
-            loaded,
-            total,
-          });
-          cb(null, chunk);
-        };
-        return progress;
-      };
+      
       formData.pipe(getProgressMonitor()).pipe(req);
     });
+  } else if (Buffer.isBuffer(data)) {
+    bufferToChunks(data).pipe(getProgressMonitor()).pipe(req);
   } else {
     req.end(data);
   }

package/lib/request-base.js

@@ -244,7 +244,7 @@ RequestBase.prototype.then = function then(resolve, reject) {
   return this._fullfilledPromise.then(resolve, reject);
 };
 
-RequestBase.prototype.catch = function(cb) {
+RequestBase.prototype['catch'] = function(cb) {
   return this.then(undefined, cb);
 };
 

package/lib/response-base.js

@@ -124,6 +124,7 @@ ResponseBase.prototype._setStatusProperties = function(status){
         : false;
 
     // sugar
+    this.created = 201 == status;
     this.accepted = 202 == status;
     this.noContent = 204 == status;
     this.badRequest = 400 == status;
@@ -131,4 +132,5 @@ ResponseBase.prototype._setStatusProperties = function(status){
     this.notAcceptable = 406 == status;
     this.forbidden = 403 == status;
     this.notFound = 404 == status;
+    this.unprocessableEntity = 422 == status;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superagent",
-  "version": "3.8.2",
+  "version": "3.8.3",
   "description": "elegant & feature rich browser / node HTTP with a fluent API",
   "scripts": {
     "prepare": "make all",
@@ -29,11 +29,11 @@
     "debug": "^3.1.0",
     "extend": "^3.0.0",
     "form-data": "^2.3.1",
-    "formidable": "^1.1.1",
+    "formidable": "^1.2.0",
     "methods": "^1.1.1",
     "mime": "^1.4.1",
     "qs": "^6.5.1",
-    "readable-stream": "^2.0.5"
+    "readable-stream": "^2.3.5"
   },
   "devDependencies": {
     "Base64": "^1.0.1",
@@ -41,9 +41,9 @@
     "body-parser": "^1.18.2",
     "browserify": "^14.1.0",
     "cookie-parser": "^1.4.3",
-    "express": "^4.16.0",
+    "express": "^4.16.3",
     "express-session": "^1.15.6",
-    "marked": "^0.3.6",
+    "marked": "0.3.12",
     "mocha": "^3.5.3",
     "multer": "^1.3.0",
     "should": "^11.2.0",