✨ Add helper functions

Author: distolma

README.md

@@ -7,7 +7,7 @@
 
 [Storeon] is a tiny event-based Redux-like state manager without dependencies. `@storeon/vue` package helps to connect store with [Vue] to provide a better performance and developer experience while remaining so tiny.
 
-- **Size**. 136 bytes (+ Storeon itself) instead of ~3kB of [Vuex] (minified and gzipped).
+- **Size**. 160 bytes (+ Storeon itself) instead of ~3kB of [Vuex] (minified and gzipped).
 - **Ecosystem**. Many additional [tools] can be combined with a store.
 - **Speed**. It tracks what parts of state were changed and re-renders only components based on the changes.
 
@@ -97,15 +97,74 @@ export default {
 </script>
 ```
 
+### The `mapState` Helper
+
+When a component needs to make use of multiple store state properties, declaring all these computed properties can get repetitive and verbose. To deal with this we can make use of the `mapState` helper which generates computed getter functions for us, saving us some keystrokes:
+
+```js
+import { mapState } from '@storeon/vue/helpers'
+
+export default {
+  computed: mapState({
+    // arrow functions can make the code very succinct!
+    count: state => state.count,
+    // passing the string value 'count' is same as `state => state.count`
+    countAlias: 'count',
+    // to access local state with `this`, a normal function must be used
+    countPlusLocalState (state) {
+      return state.count + this.localCount
+    }
+  })
+}
+```
+
+We can also pass a string array to `mapState` when the name of a mapped computed property is the same as a state sub tree name.
+
+```js
+import { mapState } from '@storeon/vue/helpers'
+
+export default {
+  computed: mapState([
+    // map this.count to storeon.state.count
+    'count'
+  ])
+}
+```
+
+### The `mapDispatch` Helper
+
+You can dispatch actions in components with `this.$storeon.dispatch('xxx')`, or use the `mapDispatch` helper which maps component methods to `store.dispatch` calls:
+
+```js
+import { mapDispatch } from '@storeon/vue/helpers'
+
+export default {
+  methods: {
+    ...mapDispatch([
+      // map `this.inc()` to `this.$storeon.dispatch('increment')`
+      'inc',
+      // map `this.incBy(amount)` to `this.$storeon.dispatch('incBy', amount)`
+      'incBy'
+    ]),
+    ...mapDispatch({
+      // map `this.add()` to `this.$storeon.dispatch('inc')`
+      add: 'inc'
+    })
+  }
+}
+
+```
+
 ## Using with TypeScript
 
-Plugin add to Vue’s global/instance properties and component options. In these cases, type declarations are needed to make plugins compile in TypeScript. We can declare an instance property `$storeon` and `$state` with type `StoreonStore<State, Events>`. You can also declare component options `store`:
+Plugin add to Vue’s global/instance properties and component options. In these cases, type declarations are needed to make plugins compile in TypeScript. We can declare an instance property `$storeon` with type `StoreonStore<State, Events>`. You can also declare component options `store`:
 
 #### `typing.d.ts`
 
 ```ts
 import Vue, { ComponentOptions } from 'vue'
 import { StoreonStore } from 'storeon'
+import { StoreonVueStore } from '@storeon/vue'
 import { State, Events } from './store'
 
 declare module 'vue/types/options' {
@@ -116,8 +175,20 @@ declare module 'vue/types/options' {
 
 declare module 'vue/types/vue' {
   interface Vue {
-    $storeon: StoreonStore<State, Events>;
-    $state: State;
+    $storeon: StoreonVueStore<State, Events>;
   }
 }
 ```
+
+To let TypeScript properly infer types inside Vue component options, you need to define components with `Vue.component` or `Vue.extend`:
+
+```diff
+-export default {
++export default Vue.extend({
+  methods: {
+    inc() {
+      this.$storeon.dispatch('inc')
+    }
+  }
+};
+```

helpers/index.d.ts

@@ -0,0 +1,28 @@
+import Vue from 'vue';
+import { StoreonDispatch } from 'storeon';
+
+type Computed = () => any;
+type ActionMethod = (...args: any[]) => Promise<any>;
+type InlineComputed<T extends Function> = T extends (...args: any[]) => infer R ? () => R : never
+type InlineMethod<T extends (fn: any, ...args: any[]) => any> = T extends (fn: any, ...args: infer Args) => infer R ? (...args: Args) => R : never
+type CustomVue = Vue & Record<string, any>;
+
+interface Mapper<R> {
+  <Key extends string>(map: Key[]): { [K in Key]: R };
+  <Map extends Record<string, string>>(map: Map): { [K in keyof Map]: R };
+}
+
+interface MapperForState {
+  <S, Map extends Record<string, (this: CustomVue, state: S, getters: any) => any> = {}>(
+    map: Map
+  ): { [K in keyof Map]: InlineComputed<Map[K]> };
+}
+
+interface MapperForAction {
+  <Map extends Record<string, (this: CustomVue, dispatch: StoreonDispatch<any>, ...args: any[]) => any>>(
+    map: Map
+  ): { [K in keyof Map]: InlineMethod<Map[K]> };
+}
+
+export declare const mapState: Mapper<Computed> & MapperForState;
+export declare const mapActions: Mapper<ActionMethod> & MapperForAction;

helpers/index.js

@@ -0,0 +1,55 @@
+const mapState = states => {
+  let res = {}
+  if (process.env.NODE_ENV !== 'production' && !isValidMap(states)) {
+    console.error('Mapper parameter must be either an Array or an Object')
+  }
+  normalizeMap(states).forEach(({ key, val }) => {
+    res[key] = function () {
+      let state = this.$storeon.state
+
+      return typeof val === 'function' ? val.call(this, state) : state[val]
+    }
+  })
+  return res
+}
+
+const mapDispatch = events => {
+  let res = {}
+  if (process.env.NODE_ENV !== 'production' && !isValidMap(events)) {
+    console.error('Mapper parameter must be either an Array or an Object')
+  }
+  normalizeMap(events).forEach(({ key, val }) => {
+    res[key] = function (...args) {
+      let dispatch = this.$storeon.dispatch
+
+      if (typeof val === 'function') {
+        return val.apply(this, [dispatch].concat(args))
+      } else {
+        return dispatch.apply(this.$storeon, [val].concat(args))
+      }
+    }
+  })
+  return res
+}
+
+module.exports = { mapState, mapDispatch }
+
+function normalizeMap (map) {
+  if (!isValidMap(map)) {
+    return []
+  }
+
+  if (Array.isArray(map)) {
+    return map.map(key => ({ key, val: key }))
+  } else {
+    return Object.keys(map).map(key => ({ key, val: map[key] }))
+  }
+}
+
+function isObject (obj) {
+  return obj !== null && typeof obj === 'object'
+}
+
+function isValidMap (map) {
+  return Array.isArray(map) || isObject(map)
+}

index.d.ts

@@ -1,3 +1,7 @@
 import _Vue from 'vue'
+import { StoreonStore } from 'storeon'
 
 export declare function StoreonVue(Vue: typeof _Vue): void
+
+export declare type StoreonVueStore<State = unknown, Events = any> =
+  StoreonStore<State, Events> & { state: State }

index.js

@@ -6,14 +6,13 @@ function StoreonVue (Vue) {
 
       if (store) {
         this.$storeon = store
-        this.$state = Vue.observable(store.get())
+        this.$storeon.state = Vue.observable(store.get())
 
         this._unbind = store.on('@changed', (_, changed) => {
-          Object.assign(this.$state, changed)
+          Object.assign(this.$storeon.state, changed)
         })
       } else if (parent && parent.$storeon) {
         this.$storeon = parent.$storeon
-        this.$state = parent.$state
       }
     },
     beforeDestroy () {

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@storeon/vue",
   "version": "0.5.0",
-  "description": "A tiny (150 bytes) connector for Storeon and Vue",
+  "description": "A tiny (160 bytes) connector for Storeon and Vue",
   "main": "index.js",
   "types": "index.d.ts",
   "scripts": {
@@ -19,6 +19,10 @@
     "url": "https://github.com/storeon/vue/issues"
   },
   "homepage": "https://github.com/storeon/vue#readme",
+  "files": [
+    "index.d.ts",
+    "helpers/"
+  ],
   "peerDependencies": {
     "storeon": "^2.0.0",
     "vue": "^2.6.0"
@@ -70,7 +74,15 @@
       "import": {
         "index.js": "{ StoreonVue }"
       },
-      "limit": "136 B"
+      "limit": "160 B"
+    },
+    {
+      "name": "core + helpers",
+      "import": {
+        "index.js": "{ StoreonVue }",
+        "helpers/index.js": "{ mapState, mapDispatch }"
+      },
+      "limit": "342 B"
     }
   ],
   "eslintConfig": {

test/helpers.test.js

@@ -0,0 +1,113 @@
+const Vue = require('vue')
+
+const { createStore } = require('./utils')
+const { StoreonVue } = require('../index')
+const { mapState, mapDispatch } = require('../helpers')
+
+it('mapState (array)', () => {
+  let store = createStore()
+  Vue.use(StoreonVue)
+  let vm = new Vue({
+    store,
+    computed: mapState(['count'])
+  })
+  expect(vm.count).toBe(0)
+  store.dispatch('inc')
+  expect(vm.count).toBe(1)
+})
+
+it('mapState (object)', () => {
+  let store = createStore()
+  Vue.use(StoreonVue)
+  let vm = new Vue({
+    store,
+    computed: mapState({
+      a: state => {
+        return state.count + 1
+      }
+    })
+  })
+  expect(vm.a).toBe(1)
+  store.dispatch('inc')
+  expect(vm.a).toBe(2)
+})
+
+it('mapState (with undefined states)', () => {
+  jest.spyOn(console, 'error')
+  let store = createStore()
+  Vue.use(StoreonVue)
+  let vm = new Vue({
+    store,
+    computed: mapState('foo')
+  })
+  expect(vm.count).toBeUndefined()
+  expect(console.error).toHaveBeenCalledWith(
+    'Mapper parameter must be either an Array or an Object'
+  )
+})
+
+it('mapDispatch (array)', () => {
+  let store = createStore()
+  jest.spyOn(store, 'dispatch')
+  Vue.use(StoreonVue)
+  let vm = new Vue({
+    store,
+    methods: mapDispatch(['inc', 'foo/set'])
+  })
+  vm.inc()
+  expect(store.dispatch).toHaveBeenCalledWith('inc')
+  expect(store.dispatch).not.toHaveBeenCalledWith('foo/set')
+  vm['foo/set']()
+  expect(store.dispatch).toHaveBeenCalledWith('foo/set')
+})
+
+it('mapDispatch (object)', () => {
+  let store = createStore()
+  jest.spyOn(store, 'dispatch')
+  Vue.use(StoreonVue)
+  let vm = new Vue({
+    store,
+    methods: mapDispatch({
+      foo: 'inc',
+      bar: 'foo/set'
+    })
+  })
+  vm.bar('bar')
+  expect(store.dispatch).toHaveBeenCalledWith('foo/set', 'bar')
+  expect(store.dispatch).not.toHaveBeenCalledWith('inc')
+  expect(vm.$storeon.state.foo).toBe('bar')
+  vm.foo()
+  expect(store.dispatch).toHaveBeenCalledWith('inc')
+})
+
+it('mapDispatch (function)', () => {
+  let store = createStore()
+  jest.spyOn(store, 'dispatch')
+  Vue.use(StoreonVue)
+  let vm = new Vue({
+    store,
+    methods: mapDispatch({
+      foo (dispatch, arg) {
+        dispatch('a', arg + 'bar')
+      }
+    })
+  })
+  vm.foo('foo')
+  expect(store.dispatch.mock.calls[0][1]).toBe('foobar')
+})
+
+it('mapDispatch (with undefined actions)', () => {
+  jest.spyOn(console, 'error')
+  let store = createStore()
+  jest.spyOn(store, 'dispatch')
+  Vue.use(StoreonVue)
+  let vm = new Vue({
+    store,
+    methods: mapDispatch('inc')
+  })
+  expect(vm.count).toBeUndefined()
+  expect(store.dispatch).not.toHaveBeenCalled()
+  expect(console.error).toHaveBeenCalledWith(
+    'Mapper parameter must be either an Array or an Object'
+  )
+})

test/index.test.js

@@ -4,7 +4,7 @@ const { mountComponent, ComponentWithChild, Child } = require('./utils')
 
 it('should render with initial state', () => {
   let { store, wrapper } = mountComponent()
-  expect(wrapper.vm.$state).toEqual(store.get())
+  expect(wrapper.vm.$storeon.state).toEqual(store.get())
 })
 
 it('should provide Storeon', () => {
@@ -21,13 +21,13 @@ it('should unsubscribe only on root destroy', () => {
   let child = wrapper.find(Child)
 
   store.dispatch('inc')
-  expect(wrapper.vm.$state.count).toBe(1)
+  expect(wrapper.vm.$storeon.state.count).toBe(1)
   child.destroy()
   store.dispatch('inc')
-  expect(wrapper.vm.$state.count).toBe(2)
+  expect(wrapper.vm.$storeon.state.count).toBe(2)
   wrapper.destroy()
   store.dispatch('inc')
-  expect(wrapper.vm.$state.count).toBe(2)
+  expect(wrapper.vm.$storeon.state.count).toBe(2)
 })
 
 it('should update view on dispatch', async () => {