Generate a reducer and a hook for performing CRUD operations on a REST API without all the boilerplate.
A few types need to be defined to ensure your hook is meaningfully typed.
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(...)
// Properties that uniquely identify an ~Example~
type ExampleCompositeIdentifier = {
key: string
}
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(...)
// Properties that represent an ~Example's~ fields
type ExampleSerialized = {
title: string
description: string
expiryDate: string
}
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.
// Parameters that resources can be filtered and sorted by.
type ReadExampleParams = {
key?: string
title?: string
expired?: boolean
byExpiryDate?: boolean
}
To facilitate filtering and sorting of resources from the client-side cache, R3G requires two user-defined functions to handle this behavior.
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
const filterExample = (
example: ExampleCompositeIdentifier & ExampleSerialized,
params: ReadExampleParams
) => {
const { key, title, expired } = params
// Match key filter
const keyFilterEnabled = (key ?? null) !== null
if (keyFilterEnabled && example.key !== key) return false
// Match title filter
const titleFilterEnabled = (title ?? null) !== null
if (titleFilterEnabled && example.title !== title) return false
// Match expired filter
const expiredFilterEnabled = (expired ?? null) !== null
if (expiredFilterEnabled) {
const expiryTimestamp = DateTime.fromISO(example.expiryDate).valueOf()
const currentTimestamp = DateTime.now().valueOf()
const isExpired = expiryTimestamp <= currentTimestamp
const conditionGetters = {
true: () => isExpired,
false: () => !isExpired
}
const getCondition = conditionGetters[expired.toString()]
const matchesCondition = getCondition()
return matchesCondition
}
return true
}
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.
R3G's generator function requires a configuration object to generate a reducer and hook for the specified resource.
const exampleRestClient = generateRestClient<
ExampleCompositeIdentifier,
ExampleSerialized,
ReadExampleParams
>({
name: 'example',
identifiers: ['key'],
primaryIdentifier: 'key',
initialFields: {
title: 'Lorem ipsum',
description: 'Lorem ipsum dolor sit amet, consectetur adipiscing',
expiryDate: DateTime.now().plus({ days: 7 }).toISO()
},
filter: filterExample,
sort: sortExample
})
The name of the resource in question.
A list of all the resource's identifying properties (primary identifier + parent identifiers).
The identifier belonging solely to the resource and not parents.
An initialized instance of your generic resource (no identifiers). This will be used as the initial state of a new resource being created.
The automated nature of REST client generation that R3G provides requires that you design your REST API in a highly standardized fashion.
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.
// e.g. req.body
{
title: 'Sample Title',
description: 'Lorem ipsum dolor sit amet',
expiryDate: DateTime.now().plus({ days: 7 }).toISO()
}
Returns composite identifier.
// e.g. response.data
{
key: 'abc'
}
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'.
// e.g. response.data
{
exampleList: [
{
title: 'Sample Title',
description: 'Lorem ipsum dolor sit amet',
expiryDate: '2021-04-23T22:07:43.796+00:00'
},
...
]
}
PUT - (single) - /api/parent/[pid]/child/[cid]
DELETE - (single) - /api/parent/[pid]/child/[cid]