Updates documentation with clearer return requirements (#19)

* Updates documentation with clearer return requirements

* Updates indentation

Author: emileber

docs/README.md

@@ -39,18 +39,18 @@ import { Service } from 'axios-middleware';
 const service = new Service(axios);
 
 service.register({
-    onRequest(config) {
-        console.log('onRequest');
-        return config;
-    },
-    onSync(promise) {
-		console.log('onSync');
-        return promise;
-    },
-    onResponse(response) {
-        console.log('onResponse');
-        return response;
-    }
+  onRequest(config) {
+    console.log('onRequest');
+    return config;
+  },
+  onSync(promise) {
+    console.log('onSync');
+    return promise;
+  },
+  onResponse(response) {
+    console.log('onResponse');
+    return response;
+  }
 });
 
 console.log('Ready to fetch.');

docs/_sidebar.md

@@ -2,12 +2,13 @@
   - [Getting started]()
   - [Installation](installation.md)
   - [Simplified syntax](simplified-syntax.md)
-  
+
 - API
   - [Middleware methods](api/methods.md)
   - [`Service` class](api/Service.md)
 
 - Examples
+  - [Auth retry middleware](examples/auth-middleware.md)
   - [Locale middleware](examples/locale-middleware.md)
   - [Service module](examples/service.md)
   - [Returning promises](examples/promise.md)

docs/api/Service.md

@@ -1,6 +1,6 @@
 # Middleware `Service` class
 
-This is the heart of this plugin module. It works by leveraging axios' adapter to call its middleware stack at each relevant steps of a request lifecycle.
+This is the heart of this plugin module. It works by leveraging axios' adapter to call the middleware stack at each relevant steps of a request lifecycle.
 
 ## `constructor(axios)`
 
@@ -41,4 +41,3 @@ Empty the middleware stack.
 ## `adapter(config)`
 
 The adapter function that replaces the default axios adapter. It calls the default implementation and passes the resulting promise to the middleware stack's `onSync` method.
-

docs/api/methods.md

@@ -6,7 +6,7 @@ These will be called at different step of a request lifecycle. Each method can r
 
 ## `onRequest(config)`
 
-Receives the configuration objects before the request is made. Useful to add headers, query parameters, validate data, etc.
+Receives the configuration object before the request is made. Useful to add headers, query parameters, validate data, etc.
 
 !> It must return the received `config` even if no changes were made to it. It can also return a promise that should resolve with the config to use for the request.
 
@@ -16,6 +16,8 @@ No internet connection right now? You might end up in this function. Do what you
 
 You can return a promise, or throw another error to keep the middleware chain going.
 
+!> Failing to return a rejecting promise or throw an error would mean that the error was dealt with and the chain would continue on a success path.
+
 ## `onSync(promise)`
 
 The request is being made and its promise is being passed. Do what you want with it but be sure to **return a promise**, be it the one just received or a new one.
@@ -28,7 +30,7 @@ Parsing the response can be done here. Say all responses from your API are retur
 
 ```javascript
 onResponse(response) {
-    return response._data;
+  return response._data;
 }
 ```
 
@@ -39,3 +41,5 @@ onResponse(response) {
 Not authenticated? Server problems? You might end up here. Do what you need with the error.
 
 ?> You can return a promise, which is useful when you want to retry failed requests.
+
+!> Failing to return a rejecting promise or throw an error would mean that the error was dealt with and the chain would continue on a success path.

docs/examples/auth-middleware.md

@@ -0,0 +1,32 @@
+# Unauthorized requests retry middleware
+
+In a case where we'd like to retry a request if not authenticated, we could return a promise in the `onResponseError` method.
+
+```javascript
+export default class AuthMiddleware {
+  constructor(auth, http) {
+    this.auth = auth;
+    this.http = http;
+  }
+
+  onResponseError(err) {
+    if (err.response.status === 401 && err.config && !err.config.hasRetriedRequest) {
+      return this.auth()
+        // Retrying the request now that we're authenticated.
+        .then((token) => this.http({
+          ...err.config
+          hasRetriedRequest: true,
+          headers: {
+            ...err.config.headers,
+            Authorization: `Bearer ${token}`
+          }
+        })
+        .catch(function (error) {
+          console.log('Refresh login error: ', error);
+          throw error;
+        });
+    }
+    throw err;
+  }
+}
+```

docs/examples/browser.md

@@ -10,18 +10,20 @@ Just use the short middleware syntax to quickly define one-time use middleware.
 <script src="https://unpkg.com/axios/dist/axios.min.js"></script>
 <script src="https://unpkg.com/axios-middleware/dist/axios-middleware.min.js"></script>
 <script>
-    // Create a new service instance
-    var service = new HttpMiddlewareService(axios);
-    
-    // Then register your middleware instances.
-    service.register({
-        onRequest: function(config) {
-            // handle the request
-        },
-        onResponseError(error) {
-            // handle the response error
-        }
-    });
+  // Create a new service instance
+  var service = new HttpMiddlewareService(axios);
+
+  // Then register your middleware instances.
+  service.register({
+    onRequest: function(config) {
+      // handle the request
+      return config;
+    },
+    onResponseError(error) {
+      // handle the response error
+      throw error;
+    }
+  });
 </script>
 ```
 
@@ -40,16 +42,16 @@ var app = app || {};
 * Custom Middleware class
 */
 app.MyMiddleware = (function(){
-    function MyMiddleware() {
-    }
-    
-    var proto = MyMiddleware.prototype = Object.create();
-    
-    proto.constructor = MyMiddleware;
-    proto.onRequest = function(config) {
-      // handle the request
-    };
-    return MyMiddleware;
+  function MyMiddleware() {}
+
+  var proto = MyMiddleware.prototype = Object.create();
+
+  proto.constructor = MyMiddleware;
+  proto.onRequest = function(config) {
+    // handle the request
+    return config;
+  };
+  return MyMiddleware;
 })();
 ```
 
@@ -63,13 +65,13 @@ var app = app || {};
 * Middleware Service
 */
 app.MiddlewareService = (function(MiddlewareService, MyMiddleware) {
-    // Create a new service instance
-    var service = new MiddlewareService(axios);
-    
-    // Then register your middleware instances.
-    service.register(new MyMiddleware());
-    
-    return service;
+  // Create a new service instance
+  var service = new MiddlewareService(axios);
+
+  // Then register your middleware instances.
+  service.register(new MyMiddleware());
+
+  return service;
 })(AxiosMiddleware.Service, app.MyMiddleware);
 ```
 

docs/examples/es5.md

@@ -8,8 +8,8 @@ Create a custom middleware to register.
 var BaseMiddleware = require('./base-middleware');
 
 function MyMiddleware() {
-    // call the parent constructor
-    BaseMiddleware.apply(this, arguments);
+  // call the parent constructor
+  BaseMiddleware.apply(this, arguments);
 }
 
 // Prototype wiring
@@ -19,6 +19,7 @@ proto.constructor = MyMiddleware;
 // Method overriding
 proto.onRequest = function(config) {
   // handle the request
+  return config;
 };
 
 module.exports = MyMiddleware;
@@ -39,4 +40,3 @@ service.register(new MyMiddleware());
 
 module.exports = service;
 ```
-

docs/examples/locale-middleware.md

@@ -1,19 +1,23 @@
 # Locale middleware
 
-Here's a simple example of a locale middleware who sets a language header on each AJAX request.
+Here's a simple example of a locale middleware who sets a language header on each request.
 
 ```javascript
 export default class LocaleMiddleware {
-    constructor(i18n) {
-        this.i18n = i18n;
-    }
-    
-    onRequest(config) {
-        config.headers = {
-            locale: this.i18n.lang,
-            ...config.headers
-        };
-        return config;
-    }
+  constructor(i18n) {
+    this.i18n = i18n;
+  }
+
+  onRequest(config) {
+    // returns a new Object to avoid changing the config object referenced.
+    return {
+      ...config,
+      headers: {
+        // default `locale`, can still be overwritten by config.headers.locale
+        locale: this.i18n.lang,
+        ...config.headers
+      }
+    };
+  }
 }
 ```

docs/examples/promise.md

@@ -1,30 +1,26 @@
 # Returning promises
 
-In a case where we'd like to retry a request if not authenticated, we could return a promise in the `onResponseError` method.
+Every method of our middleware are promise callback functions, meaning that they can return either a value, a new promise or throw an error and the middleware chain will react accordingly.
 
 ```javascript
-export default class AuthMiddleware {
-    constructor(auth, http) {
-        this.auth = auth;
-        this.http = http;
-    }
-    
-    onResponseError(err) {
-        if (err.response.status === 401 && err.config && !err.config.hasRetriedRequest) {
-            return this.auth()
-            .then(function (token) {
-                err.config.hasRetriedRequest = true;
-                err.config.headers.Authorization = `Bearer ${token}`;
-                
-                // Retrying the request now that we're authenticated.
-                return this.http(err.config);
-            })
-            .catch(function (error) {
-                console.log('Refresh login error: ', error);
-                throw error;
-            });
-        }
-        throw err;
+export default class DemoPromiseMiddleware {
+  onRequest(config) {
+    return asyncChecks().then(() => config);
+  }
+
+  onResponseError({ config } = {}) {
+    if (config && !config.hasRetriedRequest) {
+      // Retrying the request
+      return this.http({
+        ...config,
+        hasRetriedRequest: true,
+      })
+      .catch(function (error) {
+        console.log('Retry failed:', error);
+        throw error;
+      });
     }
+    throw err;
+  }
 }
 ```

docs/examples/service.md

@@ -11,8 +11,8 @@ const service = new Service(axios);
 
 // Then register your middleware instances.
 service.register([
-    new LocaleMiddleware(i18n),
-    new OtherMiddleware()
+  new LocaleMiddleware(i18n),
+  new OtherMiddleware()
 ]);
 
 export default service;