Create scalable, no-boilerplate redux Apps!

Arc is an abstraction layer to help you reduce boilerplate on redux-apps and also, organize better your code. Additionally, it has utilities to handle async requests.

Why

Redux is awesome! But people often complain about how much boilerplate they have to write when using it. Part of this problem, is because they feel unproductive defining constants, action creators and big reducers, but also because they don’t have a clear idea on how to organize their project, or even how to proper handle async requests. This project, intends to help on all that aspects!

We don’t intend to recreate the wheel, instead, we tried to use what the community are used with, and build up some approaches together in order to clarify the things about the project architecture, code splitting and the things around actions.

Creators and types are generated by a config

  // actions.js\n  import { createActions } from 'redux-arc';\n\n  export { types, creators } = createActions('jedi', {\n    add: null,\n  });\n

\n\n

Create reducers using createReducers and types:

  import { createReducers } from 'redux-arc';\n  import { types } from './actions';\n\n  const INITIAL_STATE = [];\n  const HANDLERS = {\n    [types.ADD]: (state, action) => [...state, action.payload]\n  };\n\n  export default createReducers(INITIAL_STATE, HANDLERS);\n

\n\n

Call the creators providing payload and meta

  import { creators } from './actions';\n\n  const payload = {\n    name: 'Luke',\n    master: 'Yoda',\n  };\n  const meta = { foo: 'bar' };\n\n  dispatch(creators.add(payload, meta))\n

\n\n

Create Async Actions

  import { createActions } from 'redux-arc';\n\n  export { types, creators } = createActions('jedi', {\n    add: { url: '/api/jedi' method: 'post'},\n  });\n\n  dispatch(creators.add(payload, meta));\n\n  types.ADD.REQUEST // JEDI_ADD_REQUEST\n  types.ADD.RESPONSE // JEDI_ADD_RESPONSE\n

\n\n

\n
createActions creates both, regular and async actions. Async types has REQUEST and RESPONSE type, respectively to when a request starts and when it finishes.
\n

Getting started

yarn add redux-arc\n

\nor

npm i --save redux-arc\n

\n\n

To understand this docs, you should have a good understand of redux: what are Action creators, what are reducers, middlewares and also, what is a Flux Standard Action. So please, if you need a recap on those concepts, read the links bellow:

Redux Docs
\nFlux Standard Action

Action creators and Types

When you have to create a new action on redux, the first 2 steps you usually do is defining a const to you action type and then defining an action creator.

const NEW_JEDI = 'NEW_JEDI';\n\nconst newJedi = (payload) => ({\n  type: NEW_JEDI,\n  payload,\n});\n

\n\n

The above code is fine, but the problem is, you have dozens or hundreds of action in an application, and you are always writing the same code. Also, if you are not strict on code review, you end up having situations where your action type has a name different from your action creator:

const NEW_JEDI = 'NEW_JEDI';\n\nconst addJedi = (payload) => ({\n  type: NEW_JEDI,\n  payload,\n});\n

\n\n

Thinking in the above issues, Arc has a createAction function, that you use to define your actions and it generates the types and action creators automatically for you. Take a look:

  import { createActions } from 'redux-arc';\n\n  const { types, creators } = createActions('yourNamespace', {\n    newJedi: null,\n  });\n\n  types.newJedi // YOUR_NAMESPACE_NEW_JEDI\n\n  const payload = {\n    master: 'Yoda',\n    name: 'Luke',\n  };\n\n  creators.newJedi(payload);\n  /*\n  {\n    type: 'YOUR_NAMESPACE_NEW_JEDI',\n    payload: {\n      master: 'Yoda',\n      name: 'Luke',\n    }\n  }\n  */\n

\n\n

The createActions method, expects a namespace as its first argument, this will be uppercased and will serve as a prefix for the actions. As the second parameter, we need to provide a config object, which the key is the action name and the value is an object with default values for payload and meta, or null if you don’t want to provide defaults. Then, it will return creators and types.

Both creators and types are objects, the first one contains the action creators for the actions you defined. As in the case above we defined an action newJedi, then we have a creator at creators.newJedi.

Creators accepts until three arguments:
\n - payload: could be of any type. Will become the action.payload
\n - meta: could be of any type. Will become the action.meta
\n - error: boolean. Indicates if the action has an error or not. You can omit it if the action has no error.

\n
The api was designed following the flux-standard-action concepts. It can be strict about how your action should look like, but this will help you creating better actions. Also, now you can be sure that the first parameter you provide to the action creator, will become the action.payload.
\n

The types is an object that contains strings. Its keys are the action names, but different from the creators, here they are uppercased:

  types.NEW_JEDI\n

\n\n

Also, when you do a console.log to see its content, you can see that we prefix the actions with the namespace you provided:

  const { types } = createActions('yourNamespace', {\n    newJedi: null,\n  });\n\n  types.NEW_JEDI // -> YOUR_NAMESPACE_NEW_JEDI\n\n

\n\n

\n
We decided to have the namespace, to not stop you from having actions with the same name in different modules. Don’t worry, you will be able to differ them easily when using redux-dev-tools, just remember to provide unique namespaces.
\n

Async Actions

Originally, Arc was created to be an abstraction layer to handle async request in Redux. So, it has all you need about that. The api to generate async actions and types is the same, you only need to provide some additional params in the action config object. Take a look below:

  import { createApiActions } from 'redux-arc';\n\n  const { creators, types } = createActions('todo', {\n    list:   { url: 'api/todo',     method: 'get'  },\n    read:   { url: 'api/todo/:id', method: 'get'  },\n    create: { url: 'api/todo',     method: 'post' },\n    update: { url: 'api/todo/:id', method: 'put'  },\n  });\n

\n\n

Above are defined three actions: list, read, create.

Two params are required for a async action config, url and method.
\n - url: You can define any url you want and it also accepts dynamic params, as you can see in the read action. We defined a dynamic param id, inserting :id
\n - method: Generally speaking, any http method your request lib supports. This will be used only by you in the asyncMiddleware that you will configure.

Async Creators and Async Types

An async creator is very similar to a simple creator. It accepts payload and meta as arguments. They will further become the action.payload and action.meta, as in a regular creator. The difference here, is that the meta, should be an object, and its values will be used to parse dynamic urls. Considering that, the creator read should be used like that:

  const payload = null;\n  const meta = { id: '123' };\n  creators.read(payload, meta);\n

\n\n

With the above code, the final url to your read request, would be api/todo/123

The async types differ a little bit from the regular ones as well. First, as a api call has two moments (request and response), we need two different types to use inside our reducers. Considering that, Arc returns an object for each type, containing a REQUEST and a RESPONSE key with the respective types:

  types.READ.REQUEST == 'TODO_READ_REQUEST';\n  types.READ.RESPONSE == 'TODO_READ_RESPONSE';\n

\n\n

Async Middleware

Arc doesn’t intend to be a request lib, so, you need to tell it how you want to make your requests, and you do that by configuring the asyncMiddleware.

It’s quite simple, take a look below in an example using axios:

import { createAsyncMiddleware } from 'redux-arc';\nimport axios from 'axios';\n\nconst asyncTask = store => done => (options) => {\n  const { method, url, payload } = options;\n  const params = method === 'get' ? { params: payload } : payload;\n\n  axios[method](url, params).then((error, response) => done(error, response));\n};\n\n// create the async middleware\nconst asyncMiddleware = createAsyncMiddleware(asyncTask);\n\n// set it to the Store\nconst store = createStore(\n  reducer,\n  applyMiddleware(asyncMiddleware),\n);\n

\n\n

\n
In the above example, we are using axios, but you can use whatever you want to perform the request, just make sure you call done, passing error and response when the request ends.
\n

For more info about asyncTask and createAsyncMiddleware, read Connecting Arc Into Redux

Reducers

Beyond types and action creators, we also have reducers. There are a few ways to deal with them, some approaches use switch case, some others use multiple IFs. With most of them, you end up having a lot of code inside the same function, which makes maintenance and focusing hard. I know some approaches mention that you can split your code into small functions when it gets bigger, but why do not start from something that is easy to scale and also allow you to focus on each action separately?

Thinking about that, we created the function createReducers

createReducers

This factory was created to work standalone, it doesn’t require you to use any other feature from Arc. If you like, you can continue creating your actions and types as you always did. Take a look at the example below:

  // vanillaActions.js\n  export const ADD_NEW_JEDI = 'ADD_NEW_JEDI';\n\n  export const addNewJedi = (name, master) => ({\n    type: ADD_NEW_JEDI,\n    name,\n    master,\n  });\n\n

\n\n

Above we defined our types and action creator using pure JavaScript . Below, you can see how we could use it with createReducers:

  import { createReducers } from 'redux-arc';\n  import { ADD_NEW_JEDI } from './vanillaActions';\n\n  const INITIAL_STATE = [];\n\n  const onAddNewJedi = (state, action) => [\n    ...state,\n    { name: action.name, master: action.master },\n  ];\n\n  const HANDLERS = {\n    [ADD_NEW_JEDI]: onAddNewJedi\n  };\n\n  export default createReducers(INITIAL_STATE, HANDLERS);\n

\n\n

You must provide a INITIAL_STATE and a HANDLERS object, which the keys should be the action types and the values should be reducers.

Using createActions with arc’s types object
\nAs the types object is a simple JavaScript object, with strings, it fits perfectly with createReducers. Take a look below in an example using both, a regular and a async action with createReducers:

actions.js:

  const { creators, types } = createActions('todo', {\n    list: { url: 'api/todo', method: 'get'  }, // async action\n    reset: null, // regular action,\n  });\n

\n\n

reducers.js

import { createReducers } from 'redux-arc'\nimport { types } from './actions';\n\nconst INITIAL_STATE = {\n  listResult: [],\n  listIsLoading: false,\n  listError: null,\n};\n\nconst onListRequest = (state, action) => ({\n  ...state,\n  listIsLoading: true,\n  listError: INITIAL_STATE.listError,\n});\n\nconst onListResponse = (state, action) => {\n  if (action.error) {\n    return {\n      ...state,\n      listIsLoading: INITIAL_STATE.listIsLoading,\n      listError: action.payload,\n    }\n  }\n\n  return {\n    ...state,\n    listIsLoading: INITIAL_STATE.listIsLoading,\n    listResult: action.payload\n  }\n};\n\nconst onReset = state => INITIAL_STATE;\n\nconst HANDLERS = {\n  [types.LIST.REQUEST]: onListRequest,\n  [types.LIST.RESPONSE]: onListResponse,\n  [types.RESET]: onReset,\n};\n\nexport default createReducers(INITIAL_STATE, HANDLERS);\n

\n\n

As we mentioned, we are using two kinds of action types, regular and async.

For the regular, there’s no much secret, types.RESET contains a string TODO_RESET generated by createActions, using the namespace and the action name we defined earlier.

The async action, contains an object, with REQUEST and RESPONSE keys, each one containing a string, which is the actual type.

Arc will dispatch the respective request and response action using the same types we have in types object and the same applies for regular actions, so Arc doesn’t open breaches for you to commit a typo.

Async Actions

Response action:

When the request is done, an action with the response will be dispatched. Considering the list example, the response action would look like this:

{\n  type: 'JEDI_LIST_RESPONSE', // types.LIST.RESPONSE,\n  meta: {\n    url: 'api/todo',\n    method: 'get',\n  },\n  payload: [\n    // resource list\n  ],\n}\n

\n\n

Error handling

The above example is a a response with success. Accordingly to FSA, errors should be treated as a First class concept. In that case, when you got some error in an async request, the response action will come with the error property as true and the payload will be the actual error. Just like the example below:

{\n  type: 'JEDI_LIST_RESPONSE', // types.LIST.RESPONSE,\n  meta: {\n    url: 'api/todo',\n    method: 'get',\n  },\n  payload: new Error('the request error'),\n  error: true,\n}\n