Adds simplified object literal syntax (#4)

* Adds simplified object literal syntax

* Refactors the 'handle' prefix in favor of the 'on' prefix

* Adds examples and api descriptions to the docs

* Adds HttpMiddlewareService api and simplified syntax documentation

* Adds test with both middleware syntaxes

Author: emileber

.eslintrc.js

@@ -18,6 +18,7 @@ module.exports = {
         'no-duplicate-imports': 'error',
         // risk only exist with semi-colon auto insertion. Not our case.
         'no-plusplus': 'off',
+        'no-param-reassign': 'off',
         'no-underscore-dangle': ['error', {
             'allowAfterSuper': true,
             'allowAfterThis': true,

docs/README.md

@@ -11,40 +11,34 @@ There are two classes exposed in this module:
 
 It works with either the global axios or a local instance.
 
-## Creating your middleware
+## Examples
 
-Here's a simple example of a locale middleware who sets a language header on each AJAX request.
+All examples are written using ES6 syntax but you can definitely use this plugin with ES5 code, even directly in the browser.
 
-```javascript
-import { HttpMiddleware } from 'axios-middleware';
+### Simplest use-case
 
-export default class ErrorMiddleware extends HttpMiddleware {
-    handleResponseError(error) {
-        console.log("Handling:", error);
-    }
-}
-```
+?> A common use-case would be to expose an instance of the service which consumes an _axios_ instance configured for an API. It's then possible to register middlewares for this API at different stages of the initialization process of an application.
 
-## Using the service
-
-Simplest use-case:
+The following example is using the [simplified syntax](simplified-syntax.md).
 
 ```javascript
 import axios from 'axios';
 import { HttpMiddlewareService } from 'axios-middleware';
-import i18n from './i18n';
-import { LocaleMiddleware, OtherMiddleware } from './middlewares';
 
 // Create a new service instance
 const service = new HttpMiddlewareService(axios);
 
 // Then register your middleware instances.
-service.register([
-    new LocaleMiddleware(i18n),
-    new OtherMiddleware()
-]);
+service.register({
+    onRequest() {
+        // handle the request
+    },
+    onResponseError(error) {
+        // handle the response error
+    }
+});
 
 // We're good to go!
+export default { service };
 ```
 
-A common use-case would be to expose an instance of the service which consumes an _axios_ instance configured for an API. It's then possible to register middlewares for this API at different stages of the initialization process of an application.

docs/_navbar.md

@@ -1,2 +1,2 @@
 - [Github](https://github.com/emileber/axios-middleware)
-- [npm](https://www.npmjs.com/package/axios-middleware)
+- [![npm version](https://badge.fury.io/js/axios-middleware.svg)](https://www.npmjs.com/package/axios-middleware)

docs/_sidebar.md

@@ -1,7 +1,17 @@
 - Introduction
   - [Getting started]()
   - [Installation](installation.md)
-  - [Examples](examples.md)
+  - [Simplified syntax](simplified-syntax.md)
+  
+- API
+  - [`HttpMiddleware`](api/HttpMiddleware.md)
+  - [`HttpMiddlewareService`](api/HttpMiddlewareService.md)
+
+- Examples
+  - [Locale middleware](examples/locale-middleware.md)
+  - [Service module](examples/service.md)
+  - [ES5 usage](examples/es5.md)
+  - [Browser usage](examples/browser.md)
 
 - Ecosystem
   - [Github](https://github.com/emileber/axios-middleware)

docs/api/HttpMiddleware.md

@@ -0,0 +1,35 @@
+# HttpMiddleware
+
+?> This class is optional if you opt to use the [simplified syntax](simplified-syntax.md).
+
+The base implementation to inherit when creating your custom implementation. **Any function is optional** and should be provided within a custom middleware only if needed.
+
+## `constructor`
+
+The constructor isn't used in the default middleware, leaving it totally available to the child classes. Very useful to pass any relevant services your middleware might need, like [the `i18n` service in our example](examples/locale-middleware.md).
+
+## `onRequest(config)`
+
+Receives the configuration objects 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.
+
+## `onRequestError(error)`
+
+No internet connection right now? You might end up in this function. Do what you need with the error.
+
+## `onResponse(response)`
+
+Parsing the response can be done here. Say all responses from your API are returned nested within a `_data` property?
+
+```javascript
+onResponse(response) {
+    return response._data;
+}
+```
+
+!> The original `response` object or _a new one_ should be returned.
+
+## `onResponseError(error)`
+
+Not authenticated? Server problems? You might end up here. Do what you need with the error.

docs/api/HttpMiddlewareService.md

@@ -0,0 +1,37 @@
+# HttpMiddlewareService
+
+This is the heart of this plugin module. It works by leveraging axios interceptors to call its middleware queue.
+
+## `constructor(axios)`
+
+You can pass an optional axios instance (the global one, or a local instance) on which to register the middlewares. If you don't pass an axios instance right away, you can use the `setHttp` method later on.
+
+Even if no axios instance was passed, you can still register middlewares.
+
+## `setHttp(axios)`
+
+Sets or replaces the axios instance on which to intercept the requests and responses.
+
+## `unsetHttp()`
+
+Removes the registered interceptors on the axios instance, if any were set.
+
+## `has(middleware)`
+
+Returns `true` is the passed `middleware` instance is within the queue.
+
+## `register(middlewares)`
+
+Adds a middleware instance or an array of middlewares to the queue.
+
+You can pass an `HttpMiddleware` instance or a simple object implementing only the functions you need (see the [simplified syntax](simplified-syntax.md)).
+
+!> Throws an error if a middleware instance is already within the queue.
+
+## `unregister(middleware)`
+
+Removes a middleware instance from the queue.
+
+## `reset()`
+
+Empty the middleware queue.

docs/examples.md

@@ -0,0 +1,87 @@
+# Usage in the browser
+
+The _axios-middleware_ plugin is made to be easily used in the browser right away.
+
+## Common usage
+
+Just use the short middleware syntax to quickly define one-time use middleware.
+
+```html
+<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
+        }
+    });
+</script>
+```
+
+
+## Advanced usage
+
+A mix of the ES5 usage within a common namespacing pattern for an app.
+
+Define your middlewares within a `Middleware.js` file.
+
+```javascript
+// Middleware.js
+var app = app || {};
+
+/**
+* Custom Middleware class
+*/
+app.MyMiddleware = (function(HttpMiddleware){
+    function MyMiddleware() {
+        // call the parent constructor
+        HttpMiddleware.apply(this, arguments);
+    }
+    
+    var proto = MyMiddleware.prototype = Object.create(HttpMiddleware.prototype);
+    
+    proto.constructor = MyMiddleware;
+    proto.onRequest = function(config) {
+      // handle the request
+    };
+    return MyMiddleware;
+})(AxiosMiddleware.HttpMiddleware);
+```
+
+Then register these middlewares with a newly created `HttpMiddlewareService` instance.
+
+```javascript
+// Service.js
+var app = app || {};
+
+/**
+* Middleware Service
+*/
+app.MiddlewareService = (function(HttpMiddlewareService, MyMiddleware) {
+    // Create a new service instance
+    var service = new HttpMiddlewareService(axios);
+    
+    // Then register your middleware instances.
+    service.register(new MyMiddleware());
+    
+    return service;
+})(AxiosMiddleware.HttpMiddlewareService, app.MyMiddleware);
+```
+
+In this case, the order in which to import the JS files is important.
+
+```html
+<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 src="Middleware.js"></script>
+<script src="Service.js"></script>
+```
+
+?> At that point, you may realise that it's a lot of files. You might want to think about using a bundler like [Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/guide/en), or a simple concatenation pipeline with [grunt](https://gruntjs.com/) or [gulp](https://gulpjs.com/).