tsed-controllers

# Ts.ED Controllers and Routing Declare endpoints with decorators and let Ts.ED map, validate and serialize. Keep controllers thin: inputs in, service call, value out. Package map (never import from `@tsed/common`): | Symbol | Package | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | | `Controller`, `Configuration`, `Inject` | `@tsed/di` | | `Get`, `Post`, `Put`, `Patch`, `Delete`, `Head`, `Options`, `All`, `Returns`, `Status`, `Redirect`, `Location`, `ContentType`, `Header`, `View`, `Hidden` | `@tsed/schema` | | `PathParams`, `QueryParams`, `BodyParams`, `HeaderParams`, `Cookies`, `Session`, `Locals`, `Context`, `RawBodyParams`, `RawPathParams`, `RawQueryParams`, `UsePipe` | `@tsed/platform-params` | | `Req`, `Res`, `Next`, `PlatformRequest`, `PlatformResponse`, `PlatformContext` | `@tsed/platform-http` | | `useDecorators`, `StoreSet` | `@tsed/core` | ## 1. Declare and mount the controller ```typescript import {Controller, Inject} from "@tsed/di"; import {NotFound} from "@tsed/exceptions"; import {BodyParams, PathParams, QueryParams} from "@tsed/platform-params"; import {Get, Post, Returns} from "@tsed/schema"; import {Calendar} from "../models/Calendar.js"; import {CalendarsService} from "../services/CalendarsService.js"; @Controller("/calendars") export class CalendarsController { @Inject() protected service: CalendarsService; @Get("/") @(Returns(200, Array).Of(Calendar)) list(@QueryParams("limit") limit: number = 20) { return this.service.list(limit); } @Get("/:id") @Returns(200, Calendar) @Returns(404, NotFound) async get(@PathParams("id") id: string) { const calendar = await this.service.get(id); if (!calendar) throw new NotFound("Calendar not found"); return calendar; } @Post("/") @Returns(201, Calendar) create(@BodyParams() payload: Calendar) { return this.service.create(payload); } } ``` 1. Mount it explicitly in the server configuration. A controller that is neither mounted nor listed as a child is never routed. ```typescript import {Configuration} from "@tsed/di"; import {CalendarsController} from "./controllers/CalendarsController.js"; @Configuration({mount: {"/rest": [CalendarsController]}}) export class Server {} ``` 2. Pass controller classes (or `Object.values()` of a barrel). Do not pass glob strings to `mount`. 3. Version an API by mounting different class lists on `/rest/v1`, `/rest/v2`. 4. Nest with `@Controller({path: "/rest", children: [CalendarsController, EventsController]})`; mount only the parent. A child can be reused under several parents. 5. Share handlers through class inheritance: put endpoints on an undecorated base class and add `@Controller` on the subclass only. ## 2. Bind inputs 1. Give every parameter a decorator: `@PathParams("id")`, `@QueryParams("q")`, `@BodyParams()`, `@BodyParams("field")`, `@HeaderParams("x-token")`, `@Cookies("sid")`, `@Session("user")`, `@Locals("key")`, `@Context() $ctx`. 2. Type parameters with model classes, not interfaces or type aliases. An interface, a union or `any` is emitted as `Object`: no mapping, no property validation. Use `@Any()` from `@tsed/schema` when any type must be accepted. 3. Pass the item class for collections, because TypeScript erases generics: `@BodyParams(Product) products: Product[]`, `@QueryParams("ids", String) ids: string[]`. 4. Use a class for a whole query string: `@QueryParams() query: SearchQuery`. 5. Add inline constraints with schema decorators on the parameter: `@PathParams("id") @Pattern(/^[0-9a-f]{24}$/) id: string`. 6. Only `@BodyParams`, `@PathParams` and `@QueryParams` run the json-mapper and validation by default. `@HeaderParams`, `@Cookies`, `@Session`, `@Locals` do not; opt in with the options form `@HeaderParams({expression: "x-id", useValidation: true, useMapper: true})`. 7. Use the `Raw*` variants to bypass mapping and validation (for example before `@UsePipe`, see tsed-middlewares). 8. Prefer `@Context() $ctx: PlatformContext` (`$ctx.request`, `$ctx.response`, `$ctx.logger`, `$ctx.endpoint`) over `@Req()`/`@Res()`. Do not type `@Req()`/`@Res()` as Express objects in portable code; use `PlatformRequest`/`PlatformResponse`. Model, validation and group rules belong to tsed-models. ## 3. Shape the response 1. Return the value. Promises, `Observable`, `Buffer` and readable streams are resolved and sent by the platform. Do not call `res.send()`/`res.json()` and also return a value. 2. Declare each status with `@Returns(status, Model)`. It drives OpenAPI and the serialization options of that status: `.Of(Item)`, `.Nested(Sub)`, `.Groups("read")`, `.ContentType("text/xml")`, `.Header("x-total", ...)`, `.Description("...")`, `.Binary()`. 3. Wrap chained decorators in parentheses: `@(Returns(200, Pagination).Of(Product))`. 4. Set a fixed status and headers with `@Status(201, Model)`, `@Header("x-version", "1")`, `@ContentType("text/csv")`. Use `$ctx.response.status(...)`, `.setHeaders(...)`, `.attachment(...)` for dynamic values. 5. Redirect with `@Redirect("/new")` or `@Redirect(301, "/new")`; add a `Location` header with `@Location("/items/1")`. 6. Render templates with `@View("calendar.ejs")` and return the view data (engine setup: https://tsed.dev/docs/templating.md). 7. Hide an endpoint or controller from OpenAPI with `@Hidden()`. Documentation details belong to tsed-openapi. ## 4. Order and write paths 1. Routes register in method declaration order. Put static paths (`/search`) above parametric ones (`/:id`). 2. Stack verb decorators to alias one handler: `@Get("/:id") @Get("/alias/:id")`. 3. Supported path tokens: `/:id`, optional `/:id?` or Express 5 `/{:id}`, named wildcard `/:path*` read with `@PathParams("path")`. Adapters convert these for Express 4/5, Koa and Fastify. 4. Do not embed RegExp groups in string paths (`/:id(\\d+)`); Express 5 rejects them and Ts.ED does not convert them. Validate with `@Pattern` instead. ## 5. Build a custom endpoint decorator Compose existing decorators with `useDecorators`; store options with `StoreSet` and read them through `$ctx.endpoint.get(Key)`. ```typescript import {StoreSet, useDecorators} from "@tsed/core"; import {UseBefore} from "@tsed/platform-middlewares"; import {Returns} from "@tsed/schema"; import {QuotaMiddleware} from "../middlewares/QuotaMiddleware.js"; export function Quota(limit: number) { return useDecorators(StoreSet(QuotaMiddleware, {limit}), UseBefore(QuotaMiddleware), Returns(429)); } ``` Middlewares, auth decorators, interceptors and pipes: tsed-middlewares. Thrown errors and error payloads: tsed-exceptions. ## Pitfalls - 404 on every route: the controller is not in `mount`, or the mount prefix was forgotten in the URL. - `/calendars/search` hits `get(":id")`: reorder the methods. - Body arrives as a plain object: the parameter type is an interface, or the collection item type was not given. - Model properties missing from input or output: the property has no schema decorator (see tsed-models). - `@Returns` does not convert the returned value to another class; it selects serialization options (groups, generics) and documents the response. - Relative imports without the `.js` extension fail at runtime in ESM projects. - Routes added through an injected `PlatformRouter` are not part of the OpenAPI document. ## Checklist - Controller decorated, exported, and mounted or listed in a parent's `children`. - Every parameter decorated and typed with a class or primitive; collections pass the item class. - Each success and error status declared with `@Returns`. - Static routes declared before parametric routes; no RegExp in string paths. - No `@tsed/common` import; relative imports end with `.js`. - Endpoint covered by a test (see tsed-testing). Depth: https://tsed.dev/docs/controllers.md, https://tsed.dev/docs/routing.md, https://tsed.dev/docs/custom-endpoint-decorators.md, https://tsed.dev/docs/request-context.md.