Redux Modules

This library is designed to reduce the boilerplate of interacting with an api, normalizing and caching responses, and describing api states.

Installation

yarn add @churchcommunitybuilder/redux-modules

Usage

There are 3 main assumptions of this library

1. You are using React
2. You are using Redux
3. You are using Redux Thunk with an extra argument that interacts with an api

You'll first need to make sure that your root reducers composes the two reducers exported from this library.

import { moduleReducers } from '@churchcommunitybuilder/redux-modules'

const appReducer = combineReducers({
  ...moduleReducers,
  ...otherAppReducers
})

Next, make a moduleFactory that encapsulates how to pass requests to your thunk api arg.

import { getModuleFactory } from '@churchcommunitybuilder/redux-modules'

export const moduleFactory = getModuleFactory((request, api) =>
  api(request),
)

where api is you thunk arg and request is defined as

interface RequestConfig {
  url: string
  method?: 'get' | 'post' | 'put' | 'delete'
  params?: {}
  data?: {}
  headers?: {}
}

At this point, everything should be wired up and you can begin creating modules.

inteface Entity {
  id: number
}

const module = moduleFactory.create<Entity>()(
  moduleFactory.createSchema('moduleName'),
  {
    get: moduleFactory.get<Entity>(({ id }) => ({
      url: `some_endpoint/${id}`,
    })),
    getList: moduleFactory.getList<Entity>(({ id }) => ({
      url: `some_endpoint/${id}`,
    })),
    put: moduleFactory.put<Entity>(({ id }) => ({
      url: `some_endpoint/${id}`,
    })),
    post: moduleFactory.post<Entity>(({ id }) => ({
      url: `some_endpoint/${id}`,
    })),
    delete: moduleFactory.delete<Entity>(({ id }) => ({
      url: `some_endpoint/${id}`,
    })),
  },
)

Api

create

This is used to create the module and pull together the normalizr schema and the api definitions. Returns the schema, entity selectors, and the api definitions

createSchema

A thin wrapper around creating a normalizr schema

apiDefinitions

All api definition factories share a similar signature:

1. A function taking the api params and returning a request config object.
2. An optional unique identifier for the module (since the url/http method is by default the unique id)

Each api definition has the following values:

• api: The api action creator that was passed in
• execute: A thunk that sets pending statuses, calls the api, and merges the response into redux state
• metaSelector: A selector to get the metadata about the module (i.e. current api status, item ids, paging)
• getKey: A helper to get the module's unique key

get

This api definition has all of the above, with the addition of a useModule hook that returns the entity and metadata for a module

getList

This api definition also has useModule, and additionally has an itemsSelector which will get the entities for the module

Testing

This library exports two test helpers from @churchcommunitybuilder/redux-modules/testing.

getModuleMock

This can be used to mock modules and entities in your redux store. actions is an array that should be dispatched to your store

import { getModuleMock } from '@churchcommunitybuilder/redux-modules/testing'

export const moduleMock = getModuleMock<Entity>(
  module.schema,
  defaultEntity,
)

const entity = moduleMockEntities(1)
const entities = moduleMockEntities(10)
const entity = moduleMockEntities({ id: 1 })
const entities = moduleMockEntities([{ id: 1 }, { id: 2 }])

const { entity, actions} = moduleMock.mockModule(1, 'uniqueModuleKey') // creates entity, and updates the module's metadata
const { entity, actions} = moduleMock.mockModule(1) // creates one default module
const { entities, actions} = moduleMock.mockModule(10) // creates ten default module
const { entity, actions} = moduleMock.mockModule({ id: 1 }) // creates one entity merged with the default entity
const { entities, actions} = moduleMock.mockModule([{ id: 1 }, { id: 1 }]) // creates two entity merged with the default entity

mockMeta

Used to mock a modules metadata

const meta = mockMeta({ status: ApiStatus.Pending })