add api reference

Author: Péter Hauszknecht

README.md

@@ -24,9 +24,11 @@ store.dispatch(increment(42));
 ## Installation
 
 ```
-npm install repatch
+npm install --save repatch
 ```
 
+## [API Reference](https://github.com/jaystack/repatch/blob/master/docs/index.md)
+
 ## Examples
 
 - [JavaScript example](https://github.com/jaystack/repatch-example-electron-app)

docs/index.md

@@ -0,0 +1,21 @@
+# Repatch API Reference
+
+## Top-Level Exports
+
+- Default export: [Store](store.md)
+- [thunk](thunk.md)
+
+## Importing
+
+### ES6
+
+```javascript
+import Store, { thunk } from 'repatch'
+```
+
+### ES5
+
+```javascript
+var Store = require('repatch').default
+var thunk = require('repatch').thunk
+```

docs/store.md

@@ -0,0 +1,135 @@
+# Store
+
+The `Store` holds the whole state tree of your application. You need to instantiate it.
+
+## Constructor
+
+#### Arguments
+
+1) **initialState** (*any*): The initial state of your application. Usually it is an object that represents the state tree.
+
+#### Returns
+
+(*Store*): The new `Store` instance.
+
+#### Example
+
+```javascript
+import Store from 'repatch'
+
+const store = new Store({ counter: 0 })
+```
+
+## Methods
+
+### `getState()`
+
+This method returns the current state of the store.
+
+#### Returns
+
+(*any*): The current state of the store.
+
+#### Example
+
+```javascript
+const store = new Store({ counter: 0 })
+
+const state = store.getState()
+
+console.log(state.counter === 0) // true
+```
+
+### `dispatch(reducer)`
+
+Dispatches a reducer.
+
+#### Arguments
+
+1) **reducer** (*ReducerFunction: State -> State*): That reducer will reduce the state of the store. This takes the current state and returns the next state. The reducer will be run synchronously after applying the middlewares - if they are given.
+
+#### Returns
+
+(*ReducerFunction*): The final reducer that is made by applying the middlewares - if they are given. If the store does not have middlewares, the `dispatch` method returns the same reducer that was taken as argument.
+
+#### Example
+
+```javascript
+const store = new Store({ counter: 0 })
+
+const increment = state => ({ counter: state.counter + 1 })
+
+const result = store.dispatch(increment)
+
+console.log(result === increment) // true
+```
+
+#### Notes
+
+1) Middlewares can modify the given reducer, so that is not guaranteed that the `dispatch` returns the original reducer that was taken as argument.
+2) The `dispatch` only runs the reducer, when the final reducer (after applying middlewares) is still a function. If the final reducer is a function, then the dispatch modifies the state by its returned value. This behaviour is strongly used by the [thunk](thunk.md) middleware, that returns the returned value of the delegate.
+
+### `subscribe(listener)`
+
+Adds a state change listener.
+
+#### Arguments
+
+1) **listener** (*ListenerFunction: void -> void*): The listener that will be synchronously run after the state was modified by dispatching a reducer.
+
+#### Returns
+
+(*UnsubscribeFunction: void -> void*): The unsubscribe function, that you can use to unsubscribe the given listener.
+
+#### Example
+
+```javascript
+const store = new Store({ counter: 0 })
+
+const increment = state => ({ counter: state.counter + 1 })
+
+const unsubscribe = store.subscribe(() => console.log(store.getState()))
+
+store.dispatch(increment) // listener logs the new state
+
+unsubscribe()
+
+store.dispatch(increment) // listener won't be fired
+```
+
+### `addMiddleware(...middlewares)`
+
+Adds middleware(s) to the store.
+
+Middlewares will be run at dispatching before the store applies the new state of the reducer. The added middlewares are composed by order of addition.
+
+#### Arguments
+
+1) **...middlewares** (*MiddlewareFunction: (Store, Reducer) -> Reducer*): Middlewares as variadic arguments. Middleware functions take the `Store` instance and the dispatched reducer and return a new reducer.
+
+#### Returns
+
+(*Store: this*): Returns the same `Store` instance for chaining.
+
+#### Example
+
+```javascript
+const store = new Store({ counter: 0 })
+
+const logger = (store, reducer) => {
+  const nextState = reducer(store.getState())
+  console.log(nextState)
+  return _ => nextState
+}
+
+store.addMiddleware(logger)
+
+store.dispatch(state => ({ counter: state.counter + 1 }))
+// logger logs { counter: 1 }
+```
+
+## Static members
+
+### `thunk`
+
+The [thunk](thunk.md) middleware.

docs/thunk.md

@@ -0,0 +1,51 @@
+# Thunk middleware
+
+Thunk is a repatch middleware to handle async actions. It is very similar to [redux-thunk](https://www.npmjs.com/package/redux-thunk). Thunk middleware allows you to create reducers that returns a function (delegate). The delegate will be fired at dispatching.
+
+## ThunkMiddleware
+
+`State -> Delegate`
+
+#### Example
+
+```javascript
+import Store, { thunk } from 'repatch'
+
+const store = new Store({ items: [] }).addMiddleware(thunk)
+
+store.dispatch(_ => async (dispatch, getState) => {
+  const items = await fetch('/items')
+  dispatch(state => ({ ...state, items }))
+})
+```
+
+## Extra arguments
+
+#### Example
+
+```javascript
+import Store, { thunk } from 'repatch'
+import api from './api'
+
+const store = new Store({ items: [] })
+  .addMiddleware(thunk.withExtraArgument(api))
+
+store.dispatch(_ => async (dispatch, getState, api) => {
+  const items = await api.get('/items')
+  dispatch(state => ({ ...state, items }))
+})
+```
+
+## Delegate
+
+#### Arguments
+
+1) **dispatch** (*Store.dispatch*): The `dispatch` method of the `Store` instance. With this you can dispatch any reducer to the store.
+
+2) **getState** (*Store.getState*): The `getState` method of the `Store` instance. With this you can get the current state of the store.
+
+3) **extraArgument** (*any*): An extra argument that you can provide at adding the thunk middleware. The `extraArgument` could be anything what you want. It is useful to keep the delegates side-effect-less.
+
+#### Returns
+
+(*any*): Delegate can return anything. If your delegate returns a `Promise`, you can chain your async actions to each other.