Tipos de middleware
Los tipos de función detrás del middleware global, del middleware con scope y del route middleware, más los tipos internos de matching del router
Un Middleware es simplemente una función — sin clase, sin decorador, nada más que pasarla a app.use() o a una ruta:
import type { Middleware } from '@arcton/contracts'
import { Arcton } from '@arcton/core'
const logger: Middleware = async (ctx, next) => {
console.log(ctx.request.method, ctx.request.url)
await next()
}
const app = Arcton()
app.use(logger)
app.get('/', () => 'ok')
app.listen()Middleware
Propósito: la forma de toda función de middleware — global, con scope, o route middleware.
Firma
import type { Body, Context, NextFunction, QueryParams, RouteParams } from '@arcton/contracts'
type Middleware<P = RouteParams, Q = QueryParams, TBody = {}, TProvided = {}> = (
ctx: Context<P, Q, TBody, TProvided>,
next: NextFunction
) => Promise<Body | void> | Body | voidComportamiento: el orden de los parámetros genéricos — P, Q, TBody, TProvided — es estructural: coincide con el propio orden de Context. El código antes de await next() corre de ida; el código después corre de vuelta. Retornar un valor sin llamar a next() corta la cadena del pipeline — nada más abajo se ejecuta. Ver Orden de ejecución.
NextFunction
Propósito: avanza el pipeline al siguiente step.
Firma
type NextFunction = () => Promise<void>Comportamiento: llama al siguiente middleware (o al handler, si no queda ninguno) y se resuelve una vez que todo lo que sigue haya terminado.
RouteHandler
Propósito: la forma del handler final de una ruta.
Firma
import type { Body, Context, QueryParams, RouteParams } from '@arcton/contracts'
type RouteHandler<P = RouteParams, Q = QueryParams, TBody = {}, TProvided = {}> = (
ctx: Context<P, Q, TBody, TProvided>
) => (Body | void) | Promise<Body | void>Comportamiento: la misma forma que Middleware, sin next — un handler siempre corre al final, así que no tiene nada que llamar. Este es el tipo del argumento final de get/post/etc. y de RouteOptions.handler.
ErrorHandler
Propósito: la forma del handler que recibe app.onError().
Firma
import type { Body, Context, QueryParams, RouteParams } from '@arcton/contracts'
type ErrorHandler<P = RouteParams, Q = QueryParams, TBody = {}, TProvided = {}> = (
err: unknown,
ctx: Context<P, Q, TBody, TProvided>
) => (Body | void) | Promise<Body | void>Comportamiento: la misma forma que RouteHandler, con el error capturado como primer argumento. err es unknown, no Error — un valor lanzado en JavaScript no tiene por qué serlo. Ver Global error handler.
MatchResult
Propósito: el resultado de hacer match entre un método y un path contra el árbol de rutas.
Firma
import type { HttpMethod, RouteHandler, RouteParams } from '@arcton/contracts'
type MatchResult =
| { matched: true; handler: RouteHandler; params: RouteParams }
| { notFound: true }
| { methodNotAllowed: true; allowed: HttpMethod[] }Comportamiento: el valor de retorno de Router.match(), descrito a continuación. El código de la aplicación no construye ni lee esto directamente — se expone para quien implemente un RuntimeAdapter personalizado.
Router
Propósito: la interfaz interna que usa ArctonApp para resolver una request a un handler.
Firma
import type { HttpMethod, MatchResult } from '@arcton/contracts'
interface Router {
match(method: HttpMethod, url: string): MatchResult
}Comportamiento: ver Precedencia para las reglas de matching — static le gana a dynamic, que le gana a wildcard, con backtracking.
ReservedKeys
Propósito: las keys que provide() rechaza agregar.
Firma
import type { BaseContext } from '@arcton/contracts'
type ReservedKeys<TProvided> =
| keyof BaseContext
| 'body'
| 'contentType'
| keyof TProvidedComportamiento: cubre los campos base de Context (request/params/query/response), 'body', 'contentType', y cualquier key ya provista antes en la cadena. Volver a proveer una de estas es un error de compilación, no uno de runtime.
ProvideFn
Propósito: la forma de función que se pasa a app.provide().
Firma
import type { Context, QueryParams, RouteParams } from '@arcton/contracts'
type ProvideFn<TProvided, R extends Record<string, unknown>> = (
ctx: Context<RouteParams, QueryParams, {}, TProvided>
) => R | Promise<R>Comportamiento: corre antes de la validación a nivel de ruta, así que solo ve los valores por defecto crudos de params/query — nunca el output del schema de una ruta. Su valor de retorno, R, se fusiona de forma plana sobre ctx. Ver Providers.