Hart Redux

Hart Redux provides a set of modules that each aim to simplify and accelerate Redux development. These modules work equally well independently or mixed and matched. The philosophy behind these modules is to maintain flexibility and interoperability. If your project requires more and more custom code, you can remove/replace every Hart Redux component gracefully; as such, these modules are excellent for jump-starting your development without committment.

Install

npm install @hart/hart-redux

yarn add @hart/hart-redux

Modules

ActionTypes

The ActionTypes module generates a nested map of action type strings for your Action Creators and Reducers to reference. The map consists of top-level "operations" with sub-maps of each of the "actions".

Usage

import { ActionTypes } from '@hart/hart-redux';

//pass in a unique model name
const actionTypes = ActionTypes("Foo");

Result

{
	CREATE: {
		REQUEST: 'FOO_CREATE_REQUEST',
		SUCCESS: 'FOO_CREATE_SUCCESS',
		ERROR: 'FOO_CREATE_ERROR'
	},
	READ: {
		REQUEST: 'FOO_READ_REQUEST',
		SUCCESS: 'FOO_READ_SUCCESS',
		ERROR: 'FOO_READ_ERROR',
	}
	...
}

//Now you can access or match your structured set of actions

const action = {
	type: actionTypes.CREATE.REQUEST,
	payload: ...
}

switch(action.type){
 case actionTypes.CREATE.REQUEST:
 	...
 case actionTypes.CREATE.SUCCESS:
 	...
 case actionTypes.CREATE.ERROR:
 	...
 default:
 	...
}

Action types strings are created with the following pattern: MODELNAME_OPERATION_ACTION

The module, by default, generates using the values ["CREATE", "READ", "UPDATE", "DELETE"] for operation names and ["REQUEST", "SUCCESS", "ERROR"] for action names. These values can be overriden.

Override Defaults

import ActionTypes, { Defaults } from '@hart/hart-redux/ActionTypes';

const actionTypes = ActionTypes("Foo", [...Defaults.operations, "UPSERT"], ["REQUEST", "SUCCESS", "SORTA_WORKED"]);

Results

{
	CREATE: {
		REQUEST: 'FOO_CREATE_SUCCESS',
		SUCCESS: 'FOO_CREATE_SUCCESS',
		SORTA_WORKED: 'FOO_CREATE_SORTA_WORKED',
	},
	...
	UPSERT: {
		REQUEST: 'FOO_UPSERT_REQUEST',
		SUCCESS: 'FOO_UPSERT_SUCCESS',
		SORTA_WORKED: 'FOO_UPSERT_SORTA_WORKED',
	}
}

If you intend to use this module with the Normalized module, it is recommended to append to the defaults rather than remove/replace. Normalized expects the default structure and while you may remap the defaults in Normalized, it may not yield intended results.

Operations

Default operations that correspond to Operation/Action combinations that Normalized Reducers/Selectors expect.

CREATE

Operation that attempts to create an object with a resulting id.

READ

Operation that attempts to retrieve an object with a specific id.

UPDATE

Operation that attempts to update an object with a specific id.

DELETE

Operation that attempts to delete an object with a specific id.

Actions

Default actions that correspond to Operation/Action combinations that Normalized Reducers/Selectors expect.

REQUEST

Action that attempts an Operation that will return a result that subsequently would be used for a SUCCESS or ERROR action.

SUCCESS

Action to dispatch the result of REQUEST action's result.

ERROR

Action to dispatch when a REQUEST action fails.

Normalized

The Normalized module aims to simplify the common use-case of handling collections of objects with ids in your redux store.

Normalized generates Reducers and Selectors for common (CRUD) operations. It does so using a map of ActionTypes. The ActionTypes module generates all of the neccesary ActionTypes and by pairing the two modules you can focus on writing the logic of your Action creators. The Normalized module is flexible and allows for renaming for reducers/selectors as well as working along side custom reducers.

Usage

const actionTypes = {
	CREATE: {
		REQUEST: 'FOO_CREATE_REQUEST',
		SUCCESS: 'FOO_CREATE_SUCCESS',
		ERROR: 'FOO_CREATE_ERROR'
	},
	READ: {
		REQUEST: 'FOO_READ_REQUEST',
		SUCCESS: 'FOO_READ_SUCCESS',
		ERROR: 'FOO_READ_ERROR',
	}
	...
}

const normalized = Normalized(actionTypes);

Result

The resulting object has reducers and selectors mapped to the actionTypes you supplied. With this result you can create a fully functioning Redux store!

const normalized = {
	reducers: {
		allIds,
		byIds,
		areObjectsLoading,
		hasObjects,
		objectCreating,
		objectUpdating,
		objectDeleting,
		pageIds,
		pages
	},
	selectors: {
		getObjectIds,
		getObjects,
		getObjectById,
		getObjectsByIds,
		areObjectsLoading,
		hasObjects,
		isObjectCreating,
		isObjectUpdating,
		isObjectDeleting,
		getObjectIdsByPage,
		getPageMetadata
	}
}

Reducers

allIds

Reducer that stores an array of object ids. Uses READ, CREATE, and DELETE, SUCCESS actions to add and remove ids from the store.

byIds

Reducer that stores a map of all of this collection's objects. Uses READ, CREATE, UPDATE, and DELETE, SUCCESS actions to add, update, and remove objects from the store.

areObjectsLoading

Reducer stores the status of READ operations.

hasObjects

Reducers that stores an object monitoring READ operations.

objectCreating

Reducer stores the status of CREATE operations.

objectUpdating

Reducer stores the status of UPDATE operations.

objectDeleting

Reducer stores the status of DELETE operations.

pageIds

Reducer that stores arrays of object ids mapped to page ids from READ.SUCCESS results.

pages

Reducer that stores metadata from the last READ.SUCCESS result.

Selectors

getObjectIds(state)

Returns an array of all object ids. Not in any particular order.

getObjects(state)

Returns an array of all objects in this collection.

getObjectById(state, id)

Returns a specific object with the specified id.

getObjectsByIds(state, ids)

Returns an array of objects corresponding to the array of ids specified.

areObjectsLoading(state)

Returns true if a READ.REQUEST is still outstanding.

hasObjects(state)

Returns an object { hasObjects, error }.

hasObjects will return true/false if there are objects in this collection AND READ.SUCCESS has returned; otherwise, hasObjects will be null and in the case of READ.ERROR, error will hold the last response's error.

isObjectCreating(state)

Returns true if a CREATE.REQUEST is still outstanding.

isObjectUpdating(state)

Returns true if a UPDATE.REQUEST is still outstanding.

isObjectDeleting(state)

Returns true if a DELETE.REQUEST is still outstanding.

getObjectIdsByPage(state, pageIndex)

Returns an array of object ids for a given page index.

getPageMetadata(state)

Returns an object with metadata from the last paged response of READ.SUCCESS.

{
	itemsPerPage: int,
	totalItems: int,
	totalPages: int
}

Override Defaults

If you would like to supply custom Reducer and/or Selector names, Normalized can handle this for you while maintaining all expected functionality.

In this example we selectively rename some Reducers and some Selectors.

All Reducer and Selector names are required when overriding; so, feel free to follow this approach if you intend to only rename/use some of the Reducers/Selectors.

import Normalized, { Defaults } from '@hart/hart-redux/Normalized';

const reducerNames = Object.assign({}, Defaults.reducerNames, {
	areObjectsLoading: "areFoosLoading",
	hasObjects: "hasFoos",
	objectCreating: "fooCreating",
	objectUpdating: "fooUpdating",
	objectDeleting: "fooDeleting"
});

const selectorNames = Object.assign({}, Defaults.selectorNames, {
	getObjectIds: "getFooIds",
	getObjects: "getFoos",
	getObjectById: "getFooById",
	areObjectsLoading: "areFoosLoading",
	hasObjects: "hasFoos",
	isObjectCreating: "isFooCreating",
	isObjectUpdating: "isFooUpdating",
	isObjectDeleting: "isFooDeleting",
});

const normalized = Normalized(actionTypes, reducerNames, selectorNames);

Result

const normalized = {
	reducers: {
		allIds,
		byIds,
		areFoosLoading,
		hasFoos,
		fooCreating,
		fooUpdating,
		fooDeleting,
		pageIds,
		pages
	},
	selectors: {
		getFooIds,
		getFoos,
		getFooById,
		getObjectsByIds,
		areFoosLoading,
		hasFoos,
		isFooCreating,
		isFooUpdating,
		isFooDeleting,
		getObjectIdsByPage,
		getPageMetadata
	}
}

RequestAction

The RequestAction module makes it simple to define action creators for long promise based operations. This makes it very simple to wire up an api with conditional logic for running the operation and dispatch actions before the request and once it succeeds or errors.

Usage with ActionTypes and Normalized modules

import { ActionTypes, Normalized, RequestAction } from '@hart/hart-redux';

const ActionTypes = ActionTypes("foos");
const normalized = Normalized(actionTypes);
const { selectors } = normalized;

const api = {
	getFoo: fooId => Promise.resolve({ 
		data: [{ id: fooId, name: "Foo!" }]  
	})
}

const loadFoos = RequestAction({
	shouldSkip: (getState, ...params) => selectors.isObjectLoading(getState()),
	operation: ActionTypes.READ,
	promise: (getState, fooId) => api.getFoo(fooId)
});

//Hart-Redux will load the foo(s) into state if you loaded normalized.reducers into your Redux Store
//selectors.getObjectById(state, fooId) === { id: fooId, name: "Foo!" }

Standalone Usage

import { RequestAction } from '@hart/hart-redux';

const ActionTypes = {
	READ: {
		REQUEST: 'FOO_READ_REQUEST',
		SUCCESS: 'FOO_READ_SUCCESS',
		ERROR: 'FOO_READ_ERROR',
	}
}

const Selectors = {
	shouldLoad: (state, ...params) => { ... }
}

const api = {
	getFoo: fooId => Promise.resolve({ 
		data: [{ id: fooId, name: "Foo!" }]  
	})
}

const loadFoos = RequestAction({
	shouldSkip: (getState, ...params) => Selectors.shouldLoad(getState(), ...params),
	operation: ActionTypes.READ,
	promise: (getState, fooId) => api.returnFoos(fooId)
});

await loadFoos(1234);

//State will reflect the outcome of ActionTypes.READ.SUCCESS with the {data} returned from the api.getFoo action

Namespace

The Namespace module applies a namespace to your Selectors so that you can easily organize your top-level modules into your Redux Store without each module having knowledge of the overall store's structure.

Usage

import { Namespace } from '@hart/hart-redux';
or
import { applyNamespace, applyNamespaceToAll } from '@hart/hart-redux/Namespace';

const state = {
	person: {
    	name: "Tester McTesterson", 
    	age: 30
	}
}

const getName = state => state.name;
const getAge = state => state.age;

const getPersonName = applyNamespace("person", getName);
const selectors = applyNamespaceToAll("person", {getName, getAge});

const name = getPersonName(state); // "Tester McTesterson"
const age = selectors.getAge(state); // 30

ModuleConfig

The ModuleConfig module presents a builder pattern for assembling your Reducers, Selectors, ActionTypes, and Action Creators into a single packaged module using a Namespace. This can optionally also remap your Action Creators with ActionTypes and Selectors to reduce interdepedency between the sources that create Action Creators, Reducers, and Selectors.

Usage

This example returns a function that accepts a Namespace before creating the Redux module. This pattern is useful to keep organization of the store out of the individual redux modules.

import { ModuleConfig } from '@hart/hart-redux';

export default function(namespace){
	return new ModuleConfig(namespace)
		.reducers(reducers)
		.selectors(selectors)
		.actionTypes(actionTypes)
		.actions(actions)
		.module();
}

Mapping ActionTypes/Selectors to Action Creators

import { ModuleConfig, ActionTypes, Normalized, RequestAction } from '@hart/hart-redux';

const actionTypes = ActionTypes("bars");
const normalized = Normalized(actionTypes);
const actions = {
	loadBar: (ActionTypes, Selectors) => RequestAction({
		shouldSkip: (getState, ...params) => Selectors.isObjectLoading(getState()),
		operation: ActionTypes.READ,
		promise: (getState, bar) => Promise.resolve({data: bar})
	})
}

export default function(namespace){
	return new ModuleConfig(namespace)
		.reducers(normalized.reducers)
		.selectors(normalized.selectors)
		.actionTypes(actionTypes)
		.buildActions(actions)
		.module();
}

api

Each function, except module(), returns the ModuleConfig object for chaining.

selectors(selectors)

Accepts a map of selector functions, maps each to the Namespace, and finally adds each into the ModuleConfig.

Can be called multiple times and successive calls will add new keys and replace same-keyed values.

reducer(reducer)

Accepts a single reducer function. Use when you have a single or combined reducer.

Successive calls will overwrite the reducer assigned to the ModuleConfig.

If both reducer() and reducers() are called, the reducer() call will prevail.

reducers(reducers)

Accepts a map of reducer functions and adds each into the ModuleConfig.

Can be called multiple times and successive calls will add new keys and replace same-keyed values.

If both reducer() and reducers() are called, the reducer() call will prevail.

actionTypes(actionTypes)

Accepts a map of ActionTypes and adds each into the ModuleConfig.

Can be called multiple times and successive calls will add new keys and replace same-keyed values.

actions(actions<map>)

Accepts a map of Action/Creator functions and adds each into the ModuleConfig.

Can be called multiple times and successive calls will add new keys and replace same-keyed values.

buildActions(actions<map>)

Accepts a map of Action/Creator functions, maps each expecting the signature below, and finally adds each resulting function into the ModuleConfig.

Can be called multiple times and successive calls will add new keys and replace same-keyed values.

(ActionTypes, Selectors) => fn

module()

Returns the assembled Redux module.

MakeStore

MakeStore is a utility function to combine initialState, middleware, enhancers, and a reducer into a Redux store.

Usage

import { combineReducers } from 'redux';
import { MakeStore } from '@hart/hart-redux';

const store = MakeStore({
	reducer: combineReducers({ reducer1, reducer2 }),
	enhancers: [ enhancer1, enhancer2 ],
	middleware: [ middlewareFn1, middleWareFn2 ],
	initialState: {}
});

StoreConfig

The StoreConfig module presents a builder pattern for assembling a Redux store. When combined with modules made with ModuleConfig, a Redux store can be created in a very readable and terse manner.

Usage

import { StoreConfig } from '@hart/hart-redux';

const storeConfig = new StoreConfig({ initialState: {} });

import thunkMiddleware from 'redux-thunk';

import Foos from './Foos'; //Module assembled using ModuleConfig

storeConfig
.addEnhancer(enhancerFunction)
.addMiddleware(thunkMiddleware)
.addModule(Foos("Foos")); //Passing "Foos" as the Namespace for the Foos modules

export const store = storeConfig.getStore();

constructor

The StoreConfig constructor accepts an object with the following options.

reducers

Map of reducer functions keyed by their Namespace.

enhancers

Array of enhancer functions.

middleware

Array of middleware functions

initialState

Object to represent the initial state of the Redux store.

_combineReducers

Override the default 'redux' combineReducers function when using getStore().

onModuleLoaded

Function to call for each instance of addModule called.

(namespace, module) => {}

api

Each function, except get() and getStore(), returns the StoreConfig object for chaining.

addReducer(namespace, reducer)

Adds a reducer using namespace.

addReducers(namespace, reducers)

Combines and adds the resulting combined reducer using namespace.

addModule(module)

Adds an entire Redux module to this store.

A Redux module is defined as an object following this pattern.

Modules created with ModuleConfig follow this pattern.

const module = {
	reducer: fn, //reducer or reducers will be added using the module's namespace.
	reducers: {}, // passing both reducer and reducers will result in an Error.
	namespace: "", //required
	... any additional properties //optional
}

addEnhancer(enhancer)

Adds an enhancer function into the config.

addMiddleware(middleware)

Adds a middleware function into config.

get()

get() returns a copy of the config object if you intend to create a Redux store without getStore().

getStore()

getStore() creates and returns a new Redux Store using the MakeStore utility. This will use 'combineReducers' from the 'redux' library to combine reducers added to this config. If does not fit your use case, you can instead use get() to get the final configuration; or pass in _combineReducers in the StoreConfig constructor.

Author

• Mark Zepeda