setup docs (#20)

* improvement(opts-helpers): add function to add a property to middleware context

* fix(opts-helpers): $addMiddlewareContext, override internal props only

* improve(opts-helpers): remove $addMiddlewareContext

* chore: setup docs

* docs: add documentations

* update docs

* update docs

* update docs

* update docs

* chore(tslint): change rules

* ci: update build branch

* refactor: install function

* add docs

Author: dsfx3d

.markdownlintrc

@@ -0,0 +1,4 @@
+{
+  "MD036": false,
+  "MD001": false
+}

.travis.yml

@@ -6,7 +6,6 @@ cache:
 branches:
   only:
     - master
-    - develop
 notifications:
   email: false
 node_js:

docs/.gitkeep

@@ -0,0 +1,43 @@
+module.exports = {
+  title: 'Vue Router Middleware Plugin',
+  description: 'The vue router middleware pipeline you deserve',
+  themeConfig: {
+    nav: [
+      { text: 'Guide', link: '/guide/' },
+      { text: 'API', link: '/api/' },
+      { text: 'GitHub', link: 'https://github.com/dsfx3d/vue-router-middleware-plugin'}
+    ],
+    sidebar: {
+      '/guide/': [
+        {
+          title: 'Getting Started',
+          collapsable: false,
+          children: [
+            '',
+            'quickstart'
+          ]
+        },
+        {
+          title: 'Advanced',
+          collapsable: false,
+          children: [
+            'configurations',
+            'context',
+            'middlewares'
+          ]
+        }
+      ],
+      '/api/': [
+        {
+          title: 'API Reference',
+          collapsable: false,
+          children: [
+            '',
+            'context',
+            'helpers'
+          ]
+        }
+      ]
+    }
+  }
+}

docs/.vuepress/config.js

@@ -0,0 +1,15 @@
+---
+home: true
+heroText: Middleware Plugin
+tagline: The middleware pipeline you deserve
+actionText: Get Started →
+actionLink: /guide/
+features:
+- title: Performant
+  details: Inspired from Nuxt Middlewares and built on top of vue router's Navigation Guards to offer the best of performance.
+- title: Light-Weight
+  details: A light weight but powerful middleware pipeline to control logic between your routes.
+- title: Extensible
+  details: The plugin API is inherently extensible to use within your applications or in integration with third-party plugins.
+footer: MIT Licensed | Copyright © 2020 @dsfx3d
+---

docs/README.md

@@ -0,0 +1,25 @@
+# Options
+
+These plugin options can be used to configure the plugin on registration.
+
+```javascript
+Vue.use(MiddlewarePlugin, {
+  router,
+  middleware,
+  context
+})
+```
+
+## Options Properties
+
+### `router: VueRouter`
+
+The vue router instance of your app.
+
+### `middleware?: function | Array<function>`
+
+The middleware property is used to register global middlewares, it can be set to either a single middleware function or an array of middleware functions. _(optional)_
+
+### `context?: object`
+
+This option is used to add custom properties to the default middleware context. The context object is merged with the middleware context on plugin registration. _(optional)_

docs/api/README.md

@@ -0,0 +1,40 @@
+# Context
+
+```javascript
+export default ({ app, to, from, redirect }) => {
+  if (to.path === '/protected') {
+    redirect(from)
+  } else {
+    const { visits } = app.$getMiddlewareContext()
+    app.$updateMiddlewareContext('visits', (visits || 0) + 1)
+  }
+}
+```
+
+## Built-In Properties
+
+The context has the following built-in properties:
+
+### `app: VueConstructor`
+
+A middleware app object with injected [helpers](helpers/).
+
+### `to: Route`
+
+The target [Route Object](https://router.vuejs.org/api/#the-route-object) being navigated to.
+
+*An argument from [Navigation Guard](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards)*
+
+### `from: Route`
+
+The target [Route Object](https://router.vuejs.org/api/#the-route-object) being navigated from.
+
+*An argument from [Navigation Guard](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards)*
+
+### `redirect: function`
+
+A function to redirect to any route. Accepts same arguments as the `next` function in a [Navigation Guard](https://router.vuejs.org/guide/advanced/navigation-guards.html#global-before-guards) but unlike a navigation guard, it's not required to be called in each middleware in order to resolve it.
+
+## Adding custom properties
+
+In the above example, we appearently add a property `visits` to the middleware context. Goto [Helper Functions](helpers.html#functions) for more.

docs/api/context.md

@@ -0,0 +1,37 @@
+# Helpers
+
+These are the helper functions of the `app` object in the context.
+
+## Properties
+
+### `$MiddlewarePlugin: boolean`
+
+A flag for other plugins to identify `vue-router-middleware-plugin` is installed in the app. This will always be `true`
+
+## Functions
+
+> __Note:__ [Built-In middleware context properties](context.html#built-in-properties) cannot be mutated from theses helper functions. If a built-in property is passed in the arguments it will get overriden by the internal value.
+
+### `$getMiddlewareContext: () => object`
+
+returns the custom middleware context.
+
+```javascript
+const context = app.$getMiddlewareContext()
+```
+
+### `$setMiddlewareContext: (context: object) => object`
+
+set custom middleware context. This will overide all existing custom properties.
+
+```javascript
+const updatedContext = app.$setMiddlewareContext({ foo: 'baz' })
+```
+
+### `$updateMiddlewareContext: (key: string, value: any) => void`
+
+add or update a custom middleware context property.
+
+```javascript
+app.$updateMiddlewareContext('foo', 'baz')
+```

docs/api/helpers.md

@@ -0,0 +1,20 @@
+# Introduction
+
+A middleware is a block of code that will run when navigating
+from one route to another.
+
+The Vue Router offers [navigation guard API](https://router.vuejs.org/guide/advanced/navigation-guards.html)
+which can be used to add control logic between your routes but they can easily make
+your route objects messy and difficult to read and there's no elegant way of reusing
+same logic in multiple routes.
+
+The plugin utilizes navigation guards to implement easy to use, readable and more
+organized middlewares for your routes.
+
+### Installation
+
+```bash
+npm i -S vue-router-middleware-plugin
+```
+
+Get started with the quickstart guide.

docs/guide/README.md

@@ -0,0 +1,67 @@
+# Configuration
+
+The plugin can be configured in multiple ways with the help of plugin options.
+
+#### 1. Simple Configuration
+
+```javascript
+import Vue from 'vue'
+import MiddlewarePlugin from 'vue-router-middleware-plugin'
+import router from '@/path-to-router'
+
+Vue.use(MiddlewarePlugin, router)
+```
+
+#### 2. Custom [Middleware Context](context)
+
+```javascript
+import Vue from 'vue'
+import MiddlewarePlugin from 'vue-router-middleware-plugin'
+import router from '@/path-to-router'
+import store from '@/path-to-store'
+
+Vue.use(MiddlewarePlugin, {
+  router,
+  context: { store }
+})
+```
+
+Now, `store` will be injected as a property in all middleware contexts.
+
+```javascript
+export default async ({ store }) => {
+  await store.dispatch('app/getData')
+}
+```
+
+#### 3. Single [Global Middleware](middlewares.html#global-middleware)
+
+```javascript
+import Vue from 'vue'
+import MiddlewarePlugin from 'vue-router-middleware-plugin'
+import router from '@/path-to-router'
+import AuthMiddleware from '@/path-to-auth-middleware'
+
+Vue.use(MiddlewarePlugin, {
+  router,
+  middleware: AuthMiddleware
+})
+```
+
+If you are wondering, it is possible to ignore a global middleware for individual
+routes.
+
+#### 4. Multiple [Global Middlewares](middlewares.html#global-middleware)
+
+```javascript
+import Vue from 'vue'
+import MiddlewarePlugin from 'vue-router-middleware-plugin'
+import router from '@/path-to-router'
+import AuthMiddleware from '@/path-to-auth-middleware'
+import LoggerMiddleware from '@/path-to-logger-middleware'
+
+Vue.use(MiddlewarePlugin, {
+  router,
+  middleware: [AuthMiddleware, LoggerMiddleware]
+})
+```

docs/guide/configurations.md

@@ -0,0 +1,90 @@
+# Context
+
+The `context` or middleware context is the only argument of a middleware function.
+
+```javascript
+export default context => {
+  const { app, to, from, redirect } = context
+
+  if (to.path === '/protected') {
+    redirect(from)
+  }
+}
+```
+
+## Custom Context
+
+The context can be extend by adding custom properties in plugin options.
+
+```javascript
+import Vue from 'vue'
+import MiddlewarePlugin from 'vue-router-middleware-plugin'
+import router from '@/path-to-router'
+import store from '@/path-to-store'
+
+Vue.use(MiddlewarePlugin, {
+  router,
+  context: { store }
+})
+```
+
+Now, `store` will be injected as a property in all middleware contexts.
+
+```javascript
+export default async ({ store }) => {
+  await store.dispatch('app/getData')
+}
+```
+
+In this case, you could've imported the store in the middleware module instead of
+adding it as a custom context property.
+
+```javascript
+import store from '@/path-to-store'
+
+export default async () => {
+  await store.dispatch('app/getData')
+}
+```
+
+If you are thinking what's the point of adding custom context. It will depend on
+the use case and personal preferences of a developer. One such case might be,
+if you are lazy and don't want to import the same module in multiple middlewares.
+
+The idea behind adding custom context was so that other plugins can leverage it
+to inject functionalities which can used inside a middleware, but there's more than
+that. With the context, you can carry state in the middleware pipeline.
+
+### Dynamic Custom Context
+
+The custom context properties can be mutated with the helper functions exposed to
+the middleware via `app` context. The ability to mutate the custom context properties
+makes it possible to use these properties as middleware state.
+
+Initialize the state in plugin options.
+
+```javascript
+import Vue from 'vue'
+import MiddlewarePlugin from 'vue-router-middleware-plugin'
+import router from '@/path-to-router'
+
+Vue.use(MiddlewarePlugin, {
+  router,
+  context: { dashboardVisits: 0 }
+})
+```
+
+Mutate `dashboardVisits` in any middleware function.
+
+```javascript
+export default ({ app, to, dashboardVisits }) => {
+  if (to.path === '/dashboard') {
+    app.$setMiddlewareContext({ dashboardVisits: dashboardVisits + 1 })
+  }
+}
+```
+
+> You cannot mutate built-in context properties. Like `redirect`, `from` etc.
+
+Goto [API References](/api/context) to find out more about helper functions and
+`app` context.