use-effect-reducer

When you call exec(effect), it returns an effect entity. You can store this entity in your state to gain control over the running effect later.

Stop an effect

Use exec.stop(entity) to explicitly stop an effect and run its cleanup function. All running effects are automatically cleaned up when the component unmounts.

Replace an effect

Use exec.replace(entity, effect) to stop an existing effect and immediately start a new one. This returns a new effect entity.

const timerReducer = (state, event, exec) => {
  if (event.type === 'START') {
    // Store the entity in state
    return {
      ...state,
      timer: exec(() => {
        const id = setTimeout(() => { /* ... */ }, 1000);
        return () => clearTimeout(id);
      }),
    };
  } else if (event.type === 'STOP') {
    // Stop using the stored entity
    exec.stop(state.timer);
    return state;
  } else if (event.type === 'LAP') {
    // Replace the existing effect with a new one
    return {
      ...state,
      timer: exec.replace(state.timer, () => doSomeDelay()),
    };
  }
  return state;
};

Instead of passing inline functions to exec, you can use named effects to make your reducers reusable and decoupled from implementation details.

1. In the reducer, pass an object to exec({ type: 'effectName', ...params }).
2. Provide an effectsMap as the third argument to useEffectReducer. This map contains the implementations for each effect type.

An effect implementation receives three arguments:

• state: The state at the time exec was called.
• effect: The effect object passed to exec.
• dispatch: The dispatch function to send events back to the reducer.

const fetchEffectReducer = (state, event, exec) => {
  switch (event.type) {
    case 'FETCH':
      // Pass an object describing the effect
      exec({ type: 'fetchFromAPI', user: event.user });
      return { ...state, status: 'fetching' };
    case 'RESOLVE':
      return { status: 'fulfilled', user: event.data };
    default:
      return state;
  }
};

const Fetcher = () => {
  const [state, dispatch] = useEffectReducer(
    fetchEffectReducer,
    { status: 'idle', user: undefined },
    {
      // Implementation map
      fetchFromAPI: (_, effect, dispatch) => {
        fetch(`/api/users/${effect.user}`)
          .then((res) => res.json())
          .then((data) => {
            dispatch({ type: 'RESOLVE', data });
          });
      },
    }
  );

  // ...
};

The useEffectReducer hook is similar to useReducer. It takes an effect reducer function as its first argument. The reducer function receives three arguments:

1. state: The current state.
2. event: The event dispatched.
3. exec: A function used to capture effects to be executed. Calling exec returns an effect entity.

When exec is called within the reducer, the hook ensures the effect is executed within a useEffect lifecycle hook.

import { useEffectReducer } from 'use-effect-reducer';

const countReducer = (state, event, exec) => {
  switch (event.type) {
    case 'INC':
      exec(() => {
        console.log('Going up!');
      });

      return {
        ...state,
        count: state.count + 1,
      };

    default:
      return state;
  }
};

const App = () => {
  const [state, dispatch] = useEffectReducer(countReducer, { count: 0 });

  return (
    <div>
      <output>Count: {state.count}</output>
      <button onClick={() => dispatch('INC')}>Increment</button>
    </div>
  );
};

Use the EffectReducer<TState, TEvent, TEffect> generic type to provide full type safety for your state, events, and named effects.

import { useEffectReducer, EffectReducer } from 'use-effect-reducer';

interface User {
  name: string;
}

type FetchState =
  | { status: 'idle'; user: undefined }
  | { status: 'fetching'; user: User | undefined }
  | { status: 'fulfilled'; user: User };

type FetchEvent =
  | { type: 'FETCH'; user: string }
  | { type: 'RESOLVE'; data: User };

type FetchEffect = {
  type: 'fetchFromAPI';
  user: string;
};

const fetchEffectReducer: EffectReducer<
  FetchState,
  FetchEvent,
  FetchEffect
> = (state, event, exec) => {
  switch (event.type) {
    case 'FETCH':
      exec({ type: 'fetchFromAPI', user: event.user });
      return { ...state, status: 'fetching' };
    case 'RESOLVE':
      return { status: 'fulfilled', user: event.data };
    default:
      return state;
  }
};