axios 0.26.1 → 0.27.0

package/CHANGELOG.md

@@ -1,9 +1,34 @@
 # Changelog
 
+### 0.27.0 (April 19, 2022)
+
+Breaking changes:
+- New toFormData helper function that allows the implementor to pass an object and allow axios to convert it to FormData ([#3757](https://github.com/axios/axios/pull/3757))
+- Removed functionality that removed the the `Content-Type` request header when passing FormData ([#3785](https://github.com/axios/axios/pull/3785))
+- **(*)** Refactored error handling implementing AxiosError as a constructor, this is a large change to error handling on the whole ([#3645](https://github.com/axios/axios/pull/3645))
+- Separated responsibility for FormData instantiation between `transformRequest` and `toFormData` ([#4470](https://github.com/axios/axios/pull/4470))
+- **(*)** Improved and fixed multiple issues with FormData support ([#4448](https://github.com/axios/axios/pull/4448))
+
+QOL and DevX improvements:
+- Added a multipart/form-data testing playground allowing contributors to debug changes easily ([#4465](https://github.com/axios/axios/pull/4465))
+
+Fixes and Functionality:
+- Refactored project file structure to avoid circular imports ([#4515](https://github.com/axios/axios/pull/4516)) & ([#4516](https://github.com/axios/axios/pull/4516))
+- Bumped follow-redirects to ^1.14.9 ([#4562](https://github.com/axios/axios/pull/4562))
+
+Internal and Tests:
+- Updated dev dependencies to latest version
+
+Documentation:
+- Fixing incorrect link in changelog ([#4551](https://github.com/axios/axios/pull/4551))
+
+Notes:
+- **(*)** Please read these pull requests before updating, these changes are very impactful and far reaching.
+
 ### 0.26.1 (March 9, 2022)
 
 Fixes and Functionality:
-- Refactored project file structure to avoid circular imports ([##4220](https://github.com/axios/axios/pull/#4220))
+- Refactored project file structure to avoid circular imports ([#4220](https://github.com/axios/axios/pull/4220))
 
 ### 0.26.0 (February 13, 2022)
 
@@ -11,7 +36,7 @@ Fixes and Functionality:
 - Fixed The timeoutErrorMessage property in config not work with Node.js ([#3581](https://github.com/axios/axios/pull/3581))
 - Added errors to be displayed when the query parsing process itself fails ([#3961](https://github.com/axios/axios/pull/3961))
 - Fix/remove url required ([#4426](https://github.com/axios/axios/pull/4426))
-- Update follow-redirects dependency due to Vurnerbility ([#4462](https://github.com/axios/axios/pull/4462))
+- Update follow-redirects dependency due to Vulnerability ([#4462](https://github.com/axios/axios/pull/4462))
 - Bump karma from 6.3.11 to 6.3.14 ([#4461](https://github.com/axios/axios/pull/4461))
 - Bump follow-redirects from 1.14.7 to 1.14.8 ([#4473](https://github.com/axios/axios/pull/4473))
 
@@ -19,7 +44,7 @@ Fixes and Functionality:
 
 Breaking changes:
 - Fixing maxBodyLength enforcement ([#3786](https://github.com/axios/axios/pull/3786))
-- Don't rely on strict mode behaviour for arguments ([#3470](https://github.com/axios/axios/pull/3470))
+- Don't rely on strict mode behavior for arguments ([#3470](https://github.com/axios/axios/pull/3470))
 - Adding error handling when missing url ([#3791](https://github.com/axios/axios/pull/3791))
 - Update isAbsoluteURL.js removing escaping of non-special characters ([#3809](https://github.com/axios/axios/pull/3809))
 - Use native Array.isArray() in utils.js ([#3836](https://github.com/axios/axios/pull/3836))
@@ -36,14 +61,13 @@ Fixes and Functionality:
 - Adding responseEncoding prop type in AxiosRequestConfig ([#3918](https://github.com/axios/axios/pull/3918))
 
 Internal and Tests:
-- Adding axios-test-instance to ecosystem ([#3786](https://github.com/axios/axios/pull/3786))
+- Adding axios-test-instance to ecosystem ([#3496](https://github.com/axios/axios/pull/3496))
 - Optimize the logic of isAxiosError ([#3546](https://github.com/axios/axios/pull/3546))
 - Add tests and documentation to display how multiple inceptors work ([#3564](https://github.com/axios/axios/pull/3564))
 - Updating follow-redirects to version 1.14.7 ([#4379](https://github.com/axios/axios/pull/4379))
 
-
 Documentation:
-- Fixing changelog to show corrext pull request ([#4219](https://github.com/axios/axios/pull/4219))
+- Fixing changelog to show correct pull request ([#4219](https://github.com/axios/axios/pull/4219))
 - Update upgrade guide for https proxy setting ([#3604](https://github.com/axios/axios/pull/3604))
 
 Huge thanks to everyone who contributed to this release via code (authors listed below) or via reviews and triaging on GitHub:
@@ -134,7 +158,7 @@ Huge thanks to everyone who contributed to this release via code (authors listed
 ### 0.21.4 (September 6, 2021)
 
 Fixes and Functionality:
-- Fixing JSON transform when data is stringified. Providing backward compatability and complying to the JSON RFC standard ([#4020](https://github.com/axios/axios/pull/4020))
+- Fixing JSON transform when data is stringified. Providing backward compatibility and complying to the JSON RFC standard ([#4020](https://github.com/axios/axios/pull/4020))
 
 Huge thanks to everyone who contributed to this release via code (authors listed below) or via reviews and triaging on GitHub:
 
@@ -169,9 +193,9 @@ Fixes and Functionality:
 
 Internal and Tests:
 
-- Updating build dev dependancies ([#3401](https://github.com/axios/axios/pull/3401))
+- Updating build dev dependencies ([#3401](https://github.com/axios/axios/pull/3401))
 - Fixing builds running on Travis CI ([#3538](https://github.com/axios/axios/pull/3538))
-- Updating follow rediect version ([#3694](https://github.com/axios/axios/pull/3694), [#3771](https://github.com/axios/axios/pull/3771))
+- Updating follow redirect version ([#3694](https://github.com/axios/axios/pull/3694), [#3771](https://github.com/axios/axios/pull/3771))
 - Updating karma sauce launcher to fix failing sauce tests ([#3712](https://github.com/axios/axios/pull/3712), [#3717](https://github.com/axios/axios/pull/3717))
 - Updating content-type header for application/json to not contain charset field, according do RFC 8259 ([#2154](https://github.com/axios/axios/pull/2154))
 - Fixing tests by bumping karma-sauce-launcher version ([#3813](https://github.com/axios/axios/pull/3813))
@@ -181,9 +205,9 @@ Documentation:
 
 - Updating documentation around the use of `AUTH_TOKEN` with multiple domain endpoints ([#3539](https://github.com/axios/axios/pull/3539))
 - Remove duplication of item in changelog ([#3523](https://github.com/axios/axios/pull/3523))
-- Fixing gramatical errors ([#2642](https://github.com/axios/axios/pull/2642))
+- Fixing grammatical errors ([#2642](https://github.com/axios/axios/pull/2642))
 - Fixing spelling error ([#3567](https://github.com/axios/axios/pull/3567))
-- Moving gitpod metion ([#2637](https://github.com/axios/axios/pull/2637))
+- Moving gitpod mention ([#2637](https://github.com/axios/axios/pull/2637))
 - Adding new axios documentation website link ([#3681](https://github.com/axios/axios/pull/3681), [#3707](https://github.com/axios/axios/pull/3707))
 - Updating documentation around dispatching requests ([#3772](https://github.com/axios/axios/pull/3772))
 - Adding documentation for the type guard isAxiosError ([#3767](https://github.com/axios/axios/pull/3767))
@@ -261,7 +285,7 @@ Internal and Tests:
 
 Documentation:
 
-- Fixing simple typo, existant -> existent ([#3252](https://github.com/axios/axios/pull/3252))
+- Fixing simple typo, existent -> existent ([#3252](https://github.com/axios/axios/pull/3252))
 - Fixing typos ([#3309](https://github.com/axios/axios/pull/3309))
 
 Huge thanks to everyone who contributed to this release via code (authors listed below) or via reviews and triaging on GitHub:

package/README.md

@@ -23,7 +23,7 @@ Promise based HTTP client for the browser and node.js
   - [Example](#example)
   - [Axios API](#axios-api)
   - [Request method aliases](#request-method-aliases)
-  - [Concurrency (Deprecated)](#concurrency-deprecated)
+  - [Concurrency 👎](#concurrency-deprecated)
   - [Creating an instance](#creating-an-instance)
   - [Instance methods](#instance-methods)
   - [Request Config](#request-config)
@@ -36,11 +36,15 @@ Promise based HTTP client for the browser and node.js
     - [Multiple Interceptors](#multiple-interceptors)
   - [Handling Errors](#handling-errors)
   - [Cancellation](#cancellation)
+    - [AbortController](#abortcontroller)
+    - [CancelToken 👎](#canceltoken-deprecated)
   - [Using application/x-www-form-urlencoded format](#using-applicationx-www-form-urlencoded-format)
     - [Browser](#browser)
     - [Node.js](#nodejs)
       - [Query string](#query-string)
       - [Form data](#form-data)
+        - [Automatic serialization](#-automatic-serialization)
+        - [Manual FormData passing](#manual-formdata-passing)
   - [Semver](#semver)
   - [Promises](#promises)
   - [TypeScript](#typescript)
@@ -113,7 +117,7 @@ const axios = require('axios').default;
 Performing a `GET` request
 
 ```js
-const axios = require('axios');
+const axios = require('axios').default;
 
 // Make a request for a user with a given ID
 axios.get('/user?ID=12345')
@@ -231,7 +235,7 @@ axios('/user/12345');
 
 ### Request method aliases
 
-For convenience aliases have been provided for all supported request methods.
+For convenience, aliases have been provided for all common request methods.
 
 ##### axios.request(config)
 ##### axios.get(url[, config])
@@ -414,7 +418,18 @@ These are the available config options for making requests. Only the `url` is re
 
   // `maxRedirects` defines the maximum number of redirects to follow in node.js.
   // If set to 0, no redirects will be followed.
-  maxRedirects: 5, // default
+  maxRedirects: 21, // default
+
+  // `beforeRedirect` defines a function that will be called before redirect.
+  // Use this to adjust the request options upon redirecting,
+  // to inspect the latest response headers,
+  // or to cancel the request by throwing an error
+  // If maxRedirects is set to 0, `beforeRedirect` is not used.
+  beforeRedirect: (options, { headers }) => {
+    if (options.hostname === "example.com") {
+      options.auth = "user:password";
+    }
+  };
 
   // `socketPath` defines a UNIX Socket to be used in node.js.
   // e.g. '/var/run/docker.sock' to send requests to the docker daemon.
@@ -483,6 +498,11 @@ These are the available config options for making requests. Only the `url` is re
     
     // throw ETIMEDOUT error instead of generic ECONNABORTED on request timeouts
     clarifyTimeoutError: false,
+  },
+
+  env: {
+    // The FormData class to be used to automatically serialize the payload into a FormData object
+    FormData: window?.FormData || global?.FormData
   }
 }
 ```
@@ -707,10 +727,30 @@ axios.get('/user/12345')
 
 ## Cancellation
 
-You can cancel a request using a *cancel token*.
+### AbortController
+
+Starting from `v0.22.0` Axios supports AbortController to cancel requests in fetch API way:
+
+```js
+const controller = new AbortController();
+
+axios.get('/foo/bar', {
+   signal: controller.signal
+}).then(function(response) {
+   //...
+});
+// cancel the request
+controller.abort()
+```
+
+### CancelToken `👎deprecated`
+
+You can also cancel a request using a *CancelToken*.
 
 > The axios cancel token API is based on the withdrawn [cancelable promises proposal](https://github.com/tc39/proposal-cancelable-promises).
 
+> This API is deprecated since v0.22.0 and shouldn't be used in new projects
+
 You can create a cancel token using the `CancelToken.source` factory as shown below:
 
 ```js
@@ -754,22 +794,11 @@ axios.get('/user/12345', {
 cancel();
 ```
 
-Axios supports AbortController to abort requests in [`fetch API`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API#aborting_a_fetch) way:
-```js
-const controller = new AbortController();
-
-axios.get('/foo/bar', {
-   signal: controller.signal
-}).then(function(response) {
-   //...
-});
-// cancel the request
-controller.abort()
-```
-
 > Note: you can cancel several requests with the same cancel token/abort controller.
 > If a cancellation token is already cancelled at the moment of starting an Axios request, then the request is cancelled immediately, without any attempts to make real request.
 
+> During the transition period, you can use both cancellation APIs, even for the same request:
+
 ## Using application/x-www-form-urlencoded format
 
 By default, axios serializes JavaScript objects to `JSON`. To send data in the `application/x-www-form-urlencoded` format instead, you can use one of the following options.
@@ -829,11 +858,75 @@ axios.post('http://something.com/', params.toString());
 
 You can also use the [`qs`](https://github.com/ljharb/qs) library.
 
-###### NOTE
-The `qs` library is preferable if you need to stringify nested objects, as the `querystring` method has known issues with that use case (https://github.com/nodejs/node-v0.x-archive/issues/1665).
+> NOTE: 
+> The `qs` library is preferable if you need to stringify nested objects, as the `querystring` method has [known issues](https://github.com/nodejs/node-v0.x-archive/issues/1665) with that use case.
 
 #### Form data
 
+##### 🆕 Automatic serialization
+
+Starting from `v0.27.0`, Axios supports automatic object serialization to a FormData object if the request `Content-Type` 
+header is set to `multipart/form-data`.
+
+The following request will submit the data in a FormData format (Browser & Node.js):
+
+```js
+import axios from 'axios';
+
+axios.post('https://httpbin.org/post', {x: 1}, {
+  headers: {
+    'Content-Type': 'multipart/form-data'
+  }
+}).then(({data})=> console.log(data));
+```
+
+In the `node.js` build, the ([`form-data`](https://github.com/form-data/form-data)) polyfill is used by default.
+
+You can overload the FormData class by setting the `env.FormData` config variable,
+but you probably won't need it in most cases:
+
+```js
+const axios= require('axios');
+var FormData = require('form-data');
+
+axios.post('https://httpbin.org/post', {x: 1, buf: new Buffer(10)}, {
+  headers: {
+    'Content-Type': 'multipart/form-data'
+  }
+}).then(({data})=> console.log(data));
+```
+
+Axios FormData serializer supports some special endings to perform the following operations:
+
+- `{}` - serialize the value with JSON.stringify
+- `[]` - unwrap the array like object as separate fields with the same key 
+
+```js
+const axios= require('axios');
+
+axios.post('https://httpbin.org/post', {
+  'myObj{}': {x: 1, s: "foo"},
+  'files[]': document.querySelector('#fileInput').files 
+}, {
+  headers: {
+    'Content-Type': 'multipart/form-data'
+  }
+}).then(({data})=> console.log(data));
+```
+
+Axios supports the following shortcut methods: `postForm`, `putForm`, `patchForm`
+which are just the corresponding http methods with a header preset: `Content-Type`: `multipart/form-data`.
+
+FileList object can be passed directly:
+
+```js
+await axios.postForm('https://httpbin.org/post', document.querySelector('#fileInput').files)
+```
+
+All files will be sent with the same field names: `files[]`;
+
+##### Manual FormData passing
+  
 In node.js, you can use the [`form-data`](https://github.com/form-data/form-data) library as follows:
 
 ```js
@@ -844,18 +937,7 @@ form.append('my_field', 'my value');
 form.append('my_buffer', new Buffer(10));
 form.append('my_file', fs.createReadStream('/foo/bar.jpg'));
 
-axios.post('https://example.com', form, { headers: form.getHeaders() })
-```
-
-Alternatively, use an interceptor:
-
-```js
-axios.interceptors.request.use(config => {
-  if (config.data instanceof FormData) {
-    Object.assign(config.headers, config.data.getHeaders());
-  }
-  return config;
-});
+axios.post('https://example.com', form)
 ```
 
 ## Semver