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