ArctonArcton
Arquitectura

Runtime Abstraction

Por qué los tipos de runtime viven en su propio paquete, y qué le compra eso al core, a los adapters y a tu aplicación.

@arcton/contracts contiene tipos y nada más. Ninguna función, ninguna clase, ningún código de runtime. Cada otro paquete depende de él, y él no depende de nada.

@arcton/core ──┐
               ├──→ @arcton/contracts
@arcton/adapter-bun ──┤
@arcton/adapter-node ─┤
@arcton/cors ─────────┘

Por qué un paquete separado

El core necesita describir qué espera de un runtime. Un adapter necesita implementar exactamente eso. Si cualquiera de los dos lados fuera dueño de la descripción, el otro tendría que depender de él — y un adapter dependiendo del core, o el core dependiendo de cada adapter, es un ciclo esperando a formarse.

Poner el vocabulario en un paquete que no depende de nada rompe el ciclo. El core está escrito contra RuntimeAdapter, cada adapter implementa RuntimeAdapter, y ninguno de los dos sabe que el otro existe. Eso es lo que hace que el adapter por default se pueda reemplazar pasando una sola opción.

Tiene un segundo efecto: como el paquete solo tiene tipos, desaparece en tiempo de build. Depender del vocabulario compartido no cuesta nada en runtime.

Qué vive ahí

Dos grupos de tipos.

El contrato de runtime — RuntimeAdapter, RuntimeServer, RuntimeServeOptions, RuntimeHandler, RuntimeCapabilities, RuntimeRequestContext, y los tipos de WebSocket. Estos describen un servidor, y son lo que un adapter implementa.

El vocabulario de la aplicación — Context, Middleware, RouteHandler, NextFunction, ProvideFn, BodyParser, Body, HttpMethod, StandardSchemaV1 y compañía. Estos describen las cosas que escribe tu código.

Ambos grupos están en el mismo paquete porque ambos son compartidos: @arcton/cors necesita Middleware y Context sin necesitar el core, y lo mismo cualquier middleware que publiques tú mismo.

Por qué la interfaz es la plataforma web

El contrato está construido sobre Request, Response, Headers y ReadableStream en vez de sobre un objeto de request específico de Arcton.

Esos tipos ya existen en cada runtime objetivo, están especificados de forma independiente, y los desarrolladores ya los conocen. Un wrapper específico del framework agregaría una capa que aprender, una capa que mantener sincronizada con la plataforma, y una conversión en cada límite — a cambio de muy poco. Así que ctx.request es un Request real, y todo lo que sabes sobre la Fetch API aplica.

El único lugar donde Arcton agrega su propia forma es la respuesta, donde ctx.response guarda un status y headers que siguen siendo mutables. Un Response real es inmutable en las formas en que el middleware necesita cambiarlo, así que el pipeline mantiene un objeto mutable de staging y lo materializa — ver Pipeline.

Standard Schema, por la misma razón

La validation sigue el mismo principio. En vez de traer su propio validador o depender de uno, Arcton acepta cualquier schema que implemente Standard Schema — la interfaz que implementan Zod, Valibot y ArkType.

El framework nunca importa una librería de validación, a los usuarios no se los obliga a usar la favorita del mantenedor, y un proyecto que ya usa una sigue usándola. La interfaz es tan chica que StandardSchemaV1 está declarada en contracts junto con todo lo demás, así que ni siquiera eso es una dependencia.

Qué significa esto para tu código

Tipar un middleware o handler independiente significa importar desde contracts:

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

export const requestId: Middleware = async (ctx, next) => {
  ctx.response.headers.set('X-Request-Id', crypto.randomUUID())
  await next()
}

Como el paquete es solo-tipos, ese import desaparece del output del build.

En esta página