Implement module namespace option (#420)

* refactoring: adding module tree model

* add namespace if module namepsace option is specified

* hot reload namespace

* localize getters, dispatch and commit if module is namespaced

* add error message for unknown local action/mutation

* namespace option only accepts string value

* add more test for local getters, dispatch and commit

* update docs for namespace options

* add a caveat for plugin developers

* add more tests

* add typings for module namespace feature

* use normal object for local getters to compat with root getters

* remove unused this._options

* use root dispatch and commit if there is no namespace

Author: ktsn

docs/en/modules.md

@@ -81,42 +81,93 @@ const moduleA = {
 
 ### Namespacing
 
-Note that actions, mutations and getters inside modules are still registered under the **global namespace** - this allows multiple modules to react to the same mutation/action type. You can namespace the module assets yourself to avoid name clashing by prefixing or suffixing their names. And you probably should if you are writing a reusable Vuex module that will be used in unknown environments. For example, we want to create a `todos` module:
+Note that actions, mutations and getters inside modules are still registered under the **global namespace** - this allows multiple modules to react to the same mutation/action type. You probably should namespace your Vuex module if you are writing a reusable one that will be used in unknown environments. To support namespacing for avoiding name clashing, Vuex provides `namespace` option. If you specify string value to `namespace` option, module assets types are prefixed by the given value:
 
 ``` js
-// types.js
+export default {
+  namespace: 'account/',
 
-// define names of getters, actions and mutations as constants
-// and they are prefixed by the module name `todos`
-export const DONE_COUNT = 'todos/DONE_COUNT'
-export const FETCH_ALL = 'todos/FETCH_ALL'
-export const TOGGLE_DONE = 'todos/TOGGLE_DONE'
+  // module assets
+  state: { ... }, // module state will not be changed by prefix option
+  getters: {
+    isAdmin () { ... } // -> getters['account/isAdmin']
+  },
+  actions: {
+    login () { ... } // -> dispatch('account/login')
+  },
+  mutations: {
+    login () { ... } // -> commit('account/login')
+  },
+
+  // nested modules
+  modules: {
+    // inherit the namespace from parent module
+    myPage: {
+      state: { ... },
+      getters: {
+        profile () { ... } // -> getters['account/profile']
+      }
+    },
+
+    // nest the namespace
+    posts: {
+      namespace: 'posts/',
+
+      state: { ... },
+      getters: {
+        popular () { ... } // -> getters['account/posts/popular']
+      }
+    }
+  }
+}
 ```
 
-``` js
-// modules/todos.js
-import * as types from '../types'
+Namespaced getters and actions will receive localized `getters`, `dispatch` and `commit`. In other words, you can use the module assets without writing prefix in the same module. If you want to use the global ones, `rootGetters` is passed to the 4th argument of getter functions and the property of the action context. In addition, `dispatch` and `commit` receives `root` option on their last argument.
 
-// define getters, actions and mutations using prefixed names
-const todosModule = {
-  state: { todos: [] },
+``` js
+export default {
+  namespace: 'prefix/',
 
   getters: {
-    [types.DONE_COUNT] (state) {
-      // ...
-    }
+    // `getters` is localized to this module's getters
+    // you can use rootGetters via 4th argument of getters
+    someGetter (state, getters, rootState, rootGetters) {
+      getters.someOtherGetter // -> 'prefix/someOtherGetter'
+      rootGetters.someOtherGetter // -> 'someOtherGetter'
+    },
+    someOtherGetter: state => { ... }
   },
 
   actions: {
-    [types.FETCH_ALL] (context, payload) {
-      // ...
-    }
-  },
+    // dispatch and commit are also localized for this module
+    // they will accept `root` option for the root dispatch/commit
+    someAction ({ dispatch, commit, getters, rootGetters }) {
+      getters.someGetter // -> 'prefix/someGetter'
+      rootGetters.someGetter // -> 'someGetter'
+
+      dispatch('someOtherAction') // -> 'prefix/someOtherAction'
+      dispatch('someOtherAction', null, { root: true }) // -> 'someOtherAction'
+
+      commit('someMutation') // -> 'prefix/someMutation'
+      commit('someMutation', null, { root: true }) // -> 'someMutation'
+    },
+    someOtherAction (ctx, payload) { ... }
+  }
+}
+```
 
-  mutations: {
-    [types.TOGGLE_DONE] (state, payload) {
-      // ...
-    }
+#### Caveat for Plugin Developers
+
+You may care about unpredictable namespacing for your modules when you create a [plugin](plugins.md) that provides the modules and let users add them to a Vuex store. Your modules will be also namespaced if the plugin users add your modules under a namespaced module. To adapt this situation, you may need to receive a namespace value via your plugin option:
+
+``` js
+// get namespace value via plugin option
+// and returns Vuex plugin function
+export function createPlugin (options = {}) {
+  return function (store) {
+    // add namespace to plugin module's types
+    const namespace = options.namespace || ''
+    store.dispatch(namespace + 'pluginAction')
   }
 }
 ```