RAAX - React Action Active eXtensions

Table of contents

1. Installation and usage
2. API action description
3. Action creator helpers
4. Action handler helper
5. RAAX Middleware
6. xmess subscriber helper
7. Working with local copy of module
8. Publish a package

Installation and usage

Set private registry by adding registry=http://npm.pp.ciklum.com/ to your .npmrc file

Install RAAX library by running

npm i @ciklum/raax

Now you can use assets provided by RAAX:

import { createAction, createApiAction, handleActions, raaxMiddleware } from '@ciklum/raax'

API action description

Action creator helpers

Function createAction

createAction is a function, that creates synchronous action. Action configuration object should be provided as an argument:

• key type - action type,
• key payload - action payload,
• key meta - optional object with key withXmess set to true if action should publish it's payload to xmess channel based on action type.

Function createApiAction

createApiAction is a function to create API action that will be processed by raaxMiddleware. Action configuration object should be provided as an argument:

• key type - action type, usually string,
• key apiSvcRequest - request provided by ApiService from @ciklum/waas,
• key meta - optional object with key withXmess set to true if action should publish it's payload to xmess channel based on action type.
• optional function or array of functions that represents listeners
  • onBefore,
  • onStart,
  • onSuccess,
  • onError,
  • onFailure,
  • onCancel.

Note: dispatch and getState functions are passed as first and second arguments before other arguments, described in documentation, to all listeners

Action handler helper

handleActions is a helper function for creating reducers in the specific slice of store. Accepts both reducers object (object with action's type as key and reducer function as value) and API actions type(s).

The last argument always should be initial state.

The first optional parameter could be an object with action's type as key and reducer function as value

Other parameters - action types for API action

import { handleActions } from '@ciklum/raax'

export const TODOS_CMP_ID = 'todos'
export const FILTER_SLICE_ID = 'filter'
const TODOS_FILTER_SET = `${TODOS_CMP_ID}/${FILTER_SLICE_ID}/filter-set`

const todoReducer = handleActions(
  {
    [TODOS_FILTER_SET]: (state, { payload: { filter } }) => ({ ...state, visibility: filter }),
  },
  'GET_TODOS',
  { payload: [], meta: {}, error: false }
)

// Reducers for next actions will be created:
//  - todos/filter/filter-set
//  - GET_TODOS:before
//  - GET_TODOS:start
//  - GET_TODOS:success
//  - GET_TODOS:error
//  - GET_TODOS:failure
//  - GET_TODOS:cancel

RAAX Middleware

RAAX middleware allows you to process API actions, created with createApiAction function. To enable raaxMiddleware use:

import { createStore, applyMiddleware, compose } from 'redux'
import thunk from 'redux-thunk'
import { raaxMiddleware } from '@ciklum/raax'
import { createReducer } from './reducers'

const initialState = {}

const middlewares = [
  thunk,
  raaxMiddleware,
]

const enhancers = [
  applyMiddleware(...middlewares)
]

const store = createStore(
  createReducer(),
  initialState,
  compose(...enhancers)
)

xmess subscriber helper

createXMessSubscriber is a function that dispatches action when xmess received. createXMessSubscriber accept and object as a parameter:

• key - xmess chanel to subscribe to,
• value - redux action or an array of actions to dispatch.

Returns a function or an array of functions to unsubscribe from channel.

import { createAction, createXMessSubscriber } from '@ciklum/raax'
import { TODOS_CMP_ID, USER_SLICE_ID } from 'modules/Todos/constants'

export const TODOS_USER_SET = `${TODOS_CMP_ID}/${USER_SLICE_ID}/user-set`

export const userActions = {
  setUser: user => createAction({
    type: TODOS_USER_SET,
    payload: { id: user.id },
  }),

  subscribeToChannel: createXMessSubscriber({
    'root/user/get:success': user => userActions.setUser(user),
  }),
}

Working with local copy of module

When you want to develop new features for module, this section will be helpful for you. Package linking is a two-step process which solves this need. You need npm link for this.

Steps:

• Create global link. It will be available in folder were your npm modules are.

  npm link

• Links to the global installation target from your front end app.

  npm link @ciklum/raax

Publish a package

Publish a package to the registry by running

npm run build
npm publish