redux-leaves/README.md

# redux-leaves

Write once. Reduce anywhere.

![Travis (.org)](https://img.shields.io/travis/richardcrng/redux-leaves.svg)
[![Coverage Status](https://coveralls.io/repos/github/richardcrng/redux-leaves/badge.svg?branch=buttons)](https://coveralls.io/github/richardcrng/redux-leaves?branch=buttons)
![David](https://img.shields.io/david/richardcrng/redux-leaves.svg)
[![install size](https://packagephobia.now.sh/badge?p=redux-leaves)](https://packagephobia.now.sh/result?p=redux-leaves)
[![npm version](https://badge.fury.io/js/redux-leaves.svg)](https://badge.fury.io/js/redux-leaves)
[![Maintainability](https://api.codeclimate.com/v1/badges/371605931cb9f824e25c/maintainability)](https://codeclimate.com/github/richardcrng/redux-leaves/maintainability)

#### Getting started
- [30 second demo](#30-second-demo)
- [Motivation](docs/motivation.md)

#### API reference
- [Core: `reduxLeaves(initialState, reducers)`](docs/README.md)

## 30 second demo

### Write once.
```bash
npm install --save redux-leaves
```

```js
import { createStore } from 'redux'
import reduxLeaves from 'redux-leaves'

// 1. Define initialState
const initialState = {
  counter: 1,
  list: ['first'],
  nested: { arbitrarily: { deep: 0 } }
}

// 2. (Optional) Define custom reducers dictionary
const reducersDict = {
  double: leafState => leafState * 2,
  appendToEach: (leafState, action) => leafState.map(str => str.concat(action.payload)),
  countKeys: (leafState, action, wholeState) => Object.keys(wholeState).length
}

// 3. Grab reducer and actions from reduxLeaves, then create the Redux store
const [reducer, actions] = reduxLeaves(initialState, reducersDict)
const store = createStore(reducer)
```

### Reduce anywhere.

```js
// *** KEY ***
// Default: an action creator that ships with Redux-Leaves by default
// Custom: an action creator generated by the custom reducersDict

// Default: increment state.counter
store.dispatch(actions.counter.create.increment())
console.log(store.getState().counter) // 2

// Custom: double state.counter
store.dispatch(actions.counter.create.double())
console.log(store.getState().counter) // 4

// Default: push 'second' to state.list
store.dispatch(actions.list.create.push('second'))
console.log(store.getState().list) // ['first', 'second']

// Custom: append ' item' to each element in state.list
store.dispatch(actions.list.create.appendToEach(' item'))
console.log(store.getState().list) // ['first item', 'second item']

// Default: assign true to key 'newKey' at the top-level of state
store.dispatch(actions.create.assign({ newKey: true }))
console.log(store.getState().newKey) // true 

// Custom: update state.nested.arbitrarily.deep with state's number of top-level keys
store.dispatch(actions.nested.arbitrarily.deep.create.countKeys())
console.log(store.getState().nested.arbitrarily.deep) // 4

console.log(store.getState())
/*
  {
    counter: 4,
    list: ['first item', ' second item'],
    nested: { arbitrarily: { deep: 4 } }
  }
*/
```

## Testing

To run all tests locally:

```bash
git clone git@github.com:richardcrng/redux-leaves.git
cd redux-leaves && npm run test a
```

All tests are located alongside their relevant documentation in the [docs](/docs) folder.