No description, website, or topics provided.
Switch branches/tags
Clone or download
Latest commit 86167eb May 17, 2016
Permalink
Failed to load latest commit information.
src tweak action names Feb 23, 2016
test Initial commit Feb 23, 2016
.babelrc Initial commit Feb 23, 2016
.gitignore Initial commit Feb 23, 2016
.npmignore Initial commit Feb 23, 2016
.travis.yml Create .travis.yml Feb 23, 2016
Makefile Initial commit Feb 23, 2016
Readme.md Update Readme.md May 16, 2016
package.json Update package.json Feb 23, 2016

Readme.md

redux-subscribe

js-standard-style

Subscribe to a path in your redux state atom

Installation

$ npm install redux-subscribe

Usage

redux-subscribe is a modular primitive to providing a context-like abstraction in a component framework. It gives you the ability to dispatch an action in response to the change of a path in your global state atom. This allows you to create a Context component which will dispatch an action that updates its own local state in response to a change in the global state atom. The context component may then pass down that piece of state to its children, e.g.

function render ({props}) {
  return (
    <Context path='url'>
      {
        url => <a href={props.href} class={{active: url === href}}>{props.text}</a>
      }
    </Context>
  )
}

Example <Context/> implementation (in vdux)

import {subscribe, unsubscribe} from 'redux-subscribe'

/**
 * Setup the subscription on create, so that it dispatches a local STORE_VALUE
 * action anytime the path we're interested in changes.
 */

function onCreate ({props, key, local}) {
  return subscribe(props.path, key, local(storeValue))
}

/**
 * Render all children that are functions by passing them the current value
 * of the path we're watching
 */

function render ({children, state}) {
  return children.map(child => isFunction(child) ? child(state.value) : child)
}

/**
 * If the path we want to watch changes, cancel the old subscription
 * and create a new one
 */

function onUpdate (prev, next) {
  return [
    unsubscribe(prev.props.path, prev.key),
    subscribe(next.props.path, next.key, local(storeValue))
  ]
}

/**
 * Preserve the global value in our local state
 */

function reducer (state, action) {
  if (action.type === 'STORE_VALUE') {
    return {
      ...state,
      value: action.payload
    }
  }

  return state
}

function storeValue (path, prev, next) {
  return {
    type: 'STORE_VALUE',
    payload: next
  }
}

/**
 * Remove the subscription when the component is removed
 */

function onRemove ({props, key}) {
  return unsubscribe(props.path, key)
}

export default {
  onCreate,
  render,
  reducer,
  onRemove
}

Comparison to redux-watch

redux-watch is a similar redux-related utility, but with two important differences:

  • Performance. The most natural ways to use redux-watch in your components would create one watcher for each component instance. This scales very poorly as your component tree grows large. redux-subscribe maintains a map of all current subscriptions, so only has to lookup the values and compare them once per unique subscription, which scales very well in most applications.
  • redux-subscribe is a middleware whereas redux-watch wraps your store. This allows redux-subscribe to sit in the middle and setup/teardown subscriptions in response to actions, which lets you keep everything pure and internal to redux.

Performance

The performance of redux-subscribe is proportional to the number of unique paths that are subscribed to. This means that it scales very well, provided you aren't subscribing to lots (as in hundreds or thousands) of different things. Each time the state updates, each unique path that has been subscribed to is checked for a change, if it has been changed, the listeners are called and their results dispatched.

License

MIT