reducthor v1.2.2
Reducthor is a clean simplification of the redux workflow by letting you describe readable action objects.
Reducthor uses axios as the remote request handler and Immutbale JS to have an immutable state.
Install
npm install reducthor
yarn add reducthor
Getting started
A new instance of Reducthor should be instantiated at the beginning, passing a configuration object containing our action descriptors.
This is how a simple action looks like
// actions/setColor.js
export default {
name: 'SET_COLOR',
action: (state, color) => {
return state.set('color', color)
}
}
Typescript:
// actions/setColor.ts
import { ReducthorAction } from 'reducthor'
const action: ReducthorAction = {
name: 'SET_COLOR',
action: (state: any, color: string) => {
return state.set('color', color)
}
}
export default action
And this is how we can configure our Reducthor instance using this action
// reducthor.js
import Reducthor from 'reducthor'
import setColor from './actions/setColor'
import otherAction from './actions/otherAction'
const configuration = {
actions: [setColor, otherAction]
}
const reducthor = new Reducthor(configuration)
export default reducthor
Typescript:
// reducthor.ts
import Reducthor, { ReducthorConfiguration, ReducthorInstance } from 'reducthor'
import setColor from './actions/setColor'
import otherAction from './actions/otherAction'
const configuration: ReducthorConfiguration = {
actions: [setColor, otherAction]
}
const reducthor: ReducthorInstance = new Reducthor(configuration)
export default reducthor
And this is how you can call that action from our Reducthor object to mutate the state.
// index.js
import reducthor from './reducthor'
// This method was generated based on the configured action name 'SET_COLOR' -> 'setColor'
reducthor.setColor('red').then(() => {
// All actions in a reducthor are thenables
console.log(reducthor.store.getState())
// Map { color: 'red' }
})
Match our ReducthorInstance type with the generated functions (typescript)
Since Reducthor is going to generate functions on the fly we should extend our ReducthorInstance interface if we want typescript to be aware of them.
// reducthor.ts
import Reducthor, { ReducthorConfiguration, ReducthorInstance } from 'reducthor'
import setColor from './actions/setColor'
import otherAction from './actions/otherAction'
const configuration: ReducthorConfiguration = {
actions: [setColor, otherAction]
}
const reducthor: ReducthorInstance = new Reducthor(configuration)
/////// Important
// extend the ReducthorInstance interface
interface MyReducthorInstance extends ReducthorInstance {
setColor(color: string): Promise<void>
otherAction(): Promise<void>
}
/////// Important
// export as the new interface
export default reducthor as MyReducthorInstance
Request actions
This is a really useful type of action, it will perform a request to the specified path, method and params and then let us use the response to mutate our state.
Lets get a list of posts
// actions/getPosts.js
import Immutable from 'immutable'
export default {
name: 'GET_POSTS',
type: 'request',
path: '/posts',
method: 'get',
onRequestOk: (state, response) => {
const posts = response.data
return state.set('posts', Immutable.fromJS(posts))
}
}
Typescript:
// actions/getPosts.ts
import { ReducthorAction } from 'reducthor'
import Immutable from 'immutable'
import { AxiosResponse } from 'axios'
const action: ReducthorAction = {
name: 'GET_POSTS',
type: 'request',
path: '/posts',
method: 'get',
onRequestOk: (state: any, response: AxiosResponse) => {
const posts = response.data
return state.set('posts', Immutable.fromJS(posts))
}
}
export default action
We can configure a base URL in our Rethuctor object.
// reducthor.js
import Reducthor from 'reducthor'
import getPosts from './actions/getPosts'
const configuration = {
baseURL: 'api.postworld.com',
actions: [getPosts]
}
const reducthor = new Reducthor(configuration)
export default reducthor
Typescript:
// reducthor.ts
import Reducthor, { ReducthorConfiguration, ReducthorInstance } from 'reducthor'
import getPosts from './actions/getPosts'
const configuration: ReducthorConfiguration = {
baseURL: 'api.postworld.com',
actions: [getPosts]
}
const reducthor: ReducthorInstance = new Reducthor(configuration)
export default reducthor
Now we call the request action through our Reducthor instance and since we specified the mehtod
as get
we can pass some query params as the first argument of the generated function.
// index.js
import reducthor from './reducthor'
reducthor.getPosts({ category: 'funy' }).then(() => {
console.log(reducthor.store.getState())
// Map { GET_POSTS_STATUS: 'OK', posts: [...] }
})
All the request action callbacks
The request action has several useful callbacks for every event the request is coming through where we can mutate the state as our convenience.
// actions/getPosts.js
export default {
name: 'GET_POSTS',
type: 'request',
path: '/posts',
method: 'get',
onAction: state => state, // At the moment we call the action from the reducthor object
onRequestOk: (state, response) => state, // The request was successful
onRequestError: (state, error) => state, // The request returned with some error status number
onUploadProgress: (state, progressEvent) => state, // axios can provide this event sometimes
onDownloadProgress: (state, progressEvent) => state, // axios can provide this event sometimes
onFinish: state => state // This happens at last either with a successfull request or not
}
Typescript:
// actions/getPosts.ts
import { ReducthorAction } from 'reducthor'
import { AxiosResponse, AxiosError } from 'axios'
const action: ReducthorAction = {
name: 'GET_POSTS',
type: 'request',
path: '/posts',
method: 'get',
onAction: (state: any): any => state, // At the moment we call the action from the reducthor object
onRequestOk: (state, response: AxiosResponse): any => state, // The request was successful
onRequestError: (state, error: AxiosError): any => state, // The request returned with some error status number
onUploadProgress: (state: any, progressEvent: any): any => state, // axios can provide this event sometimes
onDownloadProgress: (state: any, progressEvent: any) => state: any, // axios can provide this event sometimes
onFinish: (state: any): any => state // This happens at last either with a successfull request or not
}
}
export default action
Dynamic path
You can specify dynamic paths that should be built on the fly. Like probably you need the path to contain the id of a specific post.
// actions/getPost.js
import Immutable from 'immutable'
export default {
name: 'GET_POST',
type: 'request',
path: '/post/:id', // the id will be set from the action call
method: 'get',
onRequestOk: (state, response) => {
const posts = response.data
return state.set('posts', Immutable.fromJS(posts))
}
}
// index.js
import reducthor from './reducthor'
// The first variable in the path is the first argument in the call
reducthor.getPost(25).then(() => {
console.log(reducthor.store.getState())
// Map { GET_POSTS_STATUS: 'OK', posts: { 25: {...} } }
})
Private request actions
If the remote server needs some kind of authentication through the request headers you can set the auth configuration.
// reducthor.js
import Reducthor from 'reducthor'
import getPosts from './actions/getPosts'
const configuration = {
baseURL: 'api.postworld.com',
authConfig: {
header: 'Authentication', // It can be any header you want default is 'Authentication'
token: 'sometoken'
},
actions: [getPosts]
}
const reducthor = new Reducthor(configuration)
export default reducthor
Just set the action as private
to use the header in the request
// actions/getPost.js
import Immutable from 'immutable'
export default {
name: 'GET_POST',
type: 'request',
path: '/post/:id',
method: 'get',
private: true,
onRequestOk: (state, response) => {
const posts = response.data
return state.set('posts', Immutable.fromJS(posts))
}
}
Send multipart/form-data
If you need to upload files to your server, you need to encode the request using multypart/formdata content type, for this you just need to set useMultyPartForm
in your action.
// actions/getPost.js
import Immutable from 'immutable'
export default {
name: 'GET_POST',
type: 'request',
path: '/post/:id',
method: 'get',
private: true,
useMultyPartForm: true, // here
onRequestOk: (state, response) => {
const posts = response.data
return state.set('posts', Immutable.fromJS(posts))
}
}
Set the auth configuration any time
If you need to specify authentication at any point you can use the configAuth
method.
// index.js
import reducthor from './reducthor'
reducthor.configAuth({ token: 'newtoken' })
Using with react-redux
If you are using react-redux to handle state from inside components you can use Reducthor to replace the mapToDispatch approach.
Just set the provider store using the Reacthor store property
import React from 'react'
import ReactDOM from 'react-dom'
import { Provider } from 'react-redux'
import reducthor from './reducthor'
import App from './App'
const rootElement = document.getElementById('root')
ReactDOM.render(
<Provider store={reducthor.store}>
<App />
</Provider>,
rootElement
)
And connect your components as you wold normally do
import { connect } from 'react-redux'
import reducthor from './reducthor'
export default class Counter extends Component {
handleButtonUp(e) {
reducthor.increment()
}
//...
}
const mapStateToProps = (state /*, ownProps*/) => {
return {
counter: state.counter
}
}
export default connect(mapStateToProps)(Counter)
Use a multy reducer store
If you like to use a multy-reducer kind of store you can specify actions in the configuration to follow this pattern.
// reducthor.js
import Reducthor from 'reducthor'
import getPosts from './actions/getPosts'
import getUsers from './actions/getUsers'
const configuration = {
baseURL: 'api.postworld.com',
actions: { posts: [getPosts], users: [getUsers] }
}
const reducthor = new Reducthor(configuration)
export default reducthor
Now action calls are separated by reducer "namespaces"
// index.js
import reducthor from './reducthor'
reducthor.posts.getPosts({ category: 'funy' })
reducthor.users.getUsers({ status: 'active' })
Initial state and middleware
You can always pass an initial state through the Reducthor configuration and some custom middleware
// reducthor.js
import Reducthor from 'reducthor'
import getPosts from './actions/getPosts'
import Immutable from 'immutable'
const configuration = {
baseURL: 'api.postworld.com',
initialState: Immutable.fromJS({ posts: [...] }),
middleware: [customMiddleware, customMiddleware2],
actions: [getPosts]
}
const reducthor = new Reducthor(configuration)
export default reducthor
Use with redux-devtools-extension
If you would like to use redux-devtools-extension to debug your redux state you can pass the composeWithDevTools function to through the configuration.
// reducthor.js
import Reducthor from 'reducthor'
import getPosts from './actions/getPosts'
import { composeWithDevTools } from 'redux-devtools-extension'
const configuration = {
baseURL: 'api.postworld.com',
composeWithDevTools: composeWithDevTools,
actions: [getPosts]
}
const reducthor = new Reducthor(configuration)
export default reducthor
Contributions
PRs are welcome
Lisence
MIT