Leer el cuerpo de la petición: json, text, formData y arrayBuffer

Toda la información que un cliente te envía —el JSON de un POST, los campos de un formulario, los bytes de un fichero subido— viaja en el cuerpo de la Request. Y ese cuerpo no es una cadena que esté ahí esperándote: es un ReadableStream que llega por la red, se consume una única vez y que tú decides cómo materializar. El runtime te ofrece cuatro lectores tipados —json, text, formData y arrayBuffer— y toda la destreza de esta lección consiste en elegir el correcto guiándote por el método y por el Content-Type, no por la costumbre.

Un cuerpo que se consume una sola vez

Cuando tu fetch handler recibe una Request, su cuerpo todavía no está en memoria. Lo que tienes es un ReadableStream conectado a la conexión del cliente: los bytes van llegando y solo se materializan cuando tú los pides. Esta pereza es deliberada —te permite empezar a decidir antes de tener el cuerpo entero, o rechazar la petición sin llegar a leerlo—, pero impone una regla férrea del estándar Fetch: un cuerpo se lee una sola vez.

Cada uno de los cuatro lectores agota ese flujo. En cuanto invocas uno, la propiedad request.bodyUsed pasa a true y cualquier segunda lectura lanza una excepción, porque ya no queda nada que leer. No es un búfer que puedas releer a voluntad: es una cinta que se reproduce una vez y se consume al pasar.

export default {
  async fetch(request: Request): Promise<Response> {
    const texto = await request.text();
    // El flujo ya se agoto: la siguiente linea lanza una excepcion.
    const datos = await request.json();
    return new Response(texto);
  },
};

Los cuatro lectores tipados

Los cuatro métodos leen el mismo flujo, pero cada uno lo interpreta de una forma y devuelve un tipo distinto. Elegir es, en el fondo, declarar qué esperas recibir:

Hay una jerarquía natural entre ellos. arrayBuffer es el más primitivo: los bytes tal cual. text es un arrayBuffer decodificado como UTF-8. json es un text pasado por JSON.parse. Y formData entiende la gramática de los formularios web, la única que además sabe separar varios ficheros y campos de un cuerpo multipart. Si pides un formato que el cuerpo no cumple —json sobre algo que no lo es—, la promesa se rechaza, así que envuelve el parseo en un try/catch cuando la entrada no sea de fiar.

El formData merece un vistazo porque es el más rico: un formulario puede mezclar campos de texto y ficheros en un mismo cuerpo multipart, y el FormData que obtienes los distingue por ti. Un campo de texto sale como cadena; un fichero subido sale como un objeto File del que puedes leer los bytes:

const form = await request.formData();
const nombre = form.get("nombre");        // un campo de texto
const avatar = form.get("avatar");        // un File si se subio uno
if (avatar instanceof File) {
  const bytes = await avatar.arrayBuffer();
  // ...por ejemplo, guardar esos bytes en R2
}

El método y las cabeceras mandan

Antes de leer, mira. El request.method te dice si siquiera cabe esperar un cuerpo: un GET o un HEAD no lo llevan, y las cabeceras Content-Type y Content-Length describen qué hay dentro y cuánto. Decidir el lector a partir de esa cabecera —y no de una suposición— es lo que separa un endpoint robusto de otro que se rompe con la primera petición inesperada.

export default {
  async fetch(request: Request): Promise<Response> {
    if (request.method !== "POST") {
      return new Response("metodo no permitido", { status: 405 });
    }
    const tipo = request.headers.get("Content-Type") ?? "";
    if (tipo.includes("application/json")) {
      const datos = await request.json();
      return Response.json({ recibido: datos });
    }
    if (tipo.includes("form")) {
      const form = await request.formData();
      return new Response(`campos: ${[...form.keys()].join(", ")}`);
    }
    return new Response("tipo no soportado", { status: 415 });
  },
};

flowchart TD
Req[Request entrante] --> M[revisar metodo]
M -->|GET o HEAD| Sin[sin cuerpo que leer]
M -->|POST PUT PATCH| CT[revisar Content-Type]
CT -->|application json| J[request.json]
CT -->|form o multipart| F[request.formData]
CT -->|texto plano| T[request.text]
CT -->|binario| A[request.arrayBuffer]

Fíjate en que cada rama devuelve un estado HTTP con sentido: 405 cuando el método no encaja, 415 cuando el tipo de medio no está soportado. Leer el cuerpo no es lo primero que haces, sino lo último, una vez que método y cabeceras te han confirmado que hay algo que merece la pena leer y que sabes cómo interpretarlo.