vue-simple-state v0.2.0
vue-simple-state
Quickly create shared complex reactive state structures. Built using @vue/reactivity and rxjs
Install
npm install --save vue-simple-state
Usage - useState
useState
is meant to be used directly inside of a setup
function in a Vue
3+ component, however, it can be used without. Read more about setup
in Vue's docs. For use outside of a Vue
3+ component, use the manualUnsub
option below (if Vue
is installed, otherwise this is the default), or manually interact with State
(see Advanced Usage)
useState(config)
- Options
config {}
- (Optional) Configuration to override base configuration per-use
state
- Direct read-only access to state
The state
property is read-only direct access to the current state. state
is used as a computed variable, its value will be accessed using the value
property.
import { useState } from 'vue-simple-state'
export default {
// ...
setup() {
const { state } = useState()
return {
state
}
}
}
computed(fn)
- Create a read-only computed state variable using a function
Variables created using the computed
method take a function to pull out a value from state. computed
is used as a computed variable, its value will be accessed using the value
property.
fn <(state) => any>
- Function used to extract value from state
import { useState } from 'vue-simple-state'
export default {
// ...
setup() {
const { computed } = useState()
const userName = computed((state) => {
return state.user.name
})
return {
userName
}
}
}
reactive(path, default?)
- Create a read-only state variable by path
Variables created using the reactive
method take a path to pull out a value from state and an optional default value if none is found. reactive
is used as a computed variable, its value will be accessed using the value
property.
path <string[]>
- Path by property name to access state valuedefault <any?>
- (Optional) Default value to return when state value is not set
import { useState } from 'vue-simple-state'
export default {
// ...
setup() {
const { reactive } = useState()
const userName = reactive(['user', 'name'], 'Joe')
return {
userName
}
}
}
writable(path, default?)
- Create a read-write computed state variable by path
Variables created using the writable
method take a path to pull out a value from state and an optional default value if none is found. writable
is used as a read-write computed variable, its value will be accessed and set using the value
property.
path <string[]>
- Path by property name to access state valuedefault <any?>
- (Optional) Default value to return when state value is not set
<template>
<input v-model="userName" />
</template>
<script>
import { useState } from 'vue-simple-state'
export default {
// ...
setup() {
const { writable } = useState()
const userName = writable(['user', 'name'], 'Joe')
return {
userName
}
}
}
</script>
useNamespace(path)
- Create a namespace for state
When using state in components, splitting out state to group related information is essential. Namespaces share all of the same properties/methods as described above but they are scoped to the defined namespace. Namespaces return their own useNamespace
method, allowing creation of a namespace off of another namespace
path <string[]>
- Path by property name to access state value
import { useState } from 'vue-simple-state'
export default {
// ...
setup() {
const { useNamespace } = useState()
const { reactive } = useNamespace(['user'])
const userName = reactive(['name'], 'Joe')
return {
userName
}
}
}
unsubscribe()
- Manually unsubscribe
This method only exists when configured with the manualUnsub
option set to true
(or when Vue
3+ is not installed). When called it will unsubscribe useState
from any future state updates
import { useState } from 'vue-simple-state'
const { state, unsubscribe } = useState({
manualUnsub: true
})
// ...use state
// cleanup subscription
unsubscribe()
Usage - config
config.set(config)
- Set application-level configuration
Any config set using this method will be used as the default config for the application. These settings can be overwritten per-use of useState(config)
config {}
- Application-level configurationmanualUnsub <bool = false*>
- Choose to manually unsubscribe from state updates. Defaults tofalse
. When set totrue
,useState
will return anunsubscribe
method to call in order to unsubscribe manually. By default,useState
will unsubscribe using theonUnmounted
component lifecycle hook.- *When
Vue
3+ is not installed, this option defaults totrue
and will requireunsubscribe
to be called manually for cleanup
- *When
import { config } from 'vue-simple-state'
config.set({
// ...options
})
config.get()
- Get the current configuration being used
import { config } from 'vue-simple-state'
const currentConfig = config.get()
config.reset()
- Reset configuration to default
import { config } from 'vue-simple-state'
// manualUnsub === true
config.reset()
// manualUnsub === false
Advanced usage - State
State
is the service maintaining the BehaviorSubject that is being used to handle the application state
State.observable
- Direct read-only access to the observable
import { State } from 'vue-simple-state'
const behaviorSubject = State.observable
behaviorSubject
.pipe(...)
.subscribe(fn)
State.update(fn)
- Update state using a function
fn <(state) => state>
- Function used to manipulate state and return an updated state
import { State } from 'vue-simple-state'
State.update((state) => {
state.property = 'value'
return state
})
State.subscribe(fn)
- Subscribe a function to state changes
Returns a function that when called will unsubscribe the observer
fn <(state) => void>
- Function called each time state changes
import { State } from 'vue-simple-state'
function onStateChange(state) {
console.log('called on state updates', state)
}
const unsubscribe = State.subscribe(onStateChange)
// cleanup subscription
unsubscribe()
Advanced Examples
Reading/Writing state to localStorage
import { State } from 'vue-simple-state'
function getSavedState() {
return window.localStorage.getItem(...)
}
function setSavedState(state) {
window.localStorage.setItem(...)
}
State.update(getSavedState)
State.subscribe(setSavedState)
Creating a custom writable computed state variable
import { computed } from 'vue'
import { State, useState } from 'vue-simple-state'
export default {
// ...
setup() {
const { writable } = useState()
// Given: state.tags === 'one,two'
// Read tags as an Array: ['one', 'two']
// Update tags in state as a String: 'one,two,X'
const stateTags = writable(['tags'])
const tags = computed({
get: () => stateTags.value.split(','),
set: (val) => (stateTags.value = val.join(','))
})
return {
tags
}
}
}