Vuex: Important confusing detail in Action doc

[EMHmark7]

Hi,
Trying to understand the doc for starting a project ASAP, and working first on a visual version of the doc.
Action syntax is confusing (even if we know ES6 destructuring) and it would be good to describe in words what is going on.

EX1) export const incrementCounter = //two first example in the doc
function ({ dispatch, state }) { dispatch('INCREMENT', 1) }

EX2) function increment (store) { store.dispatch('INCREMENT') } //Action section

EX3) function incrementBy ({ dispatch }, amount) { dispatch('INCREMENT', amount) } //Action section

//1EX1:
Doc says: Actions receive the store as first!! arg.
If only interested in the dispatch (and optionally the state) we can pull those two parameters using ES6 destructuring feature. (what is explained, nor the used syntax are not clear)

//EX2: OK

//EX3:
What is {dispatch} argument?
Any different than the state arg in first ex?
Why object syntax?
Here, no store passed!
To compare with EX1

In Shopping cart example (Actions section) and other vue.js examples, what's the point of declaring everything as const?

In same cart example, what does [... refer to? (3 dots) is it ES6, JS, other preprocessor?

Finaly, would be nice if a contributor can review my visual document, I would provide a google doc link because problems uploading PDFs here. The original is in OpenOffice Draw.

Thanks

[LinusBorg]

If you don't understand how ES6 argument destructuring works (which is ok, it's still new syntax), you should google it or ask about it on the forum.

We will not explain Javascript syntax/features in the vuex docs.

That being said:

This:

function increment (store) {
  store.dispatch('INCREMENT')
}

is the same as this:

function increment ({ dispatch }) {
  dispatch('INCREMENT')
}

With the {dispatch} we destrcture the incoming store object and only extract its dispatch property.

Example 3 is the same thing. There's no object syntax. it's ES6 argument destructuring like in the first example..

In same cart example, what does [... refer to? (3 dots) is it ES6, JS, other preprocessor?

Can you be more specific about what part of the code you refer to? Just link to the line in the repo.

[LinusBorg]

In same cart example, what does [... refer to? (3 dots) is it ES6, JS, other preprocessor?

I assume you refer to this line: https://github.com/vuejs/vuex/blob/master/examples/shopping-cart/vuex/actions.js#L11

This is called the spread operator. It's ES6: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Operators/Spread_operator

[EMHmark7]

About [..., in http://vuex.vuejs.org/en/actions.html in 3rd code snippet. Refers to ES6 Rest Operator. If we are not aware of it (now I am! : ) it is difficult to figure out or google it. The rest of your comments helped things make sense. A part of confusion comes from parameters that are injected behind the scene by vuex in action calls.

[LinusBorg]

A part of confusion comes from parameters that are injected behind the scene by vuex in action calls.

For example?

[EMHmark7]

The reader does not know the whole structure of a Vuex.Store, what's in it (before starting to use it).
Then in http://vuex.vuejs.org/en/tutorial.html
Vuex: { actions: { increment: incrementCounter } }
incrementCounter does several things behind the scene, such as providing the called action with Store object (that includes dispatch method and state). Same thing for dispatch('INCREMENT',1) that injects state in the call to INCREMENT.

Such thing is also revealed in the example of actions having an inline call http://vuex.vuejs.org/en/actions.html showing that normally, in a hidden way, the store is injected:
actions: { plus: ({ dispatch }) => dispatch('INCREMENT')

Then, in http://vuex.vuejs.org/en/actions.html
we get caller's and callee's parameters, were watch appears as a new element of Store.:
export const caller = ({dispatch, state, watch}) => { dispatch('MUTATION_1') callee({state, watch})

Conclusion: It would be cleared to explain store structure, and why things are done the way they are done, helping understand right away.

With the new destructuring syntax, it is good to know the intend of using it for those not having it as a usual tool. Here, I suppose, is for shortening the dispatch instruction (such as store.dispatch()). Once it is used for this, we had to destructure state and watch as well, which is why we cannot use just store in callee() call, but still work because state and watch are the parts that were really need to be present (rather than the whole store).

One thing I am puzzled about the doc (with my actual non deep level of knowledge of JS) is why things are declared with constants. I suppose it is because their content is just used at init time for building necessary objects. Or the constant is just for the pointer to the object, but not its content.

The only thing in the doc that remains to understand in vuex doc is in Action section, it is somehow too synthetic:

Note that instead of expecting returns values or passing callbacks to actions, the result of calling the async API is handled by dispatching mutations as well. The rule of thumb is that the only side effects produced by calling actions should be dispatched mutations.

Here is my visual version of the doc: https://drive.google.com/open?id=0B_kQr3l7tmlWX2ZMUWgwal93SFE

Comments/suggestions welcome. Let me know if it can be posted on official doc page.

[EMHmark7]

I see there are some ? remaining in my doc...

[LinusBorg]

The reader does not know the whole structure of a Vuex.Store, what's in it (before starting to use it).
Then in http://vuex.vuejs.org/en/tutorial.html
vuex: { actions: { increment: incrementCounter } }
incrementCounter does several things behind the scene, such as providing the called action with Store object (that includes dispatch method and state). Same thing for dispatch('INCREMENT',1) that injects state in the call to INCREMENT.

Nothing happens "behind the scenes", it's explained _right there in the docs_:

// An action will receive the store as the first argument.
// Since we are only interested in the dispatch (and optionally the state)
// we can pull those two parameters using the ES6 destructuring feature

export const incrementCounter = function ({ dispatch, state }) {
 dispatch('INCREMENT', 1)
}

...and it goes into more detail from there on.

If an explanation like this is nor enough for you, you might have to deepen your knowledge of Javascript itself before trying to use an advanced library like vuex.