createAsyncThunk: pending, fulfilled y rejected automáticos

La asincronía fue siempre el punto donde Redux se ponía incómodo: un reducer debe ser puro y síncrono, así que una petición a la red no cabe dentro. La respuesta clásica eran los thunks a mano, funciones que reciben dispatch y despachan acciones en distintos momentos del ciclo de una promesa, con el tedio de inventar y manejar tres acciones por cada operación. createAsyncThunk industrializa ese patrón: le das una función async y él genera y despacha por ti tres acciones —pending al empezar, fulfilled al resolver, rejected al fallar— que tú solo tienes que atender. El resultado es que la asincronía deja de ser un caso especial artesanal y se convierte en una máquina de tres estados que Redux te regala hecha, con la promesa domada en acciones inspeccionables.

Un thunk que despacha su propio ciclo de vida

createAsyncThunk recibe dos cosas: un prefijo de tipo, como usuario/cargar, y un payload creator, la función async que hace el trabajo. A partir del prefijo genera tres action creators anidados —cargarUsuario.pending, cargarUsuario.fulfilled y cargarUsuario.rejected— y devuelve un thunk que, al despacharse, los emite en el orden que corresponda: pending en cuanto arranca, y luego fulfilled con el valor resuelto o rejected con el error. El payload creator recibe el argumento que le pasaste al despachar y un objeto thunkAPI lleno de utilidades.

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

interface Usuario { id: string; nombre: string }

export const cargarUsuario = createAsyncThunk(
  "usuario/cargar",
  async (id: string, thunkAPI) => {
    const res = await fetch(`/api/usuarios/${id}`, { signal: thunkAPI.signal });
    if (!res.ok) return thunkAPI.rejectWithValue("no encontrado");
    return (await res.json()) as Usuario; // esto viaja en fulfilled.payload
  },
);

Reaccionar al ciclo en extraReducers

El thunk no sabe nada de tu estado; solo despacha acciones. Eres tú quien decide qué significan, y lo haces en extraReducers del slice, con el builder atendiendo cada fase del ciclo. El patrón canónico mantiene tres campos: un status que recorre idle, loading, succeeded y failed; los datos cuando llegan; y el error cuando lo hay. Ese trío es la representación honesta de cualquier operación asíncrona, y createAsyncThunk te da los tres momentos exactos en que actualizarlo.

import { createSlice } from "@reduxjs/toolkit";
import { cargarUsuario } from "./thunks";

interface Estado {
  usuario: Usuario | null;
  status: "idle" | "loading" | "succeeded" | "failed";
  error: string | null;
}
const inicial: Estado = { usuario: null, status: "idle", error: null };

const slice = createSlice({
  name: "usuario",
  initialState: inicial,
  reducers: {},
  extraReducers: (builder) => {
    builder
      .addCase(cargarUsuario.pending, (e) => {
        e.status = "loading";
        e.error = null;
      })
      .addCase(cargarUsuario.fulfilled, (e, accion) => {
        e.status = "succeeded";
        e.usuario = accion.payload;
      })
      .addCase(cargarUsuario.rejected, (e, accion) => {
        e.status = "failed";
        e.error = (accion.payload as string) ?? accion.error.message ?? "error";
      });
  },
});

flowchart LR
A[idle] -->|dispatch del thunk| B[pending loading]
B -->|promesa resuelta| C[fulfilled succeeded]
B -->|promesa rechazada| D[rejected failed]
C -->|volver a despachar| B
D -->|reintentar| B
style B fill:#fab387,color:#11111b
style C fill:#a6e3a1,color:#11111b
style D fill:#f38ba8,color:#11111b

thunkAPI: errores tipados, cancelación y guardas

El objeto thunkAPI es la caja de herramientas del payload creator. rejectWithValue te deja rechazar con un valor propio y tipado que llega a rejected.payload, en lugar de depender del error.message genérico: así distingues un 404 de un fallo de red con datos estructurados. signal es un AbortSignal que RTK aborta si cancelas el thunk, y pasarlo a fetch hace que la petición se corte de verdad. getState y dispatch te dejan leer o encadenar. Y la opción condition se evalúa antes de arrancar: si devuelve false, el thunk ni siquiera empieza, lo que evita relanzar una petición que ya está en curso.

import { createAsyncThunk } from "@reduxjs/toolkit";
import type { RootState } from "./store";

export const cargarUsuario = createAsyncThunk<
  Usuario,                                   // tipo del valor en fulfilled
  string,                                    // tipo del argumento
  { state: RootState; rejectValue: string }  // tipos de thunkAPI
>(
  "usuario/cargar",
  async (id, { rejectWithValue, signal }) => {
    const res = await fetch(`/api/usuarios/${id}`, { signal });
    if (!res.ok) return rejectWithValue("no encontrado");
    return (await res.json()) as Usuario;
  },
  {
    condition: (id, { getState }) => {
      // no relances si esa carga ya esta en curso
      return getState().usuario.status !== "loading";
    },
  },
);