Adds support for derived state

Author: ctrlplusb

README.md

@@ -27,11 +27,12 @@ store.getState();
 ## Features
 
   - Quick to set up, easy to use
-  - Update your state via mutations within your actions
-  - Async actions supports remote data fetching/persisting
+  - Update state via simple mutations (thanks [`immer`](https://github.com/mweststrate/immer))
+  - Derived state
+  - Async actions for remote data fetching/persisting
+  - Redux Dev Tools Extension
   - Idiomatic Redux under the hood
   - Outputs a standard Redux store
-  - Supports the Redux Dev Tools Extension
   - Supports multiple frameworks (e.g. React via `react-redux`)
 
 ## TOCs
@@ -46,12 +47,15 @@ store.getState();
     - [Modifying state via actions](#modifying-state-via-actions)
     - [Dispatching actions](#dispatching-actions)
     - [Asynchronous actions](#asynchronous-actions)
+    - [Deriving state](#deriving-state)
+    - [Accessing Derived State](#accessing-derived-state)
     - [Final notes](#final-notes)
   - [Usage with React](#usage-with-react)
   - [API](#api)
     - [createStore(model, config)](#createstoremodel-config)
     - [action](#action)
     - [effect(action)](#effectaction)
+    - [select(selector)](#select)
   - [Prior Art](#prior-art)
 
 ## Introduction
@@ -183,6 +187,39 @@ store.dispatch.todos.saveTodo('Install easy-peasy').then(() => {
 })
 ```
 
+### Deriving state
+
+If you have state that can be derived from state then you can use the [`select`](#select(selector)) helper. Simply attach it to any part of your model.
+
+```javascript
+import { select } from 'easy-peasy'; // 👈 import then helper
+
+const store = createStore({
+  shoppingBasket: {
+    products: [{ name: 'Shoes', price: 123 }, { name: 'Hat', price: 75 }],
+    totalPrice: select(state =>
+      state.products.reduce((acc, cur) => acc + cur.price, 0)
+    )
+  }
+}
+```
+
+The derived data will be cached and will only be recalculated when the associated state changes.
+
+This can be really helpful to avoid unnecessary re-renders in your react components, especially when you do things like converting an object map to an array in your `connect`. Typically people would use [`reselect`](https://github.com/reduxjs/reselect) to alleviate this issue, however, with Easy Peasy it's this feature is baked right in.
+
+You can attach selectors to any part of your state. Similar to actions they will receive the local state that they are attached to and can access all the state down that branch of state.
+
+### Accessing Derived State
+
+It's as simple as a standard get state call.
+
+```javascript
+store.getState().shoppingBasket.totalPrice
+```
+
+> Note! See how we don't call the derived state as a function. You access it as a simple property.
+
 ### Final notes
 
 This was just a brief overview of how to create and interact with an Easy Peasy store. We recommend that you read the section on [Usage with React](#usage-with-react) to see how to effectively use this library in the context of React.  Also be sure to check out and tinker with our [examples](#examples).
@@ -371,11 +408,12 @@ When your model is processed by Easy Peasy to create your store all of your acti
 #### Example
 
 ```javascript
-import { createStore, effect } from 'easy-peasy';
+import { createStore, effect } from 'easy-peasy'; // 👈 import then helper
 
 const store = createStore({
   session: {
     user: undefined,
+    // 👇 define your effectful action
     login: effect(async (dispatch, payload) => {
       const user = await loginService(payload)
       dispatch.session.loginSucceeded(user)
@@ -387,12 +425,49 @@ const store = createStore({
 });
 
 // 👇 you can dispatch and await on the effectful actions
-await store.dispatch.session.login({
+store.dispatch.session.login({
   username: 'foo',
   password: 'bar'
-});
+})
+// 👇 effectful actions _always_ return a Promise
+.then(() => console.log('Logged in'));
+
+```
+
+### select(selector)
+
+Declares a section of state that is derived via the given selector function.
+
+#### Arguments
+
+  - selector (Function, required)
+
+    The selector function responsible for resolving the derived state. It will be provided the following arguments:
+
+    - `state` (Object, required)
+
+      The local part of state that the `select` property was attached to.
+
+Select's have their outputs cached to avoid unnecessary work, and will be executed
+any time their local state changes.
+
+#### Example
+
+```javascript
+import { select } from 'easy-peasy'; // 👈 import then helper
+
+const store = createStore({
+  shoppingBasket: {
+    products: [{ name: 'Shoes', price: 123 }, { name: 'Hat', price: 75 }],
+    // 👇 define your derived state
+    totalPrice: select(state =>
+      state.products.reduce((acc, cur) => acc + cur.price, 0)
+    )
+  }
+}
 
-console.log('Logged in');
+// 👇 access the derived state as you would normal state
+store.getState().shoppingBasket.totalPrice
 ```
 
 ## Prior art

package.json

@@ -31,6 +31,7 @@
   "peerDependencies": {},
   "dependencies": {
     "immer": "^1.7.2",
+    "memoize-one": "^4.0.2",
     "redux": "^4.0.1",
     "redux-thunk": "^2.3.0"
   },

src/__tests__/easy-peasy.test.js

@@ -1,6 +1,6 @@
 /* eslint-disable no-param-reassign */
 
-import { createStore, effect } from '../index'
+import { createStore, effect, select } from '../index'
 
 const resolveAfter = (data, ms) =>
   new Promise(resolve => setTimeout(() => resolve(data), ms))
@@ -119,6 +119,25 @@ test('nested action', () => {
   })
 })
 
+test('root action', () => {
+  // arrange
+  const store = createStore({
+    todos: {
+      items: { 1: { text: 'foo' } },
+    },
+    doSomething: state => {
+      state.todos.items[2] = { text: 'bar' }
+    },
+  })
+
+  // act
+  store.dispatch.doSomething()
+
+  // assert
+  const actual = store.getState().todos.items
+  expect(actual).toEqual({ 1: { text: 'foo' }, 2: { text: 'bar' } })
+})
+
 test('redux thunk configured', async () => {
   // arrange
   const model = { foo: 'bar' }
@@ -343,3 +362,118 @@ test('dispatches an action to represent the start of an effect', () => {
   // assert
   expect(trackActions.actions).toEqual([{ type: 'foo.doSomething', payload }])
 })
+
+describe('select', () => {
+  test('is run for initialisation of store', () => {
+    // arrange
+    const selector = jest.fn()
+    selector.mockImplementation(state =>
+      Object.keys(state.items).map(key => state.items[key]),
+    )
+
+    // act
+    const store = createStore({
+      items: { 1: { text: 'foo' } },
+      itemList: select(selector),
+    })
+
+    // assert
+    const actual = store.getState().itemList
+    expect(actual).toEqual([{ text: 'foo' }])
+    expect(selector).toHaveBeenCalledTimes(1)
+  })
+
+  test('executes one only if state does not change', () => {
+    // arrange
+    const selector = jest.fn()
+    selector.mockImplementation(state =>
+      Object.keys(state.items).map(key => state.items[key]),
+    )
+    const store = createStore({
+      items: { 1: { text: 'foo' } },
+      itemList: select(selector),
+      doNothing: () => undefined,
+    })
+
+    // act
+    store.dispatch.doNothing()
+
+    // assert
+    const actual = store.getState().itemList
+    expect(actual).toEqual([{ text: 'foo' }])
+    expect(selector).toHaveBeenCalledTimes(1)
+  })
+
+  test('executes again if state does change', () => {
+    // arrange
+    const selector = jest.fn()
+    selector.mockImplementation(state =>
+      Object.keys(state.items).map(key => state.items[key]),
+    )
+    const store = createStore({
+      items: { 1: { text: 'foo' } },
+      itemList: select(selector),
+      doSomething: state => {
+        state.items[2] = { text: 'bar' }
+      },
+    })
+
+    // act
+    store.dispatch.doSomething()
+
+    // assert
+    const actual = store.getState().itemList
+    expect(actual).toEqual([{ text: 'foo' }, { text: 'bar' }])
+    expect(selector).toHaveBeenCalledTimes(2)
+  })
+
+  test('executes if parent action changes associated state', () => {
+    // arrange
+    const selector = jest.fn()
+    selector.mockImplementation(state =>
+      Object.keys(state.items).map(key => state.items[key]),
+    )
+    const store = createStore({
+      todos: {
+        items: { 1: { text: 'foo' } },
+        itemList: select(selector),
+      },
+      doSomething: state => {
+        state.todos.items[2] = { text: 'bar' }
+      },
+    })
+
+    // act
+    store.dispatch.doSomething()
+
+    // assert
+    const actual = store.getState().todos.itemList
+    expect(actual).toEqual([{ text: 'foo' }, { text: 'bar' }])
+    expect(selector).toHaveBeenCalledTimes(2)
+  })
+
+  test('root select', () => {
+    // arrange
+    const selector = jest.fn()
+    selector.mockImplementation(state =>
+      Object.keys(state.todos.items).map(key => state.todos.items[key]),
+    )
+    const store = createStore({
+      todos: {
+        items: { 1: { text: 'foo' } },
+      },
+      itemList: select(selector),
+      doSomething: state => {
+        state.todos.items[2] = { text: 'bar' }
+      },
+    })
+
+    // act
+    store.dispatch.doSomething()
+
+    // assert
+    const actual = store.getState().itemList
+    expect(actual).toEqual([{ text: 'foo' }, { text: 'bar' }])
+    expect(selector).toHaveBeenCalledTimes(2)
+  })
+})

src/easy-peasy.js

@@ -3,9 +3,13 @@ import {
   compose,
   createStore as reduxCreateStore,
 } from 'redux'
+import memoizeOne from 'memoize-one'
 import produce from 'immer'
 import thunk from 'redux-thunk'
 
+const effectSymbol = Symbol('effect')
+const selectSymbol = Symbol('select')
+
 const isObject = x => x && typeof x === 'object' && !Array.isArray(x)
 
 const get = (path, target) =>
@@ -22,14 +26,18 @@ const set = (path, target, value) => {
   }, target)
 }
 
-const effectSymbol = Symbol('effect')
-
 export const effect = fn => {
   // eslint-disable-next-line no-param-reassign
   fn[effectSymbol] = true
   return fn
 }
 
+export const select = fn => {
+  const selector = memoizeOne(state => fn(state))
+  selector[selectSymbol] = true
+  return selector
+}
+
 export const createStore = (model, options = {}) => {
   const { devTools = true, middleware = [], initialState = {} } = options
 
@@ -44,8 +52,9 @@ export const createStore = (model, options = {}) => {
   const references = {}
   const defaultState = {}
   const actionEffects = {}
-  const actionReducers = {}
   const actionCreators = {}
+  const actionReducers = {}
+  const selectorReducers = []
 
   const extract = (current, parentPath) =>
     Object.keys(current).forEach(key => {
@@ -54,7 +63,10 @@ export const createStore = (model, options = {}) => {
       if (typeof value === 'function') {
         const actionName = path.join('.')
 
-        if (value[effectSymbol]) {
+        if (value[selectSymbol]) {
+          // skip
+          selectorReducers.push([parentPath, key, value])
+        } else if (value[effectSymbol]) {
           // Effect Action
           const action = payload => {
             references.dispatch({
@@ -124,7 +136,7 @@ export const createStore = (model, options = {}) => {
       key,
       createReducers(current[key], [...path, key]),
     ])
-    return (state = get(path, defaultState), action) => {
+    const reducerForActions = (state = get(path, defaultState), action) => {
       const actionReducer = actionReducersAtPath.find(
         x => x.actionName === action.type,
       )
@@ -143,6 +155,29 @@ export const createStore = (model, options = {}) => {
       }
       return state
     }
+    let isInitial = true
+    return selectorReducers.length
+      ? (state, action) => {
+          const stateAfterActions = reducerForActions(state, action)
+          if (state !== stateAfterActions || isInitial) {
+            const stateAfterSelectors = selectorReducers.reduce(
+              (acc, [parentPath, key, selector]) =>
+                produce(acc, draft => {
+                  // eslint-disable-next-line no-param-reassign
+                  const target =
+                    parentPath.length > 0 ? get(parentPath, draft) : draft
+                  if (target) {
+                    target[key] = selector(target)
+                  }
+                }),
+              stateAfterActions,
+            )
+            isInitial = false
+            return stateAfterSelectors
+          }
+          return stateAfterActions
+        }
+      : reducerForActions
   }
 
   const reducers = createReducers(actionReducers, [])