Merge pull request vuejs#53 from blake-newman/feature/implement-getters-into-store

Feature/implement getters into store

Author: yyx990803

docs/en/SUMMARY.md

@@ -5,6 +5,7 @@
   - [State](state.md)
   - [Mutations](mutations.md)
   - [Actions](actions.md)
+  - [Getters](getters.md)
 - [Data Flow](data-flow.md)
 - [Application Structure](structure.md)
 - [Middlewares](middlewares.md)

docs/en/api.md

@@ -11,7 +11,7 @@ const store = new Vuex.Store({ ...options })
 ### Vuex.Store Constructor Options
 
 - **state**
-  
+
   - type: `Object`
 
     The root state object for the Vuex store.
@@ -43,6 +43,19 @@ const store = new Vuex.Store({ ...options })
 
     [Details](actions.md)
 
+
+- **getters**
+
+  - type: `Object | Array<Object>`
+
+    An object where each entry's key is the getter name and the value of a function which will receive the state as the first argument.
+
+    Vuex will process these entries and create the actual callable getter functions and expose them on the `getters` property of the store.
+
+    If passing in an Array of Objects, these objects will be automatically merged together into one final object.
+
+    [Details](getters.md)
+
 - **middlewares**
 
   - type: `Array<Object>`

docs/en/concepts.md

@@ -8,6 +8,8 @@ You can use the `Vuex.Store` constructor to create Vuex stores. In most cases, y
 
 - **Actions**: Functions that dispatch mutations. An action can contain asynchronous operations and can dispatch multiple mutations.
 
+- **Getters**: Functions that receive state to return a computed value. Useful for extracting shared computed functions from Vue components.
+
 Why do we differentiate between *mutations* and *actions*, rather then just simple functions that manipulate the state however we want? The reason is because we want to **separate mutation and asynchronicity**. A lot of application complexity roots from the combination of the two. When separated, they both become easier to reason about and write tests for.
 
 > If you are familiar with Flux, note there's a term/concept difference here: Vuex mutations are the equivalent of Flux **actions**, while Vuex actions are equivalent to Flux **action creators**.
@@ -24,8 +26,9 @@ import Vuex from 'vuex'
 const store = new Vuex.Store({
   state: { ... },
   actions: { ... },
-  mutations: { ... }
+  mutations: { ... },
+  getters: { ... }
 })
 ```
 
-Once created, you can access the state via `store.state`, and the actions via `store.actions`. You cannot directly access the mutation functions - they can only be triggered by actions or calling `store.dispatch()`. We will discuss each concept in more details next.
+Once created, you can access the state via `store.state`, the actions via `store.actions` and the getters though `store.getters`. You cannot directly access the mutation functions - they can only be triggered by actions or calling `store.dispatch()`. We will discuss each concept in more details next.

docs/en/getters.md

@@ -0,0 +1,46 @@
+# Getters
+
+It's possible that multiple components will need the same computed property based on Vuex state. Since computed getters are just functions, you can split them out into a separate file so that they can be shared in any component via the store:
+
+``` js
+import Vue from 'vue'
+import Vuex from '../../../src'
+import actions from './actions'
+import mutations from './mutations'
+import getters from './getters'
+
+Vue.use(Vuex)
+
+export default new Vuex.Store({
+  state: { /*...*/ },
+  actions,
+  mutations,
+  getters
+})
+```
+
+``` js
+// getters.js
+export function filteredTodos (state) {
+  return state.messages.filter(message => {
+    return message.threadID === state.currentThreadID
+  })
+}
+```
+
+``` js
+// in a component...
+import { getters } from './store'
+const { filteredTodos } = getters
+
+export default {
+  computed: {
+    filteredTodos
+  }
+}
+
+For an actual example, check out the [Shopping Cart Example](https://github.com/vuejs/vuex/tree/master/examples/shopping-cart).
+For an actual example with hot reload API, check out the [Counter Hot Example](https://github.com/vuejs/vuex/tree/master/examples/counter-hot).
+
+
+This is very similar to [Getters in NuclearJS](https://optimizely.github.io/nuclear-js/docs/04-getters.html).

docs/en/structure.md

@@ -106,28 +106,9 @@ For an actual example, check out the [Shopping Cart Example](https://github.com/
 
 ### Extracting Shared Computed Getters
 
-In large projects, it's possible that multiple components will need the same computed property based on Vuex state. Since computed getters are just functions, you can split them out into a separate file so that they can be shared in any component:
+In large projects, it's possible that multiple components will need the same computed property based on Vuex state. Since computed getters are just functions, you can split them out into a separate file so that they can be shared in any component via the store:
 
-``` js
-// getters.js
-import store from './store'
-
-export function filteredTodos () {
-  return store.state.messages.filter(message => {
-    return message.threadID === store.state.currentThreadID
-  })
-}
-```
-
-``` js
-// in a component...
-import { filteredTodos } from './getters'
-
-export default {
-  computed: {
-    filteredTodos
-  }
-}
-```
+For an actual example, check out the [Shopping Cart Example](https://github.com/vuejs/vuex/tree/master/examples/shopping-cart).
+For an actual example with hot reload API, check out the [Counter Hot Example](https://github.com/vuejs/vuex/tree/master/examples/counter-hot).
 
-This is very similar to [Getters in NuclearJS](https://optimizely.github.io/nuclear-js/docs/04-getters.html).
+For more information, check out the [Getters documentation](getters.md)

examples/counter-hot/Counter.vue

@@ -1,22 +1,26 @@
 <template>
   <div>
-    Clicked: {{ count }} times
+    Value: {{ count }}
     <button @click="increment">+</button>
     <button @click="decrement">-</button>
     <button @click="incrementIfOdd">Increment if odd</button>
     <button @click="incrementAsync">Increment async</button>
+    <div>
+      <div>Recent History: {{recentHistory}}</div>
+    </div>
   </div>
 </template>
 
 <script>
 import store from './store'
-
 export default {
   computed: {
     count () {
       return store.state.count
-    }
+    },
+    recentHistory: store.getters.recentHistory
   },
   methods: store.actions
+
 }
 </script>

examples/counter-hot/store/getters.js

@@ -0,0 +1,10 @@
+export default {
+  recentHistory (state) {
+    const end = state.history.length
+    const begin = end - 5 < 0 ? 0 : end - 5
+    return state.history
+      .slice(begin, end)
+      .toString()
+      .replace(/,/g, ', ')
+  }
+}

examples/counter-hot/store/index.js

@@ -2,26 +2,31 @@ import Vue from 'vue'
 import Vuex from '../../../src'
 import actions from './actions'
 import mutations from './mutations'
+import getters from './getters'
 
 Vue.use(Vuex)
 
 const state = {
-  count: 0
+  count: 0,
+  history: []
 }
 
 const store = new Vuex.Store({
   state,
   actions,
-  mutations
+  mutations,
+  getters
 })
 
 if (module.hot) {
-  module.hot.accept(['./actions', './mutations'], () => {
+  module.hot.accept(['./actions', './mutations', './getters'], () => {
     const newActions = require('./actions').default
     const newMutations = require('./mutations').default
+    const newGetters = require('./getters').default
     store.hotUpdate({
       actions: newActions,
-      mutations: newMutations
+      mutations: newMutations,
+      getters: newGetters
     })
   })
 }

examples/counter-hot/store/mutations.js

@@ -3,8 +3,10 @@ import { INCREMENT, DECREMENT } from './mutation-types'
 export default {
   [INCREMENT] (state) {
     state.count++
+    state.history.push('increment')
   },
   [DECREMENT] (state) {
     state.count--
+    state.history.push('decrement')
   }
 }

examples/shopping-cart/components/Cart.vue

@@ -19,16 +19,7 @@ const { checkout } = store.actions
 
 export default {
   computed: {
-    products () {
-      return store.state.cart.added.map(({ id, quantity }) => {
-        const product = store.state.products.find(p => p.id === id)
-        return {
-          title: product.title,
-          price: product.price,
-          quantity
-        }
-      })
-    },
+    products: store.getters.cartProducts,
     checkoutStatus () {
       return store.state.cart.lastCheckout
     },