Controllers
A controller is a class whose methods serve routes. List it in the controllers of a module.
@Controller('users')export class UsersController { @Get() list(): User[] {}
@Get(':id', [param('id', int)]) findOne(id: number): User {}
@Post([body(CreateUser)]) create(input: CreateUser): User {}
@Delete(':id', [param('id', int)]) @HttpCode(204) remove(id: number): void {}}Routes
@Get, @Post, @Put, @Patch, @Delete, @Options and @Head declare a route for their method; @All for every method; @Route('PROPFIND', 'path') for any other method name. A method may carry several route decorators.
The full path is the global prefix, the controller path and the route path, each with a leading slash and no trailing one:
await createApp(AppModule, { prefix: 'api' })
@Controller('users') // + @Get(':id') → /api/users/:idHEADis answered by theGETroute unless a@Headroute exists.- A path with routes, but none for the method, answers
405with anAllowheader. - A route for a concrete method wins over an
@Allroute on the same path. - A controller inherits the routes of its parent class; an override without a route decorator removes the route.
Path syntax
Each special form takes a whole segment:
| Path | Matches |
|---|---|
/users/me |
that path |
/users/:id |
one non-empty segment, as id |
/users/:id{\\d+} |
a segment matching the regex, tested on the decoded value |
/users/:id? |
with or without the last segment; only trailing parameters are optional |
/files/* |
/files and everything below |
/files/*path |
the same, the decoded remainder as path |
Routes compile into Bun’s native router. Two routes that can match the same request (the same path written twice, say) stop the startup with an error naming both.
Arguments
The second argument of a route decorator lists what the method receives, in order. Each value is read, converted and validated before the method runs; a failure answers 400 without calling it.
@Get(':id', [param('id', int), query('fields'), header('accept-language')])findOne(id: number, fields: string | undefined, language: string | undefined) {}| Argument | Value | Nest |
|---|---|---|
param(name, parser?) |
path parameter, of the route or of the controller path | @Param() |
query(name, parser?) |
first value of a query parameter | @Query() |
header(name, parser?) |
request header | @Headers() |
cookie(name, parser?) |
cookie | @Cookies() |
body(schema?) |
JSON body | @Body() |
form(schema?, limits?) |
form body, files included | @Body() with multer |
value(key) |
what a guard or an interceptor attached to the request | custom decorator, @User() |
context() |
the request context itself | @Req() |
The types are checked: findOne(id: string) after param('id', int) is a compile error, and so is a method that does not accept what the list gives. A param() name that is not in the full path stops the startup and lists the parameters the path has.
Without parser, param('id') is a string, string | undefined for an optional parameter; query(), header() and cookie() are string | undefined. Parsers and schemas are in Validation.
The context
A route without argument list receives the request context, typed by its path:
@Get(':id')findOne(ctx: Context<':id'>) { return this.#users.find(ctx.param('id'))}| Member | |
|---|---|
ctx.req |
Bun’s Request |
ctx.param(name, parser?), query(), header(), cookie() |
as the arguments above |
ctx.body(schema?), ctx.form(schema?, limits?) |
the body; read once, in one format |
ctx.cookies |
Bun’s CookieMap; what you set or delete is sent with the response |
ctx.responseHeaders |
headers added to the response, whatever it is |
ctx.url |
the parsed URL, built on first use |
ctx.ip |
address of the peer |
ctx.get(key), ctx.set(key, value), ctx.has(key) |
values attached to the request, see Request pipeline |
ctx.metadata(decorator) |
custom metadata of the route |
ctx.route |
controller, method name, HTTP method, full path |
Prefer the argument list: it is what the types, OpenAPI and the startup checks see. context() in the list gives the context next to other values, for cookies or response headers.
Responses
What the method returns becomes the response, as in Nest:
| Returned | Response |
|---|---|
a Response |
sent as is |
undefined, null |
empty body |
| a string | text/plain;charset=utf-8 |
ArrayBuffer, typed array, Blob, ReadableStream |
sent as is |
| anything else | JSON |
The status is 201 for POST and 200 otherwise; @HttpCode(204) changes it. 204, 205 and 304 never get a body. @Header(name, value) adds a header to the responses built from returned values. A returned Response keeps its own status and headers.
What the method returns is what is sent: to send less than a database row holds, say it in the method.
const User = UserRow.omit({ passwordHash: true })
@Get(':id', [param('id', int)])@ApiResponses({ 200: { description: 'The user', schema: User }, 404: { description: 'No such user' } })async findOne(id: number) { return User.parse(await this.users.find(id)) // z.object() leaves out the fields it does not declare}The same schema documents the response, see OpenAPI.
Errors are responses too: throw an HttpException and its body is sent with its status.
throw new NotFoundException(`No user ${id}`)// 404 {"statusCode":404,"message":"No user 1","error":"Not Found"}BadRequestException (400), UnauthorizedException (401), ForbiddenException (403), NotFoundException (404), ConflictException (409), PayloadTooLargeException (413), UnsupportedMediaTypeException (415), UnprocessableEntityException (422), TooManyRequestsException (429), InternalServerErrorException (500) and ServiceUnavailableException (503) exist; new HttpException(body, status) makes any other. Any other error is logged and answered with a bare 500, whose body says nothing about it.
Server-sent events
An @Sse() route returns an async iterable of messages, streamed as text/event-stream:
@Sse('ticks')async *ticks(): AsyncGenerator<SseMessage> { for (let i = 0; ; i++) { yield { data: { tick: i }, id: String(i) } // data: a string as is, anything else as JSON await Bun.sleep(1000) }}A message may also have an event name and a retry delay in milliseconds. When the client disconnects, the generator is returned, so its finally runs: release what it holds there. The response carries Nest’s headers: no caching, no buffering by nginx.
const source = new EventSource('/ticks')source.onmessage = (event) => console.log(JSON.parse(event.data))