@kubric/reducer-factory v1.1.0

Reducer factory

Bulk of the state operations performed redux reducers involve

• Extracting values from payload and assigning it to state
• Appending/prepending/inserting into the state objects/arrays/strings from action payload
• Turning on, turning off or toggling boolean values

Reducer factory enables developers to configure all these operations via JSON and so that code needs to be written only for complex state operations.

Table of contents

• Installation
• Usage
• Examples
• ReducerFactory class
  • getReducers()
  • getReducer()
• Reducer definition
  • ops
  • from,to
  • at
  • transform
  • defaultValue

Installation

yarn add @kubric/reducer-factory

or

npm i @kubric/reducer-factory

Usage

import ReducerFactory from "@kubric/reducer-factory";
import { combineReducers } from "redux";

const factory = new ReducerFactory();

const reducersConfig = {
  //config for reducer1
  reducer1: { ... },
  //config for reducer2
  reducer2: { ... }
};

/**
 * Returns the following object
 * {
 *    reducer1: () => {
 *      //reducer for reducer1 config
 *    },
 *    reducer2: () => {
 *      //reducer for reducer2 config
 *    }
 */
const reducersObject = factory.getReducers(reducersConfig);

const reducer = combineReducers(reducersObject);

const singleReducerConfig = { ... };
const singleReducer = factory.getReducer(singleReducerConfig);

Examples

1. Basic switch reducer
2. Advanced switch reducer
3. Assign reducer
4. Insert reducers
5. Transforms
6. Default values
7. Reducer delegation
8. from,to cases
9. actions config
10. Shorthands
11. Macros
12. Custom macros
13. Custom ops

ReducerFactory class

import ReducerFactory from "@kubric/reducer-factory";

const factory = new ReducerFactory(options);

options can be a JSON with the following properties

• ops: Handlers for custom ops
• macros: Handlers for custom macros
• payloadPath: Defines the base path w.r.t the dispatched action object from where from property for ops will be resolved.

getReducers()

The factory instance's getReducers method takes in a JSON object in the format given below as its argument and returns an object that can be passed directly to combineReducers to get the final reducer

/**
 * Returns an object that can be passed directly to redux combineReducers function
 */
const reducers = reducerFactory({
  reducers: {
      //Used when multiple actions are supposed to make changes to the same piece of state
  },
  types: {
      //Used when a single action should trigger the same operation in multiple reducers
  }
});

getReducer()

The factory instance's getReducer method takes in a JSON config for a single reducer and returns the reducer function for that config

Reducer definition

The definition for a reducer is provided as a JSON in the following with the following properties

ops

State operations supported by the library are defined in the ops object exported by the library.

import { ops } from "@kubric/reducer-factory"

A reducer can be configured to perform any number of state operations via its ops array. Every entry of the ops array is an object that defines a mapping between actions that are dispatched to the state and the operation that should be performed for that action. An entry of the array can have the following properties

Eg.

{
  reducers: {
    //Defines a reducer named loaded
    loaded: {

      //with default state 0
      defaultState: 0,

      //Defines array of operations that need to be performed
      ops: [

        //If the incoming action type is 'LOADING', the state of the reducer is made false
        {
          types: ['LOADING'],
          op: types.OFF
        },

        //If the incoming action is 'LOADED', "action.payload" is assigned to the state
        {
          types: ['LOADED'],
          op: types.ASSIGN
        }
      ]
    }
  }
}

from, to

The combination of from, transform, op and to determines what is extracted from action.payload, what transformation is applied to it, how it is applied to the state of the reducer and where in the state it gets applied. The value is extracted from action.payload as defined by from, will go through the transform function if defined and will then be applied to the state as defined by the op and the to parameter. The different combinations of from and to are listed below

from will not be taken into consideration for any of the boolean ops - ops.OFF, ops.ON and ops.TOGGLE

at

at is used along with ops.INSERT to specify the index at which the extracted value from the payload should be inserted.

If the index provided exceeds the length of the array, the indices from array.length to at - 1 will be filled with undefined

transform

transform is a function used to transform the extracted value from the payload before it is applied to the state. The function should return the final value that needs to be applied to the state. The function is invoked with the following arguments

• extractedValue: value extracted from the action payload
• currentState: state of the reducer before applying the action
• action: action that was dispatched to the state

There are 2 types of transform functions depending on where they are defined in the config

1. Operation level transform: Defined inside an entry of the ops array. If the incoming action triggers an op entry, it's tranform function will be called if defined.

2. Reducer level transform: Defined outside the ops array. If the op triggered for an incoming action does not have a transform defined, then it's reducer level transform function will be invoked if defined.

   Multiple tranform functions may be called for an incoming action if the action has been registered to perform multiple ops in the same reducer

   Eg.

   {
    reducers: {
      //Defines a reducer named loaded
      name: {
   
        //with default state ""
        defaultState: "",
   
        //Reducer level transform. Will be called if any of the ops in the ops array matches an 
        // incoming action and it does not have a transform defined
        transform: extractedValue => `${extractedValue}_reducer_tranform`,
   
        //Defines array of operations that need to be performed
        ops: [
   
          //If the incoming action type is 'LOADING', the state of the reducer is made false
          {
            types: ['WITH_OP_TRANSFORM'],
            op: types.ASSIGN,
            transform: extractedValue => `${extractedValue}_op_tranform`
          },
   
          //If the incoming action is 'LOADED', "action.payload" is assigned to the state
          {
            types: ['WITH_REDUCER_TRANSFORM'],
            op: types.ASSIGN
          }
        ]
      }
    }
   }

### defaultValue

If the value that is extracted from `action.payload` happens to be `undefined`, the value provided in `defaultValue` will be applied.

> If there is a `transform` function defined for the reducer and the `defaultValue` gets picked up for some action type, this default value will undergo the transformation before it is applied to the state

There are 2 places where `defaultValue` may be picked up from

1. Operation level `defaultValue`: Defined inside an entry of the `ops` array. If the incoming action triggers an `op` entry, and the extracted value turns out to be `undefined`, then this value is picked as the default value.
2. Reducer level `defaultValue`: Defined outside the `ops` array. If the `op` triggered for an incoming action does not have a `defaultValue`  defined, and the extracted value turns out to be `undefined`, then this value is picked as the default value.