ArctonArcton
Referencia de la API

ArctonApp

La interfaz que devuelve Arcton() — la superficie sobre la que registras rutas, middleware y providers

Todo método de registro en ArctonApp devuelve la app misma, por lo que las llamadas se encadenan:

import { Arcton } from '@arcton/core'

const app = Arcton()

app
  .get('/', () => 'Hello, Arcton!')
  .get('/health', () => ({ status: 'ok' }))

app.listen()

config contiene exactamente el objeto ArctonConfig pasado a Arcton():

import type { ArctonConfig } from '@arcton/core'

interface ArctonApp<TProvided = {}> {
  config: ArctonConfig
  // ...
}

get, post, put, delete, patch, head, options

Propósito: registra una ruta para un método HTTP. Las siete abreviaturas comparten las mismas dos formas de llamada — solo cambia el método.

Firma

import type { Middleware, RouteHandler, StandardSchemaV1 } from '@arcton/contracts'
import type { ArctonApp, RouteOptions } from '@arcton/core'

interface RouteMethod<TProvided> {
  <Route extends string>(
    path: Route,
    ...args: [...Middleware[], RouteHandler]
  ): ArctonApp<TProvided>
  <
    Route extends string,
    PSchema extends StandardSchemaV1 | undefined = undefined,
    QSchema extends StandardSchemaV1 | undefined = undefined,
    BSchema extends StandardSchemaV1 | undefined = undefined
  >(
    path: Route,
    options: RouteOptions<Route, TProvided, PSchema, QSchema, BSchema>
  ): ArctonApp<TProvided>
}

Parámetros

Propiedad

Tipo

Tipo de retorno: ArctonApp<TProvided> — la misma instancia, para encadenar llamadas.

Comportamiento: en la primera forma de llamada, el argumento path tipa ctx.params automáticamente a partir del literal de la ruta ('/users/:id' da { id: string }) — ver Context. La segunda forma de llamada (RouteOptions) además valida params/query/body contra un schema antes de ejecutar el handler — ver Tipos de validación.

Errores: registrar el mismo (method, path) dos veces lanza Duplicate route: <METHOD> <path> is already registered. Ver Errores de registro.

Ejemplo

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/users/:id', ctx => ({ id: ctx.params.id }))

app.post('/users/:id/orders', {
  handler: ctx => ({ userId: ctx.params.id })
})

app.listen()

all

Propósito: registra una ruta que matchea con todos los métodos HTTP que soporta Arcton — los mismos siete que get/post/etc. arriba, no un comodín para verbos arbitrarios o no estándar.

Firma: idéntica a RouteMethod<TProvided> de arriba — las mismas dos formas de llamada, los mismos genéricos.

Tipo de retorno: ArctonApp<TProvided>.

Comportamiento: registra el mismo handler para GET, POST, PUT, DELETE, PATCH, HEAD y OPTIONS en el path dado, en una sola llamada. Útil para delegar un path completo a un handler externo de Request/Response. Ver Métodos HTTP.

Errores: comparte un mismo handler entre todos los métodos de ese path — registrar un método específico en el mismo path después (o antes) tira el mismo error de "Duplicate route" que registrar ese método dos veces. Ver Registration errors.

Ejemplo

import { Arcton } from '@arcton/core'

declare const auth: { handler: (request: Request) => Promise<Response> }

const app = Arcton()

app.all('/api/auth/*path', ctx => auth.handler(ctx.request))

app.listen()

RouteOptions

Propósito: el objeto de opciones aceptado por la segunda forma de llamada de get/post/etc., para rutas que necesitan validación de la request.

Firma

import type { Middleware, RouteDetail, RouteHandler } from '@arcton/contracts'
import type { ResponseSchemas } from '@arcton/core'

interface RouteOptions<Route, TProvided, PSchema, QSchema, BSchema> {
  params?: PSchema
  query?: QSchema
  body?: BSchema
  response?: ResponseSchemas
  detail?: RouteDetail
  middleware?: Middleware[]
  handler: RouteHandler
}

Parámetros

Propiedad

Tipo

Comportamiento: la validación se ejecuta en el orden params → query → body; el primer fallo corta la cadena de inmediato con un 400. La salida del schema reemplaza el campo correspondiente de ctx. ctx.body solo existe (y solo pasa el chequeo de tipos) en una ruta que declara body; con optional: true, una request sin body se salta la validación y ctx.body es undefined (tipado Output | undefined) — ver Bodies opcionales. Con content, solo se aceptan los media types listados (415 en otro caso) y ctx.contentType guarda el que coincidió — ver Aceptar media types específicos. Ver Tipos de validación y Errores de validación.

response y detail son solo documentación — ver ResponseSchemas y RouteDetail más abajo. Ninguno de los dos lo lee el pipeline de requests: un handler que devuelve algo distinto de lo que declara response responde exactamente igual que si response no existiera (ver Response para lo que sí determina la respuesta). Ambos se leen a través de routesOf() desde cualquier cosa que documente o inspeccione una app — ver OpenAPI & Scalar.

Ejemplo

import { Arcton } from '@arcton/core'
import * as v from 'valibot'

const app = Arcton()

app.post('/users/:id/orders', {
  params: v.object({ id: v.string() }),
  body: v.object({ item: v.string() }),
  handler: ctx => ({ userId: ctx.params.id, item: ctx.body.item })
})

app.listen()

ResponseSchemas

Propósito — la forma que acepta RouteOptions.response.

Firma

import type { StandardSchemaV1 } from '@arcton/contracts'

type ResponseSchemas = StandardSchemaV1 | Record<number, StandardSchemaV1>

Comportamiento: un StandardSchemaV1 suelto es un atajo para { 200: schema } — ambas formas se distinguen en runtime comprobando la key '~standard', ya que un mapa de status → schema nunca la tiene. En cualquier caso, se normaliza a Record<number, StandardSchemaV1> antes de llegar a RouteRecord.response.

Ejemplo

import { Arcton } from '@arcton/core'
import * as v from 'valibot'

const app = Arcton()

// atajo de { response: { 200: UserSchema } }
app.get('/users/:id', {
  response: v.object({ id: v.string() }),
  handler: ctx => ({ id: ctx.params.id })
})

app.get('/orders/:id', {
  response: {
    200: v.object({ id: v.string() }),
    404: v.object({ message: v.string() })
  },
  handler: ctx => ({ id: ctx.params.id })
})

app.listen()

RouteDetail

Propósito — la metadata de documentación que acepta RouteOptions.detail.

Firma

interface RouteDetail {
  operationId?: string
  summary?: string
  description?: string
  tags?: string[]
  deprecated?: boolean
}

Parámetros

Propiedad

Tipo

Comportamiento: cada campo es solo documentación — ninguno cambia cómo se matchea, valida o maneja un request. Los cinco se mapean directamente a los campos del mismo nombre de una operación de OpenAPI — ver OpenAPI & Scalar.

Ejemplo

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/users/:id', {
  detail: {
    operationId: 'getUser',
    summary: 'Get user',
    tags: ['Users']
  },
  handler: ctx => ({ id: ctx.params.id })
})

app.listen()

ws

Propósito: registra una ruta de WebSocket.

Firma

import type { RuntimeWebSocketHandler } from '@arcton/contracts'
import type { ArctonApp } from '@arcton/core'

declare function ws<TProvided>(
  path: string,
  handler: RuntimeWebSocketHandler
): ArctonApp<TProvided>

Parámetros: path — se compara exactamente, sin segmentos :param/*wildcard. handler — un RuntimeWebSocketHandler.

Tipo de retorno: ArctonApp<TProvided>.

Comportamiento: las rutas ws se comparan por path exacto y no pasan por context, middleware ni providers. Ver WebSockets para la guía completa.

Ejemplo

import { Arcton } from '@arcton/core'

const app = Arcton()

app.ws('/chat', {
  message(ws, message) {
    ws.send(`echo: ${message}`)
  }
})

app.listen()

use

Propósito: registra middleware global, middleware con scope, o monta un module. Tres overloads, distinguidos por los argumentos que se pasan.

Firma

import type { Middleware } from '@arcton/contracts'
import type { ArctonApp } from '@arcton/core'

declare function use<TProvided>(middleware: Middleware): ArctonApp<TProvided>
declare function use<TProvided>(scope: string, middleware: Middleware): ArctonApp<TProvided>
declare function use<TProvided, M>(app: ArctonApp<M>): ArctonApp<TProvided>

Parámetros: middleware — una función Middleware. scope — una ruta estática; el middleware solo se aplica a las rutas en esa ruta o debajo de ella. app — otra instancia de ArctonApp para montar como module.

Tipo de retorno: ArctonApp<TProvided>.

Comportamiento:

  • use(middleware) registra middleware global — ver Middleware global.
  • use(scope, middleware) se selecciona por ruta en el momento del registro, comparando el path propio de la ruta contra scope — ver Middleware con scope.
  • use(module) fusiona el árbol de rutas ya construido del module dentro del árbol de esta app, en el momento del registro — ver Modules.

Errores: un argumento objeto que no sea un ArctonApp lanza use() expects a middleware function, a (scope, middleware) pair, or an Arcton app to mount. Un scope no estático lanza el mismo error de "must be a static path" que un ArctonConfig.prefix no estático. Ver Errores de registro.

Ejemplo

import { Arcton } from '@arcton/core'

const users = Arcton({ prefix: '/users' })
users.get('/:id', ctx => ({ id: ctx.params.id }))

const app = Arcton()

app.use(async (ctx, next) => {
  await next()
})

app.use('/users', async (ctx, next) => {
  await next()
})

app.use(users)

app.listen()

provide

Propósito: compone contexto tipado sobre ctx, de forma plana, para cada middleware y handler registrado después.

Firma

import type { ProvideFn, ReservedKeys } from '@arcton/contracts'
import type { ArctonApp } from '@arcton/core'

declare function provide<
  TProvided,
  R extends Partial<Record<ReservedKeys<TProvided>, never>> & Record<string, unknown>
>(fn: ProvideFn<TProvided, R>): ArctonApp<TProvided & R>

Parámetros: fn — una ProvideFn que devuelve el objeto a fusionar sobre ctx.

Tipo de retorno: ArctonApp<TProvided & R> — la app, con su tipo de contexto provisto ampliado por R.

Comportamiento: ver Providers para la guía completa.

Errores: volver a proveer una key que ya está en TProvided, o una de request/params/query/response/body/contentType, es un error de compilación (vía ReservedKeys) — no lanza una excepción en runtime.

Ejemplo

import { Arcton } from '@arcton/core'

const app = Arcton()

app
  .provide(() => ({ db: { query: async () => [] as unknown[] } }))
  .get('/users', async ctx => ctx.db.query())

app.listen()

parser

Propósito: registra un body parser personalizado para un media type exacto.

Firma

import type { BodyParser } from '@arcton/contracts'
import type { ArctonApp } from '@arcton/core'

declare function parser<TProvided>(
  mediaType: string,
  parser: BodyParser
): ArctonApp<TProvided>

Parámetros: mediaType — se compara sin distinguir mayúsculas de minúsculas, ignorando parámetros como ; charset=. parser — un BodyParser.

Tipo de retorno: ArctonApp<TProvided>.

Comportamiento: reemplaza un parser incorporado para el mismo media type, si existe uno. Registrar el mismo media type de nuevo reemplaza al parser anterior — es una tabla plana sin orden ni semántica de snapshot, a diferencia de use()/provide(). Solo se consulta para una ruta que declara un schema body, y registrar un parser no hace que una ruta acepte su media type — hay que listarlo en body.content. Ver Body parsers.

Ejemplo

import { Arcton } from '@arcton/core'

const app = Arcton()

app.parser('text/csv', async request => {
  const text = await request.text()
  return text.trim().split('\n')
})

app.listen()

onError

Propósito: registra un handler para un error que de otro modo quedaría sin capturar — de un provider, un middleware, la validación, o el propio handler de la ruta.

Firma

import type { ErrorHandler, QueryParams, RouteParams } from '@arcton/contracts'
import type { ArctonApp } from '@arcton/core'

declare function onError<TProvided>(
  handler: ErrorHandler<RouteParams, QueryParams, {}, TProvided>
): ArctonApp<TProvided>

Parámetros: handler — un ErrorHandler.

Tipo de retorno: ArctonApp<TProvided>.

Comportamiento: solo un handler a la vez — una llamada posterior reemplaza a la anterior — y solo se consulta el de la instancia cuyo propio listen() termina sirviendo el request; uno registrado en un módulo montado con use() no tiene ningún efecto. Devolver un valor o una Response maneja el error; no devolver nada lo declina, y se aplica el comportamiento por defecto de Arcton (400/415 para un ValidationError o un Content-Type de body no soportado; en cualquier otro caso el error se propaga al adapter). ctx.response.status usa 500 por defecto (400/415 para esos dos errores de request) si el handler no asigna uno, sin sobrescribir un status que algún paso ya haya asignado antes del throw. Si el propio handler lanza un error, ese error se propaga de la misma forma en que lo haría un error no capturado sin ningún handler registrado. Sin onError(), un error no capturado se sigue propagando al adapter del runtime tal como describe Errores no capturados — esto es opt-in. Ver Global error handler para la guía completa.

Ejemplo

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()

listen

Propósito: comienza a atender requests.

Firma

import type { ArctonListenOptions } from '@arcton/core'
import type { RuntimeServer } from '@arcton/contracts'

declare function listen(options?: ArctonListenOptions): RuntimeServer

Comportamiento: ver listen() para la referencia completa, incluyendo el RuntimeServer devuelto.

routesOf()

Propósito: la vista de solo lectura de cada ruta registrada en una app — los schemas y la metadata que declaró cada una, y su path final (con prefijo). Lo que permite que un paquete fuera de @arcton/core — @arcton/openapi, o cualquier otra cosa que documente o inspeccione una app — vea los contratos de las rutas sin que la app exponga directamente su router o su pipeline.

Firma

import type { RouteRecord } from '@arcton/contracts'
import type { ArctonApp } from '@arcton/core'

declare function routesOf<T>(app: ArctonApp<T>): readonly RouteRecord[]

Parámetros: app — cualquier instancia de ArctonApp, montada o no.

Tipo de retorno: readonly RouteRecord[] — ver RouteRecord.

Comportamiento: un record por cada método bajo el que se registró una ruta — app.all() produce siete, nunca un record de "cualquier método" — en el orden de registro, cada uno con su path final (con todo prefijo de montaje ya aplicado). Los records propios de un module se incluyen una vez que se monta con use(), con el mismo prefijo que su árbol de rutas; llamar a routesOf() sobre el module mismo sigue devolviendo sus records solo con su propio prefijo, sin verse afectado por dónde termine montándose. Una ruta ws() no produce ningún record, al no tener contrato que describir. Las respuestas que da un middleware openapi() nunca se incluyen, así que un documento nunca se documenta a sí mismo.

Errores: lanza routesOf() expects an Arcton app para cualquier cosa que no sea una.

Ejemplo

import { Arcton, routesOf } from '@arcton/core'
import * as v from 'valibot'

const app = Arcton()

app.get('/users/:id', {
  params: v.object({ id: v.string() }),
  handler: ctx => ({ id: ctx.params.id })
})

for (const route of routesOf(app)) {
  console.log(route.method, route.path)
}
// GET /users/:id

HttpMethod

Propósito: la unión de métodos HTTP a la que corresponden las abreviaturas de rutas de ArctonApp.

Firma

type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS'

Comportamiento: se usa en cualquier lugar donde un método necesite nombrarse fuera de llamar directamente a app.get/app.post/etc. — por ejemplo, el header Allow en una respuesta 405 lista los HttpMethod que sí soporta la ruta encontrada. Ver Métodos HTTP.

En esta página