PayloadAction: tipar el payload y cosechar la inferencia

Dentro de createSlice conviven dos tipos de naturaleza muy distinta. El del estado no hay que escribirlo dos veces: sale de initialState y llega solo a todos los reducers. El del payload sí hay que declararlo, porque una acción entra en el reducer desde fuera del slice y nada en el código dice qué trae dentro. Ese es el trabajo de PayloadAction, y lo interesante no es la anotación en sí sino su alcance: no sirve únicamente para tipar el parámetro donde la escribes, sino que es el punto desde el cual Redux Toolkit deduce la firma del action creator correspondiente. Anotas una vez, en el lugar donde se define el significado de la acción, y esa anotación viaja hasta cada dispatch de la aplicación para comprobar que quien despacha manda exactamente lo que el reducer espera recibir.

Dos tipos con orígenes distintos

El estado de un slice se infiere de initialState, y por eso ese valor merece más cuidado del que suele recibir. Un objeto literal escrito directamente en la llamada produce tipos ensanchados o demasiado estrechos según el campo: un array vacío se infiere como array de nada, un null se infiere como null a secas, y una cadena literal como idle se ensancha a string perdiendo la unión que querías. La forma robusta es declarar una interfaz para el estado, construir la constante inicial anotada con ella y pasarla al slice. A partir de ahí, todos los reducers ven el estado con el tipo correcto sin una sola anotación adicional, y la quinta lección de este nivel estudia con detalle qué ocurre cuando esta pieza se descuida.

La acción es el caso opuesto. Su payload no está en ninguna parte del slice hasta que lo declaras, así que el segundo parámetro del case reducer se anota con PayloadAction y el tipo del payload como argumento. Esa anotación no es defensiva sino generativa: Redux Toolkit la lee para construir el action creator de esa clave, que pasa a exigir un argumento de ese mismo tipo. Por eso conviene pensar en PayloadAction no como un tipo de entrada sino como la declaración del contrato de la acción, escrita en el único sitio donde ese contrato tiene sentido, que es junto a la lógica que lo consume.

import { createSlice, type PayloadAction } from "@reduxjs/toolkit";

interface Todo { id: string; texto: string; hecho: boolean }

interface EstadoTodos {
  lista: Todo[];
  filtro: "todos" | "pendientes" | "hechos";
  seleccionado: string | null;
}

// anotar la constante evita el ensanchamiento de filtro y de seleccionado
const inicial: EstadoTodos = { lista: [], filtro: "todos", seleccionado: null };

const todosSlice = createSlice({
  name: "todos",
  initialState: inicial,
  reducers: {
    anadido: (estado, accion: PayloadAction<Todo>) => {
      estado.lista.push(accion.payload);
    },
    filtrado: (estado, accion: PayloadAction<EstadoTodos["filtro"]>) => {
      estado.filtro = accion.payload;
    },
    limpiado: (estado) => {
      estado.lista = [];
    },
  },
});

flowchart LR
A[initialState anotado] --> B[tipo del estado en cada reducer]
C[PayloadAction del case reducer] --> D[firma del action creator]
D --> E[cada dispatch verificado en los componentes]
D --> F[addCase en extraReducers de otros slices]
B --> G[Draft de Immer dentro del reducer]
style C fill:#fab387,color:#11111b
style E fill:#a6e3a1,color:#11111b

La inferencia que devuelve la anotación

Lo que gana el proyecto con esa única anotación es una cadena de verificaciones que no costó nada montar. El action creator generado exige el payload correcto, de modo que despachar con un objeto incompleto o con un campo sobrante falla en el editor, en el componente, señalando la propiedad exacta. La cadena continúa hacia otros slices: cuando un tercero atiende esa acción con addCase, el parámetro de la acción llega ya tipado sin repetir nada. Y continúa hacia los tests, donde construir la acción con su creator garantiza que la prueba no se desincronice del reducer cuando el payload cambie de forma.

import { createSlice } from "@reduxjs/toolkit";
import { anadido } from "../todos/todosSlice";

const estadisticas = createSlice({
  name: "estadisticas",
  initialState: { creados: 0, ultimoTexto: "" },
  reducers: {},
  extraReducers: (builder) => {
    // accion.payload llega tipado como Todo sin declararlo aqui
    builder.addCase(anadido, (estado, accion) => {
      estado.creados += 1;
      estado.ultimoTexto = accion.payload.texto;
    });
  },
});

Fíjate en la dirección del flujo: el slice de estadísticas no sabe nada del payload y tampoco lo declara, se limita a importar el creator y dejar que su tipo viaje con él. Si mañana la acción cambia de forma, este reducer deja de compilar aunque viva en otra carpeta y lo mantenga otra persona. Esa es la diferencia práctica entre un tipo que acompaña al valor y una convención documentada: el primero recorre las fronteras de módulo por su cuenta, la segunda se queda en el fichero donde alguien la escribió.

Sin payload, con prepare y bajo el borrador de Immer

Hay tres bordes que conviene dominar. El primero es la acción sin datos: basta con omitir el segundo parámetro y Redux Toolkit generará un creator sin argumentos. Declarar un payload de tipo vacío para esos casos solo consigue obligar a quien despacha a escribir un argumento inútil. El segundo es la forma con prepare, que existe para hacer trabajo antes de construir el payload, típicamente generar un identificador o una marca de tiempo. Ahí aparece un contrato de tipos que hay que respetar: lo que prepare devuelve como payload debe coincidir con lo que su reducer declara, y si divergen el error aparece en la definición del slice, no en el punto de uso. Es un buen error, porque señala una incoherencia interna antes de que llegue a nadie.

import { createSlice, nanoid, type PayloadAction } from "@reduxjs/toolkit";

const slice = createSlice({
  name: "todos",
  initialState: inicial,
  reducers: {
    anadido: {
      // prepare recibe lo que pasa quien despacha y arma el payload
      prepare: (texto: string) => ({
        payload: { id: nanoid(), texto, hecho: false },
        meta: { creadoEn: Date.now() },
      }),
      // el tipo del payload debe coincidir con lo que prepare devuelve
      reducer: (estado, accion: PayloadAction<Todo, string, { creadoEn: number }>) => {
        estado.lista.push(accion.payload);
      },
    },
  },
});

El tercer borde es el estado, no la acción. Dentro de un case reducer, el estado no llega con su tipo declarado sino envuelto en el borrador de Immer, que lo transforma en una versión mutable de sí mismo. En la práctica es transparente hasta que el estado contiene campos de solo lectura o tuplas fijas: entonces el borrador y la declaración discrepan y aparecen errores desconcertantes al asignar. La lectura correcta de esos errores es que el tipo del estado y el tipo del borrador no son el mismo, y que casi siempre la solución está en el estado, no en una aserción sobre el borrador.