Kdux

API Reference

Store

createStore

  • createStore<S>(options: StoreOptions<S>): Store<S>

    Creates a new store.

    import { createStore } from 'kdux'

const store = createStore({ ...options })

Store Constructor Options

state

  • type: Object | Function

    The root state object for the Kdux store. Details

    If you pass a function that returns an object, the returned object is used as the root state. This is useful when you want to reuse the state object especially for module reuse. Details

mutations

  • type: { [type: string]: Function }

    Register mutations on the store. The handler function always receives state as the first argument (will be module local state if defined in a module), and receives a second payload argument if there is one.

    Details

actions

  • type: { [type: string]: Function }

    Register actions on the store. The handler function receives a context object that exposes the following properties:

    {
  state,      // same as `store.state`, or local state if in modules
  rootState,  // same as `store.state`, only in modules
  commit,     // same as `store.commit`
  dispatch,   // same as `store.dispatch`
  getters,    // same as `store.getters`, or local getters if in modules
  rootGetters // same as `store.getters`, only in modules
}

    And also receives a second payload argument if there is one.

    Details

getters

  • type: { [key: string]: Function }

    Register getters on the store. The getter function receives the following arguments:

    state,     // will be module local state if defined in a module.
getters    // same as store.getters

    Specific when defined in a module

    state,       // will be module local state if defined in a module.
getters,     // module local getters of the current module
rootState,   // global state
rootGetters  // all getters

    Registered getters are exposed on store.getters.

    Details

modules

  • type: Object

    An object containing sub modules to be merged into the store, in the shape of:

    {
  key: {
    state,
    namespaced?,
    mutations?,
    actions?,
    getters?,
    modules?
  },
  ...
}

    Each module can contain state and mutations similar to the root options. A module's state will be attached to the store's root state using the module's key. A module's mutations and getters will only receives the module's local state as the first argument instead of the root state, and module actions' context.state will also point to the local state.

    Details

plugins

  • type: Array<Function>

    An array of plugin functions to be applied to the store. The plugin simply receives the store as the only argument and can either listen to mutations (for outbound data persistence, logging, or debugging) or dispatch mutations (for inbound data e.g. websockets or observables).

    Details

strict

  • type: boolean

  • default: false

    Force the Kdux store into strict mode. In strict mode any mutations to Kdux state outside of mutation handlers will throw an Error.

    Details

devtools

  • type: boolean

    Turn the devtools on or off for a particular Kdux instance. For instance, passing false tells the Kdux store to not subscribe to devtools plugin. Useful when you have multiple stores on a single page.

    {
  devtools: false
}

Store Instance Properties

state

  • type: Object

    The root state. Read only.

getters

  • type: Object

    Exposes registered getters. Read only.

Store Instance Methods

commit

  • commit(type: string, payload?: any, options?: Object)
  • commit(mutation: Object, options?: Object)

Commit a mutation. options can have root: true that allows to commit root mutations in namespaced modules. Details

dispatch

  • dispatch(type: string, payload?: any, options?: Object): Promise<any>
  • dispatch(action: Object, options?: Object): Promise<any>

Dispatch an action. options can have root: true that allows to dispatch root actions in namespaced modules. Returns a Promise that resolves all triggered action handlers. Details

replaceState

  • replaceState(state: Object)

Replace the store's root state. Use this only for state hydration / time-travel purposes.

watch

  • watch(fn: Function, callback: Function, options?: Object): Function

Reactively watch fn's return value, and call the callback when the value changes. fn receives the store's state as the first argument, and getters as the second argument. Accepts an optional options object that takes the same options as Kdu's vm.$watch method.

To stop watching, call the returned unwatch function.

subscribe

  • 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.

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.

store.subscribe(handler, { prepend: true })

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 Kdux Module and unsubscribe when you unregister the module. Or you might call subscribe from inside a Kdu Component and then destroy the component later. In these cases, you should remember to unsubscribe the subscription manually.

Most commonly used in plugins. Details

subscribeAction

  • subscribeAction(handler: Function, options?: Object): Function

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 Kdux module or before destroying a Kdu component.

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.

store.subscribeAction(handler, { prepend: true })

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 Kdux Module and unsubscribe when you unregister the module. Or you might call subscribeAction from inside a Kdu Component and then destroy the component later. In these cases, you should remember to unsubscribe the subscription manually.

subscribeAction can also specify whether the subscribe handler should be called before or after an action dispatch (the default behavior is before):

store.subscribeAction({
  before: (action, state) => {
    console.log(`before action ${action.type}`)
  },
  after: (action, state) => {
    console.log(`after action ${action.type}`)
  }
})

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.

store.subscribeAction({
  error: (action, state, error) => {
    console.log(`error action ${action.type}`)
    console.error(error)
  }
})

The subscribeAction method is most commonly used in plugins. Details

registerModule

  • registerModule(path: string | Array<string>, module: Module, options?: Object)

Register a dynamic module. Details

options can have preserveState: true that allows to preserve the previous state. Useful with Server Side Rendering.

unregisterModule

  • unregisterModule(path: string | Array<string>)

Unregister a dynamic module. Details

hasModule

  • hasModule(path: string | Array<string>): boolean

    Check if the module with the given name is already registered. Details

hotUpdate

  • hotUpdate(newOptions: Object)

Hot swap new actions and mutations. Details

Component Binding Helpers

mapState

  • mapState(namespace?: string, map: Array<string> | Object<string | function>): Object

Create component computed options that return the sub tree of the Kdux store. Details

The first argument can optionally be a namespace string. Details

The second object argument's members can be a function. function(state: any)

mapGetters

  • mapGetters(namespace?: string, map: Array<string> | Object<string>): Object

Create component computed options that return the evaluated value of a getter. Details

The first argument can optionally be a namespace string. Details

mapActions

  • mapActions(namespace?: string, map: Array<string> | Object<string | function>): Object

Create component methods options that dispatch an action. Details

The first argument can optionally be a namespace string. Details

The second object argument's members can be a function. function(dispatch: function, ...args: any[])

mapMutations

  • mapMutations(namespace?: string, map: Array<string> | Object<string | function>): Object

Create component methods options that commit a mutation. Details

The first argument can optionally be a namespace string. Details

The second object argument's members can be a function. function(commit: function, ...args: any[])

createNamespacedHelpers

  • createNamespacedHelpers(namespace: string): Object

Create namespaced component binding helpers. The returned object contains mapState, mapGetters, mapActions and mapMutations that are bound with the given namespace. Details

Composable Functions

useStore

  • useStore<S = any>(injectKey?: InjectionKey<Store<S>> | string): Store<S>;

    Fetches the injected store when called inside the setup hook. When using the Composition API, you can retrieve the store by calling this method.

    import { useStore } from 'kdux'

export default {
  setup () {
    const store = useStore()
  }
}

    TypeScript users can use an injection key to retrieve a typed store. In order for this to work, you must define the injection key and pass it along with the store when installing the store instance to the Kdu app.

    First, declare the injection key using Kdu's InjectionKey interface.

    // store.ts
import { InjectionKey } from 'kdu'
import { createStore, Store } from 'kdux'

export interface State {
  count: number
}

export const key: InjectionKey<Store<State>> = Symbol()

export const store = createStore<State>({
  state: {
    count: 0
  }
})

    Then, pass the defined key as the second argument for the app.use method.

    // main.ts
import { createApp } from 'kdu'
import { store, key } from './store'

const app = createApp({ ... })

app.use(store, key)

app.mount('#app')

    Finally, you can pass the key to the useStore method to retrieve the typed store instance.

    // in a kdu component
import { useStore } from 'kdux'
import { key } from './store'

export default {
  setup () {
    const store = useStore(key)

    store.state.count // typed as number
  }
}