Middleware Types
The function types behind global, scoped, and route middleware, plus the router's internal matching types
A Middleware is a plain function — no class, no decorator, nothing beyond passing it to app.use() or a route:
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
Purpose: the shape of every global, scoped, and route middleware function.
Signature
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 | voidBehavior: the generic parameter order — P, Q, TBody, TProvided — is load-bearing: it matches Context's own order. Code before await next() runs on the way in; code after runs on the way out. Returning a value without calling next() short-circuits the pipeline — nothing downstream runs. See Execution order.
NextFunction
Purpose: advances the pipeline to the next step.
Signature
type NextFunction = () => Promise<void>Behavior: calls the next middleware (or the handler, if there is none left) and resolves once everything downstream has finished.
RouteHandler
Purpose: the shape of a route's final handler.
Signature
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>Behavior: the same shape as Middleware, minus next — a handler always runs last, so it has nothing to call. This is the type of the trailing argument to get/post/etc. and of RouteOptions.handler.
ErrorHandler
Purpose: the shape of the handler passed to app.onError().
Signature
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>Behavior: the same shape as RouteHandler, with the caught error prepended as the first argument. err is unknown, not Error — a thrown value in JavaScript isn't guaranteed to be one. See Global error handler.
MatchResult
Purpose: the result of matching a method and path against the route tree.
Signature
import type { HttpMethod, RouteHandler, RouteParams } from '@arcton/contracts'
type MatchResult =
| { matched: true; handler: RouteHandler; params: RouteParams }
| { notFound: true }
| { methodNotAllowed: true; allowed: HttpMethod[] }Behavior: Router.match()'s return value, described next. Application code doesn't construct or read this directly — it's exposed for anyone implementing a custom RuntimeAdapter.
Router
Purpose: the internal interface ArctonApp uses to resolve a request to a handler.
Signature
import type { HttpMethod, MatchResult } from '@arcton/contracts'
interface Router {
match(method: HttpMethod, url: string): MatchResult
}Behavior: see Precedence for the matching rules — static beats dynamic beats wildcard, with backtracking.
ReservedKeys
Purpose: the keys provide() refuses to add.
Signature
import type { BaseContext } from '@arcton/contracts'
type ReservedKeys<TProvided> =
| keyof BaseContext
| 'body'
| 'contentType'
| keyof TProvidedBehavior: covers the base Context fields (request/params/query/response), 'body', 'contentType', and any key already provided earlier in the chain. Re-providing one of these is a compile error, not a runtime one.
ProvideFn
Purpose: the function shape passed to app.provide().
Signature
import type { Context, QueryParams, RouteParams } from '@arcton/contracts'
type ProvideFn<TProvided, R extends Record<string, unknown>> = (
ctx: Context<RouteParams, QueryParams, {}, TProvided>
) => R | Promise<R>Behavior: runs before route-level validation, so it only ever sees the raw params/query defaults — never a route's schema output. Its return value, R, is merged flat onto ctx. See Providers.