Feature: allow same paradigm for lazy loading modules

Author: blake-newman

docs/en/api.md

@@ -158,8 +158,12 @@ const store = new Vuex.Store({ ...options })
 
 - **`registerModule(path: string | Array<string>, module: Module)`**
 
+  **`registerModule(path: string | Array<string>, module: () => Promise<Module>): Promise<Module>`**
+
   Register a dynamic module. [Details](modules.md#dynamic-module-registration)
 
+  Lazy load a dynamic module. [Details](modules.md#lazy-load-dynamic-modules)
+  
 - **`unregisterModule(path: string | Array<string>)`**
 
   Unregister a dynamic module. [Details](modules.md#dynamic-module-registration)

docs/en/modules.md

@@ -242,7 +242,57 @@ The module's state will be exposed as `store.state.myModule` and `store.state.ne
 
 Dynamic module registration makes it possible for other Vue plugins to also leverage Vuex for state management by attaching a module to the application's store. For example, the [`vuex-router-sync`](https://github.com/vuejs/vuex-router-sync) library integrates vue-router with vuex by managing the application's route state in a dynamically attached module.
 
-You can also remove a dynamically registered module with `store.unregisterModule(moduleName)`. Note you cannot remove static modules (declared at store creation) with this method.
+### Lazy Load Dynamic Modules
+
+You can code split you Vuex store and dynamically register store modules. 
+
+``` js
+const myModule = () => import('path/to/module')
+
+store.registerModule('myModule', myModule)
+```
+
+This is simple enough, however you will need to ensure that modules are registered before you can use them. Attempting to use a module before it is registered will not work and will cause errors. 
+
+For example, with vue-router, you can ensure that routing does not resolve until the required modules have been loaded. You can find further [implementation details here](https://ssr.vuejs.org/en/data.html) under the **Client Data Fetching** section. Using this pattern will ensure that we can register modules before use within components.
+
+Overall this pattern will require more awareness and management of the store module registration, however if well managed it can be a very poweful feature and significantly reduce the initial bundle size of your application.
+
+``` js
+import { mapGetters } from 'vuex'
+
+const myModule = () => import('path/to/module')
+
+export default {
+  asyncData(store) {
+    return store.registerModule('myModule', myModule)
+      .then(() => store.dispatch('myModule/getData'))
+  },
+
+  computed: {
+    ...mapGetters('myModule', ['a'])
+  }
+}
+```
+
+Using async and await this becomes less verbose for the registering of a module:
+
+``` js
+import { mapGetters } from 'vuex'
+
+const myModule = () => import('path/to/module')
+
+export default {
+  async asyncData(store) {
+    await store.registerModule('myModule', myModule)
+    await store.dispatch('myModule/getData')
+  },
+
+  computed: {
+    ...mapGetters('myModule', ['a'])
+  }
+}
+```
 
 ### Module Reuse
 

src/store.js

@@ -158,10 +158,15 @@ export class Store {
       assert(path.length > 0, 'cannot register the root module by using registerModule.')
     }
 
-    this._modules.register(path, rawModule)
-    installModule(this, this.state, path, this._modules.get(path))
-    // reset store to update getters...
-    resetStoreVM(this, this.state)
+    const moduleResolved = module => {
+      this._modules.register(path, module.default || module)
+      installModule(this, this.state, path, this._modules.get(path))
+      // reset store to update getters...
+      resetStoreVM(this, this.state)
+    }
+
+    if (typeof rawModule === 'function') return rawModule().then(moduleResolved)
+    moduleResolved(rawModule)
   }
 
   unregisterModule (path) {

test/unit/modules.spec.js

@@ -82,6 +82,36 @@ describe('Modules', () => {
     })
   })
 
+  it('dynamic module registration with promise (dynamic import)', () => {
+    const store = new Vuex.Store({
+      modules: {
+        a: {
+          namespaced: true
+        }
+      }
+    })
+    const actionSpy = jasmine.createSpy()
+    const mutationSpy = jasmine.createSpy()
+    const module = () => Promise.resolve({
+      state: { value: 1 },
+      getters: { foo: state => state.value },
+      actions: { foo: actionSpy },
+      mutations: { foo: mutationSpy }
+    })
+
+    store.registerModule(['a', 'b'], module)
+      .then(() => {
+        expect(store.state.a.b.value).toBe(1)
+        expect(store.getters['a/foo']).toBe(1)
+
+        store.dispatch('a/foo')
+        expect(actionSpy).toHaveBeenCalled()
+
+        store.commit('a/foo')
+        expect(mutationSpy).toHaveBeenCalled()
+      })
+  })
+
   // #524
   it('should not fire an unrelated watcher', done => {
     const spy = jasmine.createSpy()

types/index.d.ts

@@ -22,6 +22,7 @@ export declare class Store<S> {
 
   registerModule<T>(path: string, module: Module<T, S>): void;
   registerModule<T>(path: string[], module: Module<T, S>): void;
+  registerModule<T>(path: string[], module: () => Promise<Module<T, S>>): Promise<Module<T, S>>;
 
   unregisterModule(path: string): void;
   unregisterModule(path: string[]): void;

types/test/index.ts

@@ -199,6 +199,10 @@ namespace RegisterModule {
     state: { value: 2 }
   });
 
+  store.registerModule("a", () => Promise.resolve({
+    state: { value: 1 }
+  }));
+
   store.unregisterModule(["a", "b"]);
   store.unregisterModule("a");
 }