react-redux-rest-generator (R3G)

Generate a reducer and a hook for performing CRUD operations on a REST API without all the boilerplate.

---

Types

A few types need to be defined to ensure your hook is meaningfully typed.

Composite Identifier

Resources may be uniquely identified by one or more properties. R3G uses the combination of these properties in a single object to handle identification of resources.

The composite identifier must be compatible with JSON.stringify(...)

1// Properties that uniquely identify an ~Example~
2type ExampleCompositeIdentifier = {
3    key: string
4}

Serialized Generic Resource

R3G also requires a type that reflects the data/fields of your resource.

Often times the composite identifier and serialized generic will be combined (resulting type will be an intersection of the two) to represent a complete identifiable resource with all its data.

The serialized generic resource must be compatible with JSON.stringify(...)

1// Properties that represent an ~Example's~ fields
2type ExampleSerialized = {
3    title: string
4    description: string
5    expiryDate: string
6}

Read Params

R3G allows client-side filtering and sorting of resources that have been locally cached. In order to do so, an object of optional parameters is required.

1// Parameters that resources can be filtered and sorted by.
2type ReadExampleParams = {
3    key?: string
4    title?: string
5    expired?: boolean
6    byExpiryDate?: boolean
7}

---

Query Functions

To facilitate filtering and sorting of resources from the client-side cache, R3G requires two user-defined functions to handle this behavior.

Filter

Resembling the native Array.filter(...) function, the R3G filter function is given a resource object and read parameters, which it can use to determine if the resource is to be filtered out of the query or not.

Returning true indicates the resource is valid and will be returned in the query. Returning false indicated the resource will be filtered out of the query.

Example snippet makes use of DateTime object from luxon library

1const filterExample = (
2    example: ExampleCompositeIdentifier & ExampleSerialized,
3    params: ReadExampleParams
4) => {
5    const { key, title, expired } = params
6
7    // Match key filter
8    const keyFilterEnabled = (key ?? null) !== null
9    if (keyFilterEnabled && example.key !== key) return false
10
11    // Match title filter
12    const titleFilterEnabled = (title ?? null) !== null
13    if (titleFilterEnabled && example.title !== title) return false
14
15    // Match expired filter
16    const expiredFilterEnabled = (expired ?? null) !== null
17    if (expiredFilterEnabled) {
18        const expiryTimestamp = DateTime.fromISO(example.expiryDate).valueOf()
19        const currentTimestamp = DateTime.now().valueOf()
20        const isExpired = expiryTimestamp <= currentTimestamp
21        const conditionGetters = {
22            true: () => isExpired,
23            false: () => !isExpired
24        }
25        const getCondition = conditionGetters[expired.toString()]
26        const matchesCondition = getCondition()
27        return matchesCondition
28    }
29
30    return true
31}

Sort

Resembling the native Array.sort(...) function, the R3G sort function is given two resources to compare and read parameters. It uses these to determine if resource A should come before or after resource B in the resulting array.

Returning value greater than 0 indicates resource B comes after resource A. Returning value less than 0 indicates resource B combes before resource A. Return value equal to 0 leaves the resources in the same comparative position in the resulting array.

---

Configuration

R3G's generator function requires a configuration object to generate a reducer and hook for the specified resource.

1const exampleRestClient = generateRestClient<
2    ExampleCompositeIdentifier,
3    ExampleSerialized,
4    ReadExampleParams
5>({
6    name: 'example',
7    identifiers: ['key'],
8    primaryIdentifier: 'key',
9    initialFields: {
10        title: 'Lorem ipsum',
11        description: 'Lorem ipsum dolor sit amet, consectetur adipiscing',
12        expiryDate: DateTime.now().plus({ days: 7 }).toISO()
13    },
14    filter: filterExample,
15    sort: sortExample
16})

Name

The name of the resource in question.

Identifiers

A list of all the resource's identifying properties (primary identifier + parent identifiers).

Primary Identifier

The identifier belonging solely to the resource and not parents.

Initial Fields

An initialized instance of your generic resource (no identifiers). This will be used as the initial state of a new resource being created.

---

Conventions and Limitations

The automated nature of REST client generation that R3G provides requires that you design your REST API in a highly standardized fashion.

API Routes

For sake of simplicity and keeping things systematic and therefore convenient for the REST client generator to interpret, API routes are always identified by singular nouns rather than plurals, and follow a specific pattern. Essentially, only a sub-set of the REST pattern is supported.

POST (single) - /api/parent/[pid]/child

Requires request body to contain all fields of serialized generic resource object.

1// e.g. req.body
2{
3    title: 'Sample Title',
4    description: 'Lorem ipsum dolor sit amet',
5    expiryDate: DateTime.now().plus({ days: 7 }).toISO()
6}

Returns composite identifier.

1// e.g. response.data
2{
3    key: 'abc'
4}

GET (many) - /api/parent/child?[query]

Requires query string, which is the read params converted into URLSearchParams type.

Returns array of identified resource objects (composite identifier & serialized generic) in property named as the resource name suffixed with 'List'.

1// e.g. response.data
2{
3    exampleList: [
4        {
5            title: 'Sample Title',
6            description: 'Lorem ipsum dolor sit amet',
7            expiryDate: '2021-04-23T22:07:43.796+00:00'
8        },
9        ...
10    ]
11}

PUT - (single) - /api/parent/[pid]/child/[cid]

DELETE - (single) - /api/parent/[pid]/child/[cid]