TypeDI: TypeScript Dependency Injection

Common errors

• TypeError: Reflect.metadata is not a function

  cause `reflect-metadata` was not imported, or not imported as the very first line of your application.
  fix Ensure `import 'reflect-metadata';` is the absolute first line in your main application file before any other imports.

• Error: Service 'MyService' was not found in the container. Make sure you have decorated it with @Service() and registered it.

  cause The class intended for injection either lacks the `@Service()` decorator or the container cannot resolve its dependencies due to a misconfiguration or circular dependency.
  fix Verify that `MyService` has `@Service()` applied. Check `tsconfig.json` for `emitDecoratorMetadata` and `experimentalDecorators`. Inspect dependency graph for circular references.

• TS2304: Cannot find name 'Reflect'.

  cause TypeScript compiler is unaware of the `Reflect` global object, likely because `reflect-metadata` is installed but not included in `tsconfig.json`'s `types` or `lib`.
  fix Add `"reflect-metadata"` to the `types` array in your `tsconfig.json`'s `compilerOptions`, or ensure `"lib": ["esnext", "dom"]` (or similar) is present which often includes `esnext.reflect`.

Warnings

• breaking TypeDI versions prior to 0.6.0 had slightly different decorator application and API for registering services. While 0.10.0 is stable, always consult release notes for major version updates from older versions.
  Fix: Upgrade to the latest stable version and review the official documentation for API changes, especially around `@Service` and `Container` methods.
• gotcha The `reflect-metadata` package *must* be imported as the very first line of your application's entry file. Failing to do so will result in runtime errors related to missing metadata when decorators are processed.
  Fix: Add `import 'reflect-metadata';` to the absolute top of your main application file (e.g., `src/main.ts` or `app.ts`).
• gotcha TypeDI relies on TypeScript's experimental decorators and metadata emission. Your `tsconfig.json` must include `"emitDecoratorMetadata": true` and `"experimentalDecorators": true` under `compilerOptions`.
  Fix: Ensure the specified `compilerOptions` are present in your `tsconfig.json` file. Without them, decorators will not function as expected for DI.
• gotcha Circular dependencies can occur when Service A depends on Service B, and Service B also depends on Service A. TypeDI can sometimes resolve simple circular dependencies with constructor injection if not deeply nested, but complex cases can lead to runtime errors or `undefined` injections.
  Fix: Refactor your services to break circular dependencies, perhaps by introducing an interface, an event emitter, or restructuring responsibilities. Lazy injection patterns might also help in specific scenarios.

Install

• npm install typedi npm
• yarn add typedi yarn
• pnpm add typedi pnpm

Imports

• Container
  wrong:

  const Container = require('typedi').Container;

  correct:

  import { Container } from 'typedi';

  TypeDI is primarily designed for ESM consumption, especially with TypeScript decorators. CommonJS `require` is generally discouraged due to potential metadata issues and awkward syntax.
• Service
  wrong:

  import Service from 'typedi';

  correct:

  import { Service } from 'typedi';

  `Service` is a named export, not a default export. Ensure correct destructuring.
• 'reflect-metadata'
  wrong:

  require('reflect-metadata');

  correct:

  import 'reflect-metadata';

  This import must be the very first line of your application's entry point to ensure the `Reflect` API is available globally before any decorators are processed.

Quickstart

Demonstrates basic setup with `reflect-metadata` and TypeDI's `@Service()` decorator for both constructor and property injection, including usage of environment variables.

import 'reflect-metadata';
import { Container, Service } from 'typedi';

// A service that will be injected
@Service()
class MailerService {
  private readonly apiKey: string;

  constructor() {
    this.apiKey = process.env.MAILER_API_KEY ?? 'default-api-key';
  }

  sendMail(to: string, subject: string, body: string): void {
    console.log(`Sending email to ${to} with subject '${subject}' via API Key: ${this.apiKey}`);
    console.log(`Body: ${body}`);
  }
}

// A service that depends on MailerService
@Service()
class UserService {
  constructor(private mailer: MailerService) {}

  registerUser(email: string, username: string): void {
    console.log(`Registering user: ${username} (${email})`);
    this.mailer.sendMail(email, 'Welcome!', `Hello ${username}, welcome to our service!`);
  }
}

// Get an instance of UserService from the container, which will automatically inject MailerService
const userService = Container.get(UserService);

userService.registerUser('john.doe@example.com', 'JohnDoe');

// You can also get other services directly
const mailerService = Container.get(MailerService);
mailerService.sendMail('admin@example.com', 'System Alert', 'Server running fine!');