Kdux

# Mutations

The only way to actually change state in a Kdux store is by committing a mutation. Kdux mutations are very similar to events: each mutation has a string type and a handler. The handler function is where we perform actual state modifications, and it will receive the state as the first argument:

const store = new Kdux.Store({
  state: {
    count: 1
  },
  mutations: {
    increment (state) {
      // mutate state
      state.count++
    }
  }
})

You cannot directly call a mutation handler. Think of it more like event registration: "When a mutation with type increment is triggered, call this handler." To invoke a mutation handler, you need to call store.commit with its type:

store.commit('increment')

# Commit with Payload

You can pass an additional argument to store.commit, which is called the payload for the mutation:

// ...
mutations: {
  increment (state, n) {
    state.count += n
  }
}

store.commit('increment', 10)

In most cases, the payload should be an object so that it can contain multiple fields, and the recorded mutation will also be more descriptive:

// ...
mutations: {
  increment (state, payload) {
    state.count += payload.amount
  }
}

store.commit('increment', {
  amount: 10
})

# Object-Style Commit

An alternative way to commit a mutation is by directly using an object that has a type property:

store.commit({
  type: 'increment',
  amount: 10
})

When using object-style commit, the entire object will be passed as the payload to mutation handlers, so the handler remains the same:

mutations: {
  increment (state, payload) {
    state.count += payload.amount
  }
}

# Mutations Follow Kdu's Reactivity Rules

Since a Kdux store's state is made reactive by Kdu, when we mutate the state, Kdu components observing the state will update automatically. This also means Kdux mutations are subject to the same reactivity caveats when working with plain Kdu:

  1. Prefer initializing your store's initial state with all desired fields upfront.

  2. When adding new properties to an Object, you should either:

  • Use Kdu.set(obj, 'newProp', 123), or

  • Replace that Object with a fresh one. For example, using the object spread syntax (opens new window) we can write it like this:

    state.obj = { ...state.obj, newProp: 123 }

# Using Constants for Mutation Types

It is a commonly seen pattern to use constants for mutation types in various Flux implementations. This allows the code to take advantage of tooling like linters, and putting all constants in a single file allows your collaborators to get an at-a-glance view of what mutations are possible in the entire application:

// mutation-types.js
export const SOME_MUTATION = 'SOME_MUTATION'

// store.js
import Kdux from 'kdux'
import { SOME_MUTATION } from './mutation-types'

const store = new Kdux.Store({
  state: { ... },
  mutations: {
    // we can use the ES2015 computed property name feature
    // to use a constant as the function name
    [SOME_MUTATION] (state) {
      // mutate state
    }
  }
})

Whether to use constants is largely a preference - it can be helpful in large projects with many developers, but it's totally optional if you don't like them.

# Mutations Must Be Synchronous

One important rule to remember is that mutation handler functions must be synchronous. Why? Consider the following example:

mutations: {
  someMutation (state) {
    api.callAsyncMethod(() => {
      state.count++
    })
  }
}

Now imagine we are debugging the app and looking at the devtool's mutation logs. For every mutation logged, the devtool will need to capture a "before" and "after" snapshots of the state. However, the asynchronous callback inside the example mutation above makes that impossible: the callback is not called yet when the mutation is committed, and there's no way for the devtool to know when the callback will actually be called - any state mutation performed in the callback is essentially un-trackable!

# Committing Mutations in Components

You can commit mutations in components with this.$store.commit('xxx'), or use the mapMutations helper which maps component methods to store.commit calls (requires root store injection):

import { mapMutations } from 'kdux'

export default {
  // ...
  methods: {
    ...mapMutations([
      'increment', // map `this.increment()` to `this.$store.commit('increment')`

      // `mapMutations` also supports payloads:
      'incrementBy' // map `this.incrementBy(amount)` to `this.$store.commit('incrementBy', amount)`
    ]),
    ...mapMutations({
      add: 'increment' // map `this.add()` to `this.$store.commit('increment')`
    })
  }
}

# On to Actions

Asynchronicity combined with state mutation can make your program very hard to reason about. For example, when you call two methods both with async callbacks that mutate the state, how do you know when they are called and which callback was called first? This is exactly why we want to separate the two concepts. In Kdux, mutations are synchronous transactions:

store.commit('increment')
// any state change that the "increment" mutation may cause
// should be done at this moment.

To handle asynchronous operations, let's introduce Actions.

← Actions →