Merge 734e407 into 3fea3d3

README.md

@@ -1,8 +1,7 @@
 # React Hook Store
 [![npm version](https://badge.fury.io/js/react-hookstore.svg)](https://badge.fury.io/js/react-hookstore) [![Build Status](https://travis-ci.org/jhonnymichel/react-hookstore.svg?branch=master)](https://travis-ci.org/jhonnymichel/react-hookstore) [![Coverage Status](https://coveralls.io/repos/github/jhonnymichel/react-hookstore/badge.svg?branch=master)](https://coveralls.io/github/jhonnymichel/react-hookstore?branch=master)
 
-A very simple and small (1k gzipped!) state management lib for React that uses the bleeding edge React's `useState` hook.
-Which basically means no magic behind the curtains, only pure react APIs being used to share state across components.
+A very simple and small (less than 2k gzipped!) state management lib for React using hooks.
 
 Try it on [Codesandbox!](https://codesandbox.io/s/r58pqonkop)
 
@@ -11,7 +10,8 @@ Try it on [Codesandbox!](https://codesandbox.io/s/r58pqonkop)
 - Usage
   - [Basic](#usage_basic)
   - [Referencing stores](#usage_namespace)
-  - [Reducer powered stores](#usage_reducer)
+  - [Using reducers to update state](#usage_reducer)
+  - [Optimizing performance](#optimizing_performance)
   - [More examples](https://codesandbox.io/s/r58pqonkop)
 - API
   - [createStore](#api_createStore)
@@ -30,9 +30,7 @@ You can install the lib through NPM or grab the files in the `dist` folder of th
 ## <a name="usage">Usage</a>
 ### <a name="usage_basic">Basic</a>
 
-This is the most basic implementation of the library. create a store with its initial state.
-Later, call `useStore` inside components to retrieve its state and setState method.
-The value passed as the first argument to the setState method will be the new state. no reducer required (but you can use a reducer, see the advanced example down below).
+This is the most basic implementation of the library:
 
 ```javascript
 import React from 'react';
@@ -41,7 +39,6 @@ import { createStore, useStore } from 'react-hookstore';
 createStore('clickStore', 0);
 
 function StatefullHello() {
-  // just use the useStore method to grab the state and the setState methods
   const [ timesClicked, setClicks ] = useStore('clickStore');
 
   return (
@@ -54,7 +51,6 @@ function StatefullHello() {
 }
 
 function AnotherComponent() {
-  // you can name the state whatever you want
   const [ timesClicked ] = useStore('clickStore');
   return (
     <div>
@@ -64,9 +60,13 @@ function AnotherComponent() {
   )
 }
 ```
+Steps to reproduce:
+
+- Create a store with its initial state.
+- Later, call `useStore` inside components to retrieve its state and setState method, that we called timesClicked and setClicks.
+- The value passed as the first argument to the setClicks method will be the new state.
 
 ### <a name="usage_namespace">Referencing stores</a>
-It is possible to create multiple stores in an app.
 Stores can be referenced by using their instance that is returned by the createStore method, as well as using their name.
 
 ```javascript
@@ -95,10 +95,10 @@ function StatefullHello() {
   );
 }
 ```
-Both methods can be used and mixed according to the needs, but we recomend using the instance identifiers.
+Both methods can be used and mixed according to the needs, but it is recomended to use the instance identifiers.
 
-### <a name="usage_reducer">Reducer powered stores</a>
-We can delegate the state management to reducers (just like redux!) if we want.
+### <a name="usage_reducer">Using reducers to update state</a>
+We can delegate the state management to reducers (just like redux!) if we want:
 ```javascript
 import React from 'react';
 import { createStore, useStore } from 'react-hookstore';
@@ -168,49 +168,60 @@ function TodoList() {
 
 export { TodoList, AddTodo };
 ```
+
+Steps to reproduce:
+
+- Create a store with an aditional third parameter: a reducer function.
+- Later, call `useStore` inside components to retrieve its state and dispatch method.
+- call dispatch and provide data as the first argument. Although data can be anything, we are using the pattern of `{ type, payload }`, made popular by redux.
+
+### Optimizing performance
+
 ### More examples
 Check out the [Codesandbox demo!](https://codesandbox.io/s/r58pqonkop)
 
 ## Methods API
-### <a name="api_createStore">`createStore(name:String, state?:*, reducer?:Function):StoreInterface`</a>
+### <a name="api_createStore">`createStore(name, state?, reducer?) -> StoreInterface`</a>
 Creates a store to be used across the entire application. Returns a StoreInterface object.
 ### Arguments
-#### `name:String`
+#### `name: String`
 The namespace for your store, it can be used to identify the store across the application.
-#### `state:* = {}`
+#### `state: any = {}`
 The store's initial state. it can be any data type. defaults to an empty object. Optional
-#### `reducer:Function`
-You can specify a reducer function to take care of state changes. the reducer functions receives two arguments, the previous state and the action that triggered the state update. the function must return a new state, if not, the new state will be `null`. Optional
+#### `reducer: (state:any, data:any) -> any`
+You can specify a reducer function to take care of state changes. the reducer functions receives two arguments, the previous state and the data dispatched. the function must return a new state, if not, the new state will be `null`. Optional
 
-### <a name="api_getStoreByName">`getStoreByName(name:String):StoreInterface`</a>
+### <a name="api_getStoreByName">`getStoreByName(name) -> StoreInterface`</a>
 Finds a store by its name and returns its instance.
 ### Arguments
-#### `name:String`
+#### `name: String`
 The name of the store.
 
 ## Objects API
 ### <a name="api_storeInterface">`StoreInterface`</a>
 The store instance that is returned by the createStore and getStoreByName methods.
 ### Interface
-#### `name:String`
+#### `name: String`
 The name of the store;
-#### `getState:Function():*`
+#### `getState: () -> state`
 A method that returns the store's current state
-#### `setState:Function(state:*, callback?:Function)`
+#### `setState: (state: any, callback?: (state: any) -> void)`
 Sets the state of the store. works if the store does not use a reducer state handler. Otherwise, use `dispatch`. callback is optional and will be invoked once the state is updated, receiving the updated state as argument.
-#### `dispatch:Function(action:*, callback?:Function)`
-Dispatches whatever is passed into this function to the store. works if the store uses a reducer state handler. Otherwise, use `setState`. callback is optional and will be invoked once the state is updated, receiving the updated state as argument.
-#### `subscribe:Function(callback:Function):unsubscribe:Function`
-The callback function will be invoked everytime the store state changes. If the store is reducer-based, the callback function will be called with `action` as the first argument and `state` as the second. otherwise, it'll be called with `state` as the only argument.
+#### `dispatch(data: any, callback?: (state: any) -> void)`
+Dispatches data to update the state. works if the store uses a reducer state handler. Otherwise, use `setState`. callback is optional and will be invoked once the state is updated, receiving the updated state as argument.
+#### `subscribe(callback: (state: any, data?: any) -> void) -> unsubscribe: () -> void`
+The callback function will be invoked everytime the store state changes. If the store is reducer-based, the callback function will be called with the state and the dispatched data as arguments. otherwise, it'll be called with state as the only argument.
 
 the subscribe method returns a function that can be called in order to cancel the subscription for the callback function.
 
 ## React API
-### <a name="api_useStore">`useStore(identifier:String|StoreInterface):Array[state, setState|dispatch]`</a>
+### <a name="api_useStore">`useStore(identifier, memoFn?) -> [state, setState|dispatch]`</a>
 A function that returns a pair with the current state and a function to trigger state updates for the specified store.
 ### Arguments
-#### Identifier:String|StoreInterface
+#### `Identifier: String|StoreInterface`
 The store identifier. It can be either its string name or its StoreInterface instance returned by a createStore or getStoreByName method.
+#### `memoFn: (state) -> any`
+A function to optimize performance. return the subset of the state the component is dependent on. The component will only be updated when the subset changes. Optional.
 
 # <a name="migration">Migrating from v1.0 to v1.1</a>
 - createStore now receives 3 arguments instead of an object with 3 properties.
@@ -221,11 +232,11 @@ createStore({state: 0});
 createStore({
   name: 'store',
   state: 0,
-  reducer(state, action) {
-    return state + action;
+  reducer(state, data) {
+    return state + data;
   }
 })
 // v1.1
 createStore('myStore', 0);
-createStore('store', 0, (state, value) => state + action);
+createStore('store', 0, (state, data) => state + data);
 ```