From 83454a55f6274ee4d7b5cce6c608a62c5aa6b0cb Mon Sep 17 00:00:00 2001
From: Dmitriy Mozgovoy <robotshara@gmail.com>
Date: Thu, 13 Oct 2022 22:47:23 +0300
Subject: [PATCH] chore: added progress capturing section to the docs; (#5084)

Added rate limiting section to the docs;

Co-authored-by: Jay <jasonsaayman@gmail.com>
---
 README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 87 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 25b22afc9b..4a5af19a85 100755
--- a/README.md
+++ b/README.md
@@ -62,6 +62,8 @@
     - [🆕 Automatic serialization](#-automatic-serialization-to-formdata)
   - [Files Posting](#files-posting)
   - [HTML Form Posting](#-html-form-posting-browser)
+  - [🆕 Progress capturing](#-progress-capturing)
+  - [🆕 Rate limiting](#-progress-capturing)
   - [Semver](#semver)
   - [Promises](#promises)
   - [TypeScript](#typescript)
@@ -356,7 +358,7 @@ These are the available config options for making requests. Only the `url` is re
 
   // `paramsSerializer` is an optional config in charge of serializing `params`
   paramsSerializer: {
-    indexes: null // array indexes format (null - no brackets, false - empty brackets, true - brackets with indexes)
+    indexes: false // array indexes format (null - no brackets, false (default) - empty brackets, true - brackets with indexes)
   },
 
   // `data` is the data to be sent as the request body
@@ -364,7 +366,7 @@ These are the available config options for making requests. Only the `url` is re
   // When no `transformRequest` is set, must be of one of the following types:
   // - string, plain object, ArrayBuffer, ArrayBufferView, URLSearchParams
   // - Browser only: FormData, File, Blob
-  // - Node only: Stream, Buffer
+  // - Node only: Stream, Buffer, FormData (form-data package)
   data: {
     firstName: 'Fred'
   },
@@ -414,15 +416,15 @@ These are the available config options for making requests. Only the `url` is re
   xsrfHeaderName: 'X-XSRF-TOKEN', // default
 
   // `onUploadProgress` allows handling of progress events for uploads
-  // browser only
-  onUploadProgress: function (progressEvent) {
-    // Do whatever you want with the native progress event
+  // browser & node.js
+  onUploadProgress: function ({loaded, total, progress, bytes, estimated, rate, upload = true}) {
+    // Do whatever you want with the Axios progress event
   },
 
   // `onDownloadProgress` allows handling of progress events for downloads
-  // browser only
-  onDownloadProgress: function (progressEvent) {
-    // Do whatever you want with the native progress event
+  // browser & node.js
+  onDownloadProgress: function ({loaded, total, progress, bytes, estimated, rate, download = true}) {
+    // Do whatever you want with the Axios progress event
   },
 
   // `maxContentLength` defines the max size of the http response content in bytes allowed in node.js
@@ -533,7 +535,13 @@ These are the available config options for making requests. Only the `url` is re
       dots: boolean; // use dots instead of brackets format
       metaTokens: boolean; // keep special endings like {} in parameter key
       indexes: boolean; // array indexes format null - no brackets, false - empty brackets, true - brackets with indexes
-  }
+  },
+
+  // http adapter only (node.js)
+  maxRate: [
+    100 * 1024, // 100KB/s upload limit,
+    100 * 1024  // 100KB/s download limit
+  ]
 }
 ```
 
@@ -1142,6 +1150,76 @@ will be submitted as the following JSON object:
 
 Sending `Blobs`/`Files` as JSON (`base64`) is not currently supported.
 
+## 🆕 Progress capturing
+
+Axios supports both browser and node environments to capture request upload/download progress.
+
+```js    
+await axios.post(url, data, {
+  onUploadProgress: function (axiosProgressEvent) {
+    /*{
+      loaded: number;
+      total?: number;
+      progress?: number; // in range [0..1]
+      bytes: number; // how many bytes have been transferred since the last trigger (delta)
+      estimated?: number; // estimated time in seconds
+      rate?: number; // upload speed in bytes
+      upload: true; // upload sign
+    }*/
+  },
+
+  onDownloadProgress: function (axiosProgressEvent) {
+    /*{
+      loaded: number;
+      total?: number;
+      progress?: number;
+      bytes: number; 
+      estimated?: number;
+      rate?: number; // download speed in bytes
+      download: true; // download sign
+    }*/
+  }
+});  
+```
+
+You can also track stream upload/download progress in node.js:
+
+```js
+const {data} = await axios.post(SERVER_URL, readableStream, {
+   onUploadProgress: ({progress}) => {
+     console.log((progress * 100).toFixed(2));
+   },
+  
+   headers: {
+    'Content-Length': contentLength
+   },
+
+   maxRedirects: 0 // avoid buffering the entire stream
+});
+````
+
+> **Note:**
+> Capturing FormData upload progress is currently not currently supported in node.js environments.
+
+> **⚠️ Warning**
+> It is recommended to disable redirects by setting maxRedirects: 0 to upload the stream in the **node.js** environment,
+> as follow-redirects package will buffer the entire stream in RAM without following the "backpressure" algorithm.
+
+
+## 🆕 Rate limiting
+
+Download and upload rate limits can only be set for the http adapter (node.js):
+
+```js
+const {data} = await axios.post(LOCAL_SERVER_URL, myBuffer, {
+  onUploadProgress: ({progress, rate}) => {
+    console.log(`Upload [${(progress*100).toFixed(2)}%]: ${(rate / 1024).toFixed(2)}KB/s`)
+  },
+   
+  maxRate: [100 * 1024], // 100KB/s limit
+});
+```
+
 ## Semver
 
 Until axios reaches a `1.0` release, breaking changes will be released with a new minor version. For example `0.5.1`, and `0.5.4` will have the same API, but `0.6.0` will have breaking changes.