Vlow

A simple library for unidirectional dataflow architecture inspired by Reflux

---

• Installation
• Overview
• Create actions
• Create a store
• Map stores to Components
  • Using withVlow
  • Using Vlow Component
    • Alternative super class
  • Using altState
  • No more listeners
• TypeScript Store and Actions

---

Installation

Using npm:

$ npm i vlow

In your project:

importVlowfrom'vlow';// Exposes:// - Vlow.version// - Vlow.createActions// - Vlow.factoryActions// - Vlow.Store// - Vlow.Component// - Vlow.withVlow

Or... download the latest release from here and load the file in inside your project. For example:

<!-- Add this line to expose `window.vlow.default` --><!-- WARN: Make sure React is loaded before this line --><scriptsrc="vlow.min.js"></script>

Overview

Vlow uses actions to update one or more stores which updates the state of all components who are mapped to the store(s). In turn, a component triggers an action. Vlow can be used for keeping a global state.

There are three steps which need to be understood to use Vlow:

1. Create Actions
2. Create Stores
3. Map store(s) to Components

Create actions

Actions can be created using the Vlow.createActions function:

// this example creates an add and remove actionconstItemActions=Vlow.createActions(['add','remove',]);

Invoking an action is as simple as calling the function, for example:

ItemsActions.add(item);

Create a store

A Vlow Store is an object which holds a global state which can be shared across components.

Creating a store can be done by creating a subclass of Vlow.Store and call the Store constructor with an actions object, for example:

classItemStoreextendsVlow.Store{constructor(){// Call super with the actions to which this store should// listen too.// Note: multiple actions instances are possible,// for example super(Actions1, Actions2);super(ItemActions);// Create the initial statethis.state={items: []};}// Implement onAction functions for each action defined by actions.// It is not required to create functions for all actions but usually// this is what you want and Vlow logs a warning in `development` mode// when actions are not implemented.onAdd(item){// Update the state like you would do with React.// Just like react the first argument can also be a function.//// An optional second argument can be used. When given it must be// a callback function() which will be called once when all// components which are mapped to the store are rendered.this.setState({items: [...this.state.items,item]});}onRemove(itemId){this.setState({items: this.state.filter(i=>i.id!==itemId)});}}

Map stores to Components

Now that the actions and stores are created, it is time to map them to a component.

This can be done either by using Vlow.withVlow which is the preferred method as of version 1.1.0, or it can be done by extending the Vlow.Component class.

Using withVlow

By using withVlow the store will be mapped to the component props. The function withVlow requires a Vlow Store or an array with multiple stores and returns a new function which accepts a component you want to wrap.

Here are some valid examples:

// Just parse the storewithVlow(SomeStore)(MyComponent);// Multiple storeswithVlow([SomeStore,SomeOtherStore])(MyComponent);// Map only specific store keyswithVlow({store: ItemStore,keys: ['items']// listen only to 'items' changes})(MyComponent);

And this is an example of how withVlow can be used:

import{withVlow}from'vlow';importItemStorefrom'../Stores/ItemStore';constItemComponent=({items})=>(<ul>{items.map(i=><likey={i.id}>{i.text}</li>)}</ul>)exportdefaultwithVlow(ItemStore)(ItemComponent);

Note: It is still ok to use PropTypes for checking the props from a store, for example:

ItemComponent.propTypes={items: PropTypes.arrayOf(PropTypes.shape({id: PropTypes.number,text: PropTypes.string})).isRequired};

Using Vlow Component

It is recommended to use withVlow instead of Vlow.Component but in some cases you might prefer to extend your component directly with a Vlow.Component instead of React.Component. The main difference is that the state from the store will be merged with your components state, instead of receiving the state by props.

Inside the constructor you should use the mapStore() or mapStores() function to map the state to the store.

Here is an example of how to use Vlow.Component:

classItemComponentextendsVlow.Component{constructor(props){super(props);// In case you want to set state in the constructor, make// sure to do this before calling mapStore() since you// otherwise would overwrite the state defined by the store.this.state={some: 'state'};// Function mapStore() accepts a store in which case the// complete store state will be mapped to the components state.// There are two more options://// - Using a keys filter in which case a component only listens// to certain store changes.//// this.mapStore({// store: ItemStore,// keys: ['items'] // listen only to 'items' changes,// // other store state will be ignored// });//// - Using an altState function which allows you to modify state// before it will be applied. (more info on altState() can be// found later in this documentation)this.mapStore(ItemStore);// The state now looks like:// {some: 'state', items: []}// It's ok to modify the state as long as you do not// overwrite `this.state` with a new Object, for example:this.state.hasItems=this.state.items.length>0;}render(){return(<ul>{this.state.items.map(i=><likey={i.id}>{i.text}</li>)}</ul>);}}

In case you need multiple stores, the function this.mapStores([]) can be used which accepts an Array of stores. Each store may be defined in a different way.

this.mapStores([StoreOne,{store: StoreTwo},{store: StoreThree,keys: ['foo','status']},{store: StoreFour,altState: storeState, state,props=> storeState
}]);

Alternative super class

By default the Vlow.Component class extends the React.Component class but you might want Vlow.Component to extend your own custom class. This is possible by using Vlow.Component.extend().

// In this example we create a Vlow Component which extends// React.PureComponent instead of the default React.ComponentclassMyComponentextendsVlow.Component.extend(React.PureComponent){
...
}

Using altState

Sometimes you want to listen to state changes in a store but then do something with this state instead of just applying the state to a component. This can be done by using an altState(storeState, state, props) hook which will be triggered on state changes in the store but before the component state is changed. The altState function should return the state changes you want to make or null in case you don't want to update the state of the component.

functionaltState(storeState,state,props){// This function should return the state// you want to apply on the component. The function can// also return `null` in which case the components state// will not be changed.if(props.status==='error'){// the components state will not be changedreturnnull;}// Return some alternative state for `this` component.// Other components still receive the `original` state// from the store.return{items: storeState.items.filter(i=>i.age>state.minAge)};}// Use the altState functionconststores={store: MyStore,
altState,};

No more listeners

If there are no components left who listen to the store, the store function listenersEmpty() is called. By default, this function does nothing but you might implement it yourself and overwrite the default behavior. For example, you might want to unregister the store if no more components are listening to clean-up memory:

importVlowfrom'vlow';// define the state on the store, e.g. this.state.todosexportinterfaceIMyStore{
todos: string[];}classMyStoreextendsVlow.Store<IMyStore>{listenersEmpty(){this.unregisterStore();// the store will unregister itself from the// actions until a new store is created}}

Use TypeScript

With Vlow, it is possible to use TypeScript and have both the state in your store and the actions typed.

Example:

importVlowfrom'vlow';// define the state on the store, e.g. this.state.todosexportinterfaceIMyStore{
todos: string[];}classMyStoreextendsVlow.Store<IMyStore>{onFetch(limit: number){/* fetch todo's... */}}constactions=['fetch',]asconst;constMyActions=Vlow.factoryActions<MyStore>()(actions);// MyActions.fetch(10); understands the arguments of the `onFetch` defined in the store