@drukas/xdux

An opinionated redux library for creating actions and reducers, that gives you an ability to declare actions and handlers in one place.

Getting started

Setup

Xdux requires ramda and redux-actions to be installed.

npm install --save @drukas/xdux ramda redux-actions redux

or

yarn add @drukas/xdux ramda redux-actions redux

Use

Here is the example of simple xdux module.

./module.js

import * as R from 'ramda'
import xdux from '@drukas/xdux'

export const config = {
  namespace: 'My module' // used as prefix for actions
  sliceName: 'myModule' // state in store accessable as store.myModule
}

export const initialState = {
  count: 0,
  lib: { name: 'xdux' },
}

export const lenses = {
  count: R.lensProp('count'),
  libName: R.lensPath(['lib', 'name']),
}

export const { createAction, module, sliceSelector } = xdux({
  config,
  initialState,
})

export default module

If you are not familiar with lenses you can learn about it here. But basically lens is a unit that combines both set and get functions.

./actions.js

import * as R from 'ramda'
import myModule, { createAction, lenses } from './module'

/* There are two ways of creating actions and handlers */

/* The first "two-steps" way */
const setCount = createAction('Set count')
const setLibName = createAction('Set lib name')
myModule.handlers({
  [setCount]: (state, { payload }) => R.set(lenses.count, payload, state),
  [setLibName]: (state, { payload }) => R.set(lenses.libName, payload, state),
})

/* The second "xdux" way */
const { setCount, setLibName } = myModule.actions({
  setCount: [
    'Set count',
    (state, { payload }) => R.set(lenses.count, payload, state),
  ],
  setLibName: [
    'Set lib name',
    (state, { payload }) => R.set(lenses.libName, payload, state),
  ],
})

/* As you can see both handlers look almost the same, the only difference
   is the lens. Xdux provided few simple helpers for that cases.
*/
import { apply, assign } from '@drukas/xdux'

const { setCount, incrementCount } = myModule.actions({
  setCount: ['Set count', assign(lenses.count)],
  incrementCount: ['Increment count', apply(lenses.count, x => x + 1)],
})

./selectors.js

import * as R from 'ramda'
import { lenses, sliceSelector as _ } from './module'

export const getCount = _(R.view(lenses.count))
export const getLibName = _(R.view(lenses.libName))

And then when it's time to use it as a reducer, you simply do

import { combineReducers } from 'redux'
import myModule from './module'

const myReducer = myModule.reducer()

/* also you can access module sliceName via reducer */
myReducer.sliceName // myModule

API

xdux({ initialState, config: { namespace, sliceName } })

import xdux from '@drukas/xdux'

const count = xdux({
  config: { namespace: 'Count', sliceName: 'count' },
  initialState: 0,
})

createAction(name, ?payloadCreator, ?metaCreator)

import xdux from '@drukas/xdux'

const { createAction } = xdux({
  config: { namespace: 'Count', sliceName: 'count' },
  initialState: 0,
})

// Powered by redux-actions
const increment = createAction('Increment')
increment() // { type: '[Count] Increment', payload: undefined }

// Also you can pass any arguments, that will be stored in payload
const add = createAction('Add')
add(10) // { type: '[Count] Add', payload: 10 }

sliceSelector(select)

import xdux from '@drukas/xdux'

const { sliceSelector } = xdux({
  config: { namespace: 'Count', sliceName: 'count' },
  initialState: 0,
})

const appState = { count: 10 }
const getCount = sliceSelector(count => count)
logCount(appState) // 10

// idiomatic approach is usage with Ramda
import * as R from 'ramda'
const sliceName = 'user'
const user = { name: 'John', profile: { status: 'active' } }
const { sliceSelector as _ } = xdux(/*...*/)

const statusLens = R.lensPath(['profile', 'status'])
const getStatus = _(R.view(statusLens))
getStatus({ user }) // active

module.action(title, handler)

import xdux from '@drukas/xdux'

const { module } = xdux({
  config: { namespace: 'Count', sliceName: 'count' },
  initialState: 0,
})

// Creates both action and handler
const increment = module.action('Increment', state => state + 1)
increment() // { type: '[Count] Increment', payload: undefined }

module.actions(handlersMap)

import xdux from '@drukas/xdux'

const { module } = xdux({
  config: { namespace: 'Count', sliceName: 'count' },
  initialState: 0,
})

// Creates many actions and handlers
const { increment, decrement } = module.actions({
  increment: ['Increment', state => state + 1],
  decrement: ['Decrement', state => state - 1],
})
increment() // { type: '[Count] Increment', payload: undefined }
increment() // { type: '[Count] Decrement', payload: undefined }

module.handlers(handlersMap)

import xdux from '@drukas/xdux'

const { createAction, module } = xdux({
  config: { namespace: 'Count', sliceName: 'count' },
  initialState: 0,
})

// Creates handlers
const increment = createAction('Increment')
const decrement = createAction('Decrement')
module.handlers({
  [increment]: state => state + 1,
  [decrement]: state => state - 1,
})

module.reducer()

import xdux from '@drukas/xdux'

const { module: count } = xdux({
  config: { namespace: 'Count', sliceName: 'count' },
  initialState: 0,
})

const { add, decrement, increment } = count.actions({
  add: ['Add', (state, { payload }) => state + payload],
  decrement: ['Decrement', state => state - 1],
  increment: ['Increment', state => state + 1],
})

const countReducer = count.reducer()

const actions = [increment(), decrement(), add(5)]

actions.reduce(countReducer, 0) // 5

apply(lens, handler) assign(lens)

import { lensProp } from 'ramda'
import xdux, { apply, assign } from '@drukas/xdux'

const { module } = xdux({
  config: { namespace: 'Count', sliceName: 'count' },
  initialState: { name: 'clicks', value: 0 },
})
const lenses = {
  name: lensProp('name'),
  count: lensProp('value'),
}

const { add, setName } = module.actions({
  add: ['Add', apply(lenses.value, (value, payload) => value + payload)],
  setName: ['Set name', assign(lenses.name)],
})