Redux-store-generator

Redux-store-generator turns a JSON structure into a fully-fledged redux store.

• Redux-store-generator

  • Basic usage
  • Installation
  • Usage
    • Conventions
    • Data structures
    • A full example
  • Available verbs per node type
    • Single
    • Queue
    • Collection
    • Grouped list
  • Helper actions
    • Example:
  • Alternatives

Redux-store-generator generates:

• A root reducer
• Strongly-typed actions to mutate the state

The actions follow simple REST-like verbs (patch, update, delete, etc). The benefits of this approach are:

• Extending your store and maintaining it as easy as changing a JSON
• Reduces boilerplate code
• Increases test coverage
• (optional) Allows you to implement an API solution on top of this convention

Basic usage

Installation

yarn add redux-store-generator

Usage

import {
    generateReducersForStore,
    generateActionsForStore,
} from 'redux-store-generator';

type IUser = {
    name: string;
    email: string;
};

type MyStore = {
    user: IUser;
};

const schema: MyStore = {
    user: {
        name: 'Michael',
        email: '[email protected]',
    },
};

const rootReducer = generateReducersForStore<MyStore>(schema);
const actions = generateActionsForStore<MyStore>(schema);

const store = createStore(combineReducers(rootReducer));

// Now you have a redux-store which responds to the auto-generated actions
// In this example, this actions can be dispatch on the store:
actions.user.patch({ email: '[email protected]' });
actions.user.setAll({ name: 'Pia', email: '[email protected]' });

Conventions

Redux-store-generator depends on specific conventions:

• Shallow structure
• Key-value collections
• String based Ids *

* all inner items are expected to have an "id" field of type string

Data structures

To cover most data-structure needs, there are 4 types of entity structures:

Type	Description	Example
Single	A simple key-value object	currentUser
Collection	For instance: Record<id, Product>*	Products
List	For instance: Log[]	Logs
GroupedList	For instance: Record<id, Chat> **	Chats

* id represents a string

** In this example Chat would have an "items" field which contains an array of chat messages

A full example

import {
    generateReducersForStore,
    generateActionsForStore,
} from 'redux-store-generator';
import { combineReducers, createStore } from 'redux';

type IUser = {
    name: string;
    email: string;
};

type ILog = {
    id: string;
    timestamp: number;
    message: string;
};

type IProduct = {
    id: string;
    name: string;
    price: number;
};

type IChatMessage = {
    id: string;
    displayName: string;
    timestamp: number;
    message: string;
    isSeen: boolean;
};

type IChat = {
    id: string;
    title: string;
    items: IChatMessage[];
};

type MyStore = {
    currentUser: IUser;
    logs: ILog[];
    products: Record<string, IProduct>;
    chats: Record<string, IChat>;
};

const schema: MyStore = {
    currentUser: {
        name: 'Michael',
        email: '[email protected]',
    },
    logs: [
        {
            id: '1',
            timestamp: 0,
            message: '',
        },
    ],
    products: {
        1: {
            id: '1',
            name: 'Dji Mavic air 2',
            price: 1099,
        },
    },
    chats: {
        1: {
            id: '1',
            title: 'Sales',
            items: [
                {
                    id: '1',
                    displayName: 'Laura',
                    isSeen: true,
                    message: "Yes, it's available",
                    timestamp: 0,
                },
            ],
        },
    },
};

const rootReducer = generateReducersForStore<MyStore>(schema);
const actions = generateActionsForStore<MyStore>(schema);

const store = createStore(combineReducers(rootReducer));

// Now you have a redux-store which responds to the auto-generated actions
// this actions can be dispatch on the store:

actions.currentUser.patch({ email: '[email protected]' });
actions.currentUser.setAll({ name: 'Pia', email: '[email protected]' });

actions.logs.push({ id: '2', message: '', timestamp: 0 });
actions.logs.pop();
actions.logs.pushMany([{ id: '2', message: '', timestamp: 0 }, { id: '3', message: '', timestamp: 0 }]); // prettier-ignore
actions.logs.setAll([{ id: '2', message: '', timestamp: 0 }, { id: '3', message: '', timestamp: 0 }]); // prettier-ignore
actions.logs.clear();

actions.products.add({ id: '2', name: '', price: 10 });
actions.products.setAll({ 2: { id: '2', name: '', price: 10 } }); // replaces the collection
actions.products.setMany({ 2: { id: '2', name: '', price: 10 } }); // changes specific items
actions.products.set('1', { id: '1', name: '', price: 10 });
actions.products.delete('1');
actions.products.patch('1', { name: 'New product name' });

actions.chats.add({ id: '2', title: '' });
actions.chats.setAll({ 2: { id: '2', title: '', items: [] } }); // replaces the collection
actions.chats.setMany({ 2: { id: '2', title: '', items: [] } }); // changes specific items
actions.chats.set('1', { id: '1', title: '' });
actions.chats.delete('1');
actions.chats.patch('1', { title: 'New product name' });
// and for the inner items
actions.chats.pushItem('1', { id: '1', displayName: '', timestamp: 0, message: '', isSeen: false }); // prettier-ignore
actions.chats.popItem('1');
actions.chats.pushManyItems('1', [{ id: '1', displayName: '', timestamp: 0, message: '', isSeen: false } ]); // prettier-ignore
actions.chats.setItems('1', [{ id: '1', displayName: '', timestamp: 0, message: '', isSeen: false } ]); // prettier-ignore
actions.chats.clearItems('1');

Available verbs per node type

Single

Verb	Description
patch	partially changes the entity
setAll	replaces the entity

Queue

Verb	Description
push	adds an item to the queue
pop	pops an item from the queue
pushMany	adds many items to the queue
setAll	replaces the queue
clear	clears the queue

Collection

Verb	Description
setAll	replaces the collection
setMany	adds many items to the collection
set	replaces a specific item
delete	deletes a specific item
patch	modifies a specific item

Grouped list

Note GroupedLists are a combination of a collection with an inner queue

Verb	Description
setAll	replaces the collection
setMany	adds many items to the collection
set	replaces a specific item
delete	deletes a specific item
patch	modifies a specific item
pushItem	adds an item to an inner items queue *
popItem	pops an item from an inner items queue *
pushManyItems	adds many items to an inner items queue *
setItems	replaces an inner items queue *
clearItems	clears an inner items queue *

* if you have a GroupedList of chats an one of the chat is { id: '10', title: 'Important Chat', items: [] }, the inner items field represents a queue of chat messages. all the verbs which manipulate the inner items queue refer to the chat messages in this example. To illustrate, pushItem would be used when a new chat message arrives for this chat.

Helper actions

Helper actions are available to support API data fetches via GET and creation of new items via POST.

Entity type	Verb
single	get
queue	get *
collection	get *
groupedList	get *
collection	add
groupedList	add

* parameters can be added in a JSON structure

Those actions do not effect the store's state, they have no side-effects. They exist only to be caught via a middleware or a saga so they can be handled as needed.

For instance, when a user add a new item to a collection, an Id is not yet available as it will be given by the backend, so a common practice would be:

1. Fire a add action:

   actions.products.add({ name: 'new product', price: 10.9 }); // dispatch this action

2. Catch it in a middleware/saga and handle the API call
3. Upon success change the store via a set action:

   // dispatch this action
   actions.products.set('540', {
       id: '540',
       name: 'new product',
       price: 10.9,
   });

   In this example the backend returned 540 as the newly-generated id for this product

Example:

// for GET
actions.currentUser.get();
actions.logs.get({ page: 2 });
actions.products.get({ search: 'drone', filter: {}, sort: {} });
actions.chats.get({ limit: 50 });

// for POST
actions.products.add({ name: '', price: 10 });
actions.chats.add({ title: '' });

Alternatives

Redux Toolkit is an alternative to reduce boilerplate in redux-powered web apps. It may be better suited for certain use-cases. This comparison table may help you decide what is the best tool for your needs:

	redux-store-generator	redux-toolkit
Reducers	auto-generated	manually written *
API	none	via RTK query
Business logic in reducers	not supported	supported

Redux-toolkit (with RTK query) aims to provide an opinionated solution for a complete data cycle, from action invocation to side-effects, back to store manipulation. It has a mechanism for contributing slices to the store which are fully-configured (with API concerns).

redux-store-generator on the other hand, is a thinner opinionated solution for managing collections. You are required to implement an API mechanism on your own or use another package to do so.

The core question is whether you want to treat your store as a simple data-warehouse or a hub for business logic implementations.

If you wish to implement business-logic in your reducers, redux-toolkit would be a better fit for you. If you want to keep your reducers' logic simple and use other ways (sagas, middlewares) to implement business logic, redux-store-generator might better cater to your needs.

* simplified via convenient methods