Cheat Sheet

🚀 Server & Configuration

import {Configuration, Inject} from "@tsed/di";
import {PlatformApplication} from "@tsed/platform-http";
import * as controllers from "./controllers/index.js";

@Configuration({
  port: 3000,
  logger: true,
  mount: [...Object.values(controllers)]
})
export class Server {
  @Inject()
  protected app: PlatformApplication;
}

🎯 Simple Controller

import {Controller} from "@tsed/di";
import {Get} from "@tsed/schema";

@Controller("/hello")
export class HelloController {
  @Get("/")
  get() {
    return {message: "Hello world"};
  }
}

🧩 Service Injection

import {Injectable} from "@tsed/di";

@Injectable()
export class MyService {
  greet(name: string): string {
    return `Hello, ${name}!`;
  }
}

import {Get} from "@tsed/schema";
import {Controller, Inject} from "@tsed/di";

@Controller("/hello")
export class HelloController {
  @Inject()
  protected myService: MyService;

  @Get("/")
  get() {
    return {message: this.myService.greet("World")};
  }
}

📥 Retrieving Parameters

import {Controller} from "@tsed/di";
import {Get, Post} from "@tsed/schema";
import {PathParams, QueryParams, BodyParams, HeaderParams} from "@tsed/platform-params";

@Controller("/users")
export class UserController {
  @Get("/:id")
  getById(@PathParams("id") id: string, @QueryParams("expand") expand?: boolean) {
    // ...
  }

  @Post("/")
  create(@BodyParams() user: any, @HeaderParams("x-api-key") apiKey: string) {
    // ...
  }
}

🛡️ Custom middleware

import {Middleware} from "@tsed/platform-middlewares";
import {Context} from "@tsed/platform-params";
import {Unauthorized} from "@tsed/exceptions";

@Middleware()
export class AuthMiddleware {
  async use(@Context() ctx: Context): Promise<void> {
    const token = ctx.request.headers["authorization"];
    if (!token) {
      throw new Unauthorized("Token required");
    }
  }
}

🧪 Validating with @tsed/schema

Using decorators

import {Property, Required} from "@tsed/schema";

class UserModel {
  @Required()
  @Property()
  name: string;

  @Property()
  email?: string;
}

@Controller("/")
class MyController {
  @Post("/")
  create(@BodyParams() user: UserModel) {
    // validation automatique
  }
}

Using a schema

import {object, string} from "@tsed/schema";

const UserSchema = object({
  name: string().required().description("User's name"),
  email: string().description("User's email")
}).label("UserSchema");

interface User {
  name: string;
  email?: string;
}

@Controller("/")
class MyController {
  @Post("/")
  create(@BodyParams() @Schema(UserSchema) user: User) {
    // validation automatique
  }
}

Run validation manually

import {validate} from "@tsed/ajv";

// Shortcut to inject(AjvService).validate()
await validate(
  {
    name: "John Doe",
    email: "email@tsed.dev"
  },
  {type: UserModel}
);

or:

import {validate} from "@tsed/ajv";

await validate(
  {
    name: "John Doe",
    email: "email@tsed.dev"
  },
  UserSchema
);

🔄 Lifecycle hooks in services

Listen to service lifecycle events

import {Injectable, OnInit, OnDestroy} from "@tsed/di";

@Injectable()
export class MyService implements OnInit, OnDestroy {
  $onInit() {
    console.log("Service initialized");
  }

  $onDestroy() {
    console.log("Service destroyed");
  }
}

Emit custom events

import {$emit} from "@tsed/di";

@Injectable()
export class MyService {
  async doSomething() {
    // Do some work...

    // Emit a custom event
    $emit("myCustomEvent", {data: "Hello World"});
  }
}

Method	Description	Sync/Async	Example usage
$emit	Emits an event synchronously to all listeners.	Sync	$emit("eventName", data);
$asyncEmit	Emits an event asynchronously, waits for all listeners to complete.	Async	await $asyncEmit("eventName", data);
$alter	Passes a value through all listeners, each can alter the value (sync).	Sync	const result = $alter("eventName", value, ...args);
$asyncAlter	Like $alter, but listeners can be async and the result is awaited.	Async	const result = await $asyncAlter("eventName", value, ...args);

📚 Documentation Swagger

import {Returns, Summary} from "@tsed/schema";

class MyController {
  @Get("/")
  @Summary("Return all users")
  @(Returns(200, Array).Of(UserModel))
  getAll() {
    return [];
  }
}

Enable in the server config:

import "@tsed/swagger";

@Configuration({
  swagger: [
    {
      path: "/docs"
    }
  ]
})

🧑‍💻 Use context

In controllers:

import {Context} from "@tsed/platform-params";

@Controller("/users")
export class UserController {
  @Get("/:id")
  getById(@PathParams("id") id: string, @Context() ctx: Context) {
    // Access request/response via ctx.request and ctx.response
    return {id, userAgent: ctx.request.headers["user-agent"]};
  }
}

In services:

import {Injectable, InjectContext} from "@tsed/di";
import type {PlatformContext} from "@tsed/platform-http";

@Injectable()
export class MyService {
  @InjectContext()
  protected ctx: PlatformContext;

  async doSomething() {
    const userId = this.ctx.request.headers["user-id"];

    this.ctx.logger.info(`User ID: ${userId}`);

    // Use userId for some logic
    return `User ID is ${userId}`;
  }
}

🧪 Unit tests with PlatformTest

import {PlatformTest} from "@tsed/platform-http/testing";

beforeEach(() => PlatformTest.create());
afterEach(() => PlatformTest.reset());

it("should inject service", () => {
  const service = PlatformTest.get<MyService>(MyService);
  expect(service).toBeInstanceOf(MyService);
});

📦 Packages Overview

Package	Main purpose	Node.js/Bun.js	Browser
@tsed/core	Provides utilities, helpers, and internal decorators used by other packages.	✔️	✔️
@tsed/di	Dependency injection (IoC), service lifecycle management, injection decorators.	✔️	✔️
@tsed/hooks	Adds hooks/callbacks on the lifecycle of services and middlewares.	✔️	✔️
@tsed/json-mapper	Serialization/deserialization of JSON objects, data transformation.	✔️	✔️
@tsed/exceptions	Provides custom HTTP exception classes for error handling.	✔️	✔️
@tsed/schema	Schema declaration, validation, and model documentation (OpenAPI/Swagger).	✔️	✔️
@tsed/ajv	Consume json-schema to validate payload (based on Ajv)	✔️	✔️
@tsed/platform-http	Generic HTTP implementation, platform abstraction (Express, Koa, etc.).	✔️	❌
@tsed/platform-express	Express.js specific integration to start the server and handle requests.	✔️	❌
@tsed/platform-koa	Koa.js specific integration to start the server and handle requests.	✔️	❌
@tsed/platform-fastify	Fastify.js specific integration to start the server and handle requests.	✔️	❌
@tsed/platform-http/testing	Utilities for unit and integration testing with PlatformTest.	✔️	❌
@tsed/platform-params	Decorators and logic to extract request parameters (body, query, path, headers, etc.).	✔️	❌
@tsed/platform-router	Routing management, controller mounting, and route resolution.	✔️	❌
@tsed/platform-middlewares	Management, registration, and execution of middlewares in the request lifecycle.	✔️	❌
@tsed/engines	Integrates template engines (EJS, Pug, Handlebars…) for server-side rendering.	✔️	❌
@tsed/platform-views	Adds support for view rendering in controllers/responses via configured engines.	✔️	❌

📝 Notes

TIP

• In TS.ED v8, always prefer @tsed/di for injection, @tsed/schema for schema declaration and HTTP decorators.
• @tsed/common is being deprecated in v8.
• Asynchronous middleware without next(). Ts.ED automatically handles promises.
• Use @tsed/platform-express (or another platform) to start the server.