import { action, createStore, StoreProvider, useStore, useActions } from '@redux-app/store';

// 👇 create your store, providing the model
const store = createStore({
  todos: {
    items: ['Install @redux-app/store', 'Define your model', 'Have fun'],
    // 👇 define actions directly on your model
    add: action((state, payload) => {
      // simply mutate state to update, and we convert to immutable updates
      state.items.push(payload)
      // (you can also return a new immutable version of state if you prefer)
    })
  }
});

const App = () => (
  // 👇 wrap your app to expose the store
  <StoreProvider store={store}>
    <TodoList />
  </StoreProvider>
)

function TodoList() {
  // 👇  use hooks to get state or actions
  const todos = useStore(state => state.todos.items)
  const add = useActions(actions => actions.todos.add)
  return (
    <div>
      {todos.map((todo, idx) => <div key={idx}>{todo}</div>)}
      <AddTodo onAdd={add} />
    </div>
  )
}

Features

• Intuitive API that allows rapid development
• Full Typescript support
• Mutate state, we do the hard work for you, auto converting mutations to immutable updates
• Derived state with auto memoisation
• Thunks for data fetching and side effects
• Listeners to respond to updates across your model
• React Hook based API
• Testing helpers baked in
• Supports React Native
• Redux under the hood
  • The power of Redux, without the boilerplate
  • Redux Dev Tools out of the box
  • Custom middleware
  • Customise root reducer enhancer
  • Easy migration path for react-redux based apps

TOCs

• Introduction
• Installation
• Tutorial
  • Core Concepts
    • Creating the store
    • Accessing state directly via the store
    • Modifying state via actions
    • Dispatching actions directly via the store
    • Creating a thunk action
    • Dispatching a thunk action directly via the store
    • Deriving state via select
    • Accessing Derived State directly via the store
    • Updating multiple parts of your state in response to a thunk/action
  • Usage with React
    • Wrap your app with StoreProvider
    • Accessing state in your Components
    • Dispatching actions in your Components
    • Usage via react-redux
• API
  • createStore(model, config)
  • action
  • thunk(action)
  • reducer(fn)
  • select(selector)
  • listen(on)
  • StoreProvider
  • useStore(mapState, externals)
  • useActions(mapActions)
  • useDispatch()
• Usage with Typescript
• Usage with React Native
• Writing Tests
• Typescript API
• Tips and Tricks
  • Generalising effects/actions/state via helpers
• Prior Art

Introduction

Easy Peasy gives you the power of Redux (and its tooling) whilst avoiding the boilerplate. It allows you to create a Redux store by defining a model that describes your state and its actions. Batteries are included - you don't need to configure any additional packages to support derived state, side effects, memoisation, or integration with React.

Installation

Firstly, install React and React DOM.

npm install react
npm install react-dom

Note: please ensure you install versions >= 16.8.0 for both react and react-dom, as this library depends on the new hooks feature

Then install Easy Peasy.

npm install @redux-app/state

You're off to the races.

Tutorial

The below will introduce you to the core concepts of Easy Peasy, where we will interact with the Redux store directly. In a following section we shall illustrate how to integrate Easy Peasy within a React application.

Core Concepts

Creating the store

Firstly you need to define your model. This represents the structure of your Redux state along with its default values. Your model can be as deep and complex as you like. Feel free to split your model across many files, importing and composing them as you like.

const model = {
  todos: {
    items: [],
  }
};

Then you provide your model to createStore.

import { createStore } from '@redux-app/state';

const store = createStore(model);

You will now have a Redux store - all the standard APIs of a Redux store is available to you. 👍

Accessing state directly via the store

You can access your store's state using the getState API of the Redux store.

store.getState().todos.items;

Modifying state via actions

In order to mutate your state you need to define an action against your model.

import { action } from '@redux-app/store'; // 👈 import the helper

const store = createStore({
  todos: {
    items: [],
    //         👇 define the action with the helper
    addTodo: action((state, payload) => {
      // Mutate the state directly. Under the hood we convert this to an
      // an immutable update.
      state.items.push(payload)
    })
  }
});

The action will receive as its first parameter the slice of the state that it was added to. So in the example above our action would receive { items: [] } as the value for its state argument. It will also receive any payload that may have been provided when the action was triggered.

Note: Some prefer not to use a mutation based API. You can alternatively return new instances of your state:

addTodo: action((state, payload) => {
  return { ...state, items: [...state.items, payload] };
})

Personally I find the above harder to read and more prone to error.

Dispatching actions directly via the store

Easy Peasy will bind your actions against the stores dispatch. They will be bound using paths that match the location of the action on your model.

//                                    |-- payload
//                           |------------------|
store.dispatch.todos.addTodo('Install @redux-app/store');
//            |-------------|
//                  |-- path matches our model (todos.addTodo)

Call getState to see the updated state.

store.getState().todos.items;
// ['Install @redux-app/state']

Creating a thunk action

If you wish to perform side effects, such as fetching or persisting data from your server then you can use the thunk helper to declare a thunk action.

import { thunk } from '@redux-app/state'; // 👈 import the helper

const store = createStore({
  todos: {
    items: [],

    //          👇 define a thunk action via the helper
    saveTodo: thunk(async (actions, payload) => {
      //                      👆
      // Notice that the thunk will receive the actions allowing you to dispatch
      // other actions after you have performed your side effect.
      const saved = await todoService.save(payload);
      // Now we dispatch an action to add the saved item to our state
      //         👇
      actions.todoSaved(saved);
    }),

    todoSaved: action((state, payload) => {
      state.items.push(payload)
    })
  }
});

You cannot modify the state within a thunk, however, the thunk is provided the actions that are local to it. This allows you to delegate state updates via your actions (an experience similar to that of redux-thunk).

Dispatching a thunk action directly via the store

You can dispatch a thunk action in the same manner as a normal action. A thunk action always returns a Promise allowing you to execute any process after the thunk has completed.

store.dispatch.todos.saveTodo('Install @redux-app/state').then(() => {
  console.log('Todo saved');
})

Deriving state via select

If you have state that can be derived from state then you can use the select helper. Simply attach it to any part of your model.

import { select } from '@redux-app/state'; // 👈 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 to alleviate this issue, however, with Easy Peasy it's this feature is baked right in.

Note: we don't recommend attaching selectors to the root of your store, as those will be executed for every change to your store. If you absolutely need to, try to attach as few selectors to the root as you can.

Accessing Derived State directly via the store

You can access derived state as though it were a normal piece of state.

store.getState().shoppingBasket.totalPrice

Note! See how we don't call the derived state as a function. You access it as a simple property.

Updating multiple parts of your state in response to a thunk/action

When firing an action you may want multiple parts of your model to respond to it. For example, you may want to clear certain parts of your state when a user logs out. Or perhaps you want an audit log that tracks specific events.

Easy Peasy provides you with the listen helper to do this.

import { listen } from '@redux-app/store'; // 👈 import then helper

const todosModel = {
  items: [],
  // 👇 the action we wish to respond to / track
  addTodo: action((state, payload) => {
    state.items.push(payload)
  })
};

const auditModel = {
  logs: [],
  //          👇 declare listeners via the helper
  listeners: listen((on) => {
    on(
      //           👇 pass in the reference to the action we wish to listen to
      todosModel.addTodo,
      // 👇 the action we wish to execute after `addTodo` has completed
      action((state, payload) => {
        state.logs.push(`Added a new todo: ${payload}`);
      })
    );
  })
};

const model = {
  todos: todosModel,
  audit: auditModel
};

This is a more advanced feature, however, using this method allows a clearer seperation of concerns and promotes reactive programming.

You can do more than this with the listen helper. You can listen to an action or a thunk, and can execute either an action or a thunk in response. Please read the docs for more information.

Usage with React

We will now cover how to integrate your store with your React components. We leverage Hooks to do so. If you aren't familiar with hooks yet we highly recommend that you read the official documentation and try playing with our examples.

If you want to be able to use your Easy Peasy store with Class components then you can utilise the react-redux package - this is covered further down in the tutorial.

If you haven't done so already we highly recommend that you install the Redux Dev Tools Extension. This will allow you to visualise your actions firing along with the associated state updates.

Wrap your app with StoreProvider

Firstly you need to create your store then wrap your application with the StoreProvider.

import { StoreProvider, createStore } from '@redux-app/state';
import model from './model'

const store = createStore(model);

const App = () => (
  <StoreProvider store={store}>
    <TodoList />
  </StoreProvider>
)

Accessing state in your Components

To access state within your components you can use the useStore hook.

import { useStore } from '@redux-app/state';

const TodoList = () => {
  const todos = useStore(state => state.todos.items);
  return (
    <div>
      {todos.map((todo, idx) => <div key={idx}>{todo.text}</div>)}
    </div>
  );
};

In the case that your useStore implementation depends on an "external" value when mapping state, you should provide the respective "external" within the second argument to the useStore. This is a similar requirement to some of the official hooks that are bundled with React. The useStore hook will then track the external value and ensure that the state is remapped every time the external value(s) change.

import { useStore } from '@redux-app/state';

const Product = ({ id }) => {
  const product = useStore(
    state => state.products[id], // 👈 we are using an external value: "id"
    [id] // 👈 we provide "id" so our useStore knows to re-execute mapState
         //    if the "id" value changes
  );
  return (
    <div>
      <h1>{product.title}</h1>
      <p>{product.description}</p>
    </div>
  );
};

We recommend that you read the API docs for the useStore hook to gain a full understanding of the behaviours and pitfalls of the hook.

Dispatching actions in your Components

In order to fire actions in your components you can use the useActions hook.

import { useState } from 'react';
import { useActions } from '@redux-app/state';

const AddTodo = () => {
  const [text, setText] = useState('');
  const addTodo = useActions(actions => actions.todos.add);
  return (
    <div>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <button onClick={() => addTodo(text)}>Add</button>
    </div>
  );
};

For more on how you can use this hook please ready the API docs for the useActions hook.

Usage via react-redux

As Easy Peasy outputs a standard Redux store it is entirely possible to use Easy Peasy with the official react-redux package.

This allows you to do a few things:

• Slowly migrate a legacy application that is built using react-redux
• Connect your store to Class components via connect

npm install react-redux

import React from 'react';
import { render } from 'react-dom';
import { createStore } from '@redux-app/state';
import { Provider } from 'react-redux'; // 👈 import the provider
import model from './model';
import TodoList from './components/TodoList';

// 👇 then create your store
const store = createStore(model);

const App = () => (
  // 👇 then pass it to the Provider
  <Provider store={store}>
    <TodoList />
  </Provider>
)

render(<App />, document.querySelector('#app'));

import React, { Component } from 'react';
import { connect } from 'react-redux'; // 👈 import the connect

function TodoList({ todos, addTodo }) {
  return (
    <div>
      {todos.map(({id, text }) => <Todo key={id} text={text} />)}
      <AddTodo onSubmit={addTodo} />
    </div>
  )
}

export default connect(
  // 👇 Map to your required state
  state => ({ todos: state.todos.items }
  // 👇 Map your required actions
  dispatch => ({ addTodo: dispatch.todos.addTodo })
)(EditTodo)

This is by no means an exhaustive overview of Easy Peasy. We highly recommend you read through the API documentation to gain a more full understanding of the tools and helpers that Easy Peasy exposes to you.

API

Below is an overview of the API exposed by Easy Peasy.

createStore(model, config)

Creates a Redux store based on the given model. The model must be an object and can be any depth. It also accepts an optional configuration parameter for customisations.

• model (Object, required)

  Your model representing your state tree, and optionally containing action functions.

• config (Object, not required)

  Provides custom configuration options for your store. It supports the following options:

  • compose (Function, not required, default=undefined)

    Custom compose function that will be used in place of the one from Redux or Redux Dev Tools. This is especially useful in the context of React Native and other environments. See the Usage with React Native notes.

  • devTools (bool, not required, default=true)

    Setting this to true will enable the Redux Dev Tools Extension.

  • disableInternalSelectFnMemoize (bool, not required, default=false)

    Setting this to true will disable the automatic memoisation of a fn that you may return in any of your select implementations. Please see the select documentation for more information.

  • enhancers (Array, not required, default=[])

    Any custom store enhancers you would like to apply to your Redux store.

  • initialState (Object, not required, default=undefined)

    Allows you to hydrate your store with initial state (for example state received from your server in a server rendering context).

  • injections (Any, not required, default=undefined)

    Any dependencies you would like to inject, making them available to your effect actions. They will become available as the 4th parameter to the effect handler. See the effect docs for more.

  • middleware (Array, not required, default=[])

    Any additional middleware you would like to attach to your Redux store.

  • mockActions (boolean, not required, default=false)

    Useful when testing your store, especially in the context of thunks. When set to true none of the actions dispatched will update the state, they will be instead recorded and can be accessed via the getMockedActions API that is added to the store. Please see the "Writing Tests" section for more information.

  • reducerEnhancer (Function, not required, default=(reducer => reducer))

    Any additional reducerEnhancer you would like to enhance to your root reducer (for example you want to use redux-persist).

When you have created a store all the standard APIs of a Redux Store are available. Please reference their docs for more information. In addition to the standard APIs, Easy Peasy enhances the instance to contain the following:

• dispatch (Function & Object, required)

  The Redux store dispatch behaves as normal, however, it also has the actions from your model directly mounted against it - allowing you to easily dispatch actions. Please see the docs on actions/thunks for examples.

• getMockedActions (Function, required)

  When the mockActions configuration value was passed to the createStore then calling this function will return the actions that have been dispatched (and mocked). This is useful in the context of testing - especially thunks.

• clearMockedActions (Function, required)

  When the mockActions configuration value was passed to the createStore then calling this function clears the list of mocked actions that have been tracked by the store. This is useful in the context of testing - especially thunks.

import { createStore } from '@redux-app/store';

const store = createStore({
  todos: {
    items: [],
    addTodo: (state, text) => {
      state.items.push(text)
    }
  },
  session: {
    user: undefined,
  }
})

action

Declares an action on your model. An action allows you to perform updates on your store.

The action will have access to the part of the state tree where it was defined.

• action (Function, required)

  The action definition. It receives the following arguments:

  • state (Object, required)

    The part of the state tree that the action is against. You can mutate this state value directly as required by the action. Under the hood we convert these mutations into an update against the Redux store.

  • payload (Any)

    The payload, if any, that was provided to the action.

When your model is processed by Easy Peasy to create your store all of your actions will be made available against the store's dispatch. They are mapped to the same path as they were defined in your model. You can then simply call the action functions providing any required payload. See the example below.

import { action, createStore } from '@redux-app/store';

const store = createStore({
  todos: {
    items: [],
    add: action((state, payload) => {
      state.items.push(payload)
    })
  }
});

store.dispatch.todos.add('Install @redux-app/store');

thunk(action)

Declares a thunk action on your model. Allows you to perform effects such as data fetching and persisting.

• action (Function, required)

  The thunk action definition. A thunk typically encapsulates side effects (e.g. calls to an API). It can be asynchronous - i.e. use Promises or async/await. Thunk actions cannot modify state directly, however, they can dispatch other actions to do so.

  It receives the following arguments:

  • actions (required)

    The actions that are bound to same section of your model as the thunk. This allows you to dispatch another action to update state for example.

  • payload (Any, not required)

    The payload, if any, that was provided to the action.

  • helpers (Object, required)

    Contains a set of helpers which may be useful in advanced cases. The object contains the following properties:

    • dispatch (required)

      The Redux store dispatch instance. This will have all the Easy Peasy actions bound to it allowing you to dispatch additional actions.

    • getState (Function, required)

      When executed it will provide the local state of where the thunk is attached to your model. This can be useful in the cases where you require state in the execution of your thunk.

    • getStoreState (Function, required)

      When executed it will provide the root state of your model. This can be useful in the cases where you require state in the execution of your thunk.

    • injections (Any, not required, default=undefined)

      Any dependencies that were provided to the createStore configuration will be exposed as this argument. See the createStore docs on how to specify them.

    • meta (Object, required)

      This object contains meta information related to the effect. Specifically it contains the following properties:

      • parent (Array, string, required)

        An array representing the path of the parent to the action.

      • path (Array, string, required)

        An array representing the path to the action.

      This can be represented via the following example:

      const store = createStore({
        products: {
          fetchById: thunk((dispatch, payload, { meta }) => {
            console.log(meta);
            // {
            //   parent: ['products'],
            //   path: ['products', 'fetchById']
            // }
          })
        }
      });

When your model is processed by Easy Peasy to create your store all of your thunk actions will be made available against the store's dispatch. They are mapped to the same path as they were defined in your model. You can then simply call the action functions providing any required payload. See the examples below.

import { action, createStore, thunk } from '@redux-app/store'; // 👈 import then helper

const store = createStore({
  session: {
    user: undefined,
    // 👇 define your thunk action
    login: thunk(async (actions, payload) => {
      const user = await loginService(payload)
      actions.loginSucceeded(user)
    }),
    loginSucceeded: action((state, payload) => {
      state.user = payload
    })
  }
});

// 👇 you can dispatch and await on the thunk action
store.dispatch.session.login({
  username: 'foo',
  password: 'bar'
})
// 👇 thunk actions _always_ return a Promise
.then(() => console.log('Logged in'));

import { createStore, thunk } from '@redux-app/state';

const store = createStore({
  counter: {
    count: 1,
    // getState allows you to gain access to the local state
    //                                               👇
    doSomething: thunk(async (dispatch, payload, { getState }) => {
      // Calling it exposes the local state. i.e. the part of state where the
      // thunk was attached
      //            👇
      console.log(getState())
      // { count: 1 }
    }),
  }
});

store.dispatch.doSomething()

import { action, createStore, thunk } from '@redux-app/state';

const store = createStore({
  counter: {
    count: 1,
    // getStoreState allows you to gain access to the  store's state
    //                                               👇
    doSomething: thunk(async (dispatch, payload, { getStoreState }) => {
      // Calling it exposes the root state of your store. i.e. the full
      // store state 👇
      console.log(getStoreState())
      // { counter: { count: 1 } }
    }),
  }
});

store.dispatch.doSomething()

import { action, createStore, thunk } from '@redux-app/store';

const store = createStore({
  audit: {
    logs: [],
    add: action((state, payload) => {
      audit.logs.push(payload);
    })
  },
  todos: {
    // dispatch allows you to gain access to the store's dispatch
    //                                      👇
    saveTodo: thunk((actions, payload, { dispatch }) => {
      // ...
      dispatch.audit.add('Added a todo');
    })
  }
});

store.dispatch.todos.saveTodo('foo');

We don't recommned doing this, and instead encourage you to use the listen helper to invert responsibilites. However, there may exceptional cases in which you need to do the above.

import { createStore, thunk } from '@redux-app/state';
import api from './api' // 👈 a dependency we want to inject

const store = createStore(
  {
    foo: 'bar',
    //                       injections are exposed here 👇
    doSomething: thunk(async (dispatch, payload, { injections }) => {
      const { api } = injections
      await api.foo()
    }),
  },
  {
    // 👇 specify the injections parameter when creating your store
    injections: {
      api,
    }
  }
);

store.dispatch.doSomething()

reducer(fn)

Declares a section of state to be calculated via a "standard" reducer function - as typical in Redux. This was specifically added to allow for integrations with existing libraries, or legacy Redux code.

Some 3rd party libraries, for example connected-react-router, require you to attach a reducer that they provide to your state. This helper will you achieve this.

• fn (Function, required)

  The reducer function. It receives the following arguments.

  • state (Object, required)

    The current value of the property that the reducer was attached to.

  • action (Object, required)

    The action object, typically with the following shape.

    • type (string, required)

      The name of the action.

    • payload (any)

      Any payload that was provided to the action.

import { createStore, reducer } from '@redux-app/state';

const store = createStore({
  counter: reducer((state = 1, action) => {
    switch (action.type) {
      case 'INCREMENT': state + 1;
      default: return state;
    }
  })
});

store.dispatch({ type: 'INCREMENT' });

store.getState().counter;
// 2

select(selector)

Attach derived state (i.e. is calculated from other parts of your state) to your store.

The results of your selectors will be cached, and will only be recomputed if the state that they depend on changes. You may be familiar with reselect - this feature provides you with the same benefits.

• 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.

  You can return any derived state you like.

  It also supports returning a function. This allows you to support creating a "dynamic" selector that accepts arguments (e.g. productById(1)). We will automatically optimise the function that you return - ensuring that any calls to the function will be automatically be memoised - i.e. calls to it with the same arguments will return cached results. This automatic memoisation of the function can be disabled via the disableInternalSelectFnMemoize setting on the createStore's config argument.

• dependencies (Array, not required)

  If this selector depends on data from other selectors then you should provide the respective selectors within an array to indicate the case. This allows us to make guarantees of execution order so that your state is derived in the manner you expect it to.

import { select } from '@redux-app/state'; // 👈 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)
    )
  }
};

// 👇 access the derived state as you would normal state
store.getState().shoppingBasket.totalPrice;

import { select } from '@redux-app/state'; // 👈 import then helper

const store = createStore({
  products: [{ id: 1, name: 'Shoes', price: 123 }, { id: 2, name: 'Hat', price: 75 }],

  productById: select(state =>
    // 👇 return a function that accepts the arguments
    id => state.products.find(x => x.id === id)
  )
};

// 👇 access the select fn and provide its required arguments
store.getState().productById(1);

// This next call will return a cached result
store.getState().productById(1);

import { select } from '@redux-app/store';

const totalPriceSelector = select(state =>
  state.products.reduce((acc, cur) => acc + cur.price, 0),
)

const netPriceSelector = select(
  state => state.totalPrice * ((100 - state.discount) / 100),
  [totalPriceSelector] // 👈 declare that this selector depends on totalPrice
)

const store = createStore({
  discount: 25,
  products: [{ name: 'Shoes', price: 160 }, { name: 'Hat', price: 40 }],
  totalPrice: totalPriceSelector,
  netPrice: netPriceSelector // price after discount applied
});

listen(on)

Allows you to attach listeners to any action or thunk.

This enables parts of your model to respond to actions being fired in other parts of your model. For example you could have a "notifications" model that populates based on certain actions being fired (logged in, product added to basket, etc).

It also supports attach listeners to a "string" named action. This allows with interop with 3rd party libraries, or aids in migration.

Note: If any action being listened to does not complete successfully (i.e. throws an exception), then no listeners will be fired.

• on (Function, required)

  Allows you to attach a listener to an action. It expects the following arguments:

  • target (action | thunk | string, required)

    The target action you wish to listen to - you provide the direct reference to the action, or the string name of it.

  • handler (Function, required)

    The handler thunk to be executed after the target action is fired successfully. It can be an action or a thunk.

    The payload for the handler will be the same payload that the target action received

import { action, listen } from '@redux-app/store'; // 👈 import the helper

const userModel = {
  user: null,
  loggedIn: action((state, user) => {
    state.user = user;
  }),
  logOut: action((state) => {
    state.user = null;
  })
};

const notificationModel = {
  msg: '',

  // 👇 you can label your listeners as you like, e.g. "userListeners"
  listeners: listen((on) => {
    // Thunk handler
    on(userModel.loggedIn, thunk(async (actions, payload, helpers) => {
      const msg = `${payload.username} logged in`
      await auditService.log(msg)
    }));

    // Action handler
    on(userModel.logOut, action((state) => {
      state.msg = 'User logged out'
    });
  })
};

const model = {
  user: userModel,
  notification: notificationModel
};

import { listen } from '@redux-app/store';

const model = {
  msg: '',
  set: (state, payload) => { state.msg = payload; },

  listeners: listen((on) => {
    //      👇 passing in action name
    on('ROUTE_CHANGED', action(actions, payload) => {
      //                            👆
      // We won't know the type of payload, so it will be "any".
      // You will have to annotate it manually if you are using
      // Typescript and care about the payload type.
      actions.set(`Route was changed`);
    }));
  })
};

StoreProvider

Initialises your React application with the store so that your components will be able to consume and interact with the state via the useStore and useActions hooks.

import { StoreProvider, createStore } from '@redux-app/store';
import model from './model'

const store = createStore(model);

const App = () => (
  <StoreProvider store={store}>
    <TodoList />
  </StoreProvider>
)

useStore(mapState, externals)

A hook granting your components access to the store's state.

• mapState (Function, required)

  The function that is used to resolved the piece of state that your component requires. The function will receive the following arguments:

  • state (Object, required)

    The root state of your store.

• externals (Array of any, not required)

  If your useStore function depends on an external value (for example a property of your component), then you should provide the respective value within this argument so that the useStore knows to remap your state when the respective externals change in value.

Your mapState can either resolve a single piece of state. If you wish to resolve multiple pieces of state then you can either call useStore multiple times, or if you like resolve an object within your mapState where each property of the object is a resolved piece of state (similar to the connect from react-redux). The examples will illustrate the various forms.

import { useStore } from '@redux-app/store';

const TodoList = () => {
  const todos = useStore(state => state.todos.items);
  return (
    <div>
      {todos.map((todo, idx) => <div key={idx}>{todo.text}</div>)}
    </div>
  );
};

import { useStore } from '@redux-app/store';

const BasketTotal = () => {
  const totalPrice = useStore(state => state.basket.totalPrice);
  const netPrice = useStore(state => state.basket.netPrice);
  return (
    <div>
      <div>Total: {totalPrice}</div>
      <div>Net: {netPrice}</div>
    </div>
  );
};

import { useStore } from '@redux-app/store';

const BasketTotal = () => {
  const { totalPrice, netPrice } = useStore(state => ({
    totalPrice: state.basket.totalPrice,
    netPrice: state.basket.netPrice
  }));
  return (
    <div>
      <div>Total: {totalPrice}</div>
      <div>Net: {netPrice}</div>
    </div>
  );
};

Please be careful in the manner that you resolve values from your mapToState. To optimise the rendering performance of your components we use equality checking (===) to determine if the mapped state has changed.

When an action changes the piece of state your mapState is resolving the equality check will break, which will cause your component to re-render with the new state.

Therefore deriving state within your mapState in a manner that will always produce a new value (for e.g. an array) is an anti-pattern as it will break our equality checks.

// ❗️ Using .map will produce a new array instance every time mapState is called
//                                                     👇
const productNames = useStore(state => state.products.map(x => x.name))

You have two options to solve the above.

Firstly, you could just return the products and then do the .map outside of your mapState:

const products = useStore(state => state.products)
const productNames = products.map(x => x.name)

Alternatively you could use the select helper to define derived state against your model itself.

import { select, createStore } from '@redux-app/store';

const createStore = ({
  products: [{ name: 'Boots' }],
  productNames: select(state => state.products.map(x => x.name))
});

Note, the same rule applies when you are using the object result form of mapState:

const { productNames, total } = useStore(state => ({
  productNames: state.products.map(x => x.name), // ❗️ new array every time
  total: state.basket.total
}));

useActions(mapActions)

A hook granting your components access to the store's actions.

• mapActions (Function, required)

  The function that is used to resolved the action(s) that your component requires. Your mapActions can either resolve single or multiple actions. The function will receive the following arguments:

  • actions (Object, required)

    The actions of your store.

import { useState } from 'react';
import { useActions } from '@redux-app/store';

const AddTodo = () => {
  const [text, setText] = useState('');
  const addTodo = useActions(actions => actions.todos.add);
  return (
    <div>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <button onClick={() => addTodo(text)}>Add</button>
    </div>
  );
};

import { useState } from 'react';
import { useActions } from '@redux-app/store';

const EditTodo = ({ todo }) => {
  const [text, setText] = useState(todo.text);
  const { saveTodo, removeTodo } = useActions(actions => ({
    saveTodo: actions.todos.save,
    removeTodo: actions.todo.toggle
  }));
  return (
    <div>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <button onClick={() => saveTodo(todo.id)}>Save</button>
      <button onClick={() => removeTodo(todo.id)}>Remove</button>
    </div>
  );
};

useDispatch()

A hook granting your components access to the store's dispatch.

import { useState } from 'react';
import { useDispatch } from '@redux-app/store';

const AddTodo = () => {
  const [text, setText] = useState('');
  const dispatch = useDispatch();
  return (
    <div>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <button onClick={() => dispatch({ type: 'ADD_TODO', payload: text })}>Add</button>
    </div>
  );
};

Usage with Typescript

Easy Peasy has full support for Typescript, via its bundled definitions.

We announced our support for Typescript via this Medium post.

The documentation below will be expanded into higher detail soon, but the combination of the Medium post and the below examples should be enough to get you up and running for now. If anything is unclear please feel free to post and issue and we would be happy to help.

Easy Peasy exports numerous types to help you declare your model correctly.

import { Action, Reducer, Thunk, Select } from '@redux-app/store'

interface TodosModel {
  items: Array<string>
  // represents a "select"
  firstItem: Select<TodosModel, string | void>
  // represents an "action"
  addTodo: Action<TodosModel, string>
}

interface UserModel {
  token?: string
  loggedIn: Action<UserModel, string>
  // represents a "thunk"
  login: Thunk<UserModel, { username: string; password: string }>
}

interface StoreModel {
  todos: TodosModel
  user: UserModel
  // represents a custom reducer
  counter: Reducer<number>
}

// Note that as we pass the Model into the `createStore` function. This allows
// full type checking along with auto complete to take place
//                          👇
const store = createStore<StoreModel>({
  todos: {
    items: [],
    firstItem: select(state =>
      state.items.length > 0 ? state.items[0] : undefined,
    ),
    addTodo: action((state, payload) => {
      state.items.push(payload)
    }),
  },
  user: {
    token: undefined,
    loggedIn: action((state, payload) => {
      state.token = payload
    }),
    login: effect(async (dispatch, payload) => {
      const response = await fetch('/login', {
        method: 'POST',
        body: JSON.stringify(payload),
        headers: {
          'Content-Type': 'application/json',
        },
      })
      const { token } = await response.json()
      dispatch.user.loggedIn(token)
    }),
  },
  counter: reducer((state = 0, action) => {
    switch (action.type) {
      case 'COUNTER_INCREMENT':
        return state + 1
      default:
        return state
    }
  }),
})

console.log(store.getState().todos.firstItem)

store.dispatch({ type: 'COUNTER_INCREMENT' })

store.dispatch.todos.addTodo('Install typescript')

import { useStore, useActions, Actions, State } from '@redux-app/store';
import { StoreModel } from './your-store';

function MyComponent() {
  const token = useStore((state: State<StoreModel>) =>
    state.user.token
  )
  const login = useActions((actions: Actions<StoreModel>) =>
	  actions.user.login,
  )
  return (
    <button onClick={() => login({ username: 'foo', password: 'bar' })}>
      {token || 'Log in'}
    </button>
  )
}

The above can become a bit cumbersome - having to constantly provide your types to the hooks. Therefore we recommend using the bundled createTypedHooks helper in order to create pre-typed versions of the hooks.

// hooks.js

import { createTypedHooks } from "@redux-app/store";
import { StoreModel } from "./model";

export default createTypedHooks<StoreModel>();

We could then revise our previous example.

import { useStore, useActions } from './hooks';

function MyComponent() {
  const token = useStore((state) => state.user.token)
  const login = useActions((actions) => actions.user.login)
  return (
    <button onClick={() => login({ username: 'foo', password: 'bar' })}>
      {token || 'Log in'}
    </button>
  )
}

That's far cleaner - and it's still fully type checked.

const Counter: React.SFC<{ counter: number }> = ({ counter }) => (
  <div>{counter}</div>
)

connect((state: State<StoreModel>) => ({
  counter: state.counter,
}))(Counter)

Usage with React Native

Easy Peasy is platform agnostic but makes use of features that may not be available in all environments.

To use this library, you will need to pass the DevTools compose helper as part of the config object to createStore

import { createStore } from '@redux-app/store';
import { composeWithDevTools } from 'remote-redux-devtools';
import model from './model';

/**
 * model, is used for passing through the base model
 * the second argument takes an object for additional configuration
 */

const store = createStore(model, {
  compose: composeWithDevTools({ realtime: true, trace: true })
  // initialState: {}
});

export default store;

See https://github.com/zalmoxisus/remote-redux-devtools#parameters for all configuration options.

Writing Tests

The below covers some strategies for testing your store / components. If you have any useful test strategies please consider making a pull request so that we can expand this section.

All the below examples are using Jest as the test framework, but the ideas should hopefully translate easily onto your test framework of choice.

In the examples below you will see that we are testing specific parts of our model in isolation. This makes it far easier to do things like bootstrapping initial state for testing purposes, whilst making your tests less brittle to changes in your full store model structure.

Actions are relatively simple to test as they are essentially an immutable update to the store. We can therefore test the difference.

Given the following model under test:

import { action } from '@redux-app/store'

const todosModel = {
  items: {},
  add: action((state, payload) => {
    state.items[payload.id] = payload
  }),
}

We could test it like so:

test('add action', async () => {
  // arrange
  const todo = { id: 1, text: 'foo' }
  const store = createStore(todosModel)

  // act
  store.dispatch.add(todo)

  // assert
  expect(store.getState().items).toEqual({ [todo.id]: todo })
})

Thunks are more complicated to test than actions as they can invoke network requests and other actions.

There will likely be seperate tests for our actions, therefore it is recommended that you don't test for the state changes of actions fired by your thunk. We rather recommend that you test for what actions were fired from your thunk under test.

To do this we expose an additional configuration value on the createStore API, specifically mockActions. If you set the mockActions configuration value, then all actions that are dispatched will not affect state, and will instead be mocked and recorded. You can get access to the recorded actions via the getMockedActions function that is available on the store instance. We took inspiration for this functionality from the awesome redux-mock-store package.

In addition to this approach, if you perform side effects such as network requests within your thunks, we highly recommend that you expose the modules you use to do so via the injections configuration variable of your store. If you do this then it makes it significantly easier to provide mocked instances to your thunks when testing.

We will demonstrate all of the above within the below example.

Given the following model under test:

import { action, thunk } from 'thunk';

const todosModel = {
  items: {},
  add: action((state, payload) => {
    state.items[payload.id] = payload
  }),
  fetchById: thunk(async (actions, payload, helpers) => {
    const { injections } = helpers
    const todo = await injections.fetch(`/todos/${payload}`).then(r => r.json())
    actions.add(todo)
  }),
}

We could test it like so:

import { createStore, actionName, thunkStartName, thunkCompleteName, thunkFailName } from '@redux-app/store'

const createFetchMock = response =>
  jest.fn(() => Promise.resolve({ json: () => Promise.resolve(response) }))

test('fetchById', async () => {
  // arrange
  const todo = { id: 1, text: 'Test my store' }
  const fetch = createFetchMock(todo)
  const store = createStore(todosModel, {
    injections: { fetch },
    mockActions: true,
  })

  // act
  await store.dispatch.fetchById(todo.id)

  // assert
  expect(fetch).toHaveBeenCalledWith(`/todos/${todo.id}`)
  expect(store.getMockedActions()).toEqual([
    { type: thunkStartName(todosModel.fetchById), payload: todo.id },
    { type: actionName(todosModel.add), payload: todo },
    { type: thunkCompleteName(todosModel.fetchById), payload: todo.id },
  ])
})

When testing your components I strongly recommend the approach recommended by Kent C. Dodd's awesome Testing Javascript course, where you try to test the behaviour of your components using a natural DOM API, rather than reaching into the internals of your components. He has published a very useful package by the name of react-testing-library to help us do so. The tests below shall be adopting this package and strategy.

Imagine we were trying to test the following component.

function Counter() {
  const count = useStore(state => state.count)
  const increment = useActions(actions => actions.increment)
  return (
    <div>
      Count: <span data-testid="count">{count}</span>
      <button type="button" onClick={increment}>
        +
      </button>
    </div>
  )
}

As you can see it is making use of our hooks to gain access to state and actions of our store.

We could adopt the following strategy to test it.

import { createStore, StoreProvider } from '@redux-app/store'
import model from './model';

test('Counter', () => {
  // arrange
  const store = createStore(model)
  const app = (
    <StoreProvider store={store}>
      <ComponentUnderTest />
    </StoreProvider>
  )

  // act
  const { getByTestId, getByText } = render(app)

  // assert
  expect(getByTestId('count').textContent).toEqual('0')

  // act
  fireEvent.click(getByText('+'))

  // assert
  expect(getByTestId('count').textContent).toEqual('1')
})

As you can see we create a store instance in the context of our test and wrap the component under test with the StoreProvider. This allows our component to act against our store.

We then interact with our component using the DOM API exposed by the render.

This grants us great power in being able to test our components with a great degree of confidence that they will behave as expected.

Some other strategies that you could employ whilst using this pattern include:

• Providing an initial state to your store within the test.

  test('Counter', () => {
    // arrange
    const store = createStore(model, { initialState: initialStateForTest })
  
    // ...
  })

• Utilising the injections and mockActions configurations of the createStore to avoid performing actions with side effects in your test.

There is no one way to test your components, but it is good to know of the tools available to you. However you choose to test your components, I do recommend that you try to test them as close to their real behaviour as possible - i.e. try your best to prevent implementation details leaking into your tests.

Typescript API

Actions<Model = {}>

Creates a type that represents the actions for a model.

import { Actions } from '@redux-app/store';

type ModelActions = Actions<MyStoreModel>;

Action<Model = {}, Payload = any>

Represents an action, useful when defining your model interface.

import { Action, action } from '@redux-app/store';

interface Todos {
  items: string[];
  add: Action<Todos, string>;
}

const todos: Todos = {
  items: [],
  add: action((state, payload) => {
    state.items.push(payload);
  })
};

Listen<Model = {}, Injections = any, StoreModel = {}>

Represents a listen, useful when defining your model interface.

import { Listen, listen } from '@redux-app/store';

interface Audit {
  logs: string[];
  listen: Listen<Audit>;
}

const audit: Audit = {
  logs: [],
  listen: (on) => {
    on('ROUTE_CHANGED', action((state, payload) => {
      state.logs.push(payload.path);
    }));
  },
};

Reducer<State = any, Action = ReduxAction>

Represents a reducer, useful when defining your model interface.

import { Reducer, reducer } from '@redux-app/store';
import { RouterState, routerReducer } from 'my-router-solution';

interface Model {
  router: Reducer<RouterState>;
}

const model: Model = {
  router: reducer(routerReducer)
};

Select<Model = {}, Result = any>

Represents a select, useful when defining your model interface.

import { Select, select } from '@redux-app/store';

interface Todos {
  items: string[];
  firstTodo: Select<Todos, string | undefined>;
}

const todos: Todos = {
  items: [],
  firstTodo: select((state) => {
    return state.items.length > 0 ? state.items[0] : undefined;
  })
};

Thunk<Model = {}, Payload = void, Injections = any, StoreModel = {}, Result = any>

Represents a thunk, useful when defining your model interface.

import { Thunk, thunk } from '@redux-app/store';

interface Todos {
  items: string[];
  saved: Action<Todos, string>;
  save: Thunk<Todos, string>;
}

const todos: Todos = {
  items: [],
  saved: action((state, payload) => {
    state.items.push(payload);
  }),
  save: thunk(async (actions, payload) => {
    await saveTodo(payload);
    actions.saved(payload);
  })
};

createTypedHooks<StoreModel = {}>()

Allows you to create typed versions of all the hooks so that you don't need to constantly apply typing information against them.

// hooks.js
import { createTypedHooks } from '@redux-app/store';
import { StoreModel } from './model';

const { useActions, useStore, useDispatch } = createTypedHooks<StoreModel>();

export default {
  useActions,
  useStore,
  useDispatch
}

And then use your typed hooks in your components:

import { useStore } from './hooks';

export default MyComponent() {
  //                          This will be typed
  //                                       👇
  const message = useStore(state => state.message);
  return <div>{message}</div>;
}

Tips and Tricks

Below are a few useful tips and tricks when using Easy Peasy.

Generalising effects/actions/state via helpers

You may identify repeated patterns within your store implementation. It is possible to generalise these via helpers.

For example, say you had the following:

const store = createStore({
  products: {
    data: {},
    ids: select(state => Object.keys(state.data)),
    fetched: action((state, products) => {
      products.forEach(product => {
        state.data[product.id] = product;
      });
    }),
    fetch: thunk(async (actions) => {
      const data = await fetchProducts();
      actions.fetched(data);
    })
  },
  users: {
    data: {},
    ids: select(state => Object.keys(state.data)),
    fetched: action((state, users) => {
      users.forEach(user => {
        state.data[user.id] = user;
      });
    }),
    fetch: thunk(async (dispatch) => {
      const data = await fetchUsers();
      actions.fetched(data);
    })
  }
})

You will note a distinct pattern between the products and users. You could create a generic helper like so:

const data = (endpoint) => ({
  data: {},
  ids: select(state => Object.keys(state.data)),
  fetched: action((state, items) => {
    items.forEach(item => {
      state.data[item.id] = item;
    });
  }),
  fetch: thunk(async (actions, payload) => {
    const data = await endpoint();
    actions.fetched(data);
  })
})

You can then refactor the previous example to utilise this helper like so:

const store = createStore({
  products: {
    ...data(fetchProducts)
    // attach other state/actions/etc as you like
  },
  users: {
    ...data(fetchUsers)
  }
})

This produces an implementation that is like for like in terms of functionality but far less verbose.

Prior art

This library was massively inspired by the following awesome projects. I tried to take the best bits I liked about them all and create this package. Huge love to all contributors involved in the below.

• rematch

  Rematch is Redux best practices without the boilerplate. No more action types, action creators, switch statements or thunks.

• react-easy-state

  Simple React state management. Made with ❤️ and ES6 Proxies.

• mobx-state-tree

  Model Driven State Management