superagent 3.8.0-alpha.1 → 3.8.3

package/History.md

@@ -1,3 +1,28 @@
+
+# 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
+
+# 3.8.0
+
+ * Added support for "globally" defined headers and event handlers via `superagent.agent()`. It now remembers default settings for all its requests.
+ * Added optional callback to `.retry()` (Alexander Murphy)
+ * Unified auth args handling in node/browser (Edmundo Alvarez)
+ * Fixed error handling in zlib pipes (Kornel)
+ * Documented that 3xx status codes are errors (Mickey Reiss)
+
 # 3.7.0 (2017-10-17)
 
  * Limit maximum response size. Prevents zip bombs (Kornel)

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,16 +208,41 @@ 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. `.retry()` takes an optional argument which is the maximum number of times to retry failed requests; the default is 3 times.
+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.
+
+This method has two optional arguments: number of retries (default 3) and a callback. It calls `callback(err, res)` before each retry. The callback may return `true`/`false` to control whether the request sould be retried (but the maximum number of retries is always applied).
 
      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).
 
 ## Setting Accept
 
@@ -244,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.
 
@@ -254,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')
@@ -263,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
@@ -285,7 +311,7 @@ request
   .post('/client-auth')
   .key(key)
   .cert(cert)
-  .end(callback);
+  .then(callback);
 ```
 
 ```js
@@ -294,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.
 
@@ -410,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.
@@ -423,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.):
 
@@ -441,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
 
@@ -460,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)
@@ -469,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');
@@ -489,6 +541,22 @@ Or piping the response to a file:
     const req = request.get('/some.json');
     req.pipe(stream);
 
+ 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')
+      // 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()
+      // 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.
+
 ## Multipart requests
 
 SuperAgent is also great for _building_ multipart requests for which it provides methods `.attach()` and `.field()`.
@@ -499,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.
 
@@ -510,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
 
@@ -522,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
 
@@ -543,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);
       })
@@ -555,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) {
 
      });
 
@@ -565,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) {
 
       });
 
@@ -609,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

@@ -17,7 +17,6 @@ var RequestBase = require('./request-base');
 var isObject = require('./is-object');
 var ResponseBase = require('./response-base');
 var Agent = require('./agent-base');
-var shouldRetry = require('./should-retry');
 
 /**
  * Noop.
@@ -187,7 +186,7 @@ request.types = {
 
 request.serialize = {
   'application/x-www-form-urlencoded': serialize,
-  'application/json': JSON.stringify,
+  'application/json': JSON.stringify
 };
 
 /**
@@ -201,7 +200,7 @@ request.serialize = {
 
 request.parse = {
   'application/x-www-form-urlencoded': parseString,
-  'application/json': JSON.parse,
+  'application/json': JSON.parse
 };
 
 /**
@@ -244,7 +243,9 @@ function parseHeader(str) {
  */
 
 function isJSON(mime) {
-  return /[\/+]json\b/.test(mime);
+  // should match /json or +json
+  // but not /json-seq
+  return /[\/+]json($|[^-\w])/.test(mime);
 }
 
 /**
@@ -595,8 +596,7 @@ Request.prototype._getFormData = function(){
  */
 
 Request.prototype.callback = function(err, res){
-  // console.log(this._retries, this._maxRetries)
-  if (this._maxRetries && this._retries++ < this._maxRetries && shouldRetry(err, res)) {
+  if (this._shouldRetry(err, res)) {
     return this._retry();
   }