redux-controller-middleware

Adjust Redux middleware to be able to use controllers with Dependency Injection to handle actions.

• Installation
• Include in redux middleware
• How to use
  • Functional approach
  • OOP approach
  • Dependency injection
    • Functional variant
    • OOP variant
  • createAction
  • Chaining actions
  • How about tests?

Installation

npm

npm install redux-controller-middleware

yarn

yarn add redux-controller-middleware

Include in redux middleware

Add redux-controller-middleware middleware to redux.

// store.ts
import { combineReducers, configureStore } from '@reduxjs/toolkit';
import { controllerMiddleware, getReducersFromStoreSlices, InferState } from 'redux-controller-middleware';

// add user slice reducer
const makeReducers = () =>
  getReducersFromStoreSlices({
    users: UsersSlice, // read bellow what is it
    // ...
  });

export type RootState = InferState<ReturnType<typeof makeReducers>>;

export const store = configureStore({
  reducer: combineReducers(makeReducers()),
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(controllerMiddleware()),
});

How to use

Functional approach

// addUser.ts
import { createReducer, storeSlice, updateStoreSlice } from 'redux-controller-middleware';

export type User = {
  userId: string;
  userName: string;
};

@storeSlice
export class UsersSlice {
  usersList: User[] = [];
}

export const addUser = createReducer<{ name: string }, { users: UsersSlice }>(
  'addUser',
  async ({ action, dispatch, getState }) => {
    const newUserResponse = await fetch('/api/user', {
      method: 'POST',
      body: JSON.stringify({
        username: action.payload.name
      })
    });

    const newUser = await newUserResponse.json();

    const { usersList } = getState().users;
    dispatch(
      updateStoreSlice(UsersSlice)({
        usersList: usersList.concat(newUser)
      })
    );
  }
);

// your component
import { faker } from '@faker-js/faker';
import { useDispatch } from 'react-redux';
import { addUser } from './addUser.ts';
import { useAppSelector } from './store.ts';

const Users = () => {
  const dispatch = useDispatch();

  const { usersList } = useAppSelector((state) => state.users);

  return (
    <div>
      <div>
        {usersList.map((user) => (
          <p key={user.userId}>{user.userName}</p>
        ))}
      </div>

      <button
        onClick={() => {
          dispatch(addUser({ name: faker.person.fullName() }));
        }}
      >
        add user
      </button>
    </div>
  );
};

// store.ts
import { combineReducers, configureStore } from '@reduxjs/toolkit';
import { controllerMiddleware, getReducersFromStoreSlices, InferState } from 'redux-controller-middleware';
import { TypedUseSelectorHook, useSelector } from 'react-redux';
import { UsersSlice } from './addUser.ts';

// add user slice reducer
const makeReducers = () =>
  getReducersFromStoreSlices({
    users: UsersSlice,
  });

export const store = configureStore({
  reducer: combineReducers(makeReducers()),
  // add redux-controller-middleware to redux
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(controllerMiddleware()),
});

export type RootState = InferState<ReturnType<typeof makeReducers>>;
export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector;

OOP approach

NOTE: Controller - is a place for a piece of logic in your application. The differences from Saga (in redux-saga) is your methods is not static! It allows you to use dependency injection technics and simplify tests.

// Users.controller.ts
import {
  ControllerBase,
  Middleware,
  storeSlice,
  controller,
  reducer,
  Action,
  WatchedController,
} from 'redux-controller-middleware';

export type User = {
  userId: string;
  userName: string;
};

@storeSlice
export class UsersSlice {
  usersList: User[] = [];
}

@controller
class UsersController extends ControllerBase<UsersSlice, { users: UsersSlice }> {
  constructor(middleware: Middleware<{ users: UsersSlice }>) {
    super(middleware, UsersSlice);
  }

  @reducer
  async addUser(action: Action<{ name: string }>) {
    const newUserResponse = await fetch('/api/user', {
      method: 'POST',
      body: JSON.stringify({
        username: action.payload.name
      })
    });

    const newUser = await newUserResponse.json();

    const { usersList } = this.getState().users;

    this.updateStoreSlice({
      usersList: usersList.concat(newUser),
    });
  }
}

// this type casting is required because the decorator can't change the signature of the class =(
const userController = UsersController as unknown as WatchedController<UsersController>;
export { userController as UsersController };

// your component
const Users = () => {
  const dispatch = useDispatch();
  // ...

  return (
    <div>
      {/*...*/}

      <button
        onClick={() => {
          dispatch(
            // action creator looks like static method of the controller class
            UsersController.addUser({ name: faker.person.fullName() })
          );
        }}
      >
        add user
      </button>
    </div>
  );
};

Dependency injection

To use dependency injection, you need to provide container to controllerMiddleware function. Read more on cheap-di README page

// store.ts
import { configureStore } from '@reduxjs/toolkit';
import { container } from 'cheap-di';
import { controllerMiddleware } from 'redux-controller-middleware';

export const store = configureStore({
  reducer: {...},
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware().concat(
      controllerMiddleware({
        container, // DI container attached to middleware
      })
    ),
});

Configure cheap-di-ts-transform to generate dependencies metadata.

// services.ts
export class Logger {
  log(...messages: unknown[]) {
    console.log(...messages);
  }
}

export class UserApi {
  constructor(private logger: Logger) {}
  
  async get() {
    this.logger.log('[my api] fetching users list');
    const response = await fetch('/api/user');
    return response.json();
  }
}
// services.ts

Or use @inject decorator to register dependencies yourself

import { inject } from 'cheap-di';

export class Logger {
  log(...messages: unknown[]) {
    console.log(...messages);
  }
}

@inject(Logger)
export class UserApi {
  constructor(private logger: Logger) {}

  async get() {
    this.logger.log('[my api] fetching users list');
    const response = await fetch('/api/user');
    return response.json();
  }
}

NOTE: To use stage 2 decorators, you need to adjust your tsconfig.json like this:

{
  "compilerOptions": {
    // ...
    "experimentalDecorators": true
  }
}

To use stage 3 decorators, you don't need extra setup.

Functional variant

You may instantiate the service inside your reducer like this:

import { createReducer, storeSlice, updateStoreSlice } from 'redux-controller-middleware';
import { UserApi } from './services.ts';

@storeSlice
export class UsersSlice {
  usersList: string[] = [];
}

export const fetchUsers = createReducer('fetchUsers', async ({ container, dispatch }) => {
  const userApi = container?.resolve(UserApi);
  if (!userApi) {
    return;
  }

  const users = await userApi.get();

  dispatch(
    updateStoreSlice(UsersSlice)({
      usersList: users,
    })
  );
});

NOTE: such instantiation technic is called Service Locator, and it is counted as anti-pattern that is why we recommend using the OOP variant of dependency injection.

OOP variant

Controller gets its dependencies automatically from middleware

// User.controller.ts
import {
  controller,
  ControllerBase,
  Middleware,
  reducer,
  storeSlice,
  WatchedController,
} from 'redux-controller-middleware';
import { UserApi } from './services.ts';

@storeSlice
export class UsersSlice {
  usersList: string[] = [];
}

@controller
class UsersController extends ControllerBase<UsersSlice> {
  constructor(
    middleware: Middleware,
    private readonly userApi: UserApi
  ) {
    super(middleware, UsersSlice);
  }

  @reducer
  async fetchUsers() {
    const users = await this.userApi.get();

    // you also may wait untill the update will be applied to the redux state, if you need it
    await this.updateStoreSlice({
      usersList: users,
    });

    console.log('store has updated');

    const { usersList } = this.getState().users;
    console.log(`list is updated ${usersList === users}`); // true
  }
}

// this type casting is required because the decorator can't change the signature of the class =(
const userController = UsersController as unknown as WatchedController<UsersController>;
export { userController as UsersController };

createAction

You can define action creators yourself:

import { createAction } from 'redux-controller-middleware';

const loadUserList = () => createAction('load user list');

const loadUser = (data: { userID: string }) => createAction('load user', data);

Chaining actions

You can chain actions one by one:

import { useDispatch } from 'react-redux';
import { chainActions } from 'redux-controller-middleware';
import { UserController } from './User.controller';

const Page = () => {
  const dispatch = useDispatch();

  useEffect(() => {
    const action = chainActions(
      UserController.loadProfile({ userID: '123' }),
      UserController.openUserPage({ userID: '123' }),
      // ... any other
    );

    dispatch(action);
  }, []);

  return /* your layout */;
};

How about tests?

We prepare a few functions to simplify middleware and mocking in tests:

getStoreSliceUpdateActionType - helps you to extract action type of a store slice update method:

import { getStoreSliceUpdateActionType, storeSlice } from 'redux-controller-middleware';

@storeSlice
export class UserSlice {
  // ...
}

test('...', () => {
  const someActionInYourTest = /* ... */;
  
  const updateActionType = getStoreSliceUpdateActionType(UserSlice);
  expect(someActionInYourTest.type).toBe(updateActionType);
});

makeActionType - helps you to create action type with passed parameters to compare an action type in your tests with expected value. All actions except store slice update action has unique salt in their action types (that equals current milliseconds of time by default). So you may check only if your action type is started with desired action type part.

import { createReducer, makeActionType, mockMiddlewareForTests } from 'redux-controller-middleware';

const loadUsers = createReducer('loadUsers', () => {/*...*/});

test('...', async () => {
  const mockedMiddleware = mockMiddlewareForTests();
  const { dispatch, dispatchedActions } = mockedMiddleware;
  
  await dispatch(loadUsers());
	
  const [firstAction] = dispatchedActions;

  const actionTypePart = makeActionType({
    methodName: 'loadUsers',
  });
  
  expect(firstAction?.type.startsWith(actionTypePart)).toBe(true);
});

import { controller, makeActionType, mockMiddlewareForTests, reducer } from 'redux-controller-middleware';

@controller
class UserController extends ControllerBase {
	// ...
  @reducer
  async loadUsers() {
		// ...
  }
}

test('...', async () => {
  const mockedMiddleware = mockMiddlewareForTests();
  const { dispatch, dispatchedActions } = mockedMiddleware;
  
  await dispatch(UserController.loadUsers());
	
  const [firstAction] = dispatchedActions;

  const actionTypePart = makeActionType({
    controllerName: 'UserController',
    // same as 
    // controllerName: 'User'
    methodName: 'loadUsers',
  });
  
  expect(firstAction?.type.startsWith(actionTypePart)).toBe(true);
});

mockMiddlewareForTests - helps you mock middleware and state, dispatch actions and analyze the process.

test('it sets opened user to null', async () => {
  const mockedMiddleware = mockMiddlewareForTests({ users: UserSlice });
  const { dispatch, state } = mockedMiddleware;

  state.users.openedUser = {
    userId: faker.number.int(),
    name: faker.person.fullName(),
  };

  // dispatch action and wait until it will be resolved
  await dispatch(UserController.clearUser());

  expect(state.users.openedUser).toBeNull();
});

You can find more tests examples in GitHub examples