Merge branch 'dev' into 4.0

Author: kiaking

docs/README.md

@@ -4,11 +4,11 @@
 
 Vuex is a **state management pattern + library** for Vue.js applications. It serves as a centralized store for all the components in an application, with rules ensuring that the state can only be mutated in a predictable fashion. It also integrates with Vue's official [devtools extension](https://github.com/vuejs/vue-devtools) to provide advanced features such as zero-config time-travel debugging and state snapshot export / import.
 
-### What is a "State Management Pattern"?
+## What is a "State Management Pattern"?
 
 Let's start with a simple Vue counter app:
 
-``` js
+```js
 new Vue({
   // state
   data () {
@@ -58,7 +58,7 @@ If you want to learn Vuex in an interactive way you can check out this [Vuex cou
 
 ![vuex](/vuex.png)
 
-### When Should I Use It?
+## When Should I Use It?
 
 Vuex helps us deal with shared state management with the cost of more concepts and boilerplate. It's a trade-off between short term and long term productivity.
 

docs/api/README.md

@@ -6,7 +6,7 @@ sidebar: auto
 
 ## Vuex.Store
 
-``` js
+```js
 import Vuex from 'vuex'
 
 const store = new Vuex.Store({ ...options })
@@ -36,7 +36,7 @@ const store = new Vuex.Store({ ...options })
 
   Register actions on the store. The handler function receives a `context` object that exposes the following properties:
 
-  ``` js
+  ```js
   {
     state,      // same as `store.state`, or local state if in modules
     rootState,  // same as `store.state`, only in modules
@@ -81,7 +81,7 @@ const store = new Vuex.Store({ ...options })
 
   An object containing sub modules to be merged into the store, in the shape of:
 
-  ``` js
+  ```js
   {
     key: {
       state,
@@ -122,7 +122,7 @@ const store = new Vuex.Store({ ...options })
 
   Turn the devtools on or off for a particular vuex instance.  For instance passing false tells the Vuex store to not subscribe to devtools plugin.  Useful for if you have multiple stores on a single page.
 
-  ``` js
+  ```js
   {
     devtools: false
   }
@@ -176,22 +176,25 @@ const store = new Vuex.Store({ ...options })
 
 -  `subscribe(handler: Function, options?: Object): Function`
 
-  Subscribe to store mutations. The `handler` is called after every mutation and receives the mutation descriptor and post-mutation state as arguments:
+  Subscribe to store mutations. The `handler` is called after every mutation and receives the mutation descriptor and post-mutation state as arguments.
 
-  ``` js
-  store.subscribe((mutation, state) => {
+  ```js
+  const unsubscribe = store.subscribe((mutation, state) => {
     console.log(mutation.type)
     console.log(mutation.payload)
   })
+
+  // you may call unsubscribe to stop the subscription
+  unsubscribe()
   ```
 
   By default, new handler is added to the end of the chain, so it will be executed after other handlers that were added before. This can be overridden by adding `prepend: true` to `options`, which will add the handler to the beginning of the chain.
 
-  ``` js
+  ```js
   store.subscribe(handler, { prepend: true })
   ```
 
-  To stop subscribing, call the returned unsubscribe function.
+  The `subscribe` method will return an `unsubscribe` function, which should be called when the subscription is no longer needed. For example, you might subscribe to a Vuex Module and unsubscribe when you unregister the module. Or you might call `subscribe` from inside a Vue Component and then destroy the component later. In these cases, you should remember to unsubscribe the subscription manually.
 
   Most commonly used in plugins. [Details](../guide/plugins.md)
 
@@ -201,28 +204,32 @@ const store = new Vuex.Store({ ...options })
 
   > New in 2.5.0
 
-  Subscribe to store actions. The `handler` is called for every dispatched action and receives the action descriptor and current store state as arguments:
+  Subscribe to store actions. The `handler` is called for every dispatched action and receives the action descriptor and current store state as arguments.
+  The `subscribe` method will return an `unsubscribe` function, which should be called when the subscription is no longer needed. For example, when unregistering a Vuex module or before destroying a Vue component.
 
-  ``` js
-  store.subscribeAction((action, state) => {
+  ```js
+  const unsubscribe = store.subscribeAction((action, state) => {
     console.log(action.type)
     console.log(action.payload)
   })
+
+  // you may call unsubscribe to stop the subscription
+  unsubscribe()
   ```
 
   By default, new handler is added to the end of the chain, so it will be executed after other handlers that were added before. This can be overridden by adding `prepend: true` to `options`, which will add the handler to the beginning of the chain.
 
-  ``` js
+  ```js
   store.subscribeAction(handler, { prepend: true })
   ```
 
-  To stop subscribing, call the returned unsubscribe function.
+  The `subscribeAction` method will return an `unsubscribe` function, which should be called when the subscription is no longer needed. For example, you might subscribe to a Vuex Module and unsubscribe when you unregister the module. Or you might call `subscribeAction` from inside a Vue Component and then destroy the component later. In these cases, you should remember to unsubscribe the subscription manually.
 
   > New in 3.1.0
 
   Since 3.1.0, `subscribeAction` can also specify whether the subscribe handler should be called *before* or *after* an action dispatch (the default behavior is *before*):
 
-  ``` js
+  ```js
   store.subscribeAction({
     before: (action, state) => {
       console.log(`before action ${action.type}`)
@@ -237,7 +244,7 @@ const store = new Vuex.Store({ ...options })
 
   Since 3.4.0, `subscribeAction` can also specify an `error` handler to catch an error thrown when an action is dispatched. The function will receive an `error` object as the third argument.
 
-  ``` js
+  ```js
   store.subscribeAction({
     error: (action, state, error) => {
       console.log(`error action ${action.type}`)

docs/guide/README.md

@@ -8,15 +8,17 @@ At the center of every Vuex application is the **store**. A "store" is basically
 
 2. You cannot directly mutate the store's state. The only way to change a store's state is by explicitly **committing mutations**. This ensures every state change leaves a track-able record, and enables tooling that helps us better understand our applications.
 
-### The Simplest Store
+## The Simplest Store
 
 :::tip NOTE
 We will be using ES2015 syntax for code examples for the rest of the docs. If you haven't picked it up, [you should](https://babeljs.io/docs/learn-es2015/)!
 :::
 
 After [installing](../installation.md) Vuex, let's create a store. It is pretty straightforward - just provide an initial state object, and some mutations:
 
-``` js
+### Vuex 3.x (for Vue 2)
+
+```js
 import Vue from 'vue'
 import Vuex from 'vuex'
 
@@ -34,17 +36,35 @@ const store = new Vuex.Store({
 })
 ```
 
+### Vuex 4.x (for Vue 3)
+
+```js
+import { createStore } from 'vuex'
+import { createApp } from 'vue'
+
+const store = createStore({
+  state () {
+    return {
+      count: 1
+    }
+  }
+})
+
+const app = createApp({ /* your root component */ })
+app.use(store)
+```
+
 Now, you can access the state object as `store.state`, and trigger a state change with the `store.commit` method:
 
-``` js
+```js
 store.commit('increment')
 
 console.log(store.state.count) // -> 1
 ```
 
 In order to have an access to `this.$store` property in your Vue components, you need to provide the created store to Vue instance. Vuex has a mechanism to "inject" the store into all child components from the root component with the `store` option:
 
-``` js
+```js
 new Vue({
   el: '#app',
   store: store,
@@ -64,7 +84,7 @@ new Vue({
 
 Now we can commit a mutation from component's method:
 
-``` js
+```js
 methods: {
   increment() {
     this.$store.commit('increment')

docs/guide/actions.md

@@ -39,7 +39,7 @@ actions: {
 }
 ```
 
-### Dispatching Actions
+## Dispatching Actions
 
 Actions are triggered with the `store.dispatch` method:
 
@@ -98,7 +98,7 @@ actions: {
 
 Note we are performing a flow of asynchronous operations, and recording the side effects (state mutations) of the action by committing them.
 
-### Dispatching Actions in Components
+## Dispatching Actions in Components
 
 You can dispatch actions in components with `this.$store.dispatch('xxx')`, or use the `mapActions` helper which maps component methods to `store.dispatch` calls (requires root `store` injection):
 
@@ -121,7 +121,7 @@ export default {
 }
 ```
 
-### Composing Actions
+## Composing Actions
 
 Actions are often asynchronous, so how do we know when an action is done? And more importantly, how can we compose multiple actions together to handle more complex async flows?
 

docs/guide/forms.md

@@ -15,6 +15,7 @@ The "Vuex way" to deal with it is binding the `<input>`'s value and call a metho
 ``` html
 <input :value="message" @input="updateMessage">
 ```
+
 ``` js
 // ...
 computed: {
@@ -40,13 +41,14 @@ mutations: {
 }
 ```
 
-### Two-way Computed Property
+## Two-way Computed Property
 
 Admittedly, the above is quite a bit more verbose than `v-model` + local state, and we lose some of the useful features from `v-model` as well. An alternative approach is using a two-way computed property with a setter:
 
 ``` html
 <input v-model="message">
 ```
+
 ``` js
 // ...
 computed: {

docs/guide/getters.md

@@ -34,7 +34,7 @@ const store = new Vuex.Store({
 })
 ```
 
-### Property-Style Access
+## Property-Style Access
 
 The getters will be exposed on the `store.getters` object, and you access values as properties:
 
@@ -69,7 +69,7 @@ computed: {
 
 Note that getters accessed as properties are cached as part of Vue's reactivity system.
 
-### Method-Style Access
+## Method-Style Access
 
 You can also pass arguments to getters by returning a function. This is particularly useful when you want to query an array in the store:
 
@@ -88,7 +88,7 @@ store.getters.getTodoById(2) // -> { id: 2, text: '...', done: false }
 
 Note that getters accessed via methods will run each time you call them, and the result is not cached.
 
-### The `mapGetters` Helper
+## The `mapGetters` Helper
 
 The `mapGetters` helper simply maps store getters to local computed properties: