choo-store
v1.1.2
Published
Create a store for a choo application.
Readme
choo-store 
Create a store for a choo application.
Features
- namespacing: use
storeNameto keep state clean and improve tracing - scoped state: set
initialStateto make initializing and resetting easy - simplified events API: organize all your
eventsto reduce boilerplate - action functions: automagically creates
actionsthat accept data and emit events - event names in state: event names made available in
state.events.storeName - free reset event: free
resetevent included with purchase
Install
npm install choo-storeUsage
First, set up your store's name, initial state, and events:
var createStore = require('choo-store')
module.exports = createStore({
storeName: 'clicks',
initialState: { count: 0 },
events: {
increment: ({ store, emitter }) => {
store.count++
emitter.emit('render')
}
}
})Next, register your store with your choo app:
var app = require('choo')()
var store = require('./stores/clicks')
app.use(store)Now you can use store state and actions in your component:
var html = require('choo/html')
var { actions } = require('./stores/clicks')
module.exports = ({ clicks }) => {
return html`
<body>
<h1>count is ${clicks.count}</h1>
<button onclick=${e => actions.increment(1)}>Increment</button>
<button onclick=${e => actions.reset({ render: true })}>Reset</button>
</body>
`
}Example
See the example folder for a full working example.
You can also check it out locally by cloning this repo and running npm i && npm run example.
API
createStore({ storeName, initialState, events })
Params:
storeName- string: Name of store. Used for namespacing in state object and prefixing of event names.initialState- object: Initial state of store.- This will be the state of the store on initialization of the app.
- When calling the
resetevent, state will be returned to this value. - Must be valid, serializable JSON
events- object: List of named event functions.
All params are required.
Returns a regular store function (function (state, emitter, app)) to be supplied to Choo's app.use() function.
Attaches event names to state.events[storeName] for convenience. For example, if you have a store clicks with an event increment, the event name (clicks:increment) will be available at state.events.clicks.increment.
Returned function also has an actions property containing ready-to-go named functions that take whatever data you pass and emit the right event.
Event Functions
Event functions live in the events object and have the following signature:
function eventName ({ data, store, state, emitter, app }) {}Params:
data- any: Event data supplied by user.store- object: Local store state.state- object: Global app state.emitter- nanobus: Choo event emitter.app- choo: Choo instance.
Params are wrapped in a single object so that argument order is made irrelevant and users can take what they need from the event parameters object.
Emitting Events
Once a store has been created, these three methods of emitting an event all do the same thing:
store.actions.increment(1)
emit(state.events.clicks.increment, 1)
emit('clicks:increment', 1)Global Events
You can listen for any of Choo's global events (DOMContentLoaded, DOMTitleChange,
navigate, popState, pushState, render, replaceState) by adding an event
with the appropriate name to the events object:
createStore({
storeName: 'history',
initialState: { navigations: 0 },
events: {
navigate: ({ store, emitter }) => {
store.navigations++
emitter.emit('render')
}
}
})Note: global events are not added to
state.events[storeName]and do not have an action function associated with them since they are not namespaced events.
reset event
A reset event (e.g. storeName:reset) is added by default.
Emitting this event will reset the store's state to initialState.
It takes a render boolean option in case you want to emit a render event afterwards.
store.actions.reset({ render: true })Why
Q: Choo has a decent way to create a store already. Why use this?
A: Bigger apps need more structure!
As an application gets larger, some issues can arise that need to be dealt with:
- properly namespacing stores and events
- resetting stores to their initial state
- avoiding direct manipulation of other stores
- providing coherent structure for a project
- reducing repetitive boilerplate
Doing the above gets time consuming the bigger an app gets. Without lots of attention to detail, it's easy to lose track of value drift between stores in these cases. This module aims to make the process of managing stores and events simple and easy.
Contributing
Contributions welcome! Please read the contributing guidelines before getting started.