ArctonArcton
API Reference

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 | void

Behavior: 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 TProvided

Behavior: 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.

On this page