Easy Ducks
Easy Ducks is a utility that simplifies the implementation of the ducks pattern for async actions in Redux. It eliminates the need to manually create reducers (no more switch statements!) or action types, and greatly simplifies action creators.
Easy Ducks automatically handles loading states by adding loading
and didLoad
keys to each reducer. When a request is in progress, loading
will be true, and when a request has previously completed at some point, didLoad
is set to true. This can be useful if you want to show a different loading state for when there is some pre-existing data, versus the initial load with no data.
By default, Easy Ducks adds async responses to the reducer by with object spread notation, e.g.,
...state ...actionresponse
You can override this by providing resolver
functions to action creators in order to define custom behavior.
Easy Ducks assumes you're using redux-thunk middleware in your project.
The default configuration relies on the fetch API, so you may need to provide a polyfill for extended browser support. Alternatively, you can use plugins to support other http implementations.
Installation
yarn add easy-ducks # or npm install --save easy-ducks
Quick Start
First create your duck and export the reducer:
// ducks/users.js const duck = 'myDuck' baseUrl: 'https://myapi.com/api' // Pass this to redux's combineReducers functionreducer // Action creatorsconst getUser = duck const createUser = duck const editUser = duck const deleteUser = duck
Then add the exported duck.reducer
to your root reducer:
// ducks/index.js users
Options
Instance Options
The first constructor argument is a string indicating the name of the duck. The name is used to assemble the Redux action type, so it must be unique.
The format for the generated action types looks like this:
[{name}] {method}: {status}
For example, if you create a duck with the name myDuck
, the actions for duck.get()
would look like this:
// GET begin type: '[myDuck] GET: BEGIN' // GET error type: '[myDuck] GET: ERROR' error // GET success type: '[myDuck] GET: SUCCESS' response
The second constructor argument is an instance configuration object:
Name | Type | Required | Default | Description |
---|---|---|---|---|
baseUrl | string | true | The base url for your api | |
initialState | object | false | The default value to be passed to the reducer | |
plugin | function | false | Allows for http implementations other than fetch |
|
storeParams | boolean | false | false | Tells Easy Ducks to save any params passed to a request in the reducer |
As an alternative to storeParams
, you can include a params
object in the initialState
:
const duck = 'myDuck' baseUrl: 'https://myapi.com/api' initialState: params: {}
Request Options
The first request argument is path
, which is a string that indicates the remainder of the request URL after the baseUrl
provided in the constructor.
The second request argument is an optional configuration object:
Name | Type | Required | Description | Arguments |
---|---|---|---|---|
actionModifiers | object | false | Allows for modifying the dispatched action. | |
onError | function | false | Callback function for request error | error , getState |
onSuccess | function | false | Callback function for request success | success , getState |
params | object | false | Contains any parameters to be passed with the request. | |
resolver | function | false | Allows custom handling of responses | state , action |
verb | string | false | Specifies an alternate verb to use in the action type. Defaults to the http method, e.g. get , post , etc. |
Global configuration
This package provides a named export called DuckFactory
to simplify re-use of configuration values across all duck instances.
// duckFactory.js const duckFactory = baseUrl: 'https://my-api.com/api' plugin
Now import this instance into your individual duck files and create new ducks from that. Ducks created using this method will inherit any configuration options that you previously specified.
const duck = duckFactory reducer const getUsers = duck
Action Modifiers
Action modifiers are functions that allow you to modify the object that is passed to the dispatch
function. You can provide a modifier for each of the three statuses: begin
, success
, and error
.
Modifier | Arguments |
---|---|
begin | getState |
success | response , getState |
error | error , getState |
This functionality can be useful if you're using some type of redux analytics middleware, such as redux-segment to track events based on redux actions.
In this example, the analytics
key would be added to the object passed to dispatch
:
const fetchUser = duck
Callbacks
The dispatch function returns a promise, so if you want to perform actions after the request's success or failure you can do so inside a .then
block.
For example, if you wanted to save a response to local storage on success:
store
Sometimes you may want to perform some action inside the action creator itself. For this scenario there are two optional callbacks, onSuccess
and onError
. These callbacks receive response
and error
, respectively, as arguments.
Using these callbacks, the example above would look like this:
const fetchUser = duck
Resolvers
Resolvers are functions that allow you to define custom behavior for updating the store. Resolvers take the same arguments as the reducer itself, state
and action
, and return the new state on request success.
For example, if a reducer contains an array of users, and you want to add the new user object returned by your createUser
action creator, you can define a resolver that adds it to the end of the array.
const createUser = duck
Plugins
Easy Ducks uses fetch
by default to make http requests, but you can provide plugins if you'd like to use something else. Plugins for axios
and fetch
are included with the library.
const plugin = const duck = 'myDuck' baseUrl: 'https://myapi.com/api' plugin
You can also provide a configuration object to plugin which will be passed along to the config options for the http solution.
const plugin =
Since fetch
is used by default, you only need to explicitly provide the fetch
plugin if you want to pass it a custom configuration object.
Notes:
- If you're using the
axios
plugin, you must haveaxios
installed as a package dependency. - If you're using
fetch
, query params must be included directly in thepath
string.
Writing Plugins
Plugins are simply functions that take an object and map the values to the http library of your choice. The object keys are:
baseUrl
- The base URL of your APImethod
- e.g.,delete
,get
,post
,put
path
- The remainder of the request endpoint afterbaseUrl
params
- An object containing request data
Take a look at the plugins in the src/plugins
directory for some examples.
Example Project
This repo includes an example project that you can run to test out the library in action.
# Install dependencies yarn # Start the dev server yarn start
Then go to localhost:7000
to view the example project.