general-reducer
General purpose reducer generator
- full documentation can be found on https://andres-kovalev.github.io/general-reducer/
Description
general-reducer
provides utilities to generate universal reducer with corresponding actions.
Installation
As any other npm package general-reducer
can be added to your project by following command:
npm i -S general-reducer
API
Universal reducer
general-reducer
package provides general purpose reducer to perform most common operations on store. You just need to configure your store with it.
with react hook:
import React, { useReducer } from 'react'; import { reducer } from 'general-reducer'; const Component = () => { const [ value, dispatch ] = useReducer(reducer); ... }
with redux:
import { createStore } from 'redux' import { reducer } from 'general-reducer'; const store = createStore(reducer);
with react-easy-flux:
import { createStorage } from 'react-easy-flux'; import { reducer } from 'general-reducer'; const { Provider, useStorage, useActions } = createStorage(reducer);
Since
general-reducer
uses immutable-object-update under the hood, it performs immutable state update and returns frozen object.
Built-in actions
general-reducer
exposes ACTIONS
map object with actions for most common operations with state:
- all(action)
- insert(path, value)
- insertAll(path, values)
- pop(path, n)
- push(path, value)
- pushAll(path, values)
- remove(path, n)
- set(path, value)
- shift(path, n)
- unshift(path, value)
- unshiftAll(path, values)
Most of actions consumes at least 1 argument - path
to updated element, it might be an array of items or dot-separated string. When action dispatched reducer will apply corresponding operation from immutable-state-update package:
import { reducer, ACTIONS } from 'general-reducer';
const state = {
a: {
a1: 1,
a2: 2
},
b: {
b1: 3,
b2: 4
}
};
const updated = reducer(state, ACTIONS.set('b.b1', 5));
// or
const updated = reducer(state, ACTIONS.set([ 'b', 'b1' ], 5));
As a result we will receive new object with structure below:
{
a: {
a1: 1,
a2: 2
},
b: {
b1: 3,
b2: 5
}
}
Action combination
Since general-reducer
uses under the hook, we're able to use composite action to combine several simple actions and possibly improve performance a bit:
const trim = (path, n) => ACTIONS.all(
ACTIONS.shift(path, n)
ACTIONS.pop(path, n)
);
const updated = reducer(state, trim('a.b', 2));
Custom actions
It is possible to add custom actions to perform some complex updates. To so createGeneralReducer()
function is exposed. It consumes map object with custom action update functions. Each update function will consume part of a state as an argument and should return updated value.
const {
reducer,
ACTIONS
} = createGeneralReducer({
selectAll: items => items.map(
item => ({ ...item, selected: true })
),
unselectAll: items => items.map(
item => ({ ...item, selected: false })
),
removeSelected: items => items.filter(
({ selected }) => !selected
)
});
Returned actions will consume path to state piece to be updated.
const state = {
items: [
{ selected: true, text: 'Steal pants' },
{ selected: false, text: '?????' },
{ selected: false, text: 'Profit!' }
]
};
const updated = reducer(state, ACTIONS.removeSelected('items'));
/*
{
items: [
{ selected: false, text: '?????' },
{ selected: false, text: 'Profit!' }
]
};
*/
If you need any additional arguments in your update function just pass those into action creator after path:
const {
reducer,
ACTIONS
} = createGeneralReducer({
add: (value, diff) => value + diff
});
const state = {
a: 10
};
const updated = reducer(state, ACTIONS.add('a', 5));
/*
{
a: 15
}
*/
Actions namespace
By default general-reducer
uses 'general'
as a namespace for all actins, it means two different general reducers will have the same action types:
const { TYPES } = createGeneralReducer({
customCase: (...) => ...
});
/*
TYPES = {
insert: 'general.insert',
insertAll: 'general.insertAll',
pop: 'general.pop',
...
customCase: 'general.customCase'
}
*/
Because of that it can be problematic to combine general reducers. To generate unique action types just provide different namespace as 2nd argument of createGeneralReducer()
function:
const { TYPES } = createGeneralReducer({
customCase: (...) => ...
}, 'customNamespace');
/*
TYPES = {
insert: 'customNamespace.insert',
insertAll: 'customNamespace.insertAll',
pop: 'customNamespace.pop',
...
customCase: 'customNamespace.customCase'
}
*/
Definitely, in most cases to extend general reducer it's better to provide custom actions or include general reducer into custom one:
function customReducer(state, action) {
switch (action.type) {
...
default:
return generalReducer(state, action);
}
}