@keystack/fluxstate

Flux State

Read about Flux-Data-Flow

Install

$ npm install @keystack/fluxstate

This library is a Flux state management system intended to be used in react applications.

It does includes three things:

1. An action type helper to generate SUCCESS, FAIL and AFTER versions of action types. (useful for async actions)
2. An observable data store
3. An action creator with promise based async middleware to dispatch actions and handle async operations (namely XHR requests)

Action Type Generator

FluxState.createConstants( array=['ACTION_TYPE_1','ACTION_TYPE_2], prefix='DOMAIN' )

Usage

const UserConstants = FluxState.createConstants([
  'LOGIN',
  'LOGOUT'
], 'USER');

Result

{
   LOGIN:          'USER_LOGIN',
   LOGIN_SUCCESS:  'USER_LOGIN_SUCCESS',
   LOGIN_FAIL:     'USER_LOGIN_FAIL',
   LOGIN_AFTER:    'USER_LOGIN_AFTER',
   LOGOUT:         'USER_LOGOUT'
}

It is also possible to configure constant generation.

  FluxState.configs.constants.setSeparator(':');
  FluxState.configs.constants.setSuccessSuffix('OK');
  FluxState.configs.constants.setFailSuffix('ERROR');
  FluxState.configs.constants.setAfterSuffix('DONE');

now the previous example will result in:

{
   LOGIN:        'USER:LOGIN',
   LOGIN_OK:     'USER:LOGIN:OK',
   LOGIN_ERROR:  'USER:LOGIN:ERROR',
   LOGIN_DONE:   'USER:LOGIN:DONE',
   LOGOUT:       'USER:LOGOUT'
}

to go back to default configurations use:

FluxState.configs.constants.resetToDefaults();

Action Creator

FluxState.createActions(actionObject={})

Usage

const UserActions = FluxState.createActions({
  login: [UserConstants.LOGIN, function(username, password){
    return ApiUsers.login(username,password)
  }]
});

UserActions.login({
  username : 'user',
  password : 'pass'
}) 

Result

1. USER_LOGIN gets dispatched directly before the passed callback gets executed.
2. The passed callback gets executed.
3. Depending on the result of the action callback, it will either:
   • Dispatch USER_LOGIN_SUCCESS with result of resolved Promise.
   • Dispatch USER_LOGIN_FAIL with result of Rejected Promise or Error.
4. USER_LOGIN_AFTER gets dispatched after step 3 USER_LOGIN_SUCCESS gets dispatched in two cases:

USER_LOGIN_SUCCESS gets dispatched in two cases:

1. The callback returns a value 2. the callback returns a promise which gets resolved

USER_LOGIN_FAIL gets dispatched in two cases:

1. The action callback throws an exception or returns an Error
2. It returns a promise which gets rejected

Observable Data Store

FluxState.createStore(mixinObject={},[ ['EVENT_TYPE_CONSTANT',(payload)=>{}] ])

FluxState.createStore takes two parameters: 1. A mixin object for the store 2. An array of action listeners

Helper Methods

getState()       : returns a shallow copy of the current state
persist(@object) : backs up current state in local storage and merges @object
onChange(@cb)    : attaches a callback to be fired when change is observed
offChange(@cb)   : removes callback (typically used in React.Component.cdum lifecycle hook)

Usage

const UserStore = FluxState.createStore({
  
  getInitialState: function(){
    return {
      isAuth: false,
      data: null,
      isLoggingIn: false,
      error: null
    };
  },
  
  storeDidMount: function(){
    // Gets called when store is ready
  },
  
  isAuth: function(){
    return this.get('isAuth')
  }
  
},[
 
 /**
  * called directly before executing login action
  */

 [UserConstants.LOGIN, function onLogin(){
  this.setState({
    isLoggingIn: true,
    error: null
  });
 }],
 
 /**
  * called if login action was successful
  */

 [UserConstants.LOGIN_SUCCESS, function onLoginSuccess(payload){
  this.setState({
    isAuth: true,
    data: payload
  });
 }],

 /**
  * called if login action failed
  */

 [UserConstants.LOGIN_FAIL, function onloginFail(error){
  this.setState({
    error: error.message
  });
 }]
 
 /**
  * called after login action succeeds or fails
  */

 [UserConstants.LOGIN_AFTER, function onloginAfter(error){
  this.setState({
    isLoggingIn: false
  });
 }]

]);