Responses & Errors
Moost converts your handler's return value into an HTTP response automatically. This page covers response formats, status codes, headers, cookies, compression, error handling, and raw response access.
Automatic response handling
The return value of a handler determines the response:
| Return type | Content-Type | Behavior |
|---|---|---|
string | text/plain | Sent as plain text |
| object / array | application/json | JSON-serialized |
boolean / number | text/plain | Stringified ('true', '42') |
Node Readable stream | streamed | Piped to response (e.g. fs.createReadStream()) |
fetch Response | forwarded | Status, headers, and body preserved |
content-length is set automatically for non-streamed responses.
WARNING
Web ReadableStream is not special-cased — it would be JSON-serialized like a plain object. Wrap it with Readable.fromWeb() from node:stream or return it inside a fetch Response.
Mixed controllers
The response decorators on this page (@SetStatus, @SetHeader, @SetCookie, @Compress) act on HTTP events only. On a controller that also handles CLI commands, workflow steps or WebSocket messages, those events are skipped — a workflow started from an HTTP handler never touches that request's response.
Setting status codes
Without an explicit status, a response gets:
| Response | Default status |
|---|---|
| POST with a body | 201 |
| GET, PUT, PATCH, DELETE (any other method) with a body | 200 |
No body (undefined / empty) | 204 |
The rule is exported as getDefaultHttpStatus(method, hasBody) and the table as DEFAULT_HTTP_STATUS (both from @moostjs/event-http) — @moostjs/swagger documents responses with the same rule.
Version note
Up to and including 0.6.53 (wooks 0.7.x), PUT defaulted to 201 and PATCH/DELETE with a body to 202.
Static — @SetStatus
When the status code is always the same:
import { Post, SetStatus } from '@moostjs/event-http'
import { Controller } from 'moost'
@Controller('users')
export class UserController {
@Post('')
@SetStatus(201)
create() {
return { created: true } // always responds with 201
}
}By default, @SetStatus won't override a status code that was already set (e.g., by an error). Pass { force: true } to always override:
@SetStatus(200, { force: true })Dynamic — @StatusRef
When the status code depends on runtime logic:
import { Get, StatusRef } from '@moostjs/event-http'
import type { TStatusRef } from '@moostjs/event-http'
@Get('process')
process(@StatusRef() status: TStatusRef) {
if (someCondition) {
status.value = 202 // Accepted
return { status: 'processing' }
}
return { status: 'done' } // default 200
}Setting headers
Static — @SetHeader
import { Get, SetHeader } from '@moostjs/event-http'
@Get('test')
@SetHeader('x-powered-by', 'moost')
@SetHeader('cache-control', 'no-store')
test() {
return 'ok'
}@SetHeader supports additional options:
// Only set this header when the response status is 400
@SetHeader('content-type', 'text/plain', { status: 400 })
// Override even if the header was already set
@SetHeader('x-custom', 'value', { force: true })
// Set on both success and error responses
@SetHeader('x-request-id', 'abc', { when: 'always' })
// Set only on error responses
@SetHeader('x-error', 'true', { when: 'error' })Error responses are never cached
Every error response goes out with Cache-Control: no-store, and the cache and representation headers set before the failure (Cache-Control, Expires, Content-Type, …) are dropped — including a cache-control set through @SetHeader(…, { when: 'error' }) or { when: 'always' }. Other headers survive (cookies, CORS, WWW-Authenticate, Retry-After, Location, Vary, custom headers). For an error that should be cacheable, build the response yourself instead of throwing — set the status and headers with useResponse() and return the body:
import { useResponse } from '@wooksjs/event-http'
@Get('item/:id')
item(@Param('id') id: string) {
const item = findItem(id)
if (!item) {
useResponse().setStatus(404).setHeader('cache-control', 'public, max-age=60')
return { message: 'Not found' }
}
return item
}Dynamic — @HeaderRef
import { Get, HeaderRef } from '@moostjs/event-http'
import type { THeaderRef } from '@moostjs/event-http'
@Get('test')
test(@HeaderRef('x-custom') header: THeaderRef) {
header.value = `generated-${Date.now()}`
return 'ok'
}Setting cookies
Static — @SetCookie
import { Get, SetCookie } from '@moostjs/event-http'
@Get('login')
@SetCookie('session', 'abc123', { maxAge: '1h', httpOnly: true })
login() {
return { ok: true }
}INFO
@SetCookie won't overwrite a cookie that was already set in the response. This prevents accidental overwrites when multiple decorators or interceptors set the same cookie.
maxAge takes a time string ('1h', '30m', '1.5h', '1d12h') or a number of seconds. The same units apply to maxAge / sMaxage of a Cache-Control object (useResponse().setCacheControl(), static files). Values render as whole seconds; a cookie maxAge of 0 or less renders Max-Age=0. A string that is not a time string — including a bare digit string such as '3600' — throws a TypeError.
Version note
Up to and including 0.6.53 (wooks 0.7.x), a numeric duration was read as milliseconds (maxAge: 86400 rendered max-age=86.4). Remove any * 1000 you added for that.
Dynamic — @CookieRef
import { Post, CookieRef, CookieAttrsRef } from '@moostjs/event-http'
import type { TCookieRef, TCookieAttributes } from '@moostjs/event-http'
@Post('login')
login(
@CookieRef('session') cookie: TCookieRef,
@CookieAttrsRef('session') attrs: { value: TCookieAttributes },
) {
const token = generateToken()
cookie.value = token
attrs.value = { maxAge: '1h', httpOnly: true, secure: true }
return { ok: true }
}Response compression
Since 0.6.49 (wooks 0.7.28), the HTTP adapter can compress response bodies with brotli or gzip, picking the coding from the request's Accept-Encoding header. It is off by default. Turn it on with the compression option of MoostHttp, which is passed to wooks' createHttpApp:
import { MoostHttp } from '@moostjs/event-http'
import { Moost } from 'moost'
const app = new Moost()
void app.adapter(new MoostHttp({ compression: true })).listen(3000)
void app.init()compression: true uses the defaults: bodies of at least 1 KB with a compressible Content-Type (text, JSON, XML, JavaScript, SVG, …), brotli preferred over gzip. Pass an object to change them:
new MoostHttp({
compression: {
threshold: 2048, // bytes, default 1024
encodings: ['gzip'], // default ['br', 'gzip']
brotliQuality: 4, // default 4
gzipLevel: 6, // default 6
// filter: (contentType, response) => boolean — default isCompressibleType
},
})Streams, text/event-stream, HEAD, 204/304, responses that already have Content-Encoding and in-process calls (local fetch) are never compressed. The wooks guide Response Compression covers the full rules: what gets compressed, Vary and ETag handling, pre-serialized JSON and performance.
Per handler — @Compress
@Compress() overrides the app setting for a handler or, on a class, for every handler of the controller:
import { Compress, Get } from '@moostjs/event-http'
import { Controller } from 'moost'
@Controller('reports')
export class ReportsController {
@Get('full')
@Compress() // compress even when the app has compression off
full() {
return buildLargeReport()
}
@Get('archive')
@Compress({ brotliQuality: 6, threshold: 4096 }) // layered over the app settings
archive() {
return buildArchive()
}
@Get('session')
@Compress(false) // carries a token next to reflected input — never compress (BREACH)
session() {
return { token, echo: query }
}
}| Argument | Effect |
|---|---|
none / true | Compress with the app settings, or the defaults when the app has compression off |
false | Never compress this response |
| options object | Compress with these settings layered over the app settings (or the defaults) |
A method-level @Compress replaces a class-level one — options are layered over the app settings, never over the class value. The override is applied before guards and argument resolution, so it also covers error responses from guards, pipes and the handler. Unmatched routes (404) follow the app setting.
For a decision made at runtime, call the wooks composable inside the handler:
import { useResponse } from '@wooksjs/event-http'
@Get('search')
search(@Query('q') q: string) {
if (containsSecret) useResponse().setCompression(false)
return results
}isCompressibleType (the default filter) and the THttpCompressionOptions / THttpCompressionEncoding types are re-exported from @moostjs/event-http.
BREACH
Compression leaks information through the response size. When a body contains a secret (CSRF token, API key, session token) and text an attacker can influence (a reflected query parameter, a search term), the secret can be recovered from compressed sizes. Put @Compress(false) on such handlers, or keep secrets and reflected input in separate responses. See Security: BREACH in the wooks guide.
TIP
Compress in one layer only. If a reverse proxy or a Connect compression() middleware already compresses API responses, leave the adapter's compression off.
Error handling
Unhandled errors
Any uncaught exception becomes an HTTP 500 response:
@Get('fail')
fail() {
throw new Error('Something broke')
// → 500 Internal Server Error
}HttpError
Use HttpError to throw errors with specific HTTP status codes:
import { HttpError } from '@moostjs/event-http'
@Get('secret')
secret() {
throw new HttpError(403, 'Access denied')
// → 403 Forbidden with message "Access denied"
}Detailed error responses
Pass an object for structured error bodies. It needs a message; any other fields are sent as given:
throw new HttpError(422, {
message: 'Validation failed',
errors: [
{ field: 'email', message: 'Invalid email format' },
{ field: 'age', message: 'Must be a positive number' },
],
})The response body is your object plus statusCode (the status you threw) and error (the status text). The response format (JSON or HTML) adapts based on the request's Accept header.
Error codes and params
Give clients something stable to branch on: code is a machine-readable identifier (UPPER_SNAKE), params holds the values the message refers to:
throw new HttpError(409, {
message: `Name "${name}" is taken`,
code: 'NAME_TAKEN',
params: { name },
})
// → 409 { statusCode: 409, error: 'Conflict', message: 'Name "x" is taken', code: 'NAME_TAKEN', params: { name: 'x' } }With a translator registered (setTranslator()), MoostHttp translates every error body by its code (else its message text) in the request's locale — see Locale and Translation. To rewrite every error body in one place — the router's 404 and unexpected 500s included — pass transformErrorBody(body, error, ctx) to MoostHttp; it receives the already-translated body. The workflow trigger's refusals use the same shape (WF_EXPIRED, WF_FORBIDDEN, … — see Outlets).
Conditional requests
A GET/HEAD 200 that carries an ETag or Last-Modified header is answered with 304 Not Modified when the request's If-None-Match / If-Modified-Since matches — no opt-in. A GET/HEAD that would succeed answers 412 Precondition Failed when If-Match / If-Unmodified-Since does not hold (rendered like any error). Set the validators in the handler:
import { useResponse } from '@wooksjs/event-http'
@Get('doc/:id')
async doc(@Param('id') id: string) {
const doc = await loadDoc(id)
useResponse().setHeader('etag', `"${doc.version}"`).setHeader('cache-control', 'private, no-cache')
return doc
}The full rules (weak/strong comparison, compression and ETag, lost-update protection) are in the wooks guide: Conditional GET.
Version note
Up to and including 0.6.53 (wooks 0.7.x), only a prerendered ETag produced a 304, an ETag set by the handler disabled it, and GET/HEAD ignored If-Match / If-Unmodified-Since.
Error interceptors
For centralized error handling across multiple handlers, see Interceptors.
Raw response
For full control over the response, use @Res() to access the raw ServerResponse. When you do, the framework does not process the handler's return value — you're responsible for the entire response.
import { Get, Res } from '@moostjs/event-http'
import type { ServerResponse } from 'http'
@Get('raw')
raw(@Res() res: ServerResponse) {
res.writeHead(200, { 'content-type': 'text/plain' })
res.end('Manual response')
}Passthrough mode
If you need the raw response object but still want the framework to process your return value, use { passthrough: true }:
@Get('hybrid')
hybrid(@Res({ passthrough: true }) res: ServerResponse) {
res.setHeader('x-custom', 'value')
return { data: 'processed by framework' } // framework handles this
}