Merge branch 'master' of http://github.com/wbuchwalter/ng-redux

Author: wbuchwalter

README.md

@@ -1,19 +1,20 @@
 # ng-redux
 Angular bindings for [Redux](https://github.com/gaearon/redux).
 
-##Warning: The API is unstable and subject to breaking changes until Redux@1.0.0 is released.
+#####Warning: The API is unstable and subject to breaking changes until Redux@1.0.0 is released.
 
-![Travis](https://travis-ci.org/wbuchwalter/ng-redux.svg?branch=master)
+[![build status](https://img.shields.io/travis/wbuchwalter/ng-redux/master.svg?style=flat-square)](https://travis-ci.org/wbuchwalter/ng-redux)
+[![npm version](https://img.shields.io/npm/v/ng-redux.svg?style=flat-square)](https://www.npmjs.com/package/ng-redux)
 
 ## Overview
 
 ngRedux lets you easily connect your angular components with Redux.
 the API is straightforward: 
 
 ```JS
-$ngRedux.connect(selector, callback);
+$ngRedux.connect(selector, callback, disableCaching = false);
 //OR
-$ngRedux.connect([selector1, selector2, ...], callback);
+$ngRedux.connect([selector1, selector2, ...], callback, disableCaching = false);
 ```
 
 Where selector is a function taking for single argument the entire redux Store's state (a plain JS object) and returns another object, which is the slice of the state that your component is interested in.
@@ -28,6 +29,9 @@ If you haven't, check out [reselect](https://github.com/faassen/reselect), an aw
 
 This returned object will be passed as argument to the callback provided whenever the state changes.
 ngRedux checks for shallow equality of the state's selected slice whenever the Store is updated, and will call the callback only if there is a change.
+##### Important: It is assumed that you never mutate your states, if you do mutate them, ng-redux will not execute the callback properly.
+See [Redux's doc](http://gaearon.github.io/redux/docs/basics/Reducers.html) to understand why you should not mutate your states.
+If you have a good reason to mutate your states, you can still [disable caching](#Disable-caching) altogether.
 
 
 ## Getting Started
@@ -47,7 +51,7 @@ angular.module('app', ['ngRedux'])
   });
 ```
 
-### Usage
+#### Usage
 ```JS
  export default function todoLoader() {
   return {
@@ -70,7 +74,7 @@ class TodoLoaderController {
 }
 ```
 
-### Note: The callback provided to ```connect``` will be called once directly after creation to allow initialization of your component states
+##### Note: The callback provided to ```connect``` will be called once directly after creation to allow initialization of your component states
 
 
 
@@ -110,14 +114,22 @@ destroy() {
 ```
 
 
-### Accessing Redux' Store
+#### Accessing Redux' Store
 You don't need to create another service to get hold of Redux's store (although you can).
 You can access the store via ```$ngRedux.getStore()```:
 
 ```JS
 redux.bindActionCreators(actionCreator, $ngRedux.getStore().dispatch);
 ```
 
+#### Disabling caching
+Each time Redux's Store update, ng-redux will check if the slices specified via 'selectors' have changed, and if so will execute the provided callback.
+You can disable this behaviour, and force the callback to be executed even if the slices didn't change by setting ```disableCaching``` to true:
+
+```JS
+reduxConnector.connect(state => state.todos, todos => this.todos = todos, true);
+```
+
 
 ### Example:
 An example can be found here (in TypeScript): [tsRedux](https://github.com/wbuchwalter/tsRedux/blob/master/src/components/regionLister.ts).