redux-crud-async

redux-crud-async will create CRUD async actions and states automatically, just for you. The configuration is minimalist.

It currently uses axios or sails.io websocket (custom socket.io) for XHR. It allows you to use a REST API with authentication with a Bearer Token. In a near future, I will implement the possibility to create random actions like sign_in, sign_out or tranformThisLeadInGold Redux-crud-async is built against 150+ tests. Unfortunately this does not mean that redux-crud-async is bug free, please send issues if you find one !

Table of Contents

1. Setup
2. Conventions a. Routes b. Authentication c. Socket
3. Configuration
4. Actions a. Names b. Additionnal Actions
5. States (Reducers)
6. Todo
7. Change Log

---

Setup

NPM

you can find it on NPM

npm i -S redux-crud-async

ActionTypes

// redux/actionTypes/index.js
  var reduxCrudAsync = require('redux-crud-async')
  var crud = new reduxCrudAsync()

  module.exports = {
    ...crud.primaryActionTypesFor('channel'),
    ...crud.primaryActionTypesFor('tag'),

    ...crud.associationActionTypesFor('channel', 'tag')
  }

Actions

// redux/actions/index.js
  var reduxCrudAsync = require('redux-crud-async')

  var hostConfig = {
    host            : 'https://my-api.com',
    prefix          : 'v1', // Optional - default to ''
    pluralizeModels : false, // Optional - default to true

  }

  var crud = new reduxCrudAsync(hostConfig) // hostConfig is mandatory for actionsGenerator

  module.exports = {
    ...crud.primaryActionsFor('channel'),
    ...crud.primaryActionsFor('tag'),

    ...crud.associationActionsFor('channel', 'tag')
  }

Reducers

// redux/reducers/index.js
  var reduxCrudAsync = require('redux-crud-async')
  var crud = new reduxCrudAsync()

  module.exports = {
    ...crud.primaryReducerFor('user'),
    ...crud.primaryReducerFor('pet'),

    ...crud.associationReducerFor('user', 'pet')
  }

EXEMPLE USAGE Click here to see how much it is easy to use this module

---

Conventions

General

It might be obvious but all models returned by your database need to have an unique id.

Routes

This module is built to work with sails.js blueprints routes using sails-rest-api conventions. It differentiate singular and plural model name : findUser !== findUsers IMPORTANT ! As sails.js, this module uses pluralize module which pluralize words grammaticaly.

some exemples : channel -> channels person -> people coach -> coaches

By default, all your routes will be pluralized, Person model will have the following :

state : person - a single person people - all your "persons"

actions : findPerson -> will hit GET /people/:id findPeople -> will hit GET /people

You can unpluralize your urls by setting it in the config

Authentication

redux-crud-async uses a Bearer Token to authenticate requests. It is store in window.localStorage. Every request which need authentication is sent with the token in the header following this convention :

Token is set in Authorization header as :

// Config sent to axios or socket.io
{
    headers : {
      Authorization : 'Bearer '+ JWT_Token_from_localStorage
    }
}

Socket

We use the io.socket.request to communicate to the server. Make sure that your server can use it if you don't use sails.js on server side.

---

##Configuration

Config file

Name	Type	Default	Description
host	String	null	Your API host - must be defined
prefix	String	null	A prefix for all your routes. Don't add the slash / on the prefix it will be automatically added.
pluralizeModels	Boolean	true	Use pluralized model names in url. This has no affect on action names.
socket	Boolean	false	Use socket.io for actions
localStorageName	String	"JWT"	The key for retrieving your JWT Token from window.localStorage
headerContent	String	"Bearer {{JWT}}"	The format of your header content The format is affected by localStorageName
headerFormat	String	"Authorization"	The format of your header authorization key
apiSpecs	Object	null	Routes where you want to use the JWT_Token
responseSchemas	Object	{http: {success : 'data', error : 'data'}, socket : {success : null, error : null}}	schemas of your API's responses. Where the data can be found in your response object

The format of headerContent is affected by localStorageName if you change the default value

{
  localStorageName : 'myJWT',
  headerContent : 'MyContent {{myJWT}}'
}

For apiSpecs you just have to set the unpluralized modelName or primarymodelAssociatedmodels with an auth property inside which contains an array of actions to authenticate. Just follow conventions given above.

{
  host            : 'http://your-api-host',
  prefix          : 'my-prefix',
  pluralizeModels : false,
  socket          : true,
  localStorageName: 'MyJWT',
  headerContent   : 'AuthBearer {{MyJWT}}',
  headerFormat    : 'AuthBearerHeaderKey'
  apiSpecs : {

    coach : {
      // All the following actions will be beared with a JWT
      auth : ['findCoaches', 'createCoach', 'updateCoach']
    },

    coachComments : {
      auth : ['addCommentToCoach', 'removeCommentFromCoach']
    }
  }
}

#### Results findPerson -> will hit GET http://your-api-host/my-prefix/people/:id findPeople -> will hit GET http://your-api-host/my-prefix/people

With pluralizeModels : false findPerson -> will hit GET http://your-api-host/my-prefix/person/:id findPeople -> will hit GET http://your-api-host/my-prefix/person

---

Actions

Names

There is a maximum of 11 actions for a given model which will be automatically understood by reducers. 3 status actions are dispatched for every redux-crud-async action : START, SUCCESS and ERROR. They are automatically understood by reducers. eg. primary model = channel, associated model = tag

3 primary

actionName	url	param	state	state Type
findChannel	GET channels/:id	String	channel	Object
findChannels	GET channels?request	String	channels	[Object]
createChannel	POST channels	Object OR FormData	channel	Object
updateChannel	PUT channels	Object	channel	Object
destroyChannel	DELETE channels	Object	channel	Object

You can submit a FormData to create but the FormData is transmitted as is and model will not be appended to the state. If you need the model to be appended to the state, use a javascript object instead of a FormData. FormData can be used to send specific CRUD actions like uploading an image

3 association

actionName	url	parameters	state	state Type	Comment
findChannelTags	GET channels/:channelId/tags/:tagId?	String, String	channelTags	[Object]
addTagToChannel	POST channels/:channelId/tags/:tagId?	String, String OR Object	channelTag	Object	if no tag id is set you must give an object to this function
createChannel	POST channels	String, String	channelTag	Object

#### Additionnal actions

An additionnal action exists which empties reducers. Dispatch manually this action to empty your reducers.

{
  type : 'EMPTY_CHANNEL'
}
{
  type : 'EMPTY_CHANNELS'
}
{
  type : 'EMPTY_PRIMARY_ASSOCIATED_MODELS'
}

Have a look in primaryActionGenerator and associationActionGenerator and Actions Details for more precision about dispatched actions.

States (Reducers)

Reducers return the following states usable in your components

state	type
channel	Object
isFindingChannel	Boolean
channels	[Object]
isFindingChannels	Boolean
channelTags	[Object]
isFindingChannelTags	Boolean

See reducers :

• primaryReducerGenerator
• associationReducerGenerator

---

## TODO

• make API endpoints editables
• add cache for get requests
• cache timeout by route
• remove arrow functions in tests
• comment code
• find a way to test FormData in createModel
• add single actions (signup, signin)
• add coverage
• move associated record uuid generation from associationActions dispatch to reducer
• state immutability
• add tests for caching
• add some headers tests

## Change Log

0.7.0

• removed second parameter from update action

0.6.3

• update and delete primary actions
• fix bug when building with webpack - io was undefined
• fix silly bugs and add tests for them

0.5.0

• API expectation editables

0.4.0

• add socket.io support through the window.io variable
• more tests
• rewrite of the utils/xhr/* module
• doc changes
• added EMPTY_CHANNELS action in reducers