redux-detector

Redux Detector

Redux enhancer for pure detection of state changes.

Warning: API is not stable yet, will be from version 1.0

Installation

Redux Detector requires Redux 3.1.0 or later.

npm install --save redux-detector

This assumes that you’re using npm package manager with a module bundler like Webpack or Browserify to consume CommonJS modules.

To enable Redux Detector, use createDetectableStore:

import { createDetectableStore } from 'redux-detector';
import rootReducer from './reducers/index';
import rootDetector from './detectors/index';

const store = createDetectableStore(
  rootReducer,
  rootDetector
);

or if you have more complicated store creation, use createStore with createDetectorEnhancer:

import { createStore } from 'redux';
import { createDetectorEnhancer } from 'redux-detector';
import rootReducer from './reducers/index';
import rootDetector from './detectors/index';

const store = createStore(
  rootReducer,
  createDetectorEnhancer(rootDetector)
);

Motivation

Redux Detector enhancer allows you to use state changes detectors with redux. Detector is a simple and pure function which compares two states and returns action or list of actions for some states configurations. It can be used for reacting on particular state transitions.

type Detector<S> = <A extends Action>(prevState: S | undefined, nextState: S) => A | A[] | void

For example detector that checks if number of rows exceed 100 looks like this:

function rowsLimitExceededDetector(prevState, nextState) {
  if (prevState.rows.length <= 100 && nextState.rows.length > 100) {
    return { type: ROWS_LIMIT_EXCEEDED };
  }
}

You can also return array of actions to dispatch them.

Thanks to detectors purity they are predictable and easy to test. There is no problem with features like time-travel, etc.

Composition

Redux store can handle only one detector (and one reducer). But don't worry - you can combine them. To do this, use combineDetectors function.

// ./detectors/rootDetector.js
import { combineDetectors } from 'redux-detector';
import { fooDetector } from './fooDetector';
import { barDetector } from './barDetector';

export default combineDetectors(fooDetector, barDetector);

Detectors by default operates on global state, but if you want to make some reusable detector that is not binded to global state, you can use mountDetector function. With factory pattern it becomes very elastic.

// ./detectors/limitExceedDetector.js
export function createLimitExceedDetector(limit, action) {
  return function limitExceedDetector(prevState, nextState) {
    if (prevState <= limit && nextState > limit) {
      return action;
    }
  }
}

// ./detectors/rowsLimitExceedDetector.js
import { mountDetector } from 'redux-detector';
import { createLimitExceeedDetector } from './limitExceedDetector';

export const rowsLimitExceedDetector = mountDetector(
  state => state.rows.length,
  createLimitExceedDetector(100, ROWS_LIMIT_EXCEEDED)
);

Of course examples above are very trivial, but you can use it to solve more common problems like keeping state consistent (you can for example schedule resource fetch if some parameters changed).

Code Splitting

Redux Detector provides replaceDetector method on DetectableStore interface (store created by Redux Detector). It's similar to replaceReducer - it changes detector and dispatches { type: '@@detector/INIT' }.

Typings

If you are using TypeScript, you don't have to install typings - they are provided in npm package.

License

MIT