choo-store

Create a store for a choo application.

Features

namespacing: use storeName to keep state clean and improve tracing
scoped state: set initialState to make initializing and resetting easy
simplified events API: organize all your events to reduce boilerplate
action functions: automagically creates actions that accept data and emit events
event names in state: event names made available in state.events.storeName
free reset event: free reset event included with purchase

Install

npm install choo-store

Usage

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 reset event, 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.

License

ISC

choojs/choo-store