# safer-vuex

> Type-safe wrapper for vuex.

Latest version **0.0.0** (published 2018-08-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install safer-vuex
pnpm add safer-vuex
yarn add safer-vuex
bun add safer-vuex
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.0 |
| Published | 2018-08-29 |
| First published | 2018-08-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 33.4 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | Zeljko Brckovic |
| Maintainers | zeljkobrckovic |
| Keywords | vue, vuex, typescript |

## Links

- npm: https://www.npmjs.com/package/safer-vuex
- Repository: https://github.com/ZeljkoBrckovic/safer-vuex
- Issues: https://github.com/ZeljkoBrckovic/safer-vuex/issues
- npm.io page: https://npm.io/package/safer-vuex

## Dependencies (6)

- [vue](https://npm.io/package/vue.md) ^2.5.16
- [vuex](https://npm.io/package/vuex.md) ^3.0.1
- [lodash](https://npm.io/package/lodash.md) ^4.17.5
- [loglevel](https://npm.io/package/loglevel.md) ^1.6.1
- [@types/lodash](https://npm.io/package/@types/lodash.md) ^4.14.106
- [@types/loglevel](https://npm.io/package/@types/loglevel.md) ^1.5.3

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 0.0.0 (latest) — 2018-08-29

## README

# safer-vuex

This library is a simple wrapper for [vuex](https://vuex.vuejs.org/) API. Its purpose is to provide better type safety
when using vuex with typescript.

## Installation

```bash
npm install --save safer-vuex
```

## Example

Let's say we want to create a vuex store which will manage the state of a single numeric variable `counter`. We start by
providing an interface and implementation for its state:

_./root-state.ts_

```typescript
export interface IRootState {
    counter: number
}

export const rootState: IRootState = {
    counter: 0
}
```

Next we define accessors for its **getters**, **mutations** and **actions** in a separate file.

_./root.ts_

```typescript
import { createRootOptions, AccessorFactory } from "safer-vuex"
import { rootState, IRootState } from "./root-state"

// first we instantiate a factory instance which we will use to create accessors.
const f = AccessorFactory.root<IRootState>()

// now we create an object with accessors
export const root = {
    getters: {
        counter: f.getter<number>(state => state.counter)
    },
    mutations: {
        setCounter: f.mutationWPayload<number>((state, payload) => (state.counter = payload)),

        incrementCounter: f.mutation(state => state.counter++),

        decrementCounter: f.mutation(state => state.counter--)
    },
    actions: {
        countdown: f.action<number>(context => {
            return new Promise<number>(resolve => {
                const interval = setInterval(() => {
                    // here we are alraeady accessing getter through our accessor with type safety
                    // `true` flag will be explained later
                    const currentValue = counter.getters.counter.get(context.getters, true)
                    log.debug(currentValue)

                    if (currentValue === 0) {
                        clearInterval(interval)
                        resolve(currentValue)
                    } else {
                        counter.mutations.decrementCounter.commit(context)
                    }
                }, 1000)
            })
        })
    }
}

// Now we can use our `root` object with accessors to generate the actual StoreOptions<IRootState> object for
// vuex API. `createRootOptions` function expects an object which conforms to the
// IAccessorsBundle<IRootStore, any> interface so type checking is performed here.
export const storeOptions = createRootOptions(rootState, root)
```

We exported two objects from _root.ts_: `root` and `storeOptions`. `storeOptions` is only required for store
initialization, but `root` is later used for access. `storeOptions` now looks like this.

```typescript
{
    getters: {
        counter: state => state.counter
    },
    mutations: {
        setCounter: (state, payload) => state.counter = payload,
        incrementCounter: state => state.counter++,
        decrementCounter: state => state.counter--
    },
    actions: {
        countdown: context => {
            return new Promise<number>(resolve => {
                const interval = setInterval(() => {
                    const currentValue = root.getters.counter.get(context.getters, true)
                    log.debug(currentValue)

                    if (currentValue === 0) {
                        clearInterval(interval)
                        resolve(currentValue)
                    } else {
                        counter.mutations.decrementCounter.commit(context)
                    }
                }, 1000)
            })
        }
    }
}
```

This is the `StoreOptions<IRootState>` object which can now be used to initialize vuex store.  
_./store.ts_

```typescript
import Vue from "vue"
import Vuex, { Store } from "vuex"
import { IRootState } from "./root-state"
import { storeOptions } from "./root"

Vue.use(Vuex)

export const store: Store<IRootState> = new Vuex.Store<IRootState>(storeOptions)
```

Store can be safely accessed with accessors we defined in `root` object.

```typescript
import { root } from "... wherever root.ts is located relatively to this file ..."

// ... somewhere inside vue component
const store = this.$store

let currentCounterValue = root.getters.counter.get(store.getters)
log.debug(currentCounterValue) // 0

root.mutations.setCounter.commit(store, 2)

currentCounterValue = root.getters.counter.get(store.getters)
log.debug(currentCounterValue) // 2

root.mutations.incrementCounter.commit(store)

currentCounterValue = root.getters.counter.get(store.getters)
log.debug(currentCounterValue) // 3

root.actions.countdown.dispatch(store).then(value => {
    log.debug(value) // 0
})
```

As you can see, **getters**, **mutations**, and **actions** are used by calling `get`, `commit` and `dispatch` methods
respectively on their accessor objects. `commit` and `dispatch` must be provided with `context` or `store` object. They
will internally call vuex's `commit` or `dispatch` function with full namespace and mutation/action name. `get` on the
other hand receives `getters` object and an optional second parameter `local`. `local` is false by default. If you set
it to true, getter will be called only by name, not the full path (namespace + "/" + name). You can set this flag when
you call getter of a namespaced module inside its own context (see action accessor in the example above).

## Modules

Modules are created in a similar fashion. There are two differences:

1. `AccessorFactory` is instantiated by calling `module(namespace?: string)` static method and optionally providing
   namespace if module should be namespaced.
2. Instead of `createRootOptions`, `createModule` is called to generate `Module` object for registration in vuex store.

## API

Here is the summary of all factory methods available for the creation of accessors.

```typescript
/**
 * Create getter accessor.
 */
getter<ReturnT>(
    func: (state: StateT, getters: any, rootState?: RootStateT, rootGetters?: any) => ReturnT,
    name?: string
)

/**
 * Create mutation accessor.
 */
mutation(
    func: (state: StateT) => void,
    name?: string
)

/**
 * Create mutation accessor with payload.
 */
mutationWPayload<PayloadT>(
    func: (state: StateT, payload: PayloadT) => void,
    name?: string
)

/**
 * Create action accessor.
 */
action<ReturnT>(
    func: (context: ActionContext<StateT, RootStateT>) => Promise<ReturnT>,
    name?: string
)

/**
 * Create action accessor with payload.
 */
actionWPayload<PayloadT, ReturnT>(
    func: (context: ActionContext<StateT, RootStateT>, payload: PayloadT) => Promise<ReturnT>,
    name?: string
)
```

Each factory method receives optional second parameter `name`. We didn't use this parameter in our example. If provided,
`name` will be the actual key used in the generated `StoreOptions` or `Module` object. If you don't provide it,
accessor's key will be used implicitly. For example, if we had defined our `counter` getter like this:

```typescript
// ...
getters: {
    counter: f.getter<number>(state => state.counter), "getCounter"
}
// ...
```

the actual `StoreOptions` object would then look like this:

```typescript
// ...
getters: {
    getCounter: state => state.counter
}
// ...
```

---
_Source: https://npm.io/package/safer-vuex · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
