README.md

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);
    }
}