Body
Valida el body de una request con un esquema y accede al resultado parseado y validado como `ctx.body`.
Declarar un esquema de body en las opciones de una ruta te da ctx.body — el body
de la request, parseado según su Content-Type y validado contra tu esquema:
import { Arcton } from '@arcton/core'
import * as v from 'valibot'
const app = Arcton()
app.post('/users', {
body: v.object({
name: v.pipe(v.string(), v.minLength(1)),
email: v.pipe(v.string(), v.email())
}),
handler: ctx => ({ created: ctx.body })
})
app.listen()ctx.body solo aparece — y solo pasa el type-check — en una ruta que declaró un
esquema de body de esta forma. Una ruta sin uno directamente no tiene ctx.body.
Body no es solo JSON
Una ruta acepta application/json y nada más por defecto. Cualquier otro media
type — text/plain, un body de formulario, incluso un subtipo +json como
application/vnd.api+json — responde 415 antes de parsear nada, a menos que la
ruta lo declare explícitamente con
content. El esquema valida contra el valor al
que ese media type parsee, así que una ruta puede recibir texto plano:
import { Arcton } from '@arcton/core'
import * as v from 'valibot'
const app = Arcton()
app.post('/notes', {
body: { content: { 'text/plain': v.pipe(v.string(), v.minLength(1)) } },
handler: ctx => ({ length: ctx.body.length })
})
app.listen()o describir un body de FormData:
import { Arcton } from '@arcton/core'
import * as v from 'valibot'
const app = Arcton()
app.post('/upload', {
body: { content: { 'multipart/form-data': v.instance(FormData) } },
handler: ctx => ({ received: ctx.body.get('name') })
})
app.listen()Qué valores de Content-Type parsean a qué valor de JavaScript — y qué pasa cuando
el Content-Type de la request no es uno que Arcton sepa parsear — está cubierto en
Parsers de Body.
Bodies opcionales
Un body es obligatorio por defecto: una request sin body se rechaza antes de
que corra tu schema. Para aceptarla también, pasa { schema, optional: true }
en lugar de un schema pelado:
import { Arcton } from '@arcton/core'
import * as v from 'valibot'
const app = Arcton()
app.post('/reviews/:id/dismiss', {
body: {
schema: v.object({ reason: v.optional(v.string()) }),
optional: true
},
handler: ctx => ({ dismissedWith: ctx.body?.reason ?? null })
})
app.listen()Una request que no trae body se salta el parseo y la validación, y ctx.body
es undefined — no se convierte en {}, y el schema nunca lo ve. El tipo lo
refleja: ctx.body es la salida del schema o undefined. Una request que sí
trae body se trata exactamente igual que antes: {} pasa por el schema, un JSON
malformado sigue siendo 400, un Content-Type no soportado sigue siendo 415.
"Sin body" significa que la request no trae ninguno — un header Content-Type
por sí solo no cuenta como body.
Aceptar media types específicos
Un schema pelado acepta únicamente application/json. Para aceptar otros media
types, o varios, cada uno con su propio schema, usa content en lugar de schema.
content reemplaza ese valor por defecto, así que lista también application/json
si la ruta debe seguir aceptándolo:
import { Arcton } from '@arcton/core'
import * as v from 'valibot'
const app = Arcton()
app.post('/webhook', {
body: {
content: {
'application/json': v.object({ event: v.string() }),
'text/plain': v.pipe(v.string(), v.minLength(1))
}
},
handler: ctx => ({ via: ctx.contentType, received: ctx.body })
})
app.listen()Una request cuyo Content-Type no está listado responde 415 antes de parsear
nada. La comparación ignora mayúsculas y parámetros como ; charset=, y por lo
demás es exacta: application/vnd.api+json no coincide con application/json.
El media type que coincidió es ctx.contentType, y ctx.body es la salida del
schema de ese media type — por eso su tipo es la unión de las salidas. Acotar
ctx.body a partir de ctx.contentType todavía no se verifica en tipos.
content solo decide qué media types acepta la ruta; no le enseña a Arcton a
leer nuevos. Un media type sin parser integrado, como text/csv, sigue
necesitando un
app.parser() — sin uno
responde 415; registrar uno nunca cambia lo que acepta un schema pelado.
optional: true funciona igual que con schema: una request sin
body deja ctx.body y ctx.contentType en undefined. Usa schema o
content, nunca ambos. OpenAPI documenta cada
media type listado con su schema.
Orden
body se valida al final, después de params y query — ver
Descripción general de validación. Un esquema de body que falla
responde con 400 de la misma forma que las fallas de params o query — ver
Errores de validación.