Impure option

README.md

@@ -15,7 +15,7 @@ Performant and flexible.
 - [Quick Start](#quick-start)
 - [API](#api)
   - [`<Provider store>`](#provider-store)
-  - [`connect([mapStateToProps], [mapDispatchToProps], [mergeProps])`](#connectmapstatetoprops-mapdispatchtoprops-mergeprops)
+  - [`connect([mapStateToProps], [mapDispatchToProps], [mergeProps], [options])`](#connectmapstatetoprops-mapdispatchtoprops-mergeprops-options)
 - [Troubleshooting](#troubleshooting)
 - [License](#license)
 
@@ -226,7 +226,7 @@ React.render(
 );
 ```
 
-### `connect([mapStateToProps], [mapDispatchToProps], [mergeProps])`
+### `connect([mapStateToProps], [mapDispatchToProps], [mergeProps], [options])`
 
 Connects a React component to a Redux store.
 
@@ -241,6 +241,10 @@ Instead, it *returns* a new, connected component class, for you to use.
 
 * [`mergeProps(stateProps, dispatchProps, ownProps): props`] \(*Function*): If specified, it is passed the result of `mapStateToProps()`, `mapDispatchToProps()`, and the parent `props`. The plain object you return from it will be passed as props to the wrapped component. You may specify this function to select a slice of the state based on props, or to bind action creators to a particular variable from props. If you omit it, `Object.assign({}, ownProps, stateProps, dispatchProps)` is used by default.
 
+* [`options`] *(Object)* If specified, further customizes the behavior of the connector.
+
+  * [`pure`] *(Boolean)*: If true, implements `shouldComponentUpdate` and shallowly compares the result of `mergeProps`, preventing unnecessary updates, assuming that the component is a "pure" component and does not rely on any input or state other than its props and the Redux store. *Defaults to `true`.*
+
 #### Returns
 
 A React component class that injects state and action creators into your component according to the specified options.
@@ -460,6 +464,30 @@ render() {
 Conveniently, this gives your components access to the router state!
 You can also upgrade to React Router 1.0 which shouldn’t have this problem. (Let us know if it does!)
 
+### My views aren't updating when something changes outside of Redux
+
+If your views depend on global state or context, you might find that views decorated with `connect()` will fail to update.
+
+> This is because `connect()` implements [shouldComponentUpdate](https://facebook.github.io/react/docs/component-specs.html#updating-shouldcomponentupdate) by default, assuming that your component will produce the same results given the same props and state. This is a similar concept to React's [PureRenderMixin](https://facebook.github.io/react/docs/pure-render-mixin.html).
+
+The _best_ solution to this is to make sure that your components are pure and pass any external state to them via props. This will ensure that your views do not re-render unless they actually need to re-render and will greatly speed up your application.
+
+If that's not practical for whatever reason (for example, if you're using a library that depends heavily on Context), you can pass the `pure: false` option to `connect()`:
+
+```
+function mapStateToProps(state) {
+  return { todos: state.todos };
+}
+
+const options = {
+  pure: false
+};
+
+export default connect(mapStateToProps, null, null, options)(TodoApp);
+```
+
+This will remove the assumption that `TodoApp` is pure and cause it to update whenever its parent component renders.
+
 ### Could not find "store" in either the context or props
 
 If you have context issues,

src/components/createConnect.js

@@ -11,6 +11,9 @@ const defaultMergeProps = (stateProps, dispatchProps, parentProps) => ({
   ...stateProps,
   ...dispatchProps
 });
+const defaultOptions = {
+  pure: true
+};
 
 function getDisplayName(Component) {
   return Component.displayName || Component.name || 'Component';
@@ -23,7 +26,7 @@ export default function createConnect(React) {
   const { Component, PropTypes } = React;
   const storeShape = createStoreShape(PropTypes);
 
-  return function connect(mapStateToProps, mapDispatchToProps, mergeProps) {
+  return function connect(mapStateToProps, mapDispatchToProps, mergeProps, options) {
     const shouldSubscribe = Boolean(mapStateToProps);
     const finalMapStateToProps = mapStateToProps || defaultMapStateToProps;
     const finalMapDispatchToProps = isPlainObject(mapDispatchToProps) ?
@@ -32,6 +35,7 @@ export default function createConnect(React) {
     const finalMergeProps = mergeProps || defaultMergeProps;
     const shouldUpdateStateProps = finalMapStateToProps.length > 1;
     const shouldUpdateDispatchProps = finalMapDispatchToProps.length > 1;
+    const finalOptions = {...defaultOptions, ...options} || defaultOptions;
 
     // Helps track hot reloading.
     const version = nextVersion++;
@@ -88,7 +92,7 @@ export default function createConnect(React) {
         };
 
         shouldComponentUpdate(nextProps, nextState) {
-          return !shallowEqual(this.state.props, nextState.props);
+          return !finalOptions.pure || !shallowEqual(this.state.props, nextState.props);
         }
 
         constructor(props, context) {

test/components/connect.spec.js

@@ -1064,5 +1064,54 @@ describe('React', () => {
       expect(decorated.getWrappedInstance().someInstanceMethod()).toBe(someData);
       expect(decorated.refs.wrappedInstance.someInstanceMethod()).toBe(someData);
     });
+
+    it('should wrap impure components without supressing updates', () => {
+      const store = createStore(() => ({}));
+
+      class ImpureComponent extends Component {
+        static contextTypes = {
+          statefulValue: React.PropTypes.number
+        };
+
+        render() {
+          return <Passthrough statefulValue={this.context.statefulValue} />;
+        }
+      }
+
+      const decorator = connect(state => state, null, null, { pure: false });
+      const Decorated = decorator(ImpureComponent);
+
+      class StatefulWrapper extends Component {
+        state = {
+          value: 0
+        };
+
+        static childContextTypes = {
+          statefulValue: React.PropTypes.number
+        };
+
+        getChildContext() {
+          return {
+            statefulValue: this.state.value
+          };
+        }
+
+        render() {
+          return <Decorated />;
+        };
+      }
+
+      const tree = TestUtils.renderIntoDocument(
+        <ProviderMock store={store}>
+          <StatefulWrapper />
+        </ProviderMock>
+      );
+
+      const target = TestUtils.findRenderedComponentWithType(tree, Passthrough);
+      const wrapper = TestUtils.findRenderedComponentWithType(tree, StatefulWrapper);
+      expect(target.props.statefulValue).toEqual(0);
+      wrapper.setState({ value: 1 });
+      expect(target.props.statefulValue).toEqual(1);
+    });
   });
 });