# 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 })
```