valstore
Featherweight key-based central store of state with zero dependencies.
Spiritual successor to toystore. valstore is lighter weight, has no dependencies, and has a smaller, leaner API.
Val = Value
Store = Central store of application state
Easy to Learn and Use
Other state management systems can be difficult or cumbersome to use, or require a lot of repetitive boilerplate code that gets in the way.
valstore is based around get
and set
calls with nested keys for object
structures, like store.get('foo.bar.baz')
.
Install
Install valstore with NPM:
npm install valstore --save
Example
Import if using ES6+ or Transpiling:
;
Require if using ES5 or Node.js:
const valstore = ;
Create a new store instance with its initial state using valstore.create()
:
const store = valstore;
API
create(initialState)
Create a new store with its initial state. This should be an object.
const store = valstore;
get(key: string | function)
Get a value from the store by string key. Accepts simple keys like user
and
nested keys like foo.bar.baz
.
const user = store;const value = store;
Selector Functions
If you prefer using selector functions for retrieving values from the store, you can use those with get
also:
const getFooBarBaz = statefoobarbaz;const value = store;
set(key: string, value: any)
Set a value to the store with string key. Just like get
, this accepts simple
keys like user
and nested keys like foo.bar.baz
.
store;store;
batch(name: string, trx: function)
Batches set multiple values into the store in a single transaction before broadcasting any updates. For example if you
call store.set
twice (or even hundreds of times!) in a batch, all the affected keys will be collected, and your
matching subscribers will only fire once the batch is complete instead of once instead of once per set
call.
Batches are a good performant way to make many set
calls in sequence in situations where your subscribers can
wait to fire at the end.
store;
Note that any async set
calls made will not be covered in the batch (for example a set
call after a fetch
call
that is wrapped in a separate batch). Nested batches are not recommended as they are not accounted for by valstore.
subscribe(callback: function, [key: string | string[]])
Subscribe a function to changes in the store. Just like get
, this accepts
simple keys like user
and nested keys like foo.bar.baz
.
Subscribe callbacks receive the current state as the first argument.
Returns an id of the subscription that can be used with unsubscribe(id)
.
{ ;}
Subscribe to ALL/ANY changes
If you want to ALL/ANY changes in the store, just pass a function as an argument with no keys:
store;
Subscribe to specific key
If you want to subscribe to a specific key, specify the key as the first argument:
store;
Subscribe to multiple keys
If you want to subscribe to multiple keys, specify the key as an array in the first argument:
store;
unsubscribe(id|callback)
Unsubscribe by id
or callback. Unsubscribes all registered callbacks when
called with no arguments.
store;
With key only (will unsubscribe ALL listeners on this key):
store;
With key and callback:
store;
With subscriber id (returned from subscribe
call):
var id = store; store;
trigger(keys)
Used internally after calls to set
or after a batch in batch
. Triggers an update on the provided key or array
of keys. This will fire any subscriber functions that are listening on those keys.
Note: You should never have to call this manually. This is only documented here for completeness.
store;store;