feat: improve helper types for more type safety

docs/en/SUMMARY.md

@@ -18,4 +18,5 @@
 - [Form Handling](forms.md)
 - [Testing](testing.md)
 - [Hot Reloading](hot-reload.md)
+- [TypeScript Support](typescript.md)
 - [API Reference](api.md)

docs/en/api.md

@@ -212,6 +212,8 @@ const store = new Vuex.Store({ ...options })
 
   The first argument can optionally be a namespace string. [Details](modules.md#binding-helpers-with-namespace)
 
-- **`createNamespacedHelpers(namespace: string): Object`**
+- **`createNamespacedHelpers(namespace?: string): Object`**
 
   Create namespaced component binding helpers. The returned object contains `mapState`, `mapGetters`, `mapActions` and `mapMutations` that are bound with the given namespace. [Details](modules.md#binding-helpers-with-namespace)
+
+  If the namespace is not specified, it returns the root mapXXX helpers. This is mainly for TypeScript users to annotate root helper's type.

docs/en/typescript.md

@@ -0,0 +1,230 @@
+# TypeScript Support
+
+## Utility Types for Modules
+
+Vuex provides some utility types to help you to declare modules in TypeScript. They avoid runtime errors when using state, getters, mutations and actions in a module thanks to type checking.
+
+To use the utility types, you should declare module assets types at first. Following is a simple example of counter module types:
+
+```ts
+// State type
+export interface CounterState {
+  count: number
+}
+
+// Getters type
+// key: getter name
+// value: return type of getter
+export interface CounterGetters {
+  power: number
+}
+
+// Mutations type
+// key: mutation name
+// value: payload type of mutation
+export interface CounterMutations {
+  increment: { amount: number }
+}
+
+// Actions type
+// key: action name
+// value: payload type of action
+export interface CounterActions {
+  incrementAsync: { amount: number, delay: number }
+}
+```
+
+The state type must describe an actual state shape. The `CounterState` in the example indicates that the module's state has `count` property which must fulfill `number` type.
+
+The getters type describes what getter names exist in the module according to keys. The corresponding value type shows what type the getter returns. The `CounterGetters` in the example indicates that the module has a getter named `power` and it returns a value of type `number`.
+
+Both the actions and mutations type describe what thier names exist in the module as same as getters type. The value type of them indicates the payload type. The `CounterMutations` illustrates that the module has `increment` mutation and its payload is an object having `amount` property of type `number`, while the `CounterActions` shows there is `incrementAsync` action with an object payload having `amount` and `delay` property of type `number` in the module.
+
+After declaring the module assets types, you import `DefineModule` utility type and annotate the module with it:
+
+```ts
+import { DefineModule } from 'vuex'
+
+// Implementation of counter module
+export const counter: DefineModule<CounterState, CounterGetters, CounterMutations, CounterActions> = {
+  namespaced: true,
+
+  // Follow CounterState
+  state: {
+    count: 0
+  },
+
+  // Follow CounterGetters
+  getters: {
+    power: state => state.count * state.count
+  },
+
+  // Follow CounterMutations
+  mutations: {
+    increment (state, payload) {
+      state.count += payload.amount
+    }
+  },
+
+  // Follow CounterActions
+  actions: {
+    incrementAsync ({ commit }, payload) {
+      setTimeout(() => {
+        commit('increment', { amount: payload.amount })
+      }, payload.delay)
+    }
+  }
+}
+```
+
+Note that all function arguments types are inferred without manually annotating them including `dispatch` and `commit` in the action context. If you try to dispach an action (commit a mutation) that does not exist or the payload type is not valid on the declared types, it throws a compilation error.
+
+### Using external modules in the same namespace
+
+Sometimes you may want to use external modules' getters, actions and mutations in the same namespace. In that case, you can pass the external module assets types to `DefineModule` generic parameters to extend the module type:
+
+```ts
+// External module assets types
+// You may import them from another file on a practical code
+interface ExternalGetters {
+  extraValue: number
+}
+
+interface ExternalMutations {
+  loading: boolean
+}
+
+interface ExternalActions {
+  sendTrackingData: { name: string, value: string }
+}
+
+export const counter: DefineModule<
+  // The first 4 type parameters are for module assets
+  CounterState,
+  CounterGetters,
+  CounterMutations,
+  CounterActions,
+
+  // 3 type parameters that follows the module assets types are external module assets types
+  ExternalGetters,
+  ExternalMutations,
+  ExternalActions
+> = {
+  namespaced: true,
+
+  state: { /* ... */ },
+  mutations: { /* ... */ },
+
+  getters: {
+    power (state, getters) {
+      // You can use a getter from the external module
+      console.log(getters.extraValue)
+      return state.count * state.count
+    }
+  },
+
+  actions: {
+    incrementAsync ({ commit, dispatch }, payload) {
+      // Using the external action
+      dispatch('sendTrackingData', {
+        name: 'increment',
+        value: payload.amount
+      })
+
+      // Using the external mutation
+      commit('loading', true)      
+      setTimeout(() => {
+        commit('increment', { amount: payload.amount })
+        commit('loading', false)
+      }, payload.delay)
+    }
+  }
+}
+```
+
+### Using the root state, getters, actions and mutations
+
+If you want to use root state, getters, actions and mutations, you can pass root assets types following external assets types on `DefineModule`:
+
+```ts
+export const counter: DefineModule<
+  CounterState,
+  CounterGetters,
+  CounterMutations,
+  CounterActions,
+
+  // You can use `{}` type if you will not use them
+  {}, // External getters
+  {}, // External mutations
+  {}, // External actions
+
+  // Root types can be specified after external assets types
+  RootState,
+  RootGetters,
+  RootMutations,
+  RootActions
+> = {
+  /* ... module implementation ... */
+}
+```
+
+## Typed Component Binding Helpers
+
+You probably want to use fully typed `state`, `getters`, `dispatch` and `commit` not only in modules but also from components. You can use `createNamespacedHelpers` to use typed module assets on components. The `createNamespacedHelpers` accepts 4 generic parameters to annotate returned `mapState`, `mapGetters`, `mapMutations` and `mapActions` by using module assets types:
+
+```ts
+export const counterHelpers = createNamespacedHelpers<CounterState, CounterGetters, CounterMutations, CounterActions>('counter')
+```
+
+All the returned helpers and mapped computed properties and methods will be type checked. You can use them without concerning typos and invalid payload by yourself:
+
+```ts
+export default Vue.extend({
+  computed: counterHelpers.mapState({
+    value: 'count'
+  }),
+
+  methods: counterHelpers.mapMutations({
+    inc: 'increment'
+  }),
+
+  created () {
+    // These are correctly typed!
+    this.inc({ amount: 1 })
+    console.log(this.value)
+  }
+})
+```
+
+### Annotating Root Binding Helpers
+
+`createNamespacedHelpers` is made for generating new component binding helpers focusing a namespaced module. The API however is useful to create typed root binding helpers. So if you need them, you call `createNamespacedHelpers` without passing namespace:
+
+```ts
+const rootHelpers = createNamespacedHelpers<RootState, RootGetters, RootMutations, RootActions>()
+```
+
+## Explicit Payload
+
+While regular (not strictly typed) `dispatch` and `commit` can omit a payload, typed ones does not allow to omit it. This is because to ensure type safety of a payload. If you want to declare actions / mutations that do not have a payload you should explicitly pass `undefined` value.
+
+```ts
+export interface CounterMutation {
+  // This indicates the `increment` action does not have a payload
+  increment: undefined
+}
+
+// ...
+export const counter: DefineModule<CounterState, CounterGetters, CounterMutations, CounterActions> = {
+  // ...
+
+  actions: {
+    someAction ({ commit }) {
+      // Passing `undefined` value explicitly
+      commit('increment', undefined)
+    }
+  }
+}
+```
+
+This restriction might be changed after TypeScript implements [the conditional types](https://github.com/Microsoft/TypeScript/pull/21316) in the future.

package.json

@@ -10,7 +10,8 @@
     "dist",
     "types/index.d.ts",
     "types/helpers.d.ts",
-    "types/vue.d.ts"
+    "types/vue.d.ts",
+    "types/utils.d.ts"
   ],
   "scripts": {
     "dev": "node examples/server.js",
@@ -65,11 +66,11 @@
     "rollup-watch": "^4.3.1",
     "selenium-server": "^2.53.1",
     "todomvc-app-css": "^2.1.0",
-    "typescript": "^2.5.3",
+    "typescript": "^2.6.1",
     "uglify-js": "^3.1.2",
-    "vue": "^2.5.0",
+    "vue": "^2.5.13",
     "vue-loader": "^13.3.0",
-    "vue-template-compiler": "^2.5.0",
+    "vue-template-compiler": "^2.5.13",
     "webpack": "^3.7.1",
     "webpack-dev-middleware": "^1.10.0",
     "webpack-hot-middleware": "^2.19.1"

src/helpers.js

@@ -111,14 +111,16 @@ export const mapActions = normalizeNamespace((namespace, actions) => {
 
 /**
  * Rebinding namespace param for mapXXX function in special scoped, and return them by simple object
- * @param {String} namespace
+ * If the namespace is not specified, it returns the root mapXXX helpers.
+ * This is mainly for TypeScript users to annotate root helper's type.
+ * @param {String} [namespace]
  * @return {Object}
  */
 export const createNamespacedHelpers = (namespace) => ({
-  mapState: mapState.bind(null, namespace),
-  mapGetters: mapGetters.bind(null, namespace),
-  mapMutations: mapMutations.bind(null, namespace),
-  mapActions: mapActions.bind(null, namespace)
+  mapState: namespace ? mapState.bind(null, namespace) : mapState,
+  mapGetters: namespace ? mapGetters.bind(null, namespace) : mapGetters,
+  mapMutations: namespace ? mapMutations.bind(null, namespace) : mapMutations,
+  mapActions: namespace ? mapActions.bind(null, namespace) : mapActions
 })
 
 /**

test/unit/helpers.spec.js

@@ -517,4 +517,56 @@ describe('Helpers', () => {
     vm.actionB()
     expect(actionB).toHaveBeenCalled()
   })
+
+  it('createNamespacedHelpers: generates root helpers', () => {
+    const actionA = jasmine.createSpy()
+    const actionB = jasmine.createSpy()
+    const store = new Vuex.Store({
+      state: { count: 0 },
+      getters: {
+        isEven: state => state.count % 2 === 0
+      },
+      mutations: {
+        inc: state => state.count++,
+        dec: state => state.count--
+      },
+      actions: {
+        actionA,
+        actionB
+      }
+    })
+    const {
+      mapState,
+      mapGetters,
+      mapMutations,
+      mapActions
+    } = createNamespacedHelpers()
+    const vm = new Vue({
+      store,
+      computed: {
+        ...mapState(['count']),
+        ...mapGetters(['isEven'])
+      },
+      methods: {
+        ...mapMutations(['inc', 'dec']),
+        ...mapActions(['actionA', 'actionB'])
+      }
+    })
+    expect(vm.count).toBe(0)
+    expect(vm.isEven).toBe(true)
+    store.state.count++
+    expect(vm.count).toBe(1)
+    expect(vm.isEven).toBe(false)
+    vm.inc()
+    expect(store.state.count).toBe(2)
+    expect(store.getters.isEven).toBe(true)
+    vm.dec()
+    expect(store.state.count).toBe(1)
+    expect(store.getters.isEven).toBe(false)
+    vm.actionA()
+    expect(actionA).toHaveBeenCalled()
+    expect(actionB).not.toHaveBeenCalled()
+    vm.actionB()
+    expect(actionB).toHaveBeenCalled()
+  })
 })