We are baking up the next version (v2.4.0). You can see all the details within the PR and view the updated docs here.
ย
Easy peasy global state for React
ย
import { action, createStore, StoreProvider, useStore, useActions } from 'easy-peasy';
const store = createStore({
todos: {
items: ['Install easy-peasy', 'Define your model', 'Have fun'],
add: action((state, payload) => {
state.items.push(payload)
})
}
});
const App = () => (
<StoreProvider store={store}>
<TodoList />
</StoreProvider>
)
function TodoList() {
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>
)
}
View the above code snippet with comments
import { action, createStore, StoreProvider, useStore, useActions } from 'easy-peasy';
// ๐ create your store, providing the model
const store = createStore({
todos: {
items: ['Install easy-peasy', '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>
)
}
Highlights
- Wraps Redux, all the radness, without the boilerplate
- Intuitive API allowing rapid development
- Mutate state, we do the hard work for you, auto converting mutations to immutable updates
- Thunks for data fetching and side effects
- React Hook based API
- Testing helpers baked in
- Supports Typescript (ships with definitions)
- Supports React Native
- Compatible with most of the Redux ecosystem:
- Redux Dev Tools support out of the box
- Store customisation, e.g. middleware
ย
ย
TOCs
- Introduction
- Installation
- Examples
- 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
- Core Concepts
- API
- Usage with Typescript
- Usage with React Native
- Writing Tests
- Typescript API
- Tips and Tricks
- 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
andreact-dom
, as this library depends on the new hooks feature
Then install Easy Peasy.
npm install easy-peasy
You're off to the races.
ย
Examples
Easy Peasy Typescript
This GitHub repository shows off how to utilise Typescript with Easy Peasy. I highly recommend cloning it and running it so that you can experience first hand what a joy it is to have types helping you with global state.
https://github.com/ctrlplusb/easy-peasy-typescript
React Todo List
A simple implementation of a todo list that utilises a mock service to illustrate data fetching/persisting via effect actions. A fully stateful app with no class components. Hot dang hooks are awesome.
https://codesandbox.io/s/woyn8xqk15
ย
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 'easy-peasy';
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 'easy-peasy'; // ๐ 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 easy-peasy');
// |-------------|
// |-- path matches our model (todos.addTodo)
Call getState
to see the updated state.
store.getState().todos.items;
// ['Install easy-peasy']
thunk
action
Creating a 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 'easy-peasy'; // ๐ 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
).
thunk
action directly via the store
Dispatching a 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 easy-peasy').then(() => {
console.log('Todo saved');
})
select
Deriving state via 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 'easy-peasy'; // ๐ import the 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 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 'easy-peasy'; // ๐ import the 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 'easy-peasy';
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 'easy-peasy';
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 'easy-peasy';
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 'easy-peasy';
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
First, install the `react-redux` package
npm install react-redux
Then wrap your app with the `Provider`
import React from 'react';
import { render } from 'react-dom';
import { createStore } from 'easy-peasy';
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'));
Finally, use `connect` against your components
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.
Arguments
-
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 yourselect
implementations. Please see theselect
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 thegetMockedActions
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).
-
Store Instance API
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 thecreateStore
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 thecreateStore
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.
Example
import { createStore } from 'easy-peasy';
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.
Arguments
-
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.
Example
import { action, createStore } from 'easy-peasy';
const store = createStore({
todos: {
items: [],
add: action((state, payload) => {
state.items.push(payload)
})
}
});
store.dispatch.todos.add('Install easy-peasy');
thunk(action)
Declares a thunk action on your model. Allows you to perform effects such as data fetching and persisting.
Arguments
-
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 thecreateStore
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.
Example
import { action, createStore, thunk } from 'easy-peasy'; // ๐ import the 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'));
Example accessing local state via the getState parameter
import { createStore, thunk } from 'easy-peasy';
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()
Example accessing full state via the getStoreState parameter
import { createStore, thunk } from 'easy-peasy';
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()
Example dispatching an action from another part of the model
import { action, createStore, thunk } from 'easy-peasy';
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.
Example with Dependency Injection
import { createStore, thunk } from 'easy-peasy';
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.
Arguments
-
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.
-
-
Example
import { createStore, reducer } from 'easy-peasy';
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.
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.
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 thedisableInternalSelectFnMemoize
setting on thecreateStore
'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.
Example
import { select } from 'easy-peasy'; // ๐ import the 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;
Example with arguments
import { select } from 'easy-peasy'; // ๐ import the 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);
Example with Dependencies
import { select } from 'easy-peasy';
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.
Arguments
-
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 athunk
.The payload for the handler will be the same payload that the target action received
-
Example
import { action, listen } from 'easy-peasy'; // ๐ 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
};
Example listening to string named action
import { listen } from 'easy-peasy';
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.
Example
import { StoreProvider, createStore } from 'easy-peasy';
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.
Argument
-
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 theuseStore
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.
Example
import { useStore } from 'easy-peasy';
const TodoList = () => {
const todos = useStore(state => state.todos.items);
return (
<div>
{todos.map((todo, idx) => <div key={idx}>{todo.text}</div>)}
</div>
);
};
Example resolving multiple values
import { useStore } from 'easy-peasy';
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>
);
};
Example resolving multiple values via an object result
import { useStore } from 'easy-peasy';
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>
);
};
A word of caution
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 'easy-peasy';
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.
Arguments
-
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.
-
Example
import { useState } from 'react';
import { useActions } from 'easy-peasy';
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>
);
};
Example resolving multiple actions
import { useState } from 'react';
import { useActions } from 'easy-peasy';
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.
Example
import { useState } from 'react';
import { useDispatch } from 'easy-peasy';
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.
We also have an example repository which you can clone and run for a more interactive run through.
Firstly, you need to define a type that represents your model.
Easy Peasy exports numerous types to help you declare your model correctly.
import { Action, Reducer, Thunk, Select } from 'easy-peasy'
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>
}
Then you create your store.
// 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
}
}),
})
The store's APIs will be typed
console.log(store.getState().todos.firstItem)
store.dispatch({ type: 'COUNTER_INCREMENT' })
store.dispatch.todos.addTodo('Install typescript')
You can type your hooks too.
import { useStore, useActions, Actions, State } from 'easy-peasy';
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 "easy-peasy";
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.
We also support typing `react-redux` based integrations.
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.
How to enable remote Redux dev tools
React Native, hybrid, desktop and server side Redux apps can use Redux Dev Tools using the [Remote Redux DevTools](https://github.com/zalmoxisus/remote-redux-devtools) library.
To use this library, you will need to pass the DevTools compose helper as part of the config object to createStore
import { createStore } from 'easy-peasy';
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.
Testing an action
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 'easy-peasy'
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 })
})
Testing a thunk
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 'easy-peasy'
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 },
])
})
Testing components
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 @testing-library/react
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 'easy-peasy'
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
andmockActions
configurations of thecreateStore
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.
Example
import { Actions } from 'easy-peasy';
type ModelActions = Actions<MyStoreModel>;
Action<Model = {}, Payload = any>
Represents an action
, useful when defining your model interface.
Example
import { Action, action } from 'easy-peasy';
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.
Example
import { Listen, listen } from 'easy-peasy';
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.
Example
import { Reducer, reducer } from 'easy-peasy';
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.
Example
import { Select, select } from 'easy-peasy';
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.
Example
import { Thunk, thunk } from 'easy-peasy';
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.
Example
// hooks.js
import { createTypedHooks } from 'easy-peasy';
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 is Redux best practices without the boilerplate. No more action types, action creators, switch statements or thunks.
-
Simple React state management. Made with
โค๏ธ and ES6 Proxies. -
Model Driven State Management