ArctonArcton
Validación

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.

En esta página