rascl

RASCL: Redux API State Caching Layer

RASCL is an opinionated library that creates "zero boilerplate" bridges between API clients and Redux.

---

Table of Contents

• Why RASCL?
• How it works
• Installation
  • Optional Dependencies
• Related Concepts
• Inspiration

---

Documentation

• Quick Start
• Lifecycle in Depth
• Understanding createRASCL
• Common Patterns
• Motivation and Philosophy

---

Why RASCL?

Trying to follow established best practices for Redux often results in repetitious code. Because this type of code is tedious to write and time-consuming to maintain, it's also a frequent source of "copy/paste" errors.

Libraries like redux-actions and redux-act already reduce some of this boilerplate, but RASCL goes further and removes it all.

How it works

Given a map of API calls, RASCL can generate every part of a complete Redux and Redux-Saga setup:

import * as MyAPI from "./API";

const { createRASCL } = await import("rascl");

export const {
  types,         // String constants for action types
  actions,       // Action creator functions
  initialState,  // Initial Redux store state
  handlers,      // Action handlers for state updates
  watchers,      // Sagas to respond to each type of action
  reducer,       // A root reducer
  rootSaga,      // A root saga
} = createRASCL(MyAPI);

RASCL then tracks the "lifecycle" of each API call as a finite state machine. As the API call "moves" through the lifecycle, each stage dispatches a Redux action containing the relevant data.

An API endpoint's state transitions

The data contained in each action is cached in the Redux store, from the initial request parameters through to the successful API result or the details of an error.

This makes logging and debugging extremely straightforward, and upholds a core principle of RASCL: All the data is always available.

Therefore, once RASCL is configured and invoked, an application only needs to do two things:

1. Dispatch Redux actions to indirectly make API requests
2. Use selector functions to indirectly access the results

Installation

npm i -S rascl

or

yarn add rascl

Optional Dependencies

RASCL works extremely well with a collection of other packages, but none of these is strictly necessary for RASCL to function.

redux-saga

Manage and compose side effects. Used with RASCL to manage "business logic" in API requests.

ky

A more ergonomic and concise way use the fetch API. Used with RASCL to simplify API client code.

reselect

Compute derived data, memoize complex operations. Used with RASCL to access API response data in a performant way.

typescript

Strongly-typed JavaScript. Used with RASCL to provide type information for API response data and ensure beautiful autocomplete in code editors.

⚠︎ IMPORTANT NOTE
When used with TypeScript, RASCL's type declarations require TypeScript version 4.2 or greater due to a dependency on Template Literal Types. Earlier versions of TypeScript will produce opaque errors.

Related Concepts

• Cohesion
• Loose Coupling

Inspiration

• redux-actions
• redux-act