Home

Awesome

choo-store stability

npm version build status downloads js-standard-style

Create a store for a choo application.

Features

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:

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:

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:

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