Tsed Middlewares

Ts.ED Middlewares, Interceptors and Pipes

Pick the narrowest tool first, then implement it as an injectable class.

Never import from @tsed/common.

1. Write a middleware

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

@Middleware()
export class ApiKeyMiddleware implements MiddlewareMethods {
  use(@Context() $ctx: Context) {
    const options = $ctx.endpoint.get(ApiKeyMiddleware) || {};
    if ($ctx.request.get("x-api-key") !== options.key) {
      throw new Unauthorized("Invalid API key");
    }
  }
}

1. Implement use(...). Inject what is needed with parameter decorators (@Context(), @HeaderParams(), @QueryParams()); inject services with @Inject() or inject().
2. Finish by returning or awaiting. Do not call next(); throw an exception from @tsed/exceptions to stop the request.
3. Read per-endpoint options with $ctx.endpoint.get(MiddlewareClass). This is only available for endpoint-level middlewares, not global ones.
4. Use $ctx.request / $ctx.response (platform abstractions) so the code stays portable across Express, Koa and Fastify.

2. Attach to controllers and endpoints

1. @UseBefore(M): before the handler. @Use(M): just before the handler, after @UseBefore. @UseAfter(M): after the handler when it returned no data.
2. On a class, @UseBefore runs once for the controller; @UseBeforeEach(M) runs before each of its endpoints.
3. All four accept Ts.ED middleware classes or raw framework functions, and come from @tsed/platform-middlewares.
4. Call order: global middlewares, controller @UseBefore, controller @UseBeforeEach, endpoint @UseBefore, controller @Use, endpoint @Use, handler, endpoint @UseAfter, send response. Once a handler returns data the response is sent and later @UseAfter and global middlewares are skipped.
5. Prefer an interceptor or response filter over @UseAfter for post-processing.
6. Do not write Express error middlewares (@Err(), four-argument functions); use exception filters (tsed-exceptions).

3. Register global middlewares

import {Env} from "@tsed/core";
import {Configuration} from "@tsed/di";
import compression from "compression";
import helmet from "helmet";
import {RequestIdMiddleware} from "./middlewares/RequestIdMiddleware.js";

@Configuration({
  middlewares: [
    {use: helmet(), hook: "$afterInit"},
    "json-parser",
    {use: "urlencoded-parser", options: {extended: true}},
    {use: compression(), env: Env.PROD},
    RequestIdMiddleware
  ]
})
export class Server {}

1. Each entry is a function, a Ts.ED middleware class, a string, or {use, hook?, env?, options?}. Default hook: $beforeRoutesInit.
2. Built-in strings: json-parser, urlencoded-parser, text-parser, raw-parser. Any other string is imported as a module and called with options.
3. Ts.ED middleware classes need the request context: register them on $beforeRoutesInit or later. On $beforeInit, $onInit or $afterInit only raw framework middlewares are accepted and a class throws at startup.
4. Alternative: inject PlatformApplication from @tsed/platform-http in the server and call this.app.use(M) inside $beforeRoutesInit() or $afterRoutesInit(). Hook registrations run before the middlewares list.
5. Raw middlewares are framework specific. Do not register an Express middleware in a Koa or Fastify application.

4. Build an auth decorator

import {useDecorators} from "@tsed/core";
import {UseAuth} from "@tsed/platform-middlewares";
import {In, Returns, Security} from "@tsed/schema";
import {AuthMiddleware} from "../middlewares/AuthMiddleware.js";

export function Auth(options: {role?: string; scopes?: string[]} = {}): Function {
  return useDecorators(
    UseAuth(AuthMiddleware, options),
    Security("oauth", ...(options.scopes || [])),
    In("header").Name("Authorization").Type(String).Required(true),
    Returns(401),
    Returns(403)
  );
}

1. UseAuth(Guard, options) adds the guard as @UseBefore once and merges options into the endpoint store. Read them with $ctx.endpoint.get(AuthMiddleware).
2. Works on a method or on a class (applies to every endpoint; class-level and method-level options are merged in the endpoint store).
3. Throw Unauthorized for missing or invalid credentials and Forbidden for insufficient rights.
4. The Security name must match a security scheme declared in the OpenAPI configuration (tsed-openapi). Passport and OIDC: https://tsed.dev/docs/authentication.md.