diff --git a/README.md b/README.md index d409c79a5b..25652f0e7a 100755 --- a/README.md +++ b/README.md @@ -22,7 +22,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) @@ -35,11 +35,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) @@ -482,6 +486,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 } } ``` @@ -706,10 +715,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 @@ -753,22 +782,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. @@ -833,6 +851,46 @@ The `qs` library is preferable if you need to stringify nested objects, as the ` #### Form data +##### ๐Ÿ†• Automatic serialization + +Starting from `v0.26.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 object as a form: + +```js +import axios from 'axios'; + +axios.post('https://postman-echo.com/post', {x: 1}, { + headers: { + 'Content-Type': 'multipart/form-data' + } +}).then(({data})=> console.log(data)); +``` + +This will only work if the FormData class is available in the environment as a global variable. +For `node.js` you have to import FormData polyfill ([`form-data`](https://github.com/form-data/form-data)) manually and set it as an `env` section config variable.. + +```js +const axios= require('axios'); +var FormData = require('form-data'); + +// OR +// axios.defaults.env.FormData= FormData; + +axios.post('https://postman-echo.com/post', {x: 1, buf: new Buffer(10)}, { + headers: { + 'Content-Type': 'multipart/form-data' + }, + + env: { // OR + FormData + } +}).then(({data})=> console.log(data)); +``` + +##### Manual FormData passing + In node.js, you can use the [`form-data`](https://github.com/form-data/form-data) library as follows: ```js @@ -843,18 +901,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