redux-crud-provider

redux-crud-provider

This library is designed to store entities in redux and handles CRUD operations with a backend. It relies on redux-crud for handling redux and adds specific actions to create, read, update and delete entities on a backend.

How to

Define your entities

First, you need to define the entities used in your application.

The type of a ResourceDefinition can be found here.

Examples of ResourceDefinition can be found here.

Setup reducers

The library provides you with two reducers in order to keep track of the different entities of your application and the network activity.

createReducersForResources(entityDefinitions)
createActivityReducersForResources(entityDefinitions)

See an example of the redux setup here.

Selecting the entities from redux

To access the entities in your application, the library provides you with two selectors.

select(myResourceDefinition).asArray
select(myResourceDefinition).byId

Those can be used in your mapStateToProps like this:

import {select} from 'redux-crud-provider'

const mapStateToProps = state => ({
  books: select(BookResource).asArray(state),
  authorsById: select(AuthorResource).byId(state),
})

Setup the CRUD thunks

This library relies on redux-thunk in order to dispatch actions that will trigger backend calls. Make sure you have redux-thunk configured as a redux middleware in your application.

In order to update the entities in redux through backend calls, you need to create thunks.

const crudThunks = createCrudThunks(config)

The config needs to have this type. See an example here.

The createCrudThunks function will return an object with the following action creators:

Fetch all

crudThunks.fetchAll({resource, path, replace = false, params})

Parameters

Name	Type	Required	Description
resource	ResourceDefinition	yes	The resource that will be fetched
path	string		An optional path to use to fetch the resources. resource.defaultPath is used by default
replace	boolean		If true, all entities in redux will be dropped and replaced with the result from the backend. If false, entities retrieved will be merged with the existing one.
params	object		An optional object containing query params for the call

Fetch one

crudThunks.fetchOne({resource, path, uuid, params})

Parameters

Name	Type	Required	Description
resource	ResourceDefinition	yes	The resource that will be fetched
path	string		An optional path to use to fetch the resource. ${resource.defaultPath}/${uuid} is used by default
uuid	string	yes	The uuid of the entity that needs to be fetched
params	object		An optional object containing query params for the call

Create

crudThunks.createResource({resource, path, entity})

Parameters

Name	Type	Required	Description
resource	ResourceDefinition	yes	The resource that will be created
path	string		An optional path to use to fetch the resource. ${resource.defaultPath} is used by default
entity	object	yes	An object containing the properties that will be sent to the backend

Update

crudThunks.updateResource({resource, path, merge = true, entity, method, body})

Parameters

Name	Type	Required	Description
resource	ResourceDefinition	yes	The resource that will be updated
path	string		An optional path to use to fetch the resource. ${resource.defaultPath}/${entity[resource.key]} is used by default
merge	boolean		Whether or not to merge the entity provided with the existing entity in redux for the optimistic update
entity	object	yes	An object containing the properties that will be sent to the backend
method	string		The method to use for the request. PATCH by default
body	object		Sometimes you are calling a route that will return an updated entity but where the body you send is not such an entity. This is typically the case for custom actions. If you provide a body, it will be used instead of the entity for the request. The response will then be handled like normal and the entity in the store will be updated with the response.

Delete

crudThunks.deleteResource({resource, path, entity})

Parameters

Name	Type	Required	Description
resource	ResourceDefinition	yes	The resource that will be deleted
path	string		An optional path to use to fetch the resource. ${resource.defaultPath}/${entity[resource.key]} is used by default
entity	object	yes	An object containing the properties that will be sent to the backend

Providers

Often, you won't need to use the thunks directly. Instead, the library provides you with react components that dispatch those actions for you.

ResourceListProvider

Example:

<ResourceListProvider crudThunks={crudThunks} resource={BookResource}>
  {({entities}) => (
    <ul>
      {entities.map(book => (
        <li key={book.id}>{book.name}</li>
      ))}
    </ul>
  )}
</ResourceListProvider>

Props

Name	Type	Required	Description
children	function	yes	Render prop, see description below
resource	ResourceDefinition	yes	The resource to use
path	string		Passed to crudThunks.fetchAll
replace	boolean		Passed to crudThunks.fetchAll
params	object		Passed to crudThunks.fetchAll
autoFetch	boolean		Triggers a call do the backend automatically to refresh the data in redux
loadingRender	React Element		A react element to render while data are being fetched
crudThunks	object	yes	The result of createCrudThunks

Children function

The children function will be called with an object with the following properties:

Name	Type	Description
entities	array	The list of entities
fetchAll	function	A function to trigger a fetch from the backend
loading	boolean	true when there is an ongoing call to the backend

ResourceProvider

Example:

<ResourceProvider
  crudThunks={crudThunks}
  resource={Book}
  uuid={match.params.uuid}
>
  {({entity}) => <h1>{entity.name}</h1>}
</ResourceProvider>

Props

Name	Type	Required	Description
children	function	yes	Render prop, see description below
resource	ResourceDefinition	yes	The resource to use
uuid	string	yes	The uuid of the entity to manage
path	string		Passed to crudThunks.fetchOne, crudThunks.updateResource and crudThunks.deleteResource
params	object		Passed to crudThunks.fetchOne
autoFetch	boolean		Triggers a call do the backend automatically to refresh the data in redux
loadingRender	React Element		A react element to render while data are being fetched
crudThunks	object	yes	The result of createCrudThunks
postAction	function		A function called after a successful update or delete

Children function

The children function will be called with an object with the following properties:

Name	Type	Description
entity	any	The entity
fetchEntity	function	A function to re-fetch the entity from the backend
updateEntity	function	A function to update the entity (calls the backend)
deleteEntity	function	A function to delete the entity (calls the backend)
thunks.fetchOne	function	The fetchOne thunk already bound to dispatch
thunks.updateResource	function	The updateResource thunk already bound to dispatch
thunks.deleteResource	function	The deleteResource thunk already bound to dispatch
isFetching	boolean	True when the entity is being fetched
isUpdating	boolean	True when the entity is being updated
isRemoving	boolean	True when the entity is being deleted

Peer dependencies

• axios
• react
• react-redux
• redux
• reselect

yarn add axios react redux react-redux reselect