Merge pull request #44 from richardcrng/master-v0.1.1

Master v0.1.1

docs/create/README.md

@@ -66,7 +66,7 @@ console.log(typeof actions.str.obj.create.push)   // undefined
 Returns an object that, *when dispatched to a store created with the original state tree*, updates the leaf's state to the return value of `callback(leafState, entireState)`.
 
 #### Parameters
-- `callback` *(function)*: invoked by the leaf's reducer with the leaf's current state
+- `callback` *(function)*: invoked by the leaf's reducer with two arguments, `leafState` and `entireState`
 
 #### Returns
 `action` *(object)*: an object to dispatch to the `store`
@@ -80,37 +80,34 @@ const initialState = {
   bool: false,
   num: 2,
   str: 'foo',
-  arr: [1, 2, 3],
-  obj: {}
+  arr: [1, 2, 3]
 }
 
 const [reducer, actions] = reduxLeaves(initialState)
 const store = createStore(reducer)
 ```
-##### bool
-```js
-store.dispatch(actions.bool.create.apply(state => !state))
-console.log(store.getState().bool) // true
-```
-##### num
-```js
-store.dispatch(actions.num.create.apply(state => state * 3))
-console.log(store.getState().num) // 6
-```
-##### str
+
+Calling `create.apply` on a leaf:
+
 ```js
 store.dispatch(actions.str.create.apply(state => state.toUpperCase()))
 console.log(store.getState().str) // 'FOO'
 ```
-##### arr
+
+Calling `create.apply` on a branch:
+
 ```js
-store.dispatch(actions.arr.create.apply(state => state.reverse()))
-console.log(store.getState().arr) // [3, 2, 1]
+store.dispatch(actions.create.apply(state => ({ num: state.num, arr: state.arr }))
+console.log(store.getState()) // { num: 2, arr: [1, 2, 3] }
 ```
-##### obj
+
+Calling `create.apply` with two arguments:
+
 ```js
-store.dispatch(actions.obj.create.apply(state => { ...state, a: 1, b: 2 }))
-console.log(store.getState().obj) // { a: 1, b: 2 }
+store.dispatch(actions.arr.create.apply(
+  (leafState, entireState) => leafState.map(element => element * entireState.num)
+))
+console.log(store.getState()) // { num: 2, arr: [2, 4, 6] }
 ```
 
 [Back to all `create` action creators](#action-creators)
@@ -120,7 +117,7 @@ console.log(store.getState().obj) // { a: 1, b: 2 }
 
 Returns an object that, *when dispatched to a store created with the original state tree*, clears the leaf's state.
 
-If `toNull === true`, then it updates it to true, otherwise it follows the type of the leaf's initial state:
+If `toNull === true`, then it updates it to `null`, otherwise it follows the type of the leaf's initial state:
 - *number*: `0`
 - *string*: `''`
 - *boolean*: `false`
@@ -142,28 +139,27 @@ const initialState = {
   bool: true,
   num: 2,
   str: 'foo',
-  arr: [1, 2, 3],
-  obj: {}
+  arr: [1, 2, 3]
 }
 
 const [reducer, actions] = reduxLeaves(initialState)
 const store = createStore(reducer)
 ```
 ##### bool
 ```js
-store.dispatch(actions.bool.create.clear(true))
-console.log(store.getState().bool) // null
-
 store.dispatch(actions.bool.create.clear())
 console.log(store.getState().bool) // false
+
+store.dispatch(actions.bool.create.clear(true))
+console.log(store.getState().bool) // null
 ```
 ##### num
 ```js
-store.dispatch(actions.num.create.clear(true))
-console.log(store.getState().num) // null
-
 store.dispatch(actions.num.create.clear())
 console.log(store.getState().num) // 0
+
+store.dispatch(actions.num.create.clear(true))
+console.log(store.getState().num) // null
 ```
 ##### str
 ```js
@@ -183,11 +179,11 @@ console.log(store.getState().arr) // []
 ```
 ##### obj
 ```js
-store.dispatch(actions.obj.create.clear(true))
-console.log(store.getState().obj) // null
+store.dispatch(actions.create.clear(true))
+console.log(store.getState()) // null
 
-store.dispatch(actions.obj.create.clear())
-console.log(store.getState().obj) // {}
+store.dispatch(actions.create.clear())
+console.log(store.getState()) // {}
 ```
 
 [Back to all `create` action creators](#action-creators)
@@ -206,59 +202,34 @@ import { createStore } from 'redux'
 import reduxLeaves from 'reduxLeaves'
 
 const initialState = {
-  bool: true,
   num: 2,
-  str: 'foo',
-  arr: [1, 2, 3],
-  obj: {}
-}
+  arr: [1, 2, 3]
 
 const otherState = {
-  bool: false,
   num: 11,
-  str: 'bar',
-  arr: ['a', 'b', 'c'],
-  obj: { property: true }
+  arr: ['a', 'b', 'c']
 }
 
 const [reducer, actions] = reduxLeaves(initialState)
-const store = createStore(reducer, otherState)
+const store = createStore(reducer, otherState)        // preloads otherState
 
 /* store.getState()
 * {
-*   bool: false,
 *   num: 11,
-*   str: 'bar',
-*   arr: ['a', 'b', 'c'],
-*   obj: { property: true }
+*   arr: ['a', 'b', 'c']
 * }
 */
 
 ```
-##### bool
-```js
-store.dispatch(actions.bool.create.reset())
-console.log(store.getState().bool) // true
-```
-##### num
+Calling `create.reset` on a leaf:
 ```js
 store.dispatch(actions.num.create.reset())
 console.log(store.getState().num) // 2
 ```
-##### str
+Calling `create.reset` on a branch:
 ```js
-store.dispatch(actions.str.create.reset())
-console.log(store.getState().str) // 'foo'
-```
-##### arr
-```js
-store.dispatch(actions.arr.create.reset())
-console.log(store.getState().arr) // [1, 2, 3]
-```
-##### obj
-```js
-store.dispatch(actions.obj.create.reset())
-console.log(store.getState().obj) // {}
+store.dispatch(actions.create.reset())
+console.log(store.getState()) // { num: 2, arr: [1, 2, 3] }
 ```
 
 [Back to all `create` action creators](#action-creators)
@@ -283,16 +254,24 @@ const initialState = {
   bool: false,
   num: 2,
   str: 'foo',
-  arr: [1, 2, 3],
-  obj: {}
+  arr: [1, 2, 3]
 }
 
 const [reducer, actions] = reduxLeaves(initialState)
 const store = createStore(reducer)
 ```
+
+Calling `create.update` on a leaf:
+
+```js
+store.dispatch(actions.str.create.update("I can put anything here"))
+console.log(store.getState().str) // 'I can put anything here'
+```
+
+Calling `create.update` on a branch:
 ```js
-store.dispatch(actions.bool.create.update("I can put anything here"))
-console.log(store.getState().bool) // 'I can put anything here'
+store.dispatch(actions.create.update({ any: { properties: true }}))
+console.log(store.getState()) // { any: { properties: true } }
 ```
 
 [Back to all `create` action creators](#action-creators)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "redux-leaves",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "author": "Richard Ng (https://github.com/richardcrng)",
   "dependencies": {

src/__tests__/leaf/create/apply.test.js

@@ -2,7 +2,66 @@ import _ from 'lodash';
 import { createStore } from "redux";
 import reduxLeaves from '../../../..';
 
-describe("leaf.create.apply(callback): returns an action that, when dispatched, updates the leaf's state to the return value of callback(state)", () => {
+describe("leaf.create.apply(callback): returns an action that, when dispatched, updates the leaf's state to the return value of callback(state, entireState)", () => {
+
+  describe("Documentation example 1", () => {
+    describe("GIVEN setup of initialState and store as documented", () => {
+      const initialState = {
+        bool: false,
+        num: 2,
+        str: 'foo',
+        arr: [1, 2, 3],
+        obj: {}
+      }
+
+      const [reducer, actions] = reduxLeaves(initialState)
+      let store
+
+      beforeEach(() => {
+        store = createStore(reducer)
+      })
+
+      describe("WHEN we execute store.dispatch(actions.str.create.apply(state => state.toUpperCase()))", () => {
+        beforeEach(() => {
+          store.dispatch(actions.str.create.apply(state => state.toUpperCase()))
+        })
+
+        test("THEN the store's state.str is 'FOO'", () => {
+          expect(store.getState().str).toBe('FOO')
+        })
+
+        describe("AND we execute store.dispatch(actions.create.apply(state => ({ num: state.num, arr: state.arr })))", () => {
+          beforeEach(() => {
+            store.dispatch(actions.create.apply(state => ({ num: state.num, arr: state.arr })))
+          })
+
+          test("THEN the store's state is { num: 2, arr: [1, 2, 3] }", () => {
+            expect(store.getState()).toEqual({
+              num: 2,
+              arr: [1, 2, 3]
+            })
+          })
+
+          describe("AND we execute store.dispatch(actions.arr.create.apply((leafState, entireState) => (leafState.map(element => element * entireState.num))))))", () => {
+            beforeEach(() => {
+              store.dispatch(actions.arr.create.apply((leafState, entireState) => (
+                leafState.map(element => element * entireState.num)
+              )))
+            })
+
+            test("THEN the store's state is { num: 2, arr: [2, 4, 6] }", () => {
+              expect(store.getState()).toEqual({
+                num: 2,
+                arr: [2, 4, 6]
+              })
+            })
+          })
+        })
+      })
+    })
+
+
+  })
 
   describe("GIVEN non-trivially nested API (as in the documentation)", () => {
     const initialState = {

src/__tests__/leaf/create/clear.test.js

@@ -183,6 +183,28 @@ describe("leaf.create.clear(toNull = false): returns an action that, when dispat
             })
           })
         })
+
+        describe("AND we dispatch actions.create.clear(true)", () => {
+          beforeEach(() => {
+            store.dispatch(actions.create.clear(true))
+          })
+
+          test("THEN state updates to null", () => {
+            const state = store.getState()
+            expect(state).toBeNull()
+          })
+        })
+
+        describe("AND we dispatch actions.create.clear()", () => {
+          beforeEach(() => {
+            store.dispatch(actions.create.clear())
+          })
+
+          test("THEN state updates to {}", () => {
+            const state = store.getState()
+            expect(state).toEqual({})
+          })
+        })
       })
     })
   })

src/__tests__/leaf/create/reset.test.js

@@ -4,6 +4,56 @@ import reduxLeaves from '../../../..';
 
 describe("leaf.create.reset(): returns an action that, when dispatched, updates the leaf's state to the reducer's initialised state", () => {
 
+  describe("Documentation example 1", () => {
+    describe("GIVEN setup of initialState, otherState and store as documented", () => {
+      const initialState = {
+        num: 2,
+        arr: [1, 2, 3],
+      }
+
+      const otherState = {
+        num: 11,
+        arr: ['a', 'b', 'c']
+      }
+
+      const [reducer, actions] = reduxLeaves(initialState)
+      let store
+
+      beforeEach(() => {
+        store = createStore(reducer, otherState)
+      })
+
+      test("THEN store is initialised with otherState", () => {
+        expect(store.getState()).toEqual(otherState)
+      })
+
+      describe("WHEN we execute store.dispatch(actions.num.create.reset()))", () => {
+        beforeEach(() => {
+          store.dispatch(actions.num.create.reset())
+        })
+
+        test("THEN the store's state.num is 2", () => {
+          expect(store.getState().num).toBe(2)
+        })
+
+        describe("AND we execute store.dispatch(actions.create.reset())", () => {
+          beforeEach(() => {
+            store.dispatch(actions.create.reset())
+          })
+
+          test("THEN the store's state is { num: 2, arr: [1, 2, 3] }", () => {
+            expect(store.getState()).toEqual({
+              num: 2,
+              arr: [1, 2, 3]
+            })
+          })
+        })
+      })
+    })
+
+
+  })
+
   describe("GIVEN non-trivially nested API (as in the documentation)", () => {
     const initialState = {
       counter: 1,