ArctonArcton
Referencia de la API

HTTP Errors

HttpError y las factories de status Http listas para lanzar, de @arcton/core.

Resumen

Lanzá un error ya armado en vez de construir a mano ctx.response.status = ...; return {...} en cada lugar donde una request puede fallar:

import { Arcton, Http } 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.listen()

Por sí solo esto sigue siendo un error no capturado — convertirlo en una respuesta queda de tu lado, igual que con cualquier otro throw. Ver Respondiendo con errores para el patrón try/catch que mapea status/code/body de HttpError sobre ctx.response.

HttpError

Propósito — la clase de error que retorna cada factory de Http de abajo; se instancia directamente para un status sin factory con nombre.

Firma

class HttpError extends Error {
  constructor(status: number, code: string, message: string, body?: unknown)
  readonly status: number
  readonly code: string
  readonly body?: unknown
}

Parámetros

ParámetroTipoDescripción
statusnumberEl status HTTP, por ejemplo 451.
codestringUna etiqueta estable y legible por máquina, por ejemplo 'UNAVAILABLE_FOR_LEGAL_REASONS'. Segura para que un cliente haga switch sobre ella, a diferencia de message.
messagestringSe pasa al message propio de Error.
bodyunknownOpcional. El valor exacto que un catch debería devolver en vez del shape default { code, message }.

Comportamiento — HttpError lleva estos campos pero no hace nada con ellos por sí sola; nada en el pipeline de Arcton captura un HttpError automáticamente (ver Errores no capturados).

Ejemplo

import { HttpError } from '@arcton/core'

throw new HttpError(451, 'UNAVAILABLE_FOR_LEGAL_REASONS', 'Unavailable For Legal Reasons')

Http

Propósito — un namespace de atajos listos para lanzar, uno por cada status común. Cada uno es una función simple — se llama, no se instancia con new — y retorna un HttpError.

Firma

type StatusErrorFactory = (message?: string, body?: unknown) => HttpError

const Http: Record<string, StatusErrorFactory>

Parámetros

ParámetroTipoDescripción
messagestringOpcional. Por default usa la frase de razón del status (ver la tabla de abajo).
bodyunknownOpcional. El valor exacto que un catch debería devolver en vez del shape default { code, message }.

Tipo de retorno — un HttpError.

Factories

FactoryStatuscodemessage por default
Http.BadRequest400'BAD_REQUEST'Bad Request
Http.Unauthorized401'UNAUTHORIZED'Unauthorized
Http.Forbidden403'FORBIDDEN'Forbidden
Http.NotFound404'NOT_FOUND'Not Found
Http.MethodNotAllowed405'METHOD_NOT_ALLOWED'Method Not Allowed
Http.Conflict409'CONFLICT'Conflict
Http.Gone410'GONE'Gone
Http.UnprocessableEntity422'UNPROCESSABLE_ENTITY'Unprocessable Entity
Http.TooManyRequests429'TOO_MANY_REQUESTS'Too Many Requests
Http.InternalServerError500'INTERNAL_SERVER_ERROR'Internal Server Error
Http.ServiceUnavailable503'SERVICE_UNAVAILABLE'Service Unavailable

throw Http.NotFound — la referencia a la función pelada, sin () — lanza la función misma, no un HttpError. Un bloque catch que chequea instanceof HttpError no la va a reconocer, y llega al adapter como un 500 sin diferenciar. Siempre hay que llamar a la factory.

Ejemplo

import { Http } from '@arcton/core'

throw Http.Conflict('Email already registered', { field: 'email' })

ValidationError

Propósito — el error que Arcton lanza cuando falla un esquema de params, query o body (o no se puede interpretar el body). Llega a app.onError() como cualquier otro error.

Firma

class ValidationError extends HttpError {
  constructor(issues: ReadonlyArray<StandardSchemaV1.Issue>)
  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>
}

Comportamiento — status es 400, code es 'VALIDATION_FAILED' y body es { issues }. issues es exactamente el array que devolvió la librería de esquemas, sin modificar. Sin onError() (o con uno que no devuelve nada), responde 400 con { "issues": [...] }. Ver Errores de validación.

Ejemplo

import { Arcton, ValidationError } from '@arcton/core'

const app = Arcton()

app.onError(err => {
  if (err instanceof ValidationError) return { issues: err.issues }
})

En esta página