redux-schemas is a small library designed to abstract away the verbosity & boilerplate that comes when using Redux, particularly when dealing with async actions.
- Removes the need for action name constants
- Reducers, requests, selectors & initial state for a particular entity all live under the one roof.
- Selectors are scoped, just like reducers - the
stateargument represents your state slice rather than the global state. - For async actions, reducers can be split into a main one and a seperate one to handle the asynchronous lifecycle. Useful for handling
isLoadingboilerplate.
yarn add redux-schemas
Alternatively:
npm install redux-schemas --save
First, define a schema - all you need is a name and a a series of actions. At the very least, each action needs a reduce property. By adding a request property with a function that returns a Promise, you can make an async action.
export default createSchema(
'books',
{
// A simple async method (thunk)
addBook: {
request: (payload, schema, dispatch) =>
api('http://example.com/', payload),
// Reducer on promise success
reduce: (state, action) => {
return {
...state,
entities: state.entities.concat([action.payload])
};
}
},
// A simple synchronous method
changeGenre: {
reduce: (state, action) => {
return {
...state,
genre: action.payload
};
}
}
},
{
// Selectors are scoped to this state slice, with a global state escape hatch! đź‘Ś
bookCount: (state, globalState) => state.entities.length
}
);Then add them to a store, using the optional combineSchemas helper to handle keys & merging of initial state. You can mix and match currently existing reducers with redux-schemas reducers, allowing you to incrementally adopt redux-schemas if required.
import books from './schemas/books';
import movies from './schemas/movies';
import anotherReducer from './reducers/other';
import { createStore } from 'redux';
import { combineSchemas, thunk } from 'redux-schemas';
const schemas = combineSchemas([books, movies]);
export default createStore(
combineReducers({ schemas, anotherReducer }),
{},
applyMiddleware(thunk)
);Then your schemas are good to go!
import { store } from './your-store';
import 'books' from './schemas/books';
store.dispatch(
books.actionCreators.addBook({name: '1984'})
);| Parameter | Description |
|---|---|
schemaName |
Name of the schema - used for actions & the key for this particular slice of state |
actionCreators |
Object of action creator definitions. At the very least, a definition must have a reduce prop. Add a request function that returns a Promise to make it async. |
selectors (optional) |
Object of selector functions that take state as a parameter (state is scoped to the schema key, but the global state is passed as a second argument as an escape hatch). |
initialState (optional) |
The initial state for this schema key. |
A reducer function ready to be used in combineReducers, that also has several extra (non-enumerable) properties:
schemaNameactionCreatorsselectorsinitialState
| Parameter | Description |
|---|---|
schemaArray |
Array of schemas to combine |
namespace |
Dot notation string representing the state path where your schemas should live. |
A reducer function ready to be used in combineReducers, that also has an initialState prop with the combined initial state from all provided reducers.
| Parameter | Description |
|---|---|
schemas |
Array of schemas (or several params) to hook up to a React component |
An array of parameters to be spread into a react-redux connect() function. The props you'll end up getting will be namespaced by the schema name (e.g. this.props.books will contain both selectors & action creators for the books schema). If an action creator & selector share the same name, the action creator will take precedence.
Hooking up a component to a single schema is a piece of cake 🍰.
import React from 'react';
import { connect } from 'react-redux';
import books from './schemas/books';
@connect(books.selectors, books.actionCreators)
class BookScreen extends React.Component {
render() {
const { addBook, bookCount } = this.props;
return (
<div>
<h2>Books</h2>
<strong>Count: {bookCount}</strong>
<a onClick={addBook}>Add Book</a>
</div>
);
}
}To make hooking up multiple schemas easier, you can use the withSchemas helper which generates mapStateToProps and mapDispatchToProps for several schemas at once, which can then be spread into a connect function:
import React from 'react';
import { withSchemas } from 'redux-schemas';
import books from './schemas/books';
import movies from './schemas/movies';
@connect(...withSchemas(books, movies))
class BooksAndMovies extends React.Component {
render() {
const { books, movies } = this.props;
return (
<div>
<h2>Books</h2>
<strong>Count: {books.bookCount}</strong>
<a onClick={books.addBook}>Add Book</a>
<h2>Movies</h2>
<strong>Count: {movies.movieCount}</strong>
<a onClick={movies.addMovie}>Add Movie</a>
</div>
);
}
}redux-schemas lets you have total control over the request lifecycle. By default, if you pass a function to reduce in an async schema action, that reducer will be run on request success. You can instead pass an initial/success/failure object for more flexibility
The most common use case for this would be for optimistic state updates that get applied immediately, and then reverted on failure.
createSchema("books", {
addBook: {
request: payload => api("http://example.com/", payload),
reduce: {
initial: (state, action) => {
// Optimistically update state without waiting for API
return {
...state,
entities: state.entities.concat([payload])
};
},
success: state => state,
failure: (state, action) => {
// Revert optimistic changes on failure
return {
...state,
entities: state.entities.slice(0, state.entities.length - 1)
};
}
}
}
});Along with the payload argument, your request functions also receive two extra arguments: schema, which allows you to call other actions from this schema that are immediately dispatched, and dispatch itself.
createSchema('books', {
tidyUpBookshelf: {
reduce: state => ({ ...state, bookshelfTidy: true })
},
addBook: {
request: (payload, schema, dispatch) => {
return api('http://example.com/', payload).then(() => {
schema.tidyUpBookshelf(); // immediately dispatched
dispatch(anotherSchema.actionCreators.doSomething());
});
},
reduce: (state, action) => ({
...state,
entities: state.entities.concat([action.payload])
})
}
});When using an async schema action (a.k.a one with request defined) redux-schemas lets you run another set of reducers alongside your main reduction logic.
This is designed to help you abstract out common isLoading boilerplate that is probably the same for almost all the entities you're working with.
By default a generic reduceRequest is provided. It manages an isLoading key as well as an error key. You can use your own, or disable the functionality by setting reduceRequest to null or false.
createSchema('books', {
addBook: {
request: (payload) => api('http://example.com/', payload)
reduce: (state, action) => {
return {
...state,
entities: state.entities.concat([action.payload])
}
},
// The following is what it's set to by default
reduceRequest: {
initial: (state, action) => {
return {
...state,
isLoading: true,
error: null
}
},
success: (state, action) => {
return {
...state,
isLoading: false,
error: null
};
},
failure: (state, action) => {
return {
...state,
isLoading: false,
error: action.payload
}
}
}
}Just wrap the createSchema function & process as you please. For large applications, its assumed that you'd almost certainly want to do this.
If you're feeling a bit lazy, there's a handy schemaDefaults helper that takes an object of method defaults,
and generates a createSchema function that uses those defaults.
import createSchema, { schemaDefaults } from 'redux-schemas';
export function customSchemaCreator(
schemaName,
actionCreators,
selectors,
initialState
) {
return schemaDefaults({ reduceRequest: null })(
schemaName,
actionCreators,
selectors,
initialState
);
}