π¦π¦π¦Ducks is a Reducer Bundles Manager that Implementing the Redux Ducks Modular Proposal with Great Convenience.
Image Credit: Alamy
Ducks offers a method of handling redux module packaging, installing, and running with your Redux store, with middleware support.
Java has jars and beans. Ruby has gems. I suggest we call these reducer bundles "ducks", as in the last syllable of "redux".
— Erik Rasmussen, 2015 (link)
The goal of Ducks is to:
operators
and selectors
by binding the Store
to them for maximum convenience.Todo-list:
I'm building my redux ducks module for Wechaty Redux project and ...
To be written.
At last, I decide to write my own manager for ducks, which will implement the following two specifications, with my own Ducksify Extension:
selectors
and operators
The specification has rules that a module:
export default
a function called reducer()
export
its action creators as functionsnpm-module-or-app/reducer/ACTION_TYPE
UPPER_SNAKE_CASE
, if an external reducer needs to listen for them, or if it is a published reusable libraryHere's the full version of Ducks proposal: Redux Reducer Bundles, A proposal for bundling reducers, action types and actions when using Redux, Erik Rasmussen, 2015
Re-Ducks
is an extension to the original proposal for the ducks redux modular architecture.
By defining a ducks with duck folders instead of a duck file, it defines the duck folder would like:
duck/
βββ actions.js
βββ index.js
βββ operations.js
βββ reducers.js
βββ selectors.js
βββ tests.js
βββ types.js
βββ utils.js
NOTE: Each concept from your app will have a similar folder.
A duck folder:
index.js
file that exports according to the original duck rules.Here's the full version of Re-ducks proposal: Building on the duck legacy, An attempt to extend the original proposal for redux modular architecture, Alex Moldovan, 2016 and blog
In order to build a fully modularized Ducks, we define the Ducksify extension with the following rules:
MUST export its module interface as the following Duck
interface:
export interface Duck {
/**
* Ducks Modular Proposal (https://github.com/erikras/ducks-modular-redux)
*/
default: Reducer,
actions : ActionCreatorsMapObject,
operations?: OperationsMapObject,
selectors? : SelectorsMapObject,
types? : TypesMapObject,
/**
* Ducksify Extension (https://github.com/huan/ducks#3-ducksify-extension-currying--ducksify-interface)
*/
middlewares?: MiddlewaresMapObject,
epics?: EpicsMapObject,
// Disabled temporary. See: https://github.com/huan/ducks/issues/4
// sagas?: SagasMapObject,
setDucks?: (ducks: Ducks<any>) => void
}
MUST support Currying the first argument for selectors.*
with a State
object
MUST support Currying the first argument for operations.*
with a Dispatch
function
MAY export its middlewares functions called *Middleware()
MAY export its saga functions called *Saga()
MAY export its epic functions called *Epic()
MAY use typesafe-actions to creating reducers, actions, and middlewares.
If we has sagas
, epics
, or middlewares
, the duck folder would like:
duck/
βββ epics.js
βββ sagas.js
βββ middlewares.js
Node.js v16+, or Browser with ES2020 Support
npm install ducks
Duck
For example, let's create a Duck module file named counter.ts
:
export const types = { TAP: 'ducks/examples/counter/TAP' }
export const actions = { tap: () => ({ type: TAP }) }
export const operations = { tap: dispatch => dispatch(actions.tap()) }
export const selectors = { getTotal: state => () => state.total }
const initialState = { total: 0 }
export default function reducer (state = initialState, action) {
if (action.type === types.TAP) {
return ({
...state,
total: (state.total || 0) + 1,
})
}
return state
}
Ducks
Managerimport { Ducks } from 'ducks'
import * as counterDuck from './counter.js'
const ducks = new Ducks({ counter: counterDuck })
const counter = ducks.ducksify(counterDuck)
import { createStore } from 'redux'
const store = createStore(
state => state, // Your other reducers
ducks.enhancer(), // Add ducks to your store (that's all you need to do!)
)
You are all set!
The Vanilla Style and Ducksify Style is doing exactly the same thing.
store.dispatch(counterApi.actions.tap())
console.info('getTotal:', counterApi.selectors.getTotal(store.getState().counter)))
// Output: getTotal: 1
counter.operations.tap()
console.info('getTotal:', counter.selectors.getTotal()))
// Output: getTotal: 2
It turns out that the Ducksify Style is more clear and easy to use by currying them with the store as their first argument.
That's it!
Let's get to know more about Ducks by quack!
The following is the full example which demonstrate how to use Ducks.
It shows that:
redux-observable
and redux-saga
out-of-the-box with zero configuration.The following example code can be found at examples/quack.ts, you can try it by running the following commands:
git clone git@github.com:huan/ducks.git
cd ducks
npm install
npm start
import { createStore } from 'redux'
import { Duck, Ducks } from 'ducks'
import * as counterDuck from './counter.js' // Vanilla Duck: +1
import * as dingDongDuck from './ding-dong.js' // Observable Middleware
import * as pingPongDuck from './ping-pong.js' // Saga Middleware
import * as switcherDuck from './switcher.js' // Type Safe Actions: ON/OFF
const ducks = new Ducks({
counter : counterDuck,
switcher : switcherDuck,
dingDong : dingDongDuck,
pingPong : pingPongDuck,
})
const {
counter,
dingDong,
pingPong,
switcher,
} = ducks.ducksify()
const store = createStore(
state => state, // Here's our normal Redux Reducer
ducks.enhancer(), // We use Ducks by adding this enhancer to our store, and that's it!
)
/**
* Vanilla: Counter
*/
assert.strictEqual(counter.selectors.getCounter(), 0)
counter.operations.tap()
assert.strictEqual(counter.selectors.getCounter(), 1)
/**
* TypeSafe Actions: Switchers
*/
assert.strictEqual(switcher.selectors.getStatus(), false)
switcher.operations.toggle()
assert.strictEqual(switcher.selectors.getStatus(), true)
/**
* Epic Middleware: DingDong
*/
assert.strictEqual(dingDong.selectors.getDong(), 0)
dingDong.operations.ding()
assert.strictEqual(dingDong.selectors.getDong(), 1)
/**
* Saga Middleware: PingPong
*/
assert.strictEqual(pingPong.selectors.getPong(), 0)
pingPong.operations.ping()
assert.strictEqual(pingPong.selectors.getPong(), 1)
console.info('store state:', store.getState())
I hope you will like this clean and beautiful Ducksify
way with using Ducks!
Ducks is very easy to use, because one of the goals of designing it is to maximum the convenience.
We use Ducks
to manage Redux Reducer Bundle
s with the Duck
interface that following the ducks modular proposal.
For validating your Duck
form the redux module (a.k.a reducer bundle), we have a validating helper function validateDuck
that accepts a Duck
to make sure it's valid (it will throws an Error when it's not).
Duck
The Duck
is a interface which is defined from the ducks modular proposal, extended from both Re-Ducks and Ducksify.
Example:
Duck
counter example from our examples
import * as actions from './actions.js'
import * as operations from './operations.js'
import * as selectors from './selectors.js'
import * as types from './types.js'
import reducer from './reducers.js'
export {
actions,
operations,
selectors,
types,
}
export default reducer
Ducks
The Ducks
class is the manager for Duck
s and connecting them to the Redux Store by providing a enhancer()
to Redux createStore()
.
import { Ducks } from 'ducks'
import * as counterApi from './counter.js'
const ducks = new Ducks({
counter: counterApi,
})
const store = createStore(
state => state,
ducks.enhancer(),
)
// Duck will be ready to use after the store has been created.
There is one important thing that we need to figure out is that when we are passing the DucksMapObject
to initialize the Ducks
({ counter: counterDuck }
in the above case), the key name of this Api will become the mount point(name space) for its state.
Choose your key name wisely because it will inflect the state structure and the typing for your store.
There's project named Ducks++: Redux Reducer Bundles, Djamel Hassaine, 2017 to solve the mount point (namespace) problem, however, we are just use the keys in the
DucksMapObject
to archive the same goal.
Ducks#enhancer()
Returns a StoreEnhancer
for using with the Redux store creator, which is the most important and the only one who are in charge of initializing everything for the Ducks.
const store = createStore(
state => state,
ducks.enhancer(),
)
If you have other enhancers need to be used with the Ducks, for example, the applyMiddleware()
enhancer from the Redux, you can use compose()
from Redux to archive that:
import { applyMiddleware, compose, createStore } from 'redux'
import { Ducks } from 'ducks'
// ...
const store = createStore(
state => state,
compose(
ducks.enhancer(),
applyMiddleware(
// ...
),
)
)
NOTE: our
enhancer()
should be put to the most left in thecompose()
argument list, because it would be better to make it to be the most outside one to be called.
Ducks#configureStore()
If you only use Redux with Ducks without any other reducers, then you can use configureStore()
shortcut from the Ducks to get the configured store.
const store = ducks.configureStore(preloadedStates)
The above code will be equals to the following naive Redux createStore()
codes because the configureStore()
is just a shortcut of that for our convenience.
// This is exactly what `ducks.configureStore()` does:
const store = createStore(
state => state,
preloadedStates,
ducks.enhancer(),
)
Ducks#ducksify()
ducksify()
will encapsulate the Api
into the Bundle
class so that we will have a more convenience way to use it.
const { counter } = ducks.ducksify()
For example:
import * as counterDuck from './counter.js'
const ducks = new Ducks({ counter: counterDuck })
const store = ducks.configureStore()
// 1. Return all Bundles
const { counter } = ducks.ducksify()
// 2. Return the Bundle for namespace: `counter`
const counterByName = ducks.ducksify('counter')
assert(counterByName === counter)
// 3. Return the Bundle for api: `counterDuck`
const counterByApi = ducks.ducksify(counterDuck)
assert(counterByApi === counter)
Comparing the Duck with the Bundle (ducksified Duck), we will get the following differences: (counterBundle
is the ducksified counterDuck
)
For selectors
:
- counterDuck.selectors.getTotal(store.getState().counter)()
+ counterBundle.selectors.getTotal()
For operations
:
- counterDuck.operations.tap(store.dispatch)()
+ counterBundle.operations.tap()
As you see, the above differences showed that the ducksified api will give you great convenience by currying the Store
inside itself.
validateDuck()
To make sure your Ducks Api is following the specification of the ducks modular proposal, we provide a validating function to check it.
import { validateDuck } from 'ducks'
import * as counterDuck from './counter.js'
validateDuck(counterDuck) // will throw if the counterApi is invalid.
Redux Ducks Api compares with CQRS, Event Sourcing, and DDD:
Ducks | CQRS | Event Sourcing | DDD |
---|---|---|---|
actions | Domain Aggregates with Command handlers | ||
- creator | Command | ||
- payload | Event | Event | |
selectors | Query | ||
operations | Command + Event | ||
middlewares | Aggregate? | Saga ? | |
types | ?? | ||
reducers | Reducers to calculate Aggregate state |
reSolve is a Node.js library for Redux & CQRS
Domain aggregate is a business model unit. Business logic is mostly in command handlers for the aggregate.
Don't store system state, store events that brought system to this state.
CQRS system is divided in two "sides":
Release v1.0 of Redux Ducks
v0.11 (Sep 2021)
saga
support temporary due to (#4)Add setDucks()
to Duck
API interface,
so that all the Duck
can get the Ducks
instance
(if needed, by providing a setDucks()
method from the API),
which helps the Duck
s talk to each others.
Renaming for better names with a better straightforward intuition.
interface Api
to interface Duck
class Duck
to class Bundle
function validateDucksApi
to function validateDuck
Refactoring the Ducks
with better Api interface.
ducksify()
method for get Duck
instance by namespace
or api
.Fix the TypeScript Generic Template typing problems:
@gobwas is the gentleman who owned this ducks NPM module name, and he's so kind for letting me use this great NPM module name ducks
for my project. Appreciate it!
[![Powered by Ducks](https://img.shields.io/badge/Powered%20by-Ducks-yellowgreen)](https://github.com/huan/ducks#3-ducksify-extension-currying--ducksify-interface)
[![Ducksify Extension](https://img.shields.io/badge/Redux-Ducksify%202020-yellowgreen)](https://github.com/huan/ducks#3-ducksify-extension-currying--ducksify-interface)
Huan LI (ζεζ‘), Microsoft Regional Director, \zixia@zixia.net\