Redux Action Schema
Better action management for Redux
Redux Action Schema is a library for managing actions in Redux apps. It is a replacement for the constants file, providing stronger type guarantees while reducing boilerplate.
Documentation
Examples
Guide
npm install --save redux-action-schema
Creating a schema
In larger Redux projects, action types are frequently collected in a constants file. From the Redux docs:
For larger projects, there are some benefits to defining action types as constants:
- It helps keep the naming consistent because all action types are gathered in a single place.
- Sometimes you want to see all existing actions before working on a new feature. It may be that the action you need was already added by somebody on the team, but you didn’t know.
- The list of action types that were added, removed, and changed in a Pull Request helps everyone on the team keep track of scope and implementation of new features.
- If you make a typo when importing an action constant, you will get
undefined
. Redux will immediately throw when dispatching such an action, and you’ll find the mistake sooner.
But the way this is frequently implemented is primitive and repetitive:
const ADD_TODO = 'ADD_TODO'const EDIT_TODO = 'EDIT_TODO'const COMPLETE_TODO = 'COMPLETE_TODO'const DELETE_TODO = 'DELETE_TODO'const COMPLETE_ALL = 'COMPLETE_ALL'const CLEAR_COMPLETED = 'CLEAR_COMPLETED'const SET_VISIBILITY = 'SET_VISIBILITY' const SHOW_ALL = 'show_all'const SHOW_COMPLETED = 'show_completed'const SHOW_ACTIVE = 'show_active'
This gets the job done, but its ugly and repetitive. Furthermore it doesn't provide any information about the data in the action, only the type. Redux Action Schema enables compact action definitions with runtime type checks:
const showStates = "all" "completed" "active" const schema =
This provides all of the benefits of using constants, but with additional benefits:
- Consistent naming: All action types are gathered in the same place. Additionally, the argument names are gathered in the same place, so that those will be consistently named as well.
- Track changes in pull requests: You can see actions added, removed and changed at a glance in a pull request. Additionally, you can see changes in the action payloads.
- Handle typos: If you make a typo when using one of the created actions, e.g.
schema.actions.compleatTodo
, you will getundefined
. Additionally, you will get errors if you:- use an undefined action creator, e.g.
schema.actionCreators.compleatTodo()
- use an unknown action in
createReducer
, e.g.schema.createReducer({compleatTodo: (state) => state })
- dispatch an unknown action when using the validation middleware
- use an undefined action creator, e.g.
Generating a schema in an existing app
Redux Action Schema also includes a middleware that can automatically generate a schema for an existing app. Add the schema observer middleware:
/* ... */ // attached to window so its accessible from inside consolewindowschemaObserver = const store =
Run the app (manually or with a test runner). Then, from the console:
> windowschemaObserver< `createSchema([ ["foo"], ["bar", types.Number], ["baz", types.String.optional], ["quux", types.OneOfType.optional(types.Number, types.String)], ["xyzzy", ["a", types.Number], ["b", types.String]] ])`
You can copy the output of schemaDefinitionString
from the console into your code and get a head start on
Generated actions
Protect against typos and automatically handle namespaces with generated actions:
schemaactionsaddTodo // => "addTodo"schemaactionsadTodo // => undefined // actions can be namespaced:const fooSchema = schemaactionsaddTodo // => "foo_addTodo"
Action creators
An action creator is generated for each action in the schema:
const editTodo completeTodo = schemaactionCreators// => { type: "editTodo", payload: { id: 10, text: "write docs" } } // => { type: "completeTodo", payload: 20 } editTodo// => { type: "editTodo", payload: { id: 10, text: "write GOOD docs" } }
Reducers
The schema can be used to create and validate simple reducers a la redux-action's handleActions:
const todoReducer = schema
Unlike handleActions
, createReducer verifies that a reducer's handled actions are in the schema:
schema // => Uncaught Error: "unknown action: nope"
Middleware
Finally, the schema generates a redux middleware for checking that dispatched actions are in the schema:
const store = store // errorstore // error
You may choose to use all these features at once, or mix and match -- you don't need to use the action creators or createReducer to benefit from the middleware, nor vice versa.