Thunks tipados y estados de carga bien modelados

La asincronía es donde el tipado de Redux se vuelve interesante, porque hay más de un tipo en juego y todos son distintos: el argumento con que se invoca el thunk, el valor que devuelve al resolverse, el estado que puede leer por el camino y el error que produce al fallar. createAsyncThunk los admite todos, pero como parámetros opcionales, y esa opcionalidad es una trampa amable: el thunk compila sin declarar nada y solo más tarde descubres que getState te da un valor desconocido y que el payload de rechazo no tiene forma. Tipar bien un thunk es declarar esos cuatro tipos una vez y, acto seguido, hacerse la pregunta que casi nadie se hace: si el resultado de la operación se modela con un status suelto y unos campos que pueden estar vacíos, o con una estructura donde los estados imposibles simplemente no se puedan escribir.

Los tres parámetros de tipo y lo que cuesta omitirlos

createAsyncThunk acepta tres parámetros de tipo en este orden: el valor que la promesa resuelve, el argumento que recibe quien despacha, y un objeto de configuración con claves para el estado, el dispatch, el valor extra y el valor de rechazo. Los dos primeros suelen inferirse solos del payload creator y rara vez hay que escribirlos. El tercero no se infiere de nada, y ahí está el problema: si no lo declaras, thunkAPI.getState devuelve un valor de tipo desconocido y no puedes leer ninguna rama sin una aserción, thunkAPI.dispatch pierde las sobrecargas de tus middlewares, y rejectWithValue acepta cualquier cosa mientras el payload de la acción rechazada llega sin forma al reducer.

El detalle más sutil vive en el rechazo. Un thunk puede fallar de dos maneras distintas y Redux Toolkit las distingue: si el payload creator llama a rejectWithValue, la acción rejected lleva tu payload tipado; si en cambio lanza una excepción, no hay payload y el error aparece serializado en otro campo. Como el reducer no puede saber cuál de los dos caminos ocurrió, el payload de la acción rechazada es siempre opcional, aunque hayas declarado su tipo. Esa opcionalidad no es un defecto del tipado sino su lectura honesta de la realidad, y obliga a escribir en el reducer la ramificación que de verdad existe.

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

interface Usuario { id: string; nombre: string }
interface ErrorApi { codigo: number; mensaje: string }

export const cargarUsuario = createAsyncThunk<
  Usuario,                                   // lo que resuelve
  string,                                    // el argumento
  { state: RootState; dispatch: AppDispatch; rejectValue: ErrorApi }
>("usuario/cargar", async (id, thunkAPI) => {
  // getState conoce la forma del estado porque la declaramos arriba
  const token = thunkAPI.getState().sesion.token;
  const res = await fetch(`/api/usuarios/${id}`, { signal: thunkAPI.signal });
  if (!res.ok) {
    return thunkAPI.rejectWithValue({ codigo: res.status, mensaje: "fallo" });
  }
  return (await res.json()) as Usuario;
});

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

export const createAppAsyncThunk = createAsyncThunk.withTypes<{
  state: RootState;
  dispatch: AppDispatch;
  rejectValue: ErrorApi;
}>();

// a partir de aqui cada thunk solo declara lo suyo
export const guardarPerfil = createAppAsyncThunk(
  "perfil/guardar",
  async (borrador: Borrador, { getState, rejectWithValue }) => {
    if (!getState().sesion.token) return rejectWithValue({ codigo: 401, mensaje: "sin sesion" });
    return await api.guardar(borrador);
  },
);

Atender el ciclo con los tres casos tipados

En extraReducers, cada uno de los tres momentos llega con su tipo propio y merece un trato distinto. El caso pendiente no trae datos útiles salvo el argumento original en la metainformación. El caso resuelto trae el payload con el tipo declarado como valor de resolución, y ahí la inferencia funciona sin ayuda. El caso rechazado es el que exige atención, porque hay que ramificar entre el payload tipado y el error serializado. Escribir esa ramificación es incómodo la primera vez y después se agradece, porque distingue con claridad los fallos previstos del dominio de los imprevistos del programa.

flowchart TD
A[createAsyncThunk con sus tres parametros] --> B[valor resuelto tipa fulfilled]
A --> C[argumento tipa la invocacion]
A --> D[configuracion tipa getState y rejectWithValue]
B --> E[extraReducers con payload tipado]
D --> E
E --> F[union discriminada del recurso]
F --> G[componentes que estrechan por el campo estado]
style A fill:#fab387,color:#11111b
style F fill:#a6e3a1,color:#11111b
style G fill:#89b4fa,color:#11111b

Del trío de campos a la unión discriminada

El patrón canónico guarda tres campos sueltos: un status, los datos y el error. Es cómodo y es, en sentido estricto, un tipo producto: el compilador admite todas las combinaciones del producto de sus campos, incluidas las que tu aplicación jamás produce ni sabría interpretar. Estado resuelto con datos ausentes, estado cargando con error presente, estado fallido con datos de una carga anterior: combinaciones representables, y por tanto combinaciones que algún componente tendrá que comprobar defensivamente o, más probablemente, olvidará comprobar. La alternativa es modelar el recurso como una unión discriminada, un tipo suma donde cada variante lleva exactamente los campos que tienen sentido en ella y ninguno más.

type Recurso<T> =
  | { estado: "inactivo" }
  | { estado: "cargando" }
  | { estado: "listo"; datos: T }
  | { estado: "fallo"; error: ErrorApi };

const slice = createSlice({
  name: "usuario",
  initialState: { recurso: { estado: "inactivo" } } as { recurso: Recurso<Usuario> },
  reducers: {},
  extraReducers: (builder) => {
    builder
      .addCase(cargarUsuario.pending, (estado) => {
        estado.recurso = { estado: "cargando" };
      })
      .addCase(cargarUsuario.fulfilled, (estado, accion) => {
        estado.recurso = { estado: "listo", datos: accion.payload };
      })
      .addCase(cargarUsuario.rejected, (estado, accion) => {
        // payload solo existe si se uso rejectWithValue
        const error = accion.payload ?? { codigo: 0, mensaje: accion.error.message ?? "error" };
        estado.recurso = { estado: "fallo", error };
      });
  },
});