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):

1. Declare and mount the controller

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.

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.