ArctonArcton
API Reference

Context

The object passed to every handler, provider, and middleware function

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/users/:id', ctx => {
  return { id: ctx.params.id, page: ctx.query.page ?? '1' }
})

app.listen()

Every handler, provider, and middleware function receives a Context as its first argument (middleware also gets a next). This page is the type reference; see Context for the concept-first guide.

Context

Purpose: the full shape of ctx at a given point in the pipeline.

Signature

import type { BaseContext, QueryParams, RouteParams } from '@arcton/contracts'

type Context<P = RouteParams, Q = QueryParams, TBody = {}, TProvided = {}> =
  BaseContext<P, Q> & TBody & TProvided

Parameters

Prop

Type

Behavior: provided values sit flat on ctx — there is no namespace. params is inferred from the route literal passed to get/post/etc.: '/users/:id' gives { id: string }, a route with no params gives Record<string, never>, and a path passed as a non-literal string variable gives Record<string, string>. query is Record<string, string> by default, built lazily on first access — repeated keys keep the last value, and a key with no value reads as ''.

BaseContext

Purpose: the fields present on every Context, regardless of what's been provided or validated.

Signature

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

interface BaseContext<P, Q> {
  request: Request
  params: P
  query: Q
  response: ResponseContext
}

Behavior: request is the raw, unmodified Request. response is described below.

ResponseContext

Purpose: the mutable response state available before a body finalizes.

Signature

interface ResponseContext {
  status?: number
  headers: Headers
}

Behavior: ctx.response starts out as this plain object and is materialized into a real Response the moment a body finalizes at any layer (the handler returns, a step short-circuits, or a layer replaces the body after next()). Before materialization, ctx.response.status can be assigned directly. After materialization, header mutation still works and reaches the client, but status no longer accepts assignment. See Response.

Set ctx.response.status from the handler, or from middleware before calling await next(). Setting it afterward throws, because by then the body has already materialized into a real Response.

RouteParams

Purpose: the default shape of ctx.params for a route with no params schema.

Signature

type RouteParams = Record<string, string>

QueryParams

Purpose: the default shape of ctx.query for a route with no query schema.

Signature

type QueryParams = Record<string, string>

Body

Purpose: the union of values a handler or middleware may return.

Signature

type Body =
  | object
  | string
  | ArrayBufferView
  | ArrayBuffer
  | Blob
  | FormData
  | URLSearchParams
  | ReadableStream
  | Response

Behavior: each variant maps to a different HTTP response — see Response for the full mapping table, including how status and headers are derived for each case.

On this page