Observe Redux state changes and dispatch actions on change
Branch: master
Clone or download
xuoe 2.0.2
    - fix: shallowEquals() now checks for symbols and null values. (#4)
Latest commit 02d6e3e Jun 13, 2017
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src 2.0.2 Jun 13, 2017
test 2.0.2 Jun 13, 2017
.babelrc 1.0.0 Feb 7, 2016
.eslintignore initial commit Jan 28, 2016
.eslintrc initial commit Jan 28, 2016
.gitignore
.npmignore use rimraf instead of rm Feb 8, 2016
.travis.yml 1.0.0 Feb 7, 2016
LICENSE.md
README.md 2.0.2 Jun 13, 2017
package.json 2.0.2 Jun 13, 2017

README.md

redux-observers

Build Status Coverage Status NPM Version

Observe Redux state changes and dispatch actions on change.

Installation

Assuming you're using npm and a module bundler capable of consuming CommonJS modules:

npm install redux-observers --save

Usage

First, create a store object as you normally would, then create the necessary observers and pass them as arguments to observe():

import { observer, observe } from 'redux-observers'

const myObserver = observer(
  state => state.slice.of.interest,
  (dispatch, current, previous) => {
    expect(previous).to.be.ok()
    expect(current).to.not.eql(previous)
    dispatch({ type: 'SLICE_CHANGE', payload: {...} })
  }
)

observe(store, [myObserver, ...myOtherObservers])

That's the gist of it.

API

observer([mapper], dispatcher, [options]) => observerFunc

Creates an observer.

  • mapper(state) => mappedState (Function)

    Specifies which state slice(s) should be observed by returning a plain object (or any other value) extracted from the store's state. It is similar in vein to mapStateToProps() provided by react-redux.

    If no mapper is provided, the entire store state is mapped by default.

  • dispatcher(dispatch, currentState, previousState) (Function)

    Called whenever the mapped-over state changes.

  • options (Object)

    A local options object, whose values are applicable only in the context of the returned observerFunc. Any option provided here takes precedence over its global and default equivalents.

Note that if care is not exercised, infinite cycles may be created between a mapper and a dispatcher.

observe(store, observers, [options]) => unsubscribeFunc

Listens for store updates and applies given observers over the store state.

  • store (Object)

    The Redux store object.

  • observers (Array)

    An array of (observer) functions, where each member must be the result of calling observer().

  • options (Object)

    A global options object, whose values are applicable only in the context of the provided observers (i.e., observe()ing a store multiple times using the same observers, but providing different global options, results in a different behavior, as prescribed by that options object). Any option provided here takes precedence over its default value.

Options

A plain object that may be provided to observe(,, options) to describe how a set of observers must behave, or to observer(,, options) to describe how a particular observer must behave.

  • skipInitialCall (Boolean, defaults to true)

    Specifies whether dispatchers must be called immediately after Redux dispatches its @@redux/INIT action.

    If set to false, dispatchers are initially called with an undefined "previous" state; otherwise, and by default, a dispatcher is only called after the "previous" state is set (i.e., after @@redux/INIT is dispatched and the store's reducers had a chance to return their initial state).

  • equals: (currentState, previousState) => Boolean (Function, defaults to shallowEquals)

    Specifies how the previous state should be compared with the current one. Its return value must be a Boolean, which is used to determine whether a dispatcher should be called. Note that, by default, values are compared in a shallow manner via shallowEquals(), which should satisfy the common use case.

shallowEquals(a, b) => Boolean

The default comparsion helper. It determines whether two state values (be they plain objects or primitive values) are equal.