Ducks NPM | npm.io

ducks

🦆🦆🦆 Ducks is A Redux Modular Proposal Implementation for Easily Managing and Using Your Ducks Reducer Bundle Packages.

Ducks

Image Credit: Alamy

Ducks offers a method of handling redux module packaging, installing, and running with your Redux store, with middware support. The goal of Ducks is to help you organizing your code for the long term.

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)

Features

Implemented the specification from Ducks Modular Proposal, Erik Rasmussen, 2015
Easy connecting ducks to store by adding one enhancer to redux. (that's all you need to do!)
Fully typing with all APIs by TypeScript
Binding store to operators and selectors by currying for maximum convenience.

Todo-list

Ducks middleware support
Provides a Ducks Management interface for adding/deleting a duck module

Motivation

I'm building my redux ducks module for Wechaty Redux project and ...

The Ducks Modular Proposal

The specification has rules that a module...

MUST export default a function called reducer()
MUST export its action creators as functions
MUST have action types in the form npm-module-or-app/reducer/ACTION_TYPE
MAY export its action types as UPPER_SNAKE_CASE, if an external reducer needs to listen for them, or if it is a published reusable library

Here'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

The Re-Ducks Extionsion: Duck Folders

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.

General rules for a duck folder

A duck folder:

MUST contain the entire logic for handling only ONE concept in your app, ex: product, cart, session, etc.
MUST have an index.js file that exports according to the original duck rules.
MUST keep code with similar purpose in the same file, ex: reducers, selectors, actions, etc.
MUST contain the tests related to the duck.

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

Extensions

Perfrect TypeScript(v3.7) Typing Support powered by typesafe-actions.
selectors...: Currying a State
operators ... Currying a Dispatch
namespaces...
sagas...
epics...

nesting ducks?

Ducks++ is to define a string constant inside the duck to determine where the state is stored in the store; Ducks++: Redux Reducer Bundles, Djamel Hassaine, 2017

Requirements

Node.js v12+
Browsers

Usage

1 Setup Ducks

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,
    })
  }
}

2 Load Ducks

import { Ducks, Duck }    from 'ducks'
import { CounterDuckAPI } from 'ducks/examples/counter/'

const counter = new Duck(CounterDuckAPI)
const ducks   = new Ducks({ counter })

3 Create Store

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 set!

A full example that demostrate how to use Ducks 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

API References

3.1 Shortcut to Configure the Store

If you only use Redux with Ducks, then you can use the shortcut from the Ducks to get the configured store:

const store = ducks.getStore()

The ducks.getStore() will do exact the same as the above createStore() codes.

References

in compose(), ducks.enhancer() must be put before applyMiddleware

  ducks.enhancer(),
  applyMiddleware(

`reduceReducersFromMapObject`

We planed to directly use reduce-reducers before, however it does not support types well. The ReturnType of it can not reflect the data type of the reducer returned state.

Inspired from https://github.com/redux-utilities/reduce-reducers/

Knowned Issues: https://stackoverflow.com/a/44371190/1123955

const addAndMult = reduceReducers(reducerAdd, reducerMult) 

const initial = addAndMult(undefined)
/*
 * {
 *   sum: 0,
 *   totalOperations: 0
 * }
 *
 * First, reducerAdd is called, which gives us initial state { sum: 0 }
 * Second, reducerMult is called, which doesn't have payload, so it
 * just returns state unchanged.
 * That's why there isn't any `product` prop.
 */

Developing Tools

Middlewares

Articles

Modular Reducers and Selectors
Idiomatic Redux: Thoughts on Thunks, Sagas, Abstraction, and Reusability redux-middleware-lifecycle-7d8defa4db7e)
reSolve - A Redux-Inspired Backend

Sagas

Relate Libraries

Related Projects

redux-dynamic-middlewares - Allow add or remove redux middlewares dynamically

Resources

Redux Ecosystem Links - A categorized list of addon libraries for Redux, as well as other libraries that are closely related

Concepts

Redux Ducks API compares with CQRS, Event Sourcing, and DDD:

Ducks	CQRS	Event Sourcing
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