Repository files navigation

Utility functions for working with Redux

npm install --save zeal-redux-utils

zeal-redux-utils provides a number of utility functions that are useful inRedux applications, especially those that use amodular or domain-style structure.

• createActionTypes
• createReducer
• globalizeSelectors

While not required, most Redux applications define constants for the action types in the project:

constADD_TODO="ADD_TODO";

In a modular project structure, there is a chance that actions defined in different modules could collide in a global namespace. As well, the repetition of the action name as both the constant name and the value is somewhat tedious.

createActionTypes solves both of these problems. It takes a namespace and a list of action type strings and produces an object whose keys are the action type constants and whose values combine the namespace and action name.

// In modules/todos/constants/ActionType.jsimport{createActionTypes}from"zeal-redux-utils";exportdefaultcreateActionTypes("todos",["ADD_TODO","REMOVE_TODO","TOGGLE_TODO"]);// In modules/todos/actions.jsimportActionTypefrom"./constants/ActionType";exportfunctionaddTodo(text){return{type:ActionType.ADD_TODO,payload:text};}// ...etc...

The actual export will end up looking like the following (though the actual format of the string value is an implementation detail):

{ADD_TODO:'~todos/ADD_TODO',REMOVE_TODO:'~todos/REMOVE_TODO',TOGGLE_TODO:'~todos/TOGGLE_TODO'}

createReducer is an implementation of the approach described in theReducing Boilerplate section of the Redux docs.

It generates a reducer function by taking the initial state and an object containing handler functions. Rather than hand-writing aswitch statement,createReducer looks up the action type in the handler object and applies the function found there. If no function is found, the state is returned unchanged.

import{createReducer}from'zeal-redux-utils'exportconstcreateReducer([],{[ActionType.ADD_TODO]:(state,{ payload})=>[state, ...payload],// ...})

In development mode,createReducer verifies that all dispatched actions conform to theflux-standard-action specification. When an action is dispatched that does not conform, aNonStandardAction exception is raised, providing immediate notification of a problem.

This check is handy for catching the case where an action type is accidentallynull orundefined, or when data is included directly rather than under apayload key.

NOTE: This check happens in development mode only; in production mode the check is not performed.

For projects that choose not to use the flux-standard-action spec, or that use a third-party library that doesn't conform,createReducer takes an optional whitelist function that specifies when to bypass the check for flux-standard-action conformance.

Example: Whitelisting actions from a library

import{createReducer}from'zeal-redux-utils'functionisApolloAction(action){return/^APOLLO_/.test(action.type)}exportconstcreateReducer([],{[ActionType.ADD_TODO]:(state,{ payload})=>[state, ...payload],// ...},{allowNonstandardActionIf:isApolloAction})

Example: Disabling the FSA check entirely

import{createReducer}from'zeal-redux-utils'exportconstcreateReducer([],{[ActionType.ADD_TODO]:(state,{ payload})=>[state, ...payload],// ...},{allowNonstandardActionIf:()=>true})

In a modular Redux application,createReducer will be used several times. In order to avoid duplicating the whitelist function everywhere, we recommend creating a local version ofcreateReducer that applies the whitelist function, then using your local version ofcreateReducer throughout your application.

// In utils/createReducer.jsimport{createReducer}from'zeal-redux-utils'functionisApolloAction(action){return/^APOLLO_/.test(action.type)}exportdefaultfunction(initialState,handlers){createReducer(initialState,handlers,{allowNonstandardActionIf:isApolloAction})}// In your reducer file:importcreateReducerfrom'utils/createReducer'exportconstcreateReducer([],{[ActionType.ADD_TODO]:(state,{ payload})=>[state, ...payload],// ...})

Many Redux applications use selector functions to provide access to the state tree.

In a modular Redux application, we sometimes need to have selectors that work on the module's local slice of the state tree, but in other cases, we need to have selectors that work on the global state tree.

One solution is to individually export the localized selectors and then default export the globalized selectors as a single object. To use a localized selector, useimport { mySelector } from 'myModule/selectors'. To use a globalized selector, useimport MyModuleSelectors from 'myModule/selectors' and then callMyModuleSelectors.mySelector.

globalizeSelectors is designed to facilitate this approach. It takes a function that maps from the global state to the local state slice and an object of localized selector functions. It returns an object of globalized selector functions.

import{globalizeSelectors}from"zeal-redux-utils";functionlocalState(state){returnstate.todos;}exportfunctionallTodos(state){// return all todos from the local state slice}exportdefaultglobalizeSelectors(localState,{  allTodos});

This approach to selectors is described in much more detail in a series of blog posts by Randy Coulman:

• Encapsulating the Redux State Tree
• Modular Reducers and Selectors
• Globalizing Redux Selectors
• Globalizing Curried Selectors

Authored by the Engineering Team ofCoding ZEAL

Copyright (c) 2017 Zeal, LLC. Licensed under theMIT license.