Global Error Handler
Captura cualquier error no manejado en un solo lugar con app.onError()
Los errores no capturados llegan al adapter del
runtime como un 500 genérico, a menos que algo los capture antes.
app.onError() registra un único handler que captura cualquiera de esos
errores — de un provider, un middleware, un parser de body o el propio
handler de la ruta — antes de que lleguen tan lejos:
import { Arcton } from '@arcton/core'
const app = Arcton()
app.get('/risky', () => {
throw new Error('boom')
})
app.onError((err, ctx) => {
console.error(err)
return { error: 'Something went wrong' }
})
app.listen()Un request a /risky ahora responde con lo que devuelve el handler en lugar
del texto genérico del 500 del adapter. onError() es opt-in — una app
que nunca lo llama sigue comportándose exactamente como describen los
errores no capturados.
El status por defecto es 500
Si el handler no asigna ctx.response.status por su cuenta, la respuesta
usa 500 por defecto. Asígnalo explícitamente para responder con otra
cosa — por ejemplo, distinguiendo HttpError para reutilizar el status que
ya trae:
import { Arcton, Http, HttpError } from '@arcton/core'
declare function findOrder(id: string): { id: string } | undefined
const app = Arcton()
app.get('/orders/:id', ctx => {
const order = findOrder(ctx.params.id)
if (!order) throw Http.NotFound(`Order ${ctx.params.id} not found`)
return order
})
app.onError((err, ctx) => {
if (err instanceof HttpError) {
ctx.response.status = err.status
return err.body ?? { code: err.code, message: err.message }
}
return { code: 'INTERNAL_SERVER_ERROR', message: 'Internal Server Error' }
})
app.listen()Un status ya asignado antes del throw — por ejemplo, por un middleware que
corrió antes — se conserva si el handler nunca toca
ctx.response.status; el valor por defecto de 500 solo se aplica cuando
nada asignó un status en absoluto.
Como cualquier handler, onError() puede devolver un valor plano (mapeado
con las mismas reglas de Response) o un
objeto Response directamente, que se envía sin cambios.
Los errores de validación también pasan por acá
Un esquema de params, query o body que falla — o un body que Arcton no
puede interpretar en absoluto — llega a onError() como un ValidationError:
una subclase de HttpError cuyos issues son exactamente los que devolvió la
librería de esquemas. Un Content-Type de body no soportado llega como un
HttpError con status 415.
import { Arcton, ValidationError } from '@arcton/core'
import * as v from 'valibot'
const app = Arcton()
app.post('/users', {
body: v.object({ email: v.pipe(v.string(), v.email()) }),
handler: ctx => ({ created: ctx.body })
})
app.onError((err, ctx) => {
if (err instanceof ValidationError) {
return { error: 'Invalid request', issues: err.issues }
}
return { error: 'Something went wrong' }
})
app.listen()La respuesta de arriba es un 400 aunque el handler nunca asignó un status:
para estos dos errores de request el status por defecto es el suyo propio
(400, 415) en lugar de 500.
Los errores de validación se responden justo donde ocurren, así que el
middleware que envuelve la ruta — CORS, logging de requests — sigue viendo una
respuesta normal después de await next(). Cualquier otro error lanzado
atraviesa primero ese middleware.
Devolver nada declina el error
onError() maneja un error devolviendo un valor o una Response. Si no
devuelve nada, se aplica en su lugar el comportamiento por defecto de Arcton:
un error de validación responde 400 con el body de issues,
un Content-Type no soportado responde un 415 vacío, y cualquier otro error
se propaga al adapter exactamente como con ningún handler registrado. Eso
hace de onError() un buen lugar para loguear todo y quedarte solo con las
respuestas que te interesan.
También corre para el fallback de 404/405
El middleware global corre incluso cuando nada
matchea el request, así que onError() también cubre un throw ahí:
import { Arcton } from '@arcton/core'
declare function logRequest(request: Request): void
const app = Arcton()
app.use(async (ctx, next) => {
logRequest(ctx.request) // lanza un error si el logger está caído
await next()
})
app.onError((err, ctx) => ({ error: 'Something went wrong' }))
app.listen()Es un único handler, a nivel de la app completa
Solo existe un handler de onError() por app — registrar uno nuevo
reemplaza al anterior — y solo se consulta el de la instancia cuyo propio
listen() termina sirviendo el request. Si construyes parte de tu app como
un módulo separado y lo montas con app.use(módulo), un onError()
registrado en ese módulo no tiene ningún efecto; los módulos componen
rutas, middleware y providers dentro de la app que los monta, no un límite
de errores independiente.
Para un límite acotado a una sola sección de la app, envuelve next() en un
try/catch dentro de un middleware con scope — ver
Capturar un error lanzado dentro de un middleware.
Los dos se combinan bien: un try/catch con scope maneja lo que reconoce y
relanza el resto, que entonces llega a onError() como el catch-all final.
Si el propio handler de onError() lanza un error, ese error no vuelve a
pasarle por su cuenta — se propaga de la misma forma en que lo haría un
error no capturado sin ningún handler registrado.