@universal-packages/state
v1.7.4
Published
Simple state management using paths
Downloads
1,049
Readme
State
There are a lot of ways to track your app state nowadays, all reliable and easy to grasp, but sometimes they can feel a little convoluted as your application grows and you start to keep track of a lot of resolvers, transformers, actions, descriptors, selectors and so on. Universal state offers an alternative by just mutating and getting your state by using string paths.
Install
npm install @universal-packages/state
State
State class is the high level representation of the state object, it provides all tools related to modify and read from state.
import { State } from '@universal-packages/state'
async function test() {
const initialState = { loading: true }
const state = new State(initialState)
await tate.set('loading', false).await()
console.log(state.get())
}
test()
// > { loading: false }
getters
state
Returns the current state object
Instance methods
.clear()
Clears the state object and emits such big change to all listeners
.get(path: String)
Get any value using a deep path.
const state = new State(initialState)
const value = state.get('and/am/mean/it/0/it/does/not/matter/how/deep')
.mutate(mutator: Function)
Mutate enables you to apply all kinds of mutations to the state without worrying about race conditions with other mutations being applied, it takes a mutator function and calls it only when it’s its turn to be dispatched (All mutations are dispatched in a linear way). It returns a BufferDispatcher object in charge of dispatching all mutations.
import { State } from '@universal-packages/state'
async function test() {
const initialState = { loading: true, auth: { user: {}, empty: true } }
const state = new State(initialState)
const user = await getUser()
state.mutate((toolSet) => {
toolSet.set('loading', false)
toolSet.merge('auth/user', user)
toolSet.remove('auth/empty')
})
await state.waitForMutations()
console.log(state.get())
}
test()
// > { loading: false, auth: { user: { id: 1, name: 'david' } } }
ToolSet
Provides the methods to actually change the state, use only these to mutate teh state.
state.mutate((toolSet) => {
// All the mutations
})
.concat(path: String, array: Array)
Directly append an array into one inside the state
const initialState = { users: { ordered: [{ id: 1 }] } }
toolSet.concat('users/ordered', [{ id: 2 }, { id: 3 }])
.merge(path: String, subject: Object)
Merge an object into any place into the state
const initialState = { users: { ordered: [{ id: 1 }] } }
toolSet.merge('users/ordered/0', { name: 'david' })
.remove(path: String)
Completely obliterates any part of the state
const initialState = { users: { ordered: [{ id: 1 }] } }
toolSet.remove('users/ordered')
.set(path: String, subject: any)
Sets a single value into any part of the state
const initialState = { users: { ordered: [{ id: 1 }] } }
toolSet.set('users/ordered/0/name', 'david')
.update(path: String, updater: Function)
Updates a value in the state using a function providing the current value as a parameter
const initialState = { users: { ordered: [{ id: 1 }] } }
toolSet.update('users/ordered/0', (david) => {
return { id: david.id, name: 'omar' }
})
.waitForMutations()
Returns a promise that resolves when all mutations are dispatched
Listening for changes
The state object behaves just like a event emitter, you can subscribe to changes in the state for a specific path.
const initialState = { posts: { new: [{ id: 1 }, { id: 2 }] } }
const state = new State(initialState)
state.on('@', ({payload}) => console.log('State changed'))
state.on('posts', ({payload}) => console.log('Post changed'))
state.on('posts/old', ({payload}) => console.log('Old was created'))
state.on('posts/old/0', ({payload}) => console.log('Old at 0 is part of the value set'))
state.on('posts/old/0/id', ({payload}) => console.log('Old at 0/id is part of the value set'))
state.on('posts/new', ({payload}) => console.log('Post new did not changed'))
state.on('posts/new/0', ({payload}) => console.log('New at 0 changed'))
let dispatcher = state.mutate((toolSet: ToolSet): void => {
toolSet.set('/posts/old/', [{ id: 100 }])
toolSet.merge('/posts/new/0', { name: 'david' })
})
await dispatcher.await
// > State changed
// > Post changed
// > Old was created
// > New at 0 changed
Stand alone mutations
You can directly push a mutation without the need of building a mutator function by just calling the methods directly on the state object.
const state = new State(initialState)
state.set('loading', false)
state.merge('auth/user', user)
state.remove('auth/empty')
Typescript
This library is developed in TypeScript and shipped fully typed.
Contributing
The development of this library happens in the open on GitHub, and we are grateful to the community for contributing bugfixes and improvements. Read below to learn how you can take part in improving this library.