Redux Toolkit: Creating Thunk Functions

What's a Thunk?

In programming, the word thunk refers to the part of code that performs delayed work, like async functions in JavaScript.

By itself, a Redux store doesn’t handle asynchronous logic. It only knows how to:

1. Synchronously dispatch actions.
2. Update state via reducers.
3. Notify the UI about state changes.

But wait, if that's the case, how can we call APIs and update the state based on their responses, which usually takes time? How do we handle that?

This is where the thunk functions come in.

What's a Thunk Function?

A thunk function is a function created to handle async logic, like calling an API. It takes two arguments dispatch and getState to dispatch actions and have access to the current state if needed.

const getAllUsers = () => {
  return async (dispatch, getState) => {
    dispatch(fetingAllUsers());
    try {
      const users = await getUsers();
      dispatch(userUpdated(users));
    } catch (err) {
      dispatch(logError(err))
    }
  }
}

The returned function is the thunk function and getAllUsers is called the thunk action creator in this example, and it would be dispatch like this:

dispatch(getAllUsers())

A thunk action creator can be dispatched with arguments to be used in the thunk function, if needed.

Creating Thunks with createAsyncThunk

Redux Toolkit provides the createAsyncThunk API to generate thunks easily:

import { createAsyncThunk } from '@reduxjs/toolkit';

export const fetchUserById = createAsyncThunk(
  'user/fetchUserById',
  async (userId) => {
    const user = await someHttpRequest(userId);
    return user;
  }
);

fetchUserById is the thunk function created here. createAsyncThunk is taking two arguments:

• The first argument is a string prefix used for the action types generated (e.g. user/fetchUserById/pending, user/fetchUserById/fulfilled, or user/fetchUserById/rejected).
• The second argument is a "payload creator" function. It should return a Promise with the required data or an error.

Why Use createAsyncThunk?

Besides letting you create thunk functions for API calls, createAsyncThunk automatically dispatches actions to track the state of API requests:

• pending: The request is in progress.
• fulfilled: The request succeeded.
• rejected: The request failed.

This is really useful. For example, we can show a loader in the UI when the state is pending and let the user know something is happening.

Using Thunks in the Slice

Now that we’ve created the fetchUserById thunk, we can use the extraReducers field in our userSlice to handle state status changes:

import { createSlice } from '@reduxjs/toolkit';

const initialState = {
  user: null,
  status: 'idle', // 'idle' | 'pending' | 'succeeded' | 'failed'
  error: null,
};

export const userSlice = createSlice({
  name: 'user',
  initialState,
  reducers: {
    usernameUpdated: (state, action) => {
      state.user.username = action.payload;
    },
    emailUpdated: (state, action) => {
      state.user.email = action.payload;
    },
    userDataCleared: (state) => {
      state.user = null;
      state.status = 'idle';
    },
  },
  extraReducers: (builder) => {
    builder
      .addCase(fetchUserById.pending, (state) => {
        state.status = 'pending';
      })
      .addCase(fetchUserById.fulfilled, (state, action) => {
        state.status = 'succeeded';
        state.user = action.payload;
      })
      .addCase(fetchUserById.rejected, (state, action) => {
        state.status = 'failed';
        state.error = action.error.message || 'Something went wrong.';
      });
  },
});

export const { usernameUpdated, emailUpdated, userDataCleared } = userSlice.actions;

// Selector for the status to use in the application's components
export const selectStatus = (state) => state.user.status;

createAsyncThunk Conditions

What if we want to check some conditions before calling the API? For example, if the status is already pending, we don’t want to call it twice. In that case, we can use the third argument that createAsyncThunk accepts to write conditions.

export const fetchUserById = createAsyncThunk(
  "user/fetchUserById",
  async (userId) => {
    const response = await someHttpRequest(userId);
    return response;
  },
  {
    condition(_, { getState }) {
      const status = selectStatus(getState());
      if (status !== "idle") {
        return false;
      }
    },
  }
);

To learn how to use Typescript with the thunk functions, please read Type Checking Redux Thunks.