Overview

This section covers what Flare sends back: permitted handler return types, how values become bytes, and response-shaping features on FlareHttpContext.

Topic	Page
Return types and FlareResponse	This page (below)
Cookies	Cookies
Signed cookies	Signed cookies
Streaming bodies	Streaming bodies
Server-sent events	Server-sent events

For reading the inbound request, see Requests.

HandlerResult

Handlers may return:

Return	Client outcome
FlareResponse	Your status, headers, and body
Web Response	Pass-through for fetch interop
Plain object or array	Wrapped as 200 JSON
AsyncIterable	200 chunked stream
null / undefined	Throws (handler bug)
Returned Error instance	Re-thrown; use throw to reach error handlers

A plain object return is always 200. For other statuses, return FlareResponse, a controller helper (this.notFound(body)), or set status explicitly.

FlareResponse

import { FlareHost, FlareResponse } from "@flare-ts/core";
import { node } from "@flare-ts/core/node";

const host = new FlareHost(node);

host.http.get("/me", () => {
  const res = new FlareResponse(200, { id: "u1" });
  res.headers["cache-control"] = "no-store";
  return res;
});

const app = host.build();
app.run();

Field	Meaning
status	HTTP status code
headers	Outbound headers (ResponseHeaders record)
body	Materialized body after serialization
jsonBody	JSON held before per-status serializer runs
bodyStream	Chunked body for streaming responses

Cookies are not on FlareResponse. Set them with ctx.cookies (see Cookies).

Controller and middleware helpers

ControllerBase exposes protected helpers (ok, created, noContent, redirect, badRequest, unauthorized, forbidden, notFound, tooManyRequests, error) that wrap new FlareResponse(...). MiddlewareBase exposes only the failure subset (badRequest, unauthorized, forbidden, notFound, tooManyRequests, error). See Controller classes.

Response serializers

When a descriptor declares response: { 200: schema(...) }, Flare strips properties not in the schema for matching status codes on the compiled fast path. Record and discriminated-union schemas serialize via a JSON.stringify fallback and do not filter; see Serialization and HTTP contracts.

This is the guard the unshaped path lacks: when the wire format is simply whatever the handler returned, adding a field to a shared domain object silently adds it to every response built from that object, and nothing sits between the return statement and the client to notice. Declaring the response pins the wire shape in the descriptor, so on the compiled path a field added to the model later stays off the wire until it is also declared.

Related

• Routing behavior: 404/405 before a handler returns
• Error handling: mapping thrown errors to responses