ArctonArcton
Fundamentals

Response

How a handler's return value becomes an HTTP response, and how to shape status, headers, and cookies.

A handler returns whatever the response should contain, and Arcton maps it to a Response:

import { Arcton } from '@arcton/core'

const app = Arcton()

app.get('/json', () => ({ ok: true }))
app.get('/text', () => 'plain text')
app.get('/bytes', () => new Uint8Array([1, 2, 3]))
app.get('/raw', () => new Response('custom', { status: 202 }))

app.listen()

The full mapping

ReturnedBodyInferred Content-Type
Responsepassed through as-is; ctx.response is ignored entirely—
stringthe stringtext/plain; charset=UTF-8
plain object or arrayJSON.stringify(...)application/json; charset=UTF-8
Blobthe blobblob.type, or application/octet-stream when empty
FormDatathe form datanone — an explicit Content-Type is removed so the runtime can generate its own multipart boundary
URLSearchParamsthe paramsnone inferred (the runtime sets application/x-www-form-urlencoded;charset=UTF-8)
ArrayBuffer, or any view of one (Uint8Array, Int32Array, DataView, Node Buffer)the bytesapplication/octet-stream
ReadableStreamstreamedapplication/octet-stream
null, undefined, or no returnemptynone

An explicit ctx.response.headers.set('Content-Type', ...) always wins over the inferred one, with one exception:

Returning FormData drops any Content-Type you set yourself — Arcton removes it so the runtime can generate its own multipart/form-data; boundary=... header. Set other headers freely; the boundary has to come from the runtime.

Map and Set aren't handled specially — they fall into the plain-object branch, and JSON.stringify serializes them as {}. Return an array or plain object built from their entries instead, e.g. Object.fromEntries(myMap) or [...mySet].

Status

ctx.response.status sets the status; it defaults to 200. A status outside 200–599 throws Invalid response status N: must be between 200 and 599.

import { Arcton } from '@arcton/core'

const app = Arcton()

app.post('/users', ctx => {
  ctx.response.status = 201
  ctx.response.headers.set('Location', '/users/1')
  return { id: '1' }
})

app.listen()

Set ctx.response.status before the response materializes — in the handler, or before calling await next() in middleware. Setting it afterward throws, because by then it's already part of a real Response, whose status can't be reassigned.

204, 205 and 304 force an empty body: an inferred Content-Type is dropped, but a Content-Type you set explicitly survives.

import { Arcton } from '@arcton/core'

const app = Arcton()

app.delete('/users/:id', ctx => {
  ctx.response.status = 204
})

app.listen()

Setting cookies

ctx.response.headers is a real Headers object — .append('Set-Cookie', ...) adds a cookie without clobbering ones already set, so multiple cookies work by calling it more than once. This works whether you do it in the handler or in middleware after await next():

import { Arcton } from '@arcton/core'

const app = Arcton()

app.use(async (ctx, next) => {
  await next()
  ctx.response.headers.append('Set-Cookie', 'theme=dark; Path=/')
  ctx.response.headers.append('Set-Cookie', 'session=abc123; HttpOnly; Path=/')
})

app.get('/', () => ({ ok: true }))

app.listen()

Header mutation after await next() reaching the client this way — and status only being settable before that point — comes from how ctx.response materializes into a real response as the pipeline unwinds. See Request Lifecycle and Modifying Responses for that mechanism.

On this page