Tsed Di

Ts.ED Dependency Injection and Lifecycle

Register every class the framework must build, resolve dependencies through the injector, and never construct DI-managed classes with new.

Read the DI API reference for signatures, the hook order and the deprecated-API table. Depth: https://tsed.dev/docs/providers.md, https://tsed.dev/docs/custom-providers.md, https://tsed.dev/docs/hooks.md.

1. Pick one style per file

All symbols below come from @tsed/di. Decorators and the functional API are interchangeable; follow the style already used in the project.

import {Injectable, Inject, inject, injectable} from "@tsed/di";
import {UsersRepository} from "./UsersRepository.js";

@Injectable()
export class UsersService {
  @Inject()
  protected repository: UsersRepository; // decorator style

  // or: private readonly repository = inject(UsersRepository); // functional style
}

// Functional registration, without the class decorator:
// export class UsersService { ... }
// injectable(UsersService);

• inject() works in class field initializers, constructors, factories and hooks of registered providers.
• Do not call inject() at module top level: it builds the provider before configuration, imports overrides and test mocks are loaded.
• Do not mix @Injectable() and injectable(Class) on the same class.
• Controllers: @Controller("/path"), or controller(Class).path("/path"). Routing belongs to tsed-controllers.

2. Choose the provider kind

1. Plain service: @Injectable().
2. Module (groups providers, carries configuration, built before the Server): @Module({imports: [...]}).
3. Value, factory, async factory, or implementation chosen at runtime: a custom token (step 3).
4. Middleware and interceptor classes: see tsed-middlewares. @Interceptor() and @Intercept() are exported by @tsed/di.

3. Declare custom providers and tokens

import {constant, injectable} from "@tsed/di";

export const DbConnection = injectable(Symbol.for("DbConnection"))
  .asyncFactory(async () => {
    const options = constant<DbOptions>("database");
    return connect(options);
  })
  .hooks({$onDestroy: (connection) => connection.close()})
  .token();
export type DbConnection = typeof DbConnection;

• Builders: .value(v), .factory(fn), .asyncFactory(fn), .class(Klass); chain .scope(), .deps(), .imports(), .hooks(), .type(), .alias(), and end with .token().
• Inject it with inject(DbConnection) or @Inject(DbConnection) db: DbConnection.
• Symbol and string tokens always need the explicit token: @Inject(TOKEN). A bare @Inject() only works when the TypeScript type is a class.
• Interface abstraction: export const RetryPolicy = Symbol("RetryPolicy") plus export interface RetryPolicy {...}, then injectable(RetryPolicy).class(TokenBucket).
• Group implementations: injectable(Foo).type(Bar) or @Injectable({type: Bar}), then injectMany<Bar>(Bar) or @Inject(Bar) bars: Bar[].
• Swap an existing provider: @OverrideProvider(Original) on the replacement class, or imports: [{token, useClass}] in configuration.

4. Set the scope

import {Injectable, ProviderScope, Scope} from "@tsed/di";

@Injectable()
@Scope(ProviderScope.REQUEST)
export class RequestCart {}
// functional: injectable(RequestCart).scope(ProviderScope.REQUEST);

• SINGLETON (default): one instance, built at startup.
• REQUEST: one instance per request. The controller and every provider on the injection chain must also be REQUEST; a singleton parent keeps the first instance forever.
• INSTANCE: a new instance on every injection. inject(Token, {rebuild: true}) forces a fresh one ad hoc.
• Prefer the request context (step 7) over REQUEST scope when you only need per-request data.

5. Lazy-load heavy providers

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

const service = await lazyInject(() => import("./ReportService.js")); // module must `export default` the class

Decorator form: @LazyInject("ReportService", () => import("./ReportService.js")) reports: Promise<ReportService>. Only $onInit runs for lazy providers. Do not lazy-load controllers, middlewares, or providers that rely on other hooks.

6. Use lifecycle hooks

import {Injectable, OnDestroy, OnInit} from "@tsed/di";
import {$asyncEmit, $on} from "@tsed/hooks";

@Injectable()
export class QueueService implements OnInit, OnDestroy {
  async $onInit() {}
  async $onDestroy() {}
  $onReady() {}
}

$on("$onReady", () => {}); // subscribe without a class
await $asyncEmit("$orderCreated", [order]); // emit a custom hook; listeners are `$orderCreated(order)` methods

• Any method starting with $ on a provider is registered as a hook listener.
• Order: $beforeInit → $onInit → $afterInit → $beforeRoutesInit → $onRoutesInit → $afterRoutesInit → $beforeListen → $afterListen → $onReady; per request $onRequest / $onResponse; shutdown $onDestroy.
• OnInit and OnDestroy types come from @tsed/di; BeforeInit, AfterInit, BeforeRoutesInit, OnRoutesInit, AfterRoutesInit, BeforeListen, AfterListen, OnReady come from @tsed/platform-http.
• Use $alter("$name", value, [args]) / $asyncAlter for hooks that transform a value. $emit is synchronous and does not await listeners.