vuex-module-toolkit

A toolkit to create typesafe modules, getters, mutations and actions

Mutations

TBD (but pretty much the same as actions below)

Actions

Creating

Either via factory:

1const actionFactory = actionBuilderFactory<ModuleState, RootState>()
2
3const increaseAction = actionFactory.generate<{ amount: number }, number>("increase", (
4    actionContext /* ActionContext<ModuleState, RootState> */, 
5    event /* { amount: number } */
6) => {
7    /* ... */
8})

Or with a simple builder:

1const increaseAction = actionBuilder<{ amount: number }, ModuleState, RootState, number>("increase", (
2    actionContext /* ActionContext<ModuleState, RootState> */, 
3    event /* { amount: number } */
4) => {
5    /* ... */
6})

Factory vs Builder

If you plan to create multiple actions for one module it is advised to use a factory over a builder. Every time actionFactory.generate is called the generated action is returned and also cached in the factory itself.

By calling actionFactory.toActionTree() an action tree is returned which can be used in every vuex store/module.

Dispatch without namespace

There are multiple ways to use your actions after creation. Given the above creation (factory and builder return the functionally same):

1// via typed function call into a store.dispatch
2store.dispatch(increaseAction({ amount: 42 }))
3
4// via action.dispatch with the store as first argument
5increaseAction.dispatch(store, { amount: 42 })

Dispatch with namespace prefix

If you need to dispatch your actions into a specific namespace (without the type) you can also dispatch the actions directly to namespaces. All the examples below are equivalents to store.dispatch("foo/bar/increase", { amount: 42 }):

1// forcing to a specific namespace via typed function call into a store.dispatch
2store.dispatch(increaseAction({ amount: 42 }, { namespace: "foo/bar" }))
3
4// by making use of the default namespaceBuilder and a custom helper `namespaced()`
5// note that this call uses the namespaceBuilder provided on action creation
6store.dispatch(increaseAction.namespaced("foo/bar", { amount: 42 }))
7
8// via action.dispatchNamepsaced
9// store as arguments and namespace builder arguments (see below) as arguments
10// note that this call uses the namespaceBuilder provided on action creation
11increaseAction.dispatchNamespaced(store, "foo/bar", { amount: 42 })

Non-reusable Modules

Readme is TBD. Use moduleBuilderFactory without namespaceBuilder (see below) and constructor args. Then create and export something like:

1type ModuleState = { value: number }
2
3const myModuleBuilder = moduleBuilderFactory<ModuleState, RootState>({
4    state: () => ({ value: 0 }) // return type is the generic ModuleState
5})
6
7// calls an actionBuilderFactory internally and has the same signature as actionBuilderFactory.generate
8myModule.addAction(/* ... */)
9
10// calls a mutationBuilderFactory internally and has the same signature as mutationBuilderFactory.generate
11myModule.addMutation(/* ... */)
12
13// calling getModule() will automatically use all actions and mutations defined via addAction and addMutation
14export const myModule = myModuleBuilder.getModule()

Reusable Modules

Readme is TBD. Use moduleBuilderFactory and define a namespaceBuilder (see below). Also make good use of the constructorArgs type.

1type ModuleState = { value: number }
2type ConstructorArgs = { initialValue: number }
3type NamespaceArgs = { entityId: string }
4
5export const myModuleBuilderFactory = moduleBuilderFactory<ModuleState, RootState, ConstructorArgs, NamespaceArgs>({
6    state: (constructorArgs /* ConstructorArgs */) => ({ value: constructorArgs.initialValue }),
7    namespaceBuilder: (nsArgs /* NamespaceArgs */) => "foo/" + nsArgs.entityId
8})
9
10// calls an actionBuilderFactory internally and has the same signature as actionBuilderFactory.generate
11myModule.addAction(/* ... */)
12
13// calls a mutationBuilderFactory internally and has the same signature as mutationBuilderFactory.generate
14myModule.addMutation(/* ... */)

After creating and exporting a factory like so, you can dynamically register and unregister modules to your store using your moduleBuilderFactory - super type safe and with the help of the namespaceBuilder also reliably addressable with action.namespaced et al.

1// register an instance of the previously defined module to the store
2myModuleBuilderFactory.register(store, constructorArgs /* ConstructorArgs */, nsArgs /* NamespaceArgs */)
3
4// unregister under a given namespace - again making use of the namespaceBuilder
5// we only need NamespaceArgs because the constructorArgs are only relevant to the initial state
6myModuleBuilderFactory.unregister(store, nsArgs /* NamespaceArgs */)

NamespaceBuilder

Upon creation of a factory or builder instance (i.e. actionBuilder, actionBuilderFactory, mutationBuilder, mutationBuilderFactory, ) you can provide an optional namespaceBuilder. The default is args => `${args}` .

The provided namespaceBuilder will be called with the arguments provided during

• action.namespaced
• action.dispatchNamespaced
• mutation.namespaced
• mutation.dispatchNamespaced
• module.register

Here are some examples:

store.dispatch("foo/bar/baz", 42)

Equivalents:

With an actionBuilder:

1// do note the third generic which is typing the namespaceBuilder arguments
2const bazAction = actionBuilder<number, ModuleState, RootState, string>(
3    "baz", 
4    () => { /*...*/ }, { 
5    namespaceBuilder: nsArgs => `foo/${nsArgs}`
6})
7
8// every argument is typed by actionBuilder's generics
9store.dispatch(bazAction.namespaced("bar", 42))
10// <=>
11bazAction.dispatchNamespaced(store, "bar", 42)

With an actionBuilderFactory:

1const actionFactory = actionBuilderFactory<ModuleState, RootState>({
2    namespaceBuilder: nsArgs => `foo/${nsArgs}`
3})
4
5// the action receives the namespaceBuilder from the factory
6// hence all actions created with this factory instance will share the same namespace builder and typings
7const bazAction = actionFactory.generate<number>("baz", () => { /*...*/ })
8
9store.dispatch(bazAction.namespaced("bar", 42))
10// <=>
11bazAction.dispatchNamespaced(store, "bar", 42)

Calling typed Mutations and Actions from Actions

Due to the flexibility in namespacing we can combine mutations and actions within the same module without namespace and call the actions and mutations outside the module with namespace (explained in the section above).

1const increaseByMutation = mutationBuilder<number, ModuleState>("INCREASE_BY", (state, newValue) => { 
2    state.value = newValue
3})
4
5const increaseByAction = actionBuilder<number, ModuleState, RootState, string>(
6    "baz",
7    ({ commit }, event) => { 
8        const newValue = event.payload
9        
10        /* do something regarding your business logic, asynchronous calls, other dispatches, etc. */
11        
12        // call your mutation with typed arguments and no namespace
13        // this is the typed equivalent to `commit("INCREASE_BY", newValue)`
14        commit(increaseByMutation(newValue))
15    }
16)
17