Dependency Injection

The @talosjs/container package is the dependency injection (DI) engine of the framework. It wraps Inversify behind a small, typed API and exposes a single shared container singleton. Almost every artifact you build (controllers, services, middleware, and repositories) is registered into this container and resolved with its dependencies supplied through the constructor. You rarely call the container directly. The framework’s decorators register decorated classes for you, and @inject wires the graph together.

What the container gives you

One global container instance backs the whole app. A service resolved in a controller and the same service resolved in middleware share their registration, and, for singletons, their instance. You declare what a class needs with @inject(Token) in its constructor, and the container constructs the dependency tree instead of you new-ing collaborators by hand. Each registration picks a lifetime. Singleton, Transient, or Request decide whether an instance is shared, recreated on every resolution, or recreated per request. Most of the time you never reach for container.add at all: the framework decorators (@decorator.service(), @decorator.middleware(), @decorator.repository(), and controller routing) register the class as a side effect of being applied. Resolution returns typed instances through get<T> and typed values through getConstant<T>, and failures throw a ContainerException.

How it works

The package keeps one internal Inversify container (sharedDI) that every Container instance delegates to. When a class is registered, the container marks it injectable, binds it to itself, and applies the chosen scope. When you resolve it, Inversify reads the @inject metadata on its constructor and builds the dependency graph.

Stage	What happens
Registration	`container.add(MyClass, scope)` binds the class to the shared container and applies its lifetime scope. Decorators do this automatically.
Wiring	`@inject(Token)` on a constructor parameter records which dependency that slot needs.
Resolution	`container.get(MyClass)` asks Inversify for an instance; it recursively resolves and injects every `@inject` dependency.
Failure	When a binding is missing or construction throws, resolution raises a `ContainerException` with a descriptive message and code.

The shared instance is exported for direct import:

import { container } from "@talosjs/container";

The Container class

Container implements IContainer and forwards to the shared Inversify instance, so creating a new Container() and using the exported container operate on the same registrations. Use the exported singleton in application code.

Method	Signature	Description
`add`	`add(target: Constructor, scope?: EContainerScope): void`	Registers a class. Defaults to `EContainerScope.Singleton`. Re-registering rebinds.
`get`	`get<T>(target: Constructor): T`	Resolves an instance, injecting its dependencies. Throws `ContainerException` on failure.
`has`	`has(target: Constructor): boolean`	Returns `true` if the class is registered.
`remove`	`remove(target: Constructor): void`	Unbinds a registered class (no-op if not bound).
`addConstant`	`addConstant<T>(identifier: string \| symbol, value: T): void`	Stores a constant value under a string or symbol identifier.
`getConstant`	`getConstant<T>(identifier: string \| symbol): T`	Retrieves a constant. Throws `ContainerException` if not found.
`hasConstant`	`hasConstant(identifier: string \| symbol): boolean`	Returns `true` if a constant is registered.
`removeConstant`	`removeConstant(identifier: string \| symbol): void`	Unbinds a registered constant (no-op if not bound).

import { container, EContainerScope } from "@talosjs/container";

class UserService {
  public getUsers() {
    return [{ id: 1, name: "John" }];
  }
}

container.add(UserService); // singleton by default
const users = container.get(UserService).getUsers();

Scopes

A scope decides how long a resolved instance lives. Pass an EContainerScope value as the second argument to add (or as the argument to a framework decorator). The default is Singleton.

Scope	Enum member	Lifetime	Use it for
Singleton	`EContainerScope.Singleton`	One instance for the app’s lifetime.	Stateless services, config, env, loggers, repositories — the common case.
Transient	`EContainerScope.Transient`	A new instance on every resolution.	Lightweight, per-use helpers where sharing state would be wrong.
Request	`EContainerScope.Request`	A new instance per request context, reused within that request.	Per-request state such as a request-scoped logger or unit of work.

import { container, EContainerScope } from "@talosjs/container";

container.add(DatabaseConnection, EContainerScope.Singleton);
container.add(RequestLogger, EContainerScope.Request);
container.add(TemporaryWorker, EContainerScope.Transient);

const a = container.get(TemporaryWorker);
const b = container.get(TemporaryWorker);
console.log(a === b); // false: transient gives a fresh instance each time

Constructor injection with `@inject`

Declare dependencies as constructor parameters and annotate each with @inject(Token), where the token is the class (or a string alias). The container resolves and supplies them when it builds the class. inject is re-exported from @talosjs/container, so import it from there. A service injected into a controller. The controller is constructed by the container during routing, so the service arrives resolved:

import { inject } from "@talosjs/container";
import type { ContextType, IController } from "@talosjs/controller";
import type { IResponse } from "@talosjs/http-response";
import { Route } from "@talosjs/routing";
import { UserService } from "../services/UserService";

@Route.get("/api/users", {
  name: "api.users.list",
  version: 1,
  description: "List all users",
})
export class UserController implements IController {
  constructor(@inject(UserService) private readonly users: UserService) {}

  public async index(context: ContextType): Promise<IResponse> {
    return context.response.json({ users: this.users.getUsers() });
  }
}

Injecting the application environment into middleware, the same pattern the framework uses throughout:

import { AppEnv } from "@talosjs/app-env";
import { inject } from "@talosjs/container";
import type { ContextType } from "@talosjs/controller";
import { decorator, type IMiddleware } from "@talosjs/middleware";

@decorator.middleware()
export class VersionMiddleware implements IMiddleware {
  constructor(@inject(AppEnv) private readonly env: AppEnv) {}

  public async handler(context: ContextType): Promise<ContextType> {
    context.response.header.set("X-App-Version", this.env.APP_VERSION ?? "unknown");
    return context;
  }
}

Dependencies nest: a repository injects a database, a service injects the repository, a controller injects the service, and resolving the controller builds the whole chain.

Aliases and constants

Beyond classes, the container can resolve values by a string or symbol identifier. This is how the framework exposes shared infrastructure under stable names. Repositories, for example, inject the active database via the "database" alias rather than a concrete class:

import { inject } from "@talosjs/container";
import type { ITypeormDatabase } from "@talosjs/database";
import { decorator } from "@talosjs/repository";

@decorator.repository()
export class UserRepository {
  constructor(@inject("database") private readonly database: ITypeormDatabase) {}
}

Register and read constant values with addConstant / getConstant. Constants hold any value (strings, objects, or resolved instances), and get<T> / getConstant<T> return them typed:

import { container } from "@talosjs/container";

container.addConstant("app.name", "My Application");
container.addConstant<{ debug: boolean }>("app.config", { debug: true, maxConnections: 100 });

const name = container.getConstant<string>("app.name"); // "My Application"
const config = container.getConstant<{ debug: boolean }>("app.config");
console.log(config.debug); // true

Use a symbol identifier when you need a collision-proof token; use a string alias when readability and cross-package convention (like "database" or "mailer") matter more.

Auto-registration by the framework

You almost never call container.add yourself. Each framework decorator registers its class into the shared container as a side effect of being applied, using the scope you pass (default singleton). After that, resolving the class, or injecting it elsewhere, needs nothing more from you.

Decorator	Registers	Resolved by
`@decorator.service()`	A service class	Injected into controllers, middleware, other services
`@decorator.middleware()`	An HTTP or socket middleware	The request pipeline before the controller
`@decorator.repository()`	A repository class	Injected into services
Controller routing	A controller class	The router when a route matches

import { decorator } from "@talosjs/service";

@decorator.service()
export class PaymentService {
  public process(amount: number) {
    // ...
  }
}

// No manual container.add — the decorator already registered it.
// Injecting PaymentService anywhere now resolves this class.

The decorator-driven base injectable helper accepts a scope, so @decorator.service(EContainerScope.Transient) and similar control lifetime without ever touching the container API directly.

Error handling

When a binding is missing or a dependency cannot be constructed, resolution throws a ContainerException carrying a message and an error code (SERVICE_RESOLVE_FAILED for get, CONSTANT_RESOLVE_FAILED for getConstant). Catch it to distinguish DI failures from other errors:

import { container, ContainerException } from "@talosjs/container";

try {
  const service = container.get(UnregisteredService);
} catch (error) {
  if (error instanceof ContainerException) {
    console.error("Resolution failed:", error.message);
  }
}

A common cause is a forgotten decorator: if a class is injected but never registered, the framework cannot resolve it. Use container.has(MyClass) to confirm registration while debugging.

Working with the container effectively

Pull collaborators through the constructor with @inject so they are resolved, scoped, and testable. Don’t instantiate them by hand inside methods. In nearly every case the decorators do the registering for you, so prefer @decorator.service(), @decorator.middleware(), and @decorator.repository() and reach for container.add only for values the framework does not register. Most services are stateless, so leave them as singletons. Choose Transient or Request only when a fresh or per-request instance is genuinely required. Depend on a class or a stable alias such as "database" rather than reaching into another module’s globals; that keeps the dependency graph explicit. Call get<T> and getConstant<T> with the expected type so the compiler checks how you use the result. And when resolution can fail, wrap it and check instanceof ContainerException to tell DI errors apart from application errors.

Services: the unit of business logic resolved through the container.
Repositories: data-access classes that inject the database via DI.
Middleware: pipeline classes constructed with injected dependencies.
Controllers: route handlers the container builds with their services.

Getting Started

AI

Framework

Command Line

Dependency Injection

What the container gives you

How it works

The Container class

Scopes

Constructor injection with `@inject`

Aliases and constants

Auto-registration by the framework

Error handling

Working with the container effectively

​What the container gives you

​How it works

​The Container class

​Scopes

​Constructor injection with @inject

​Aliases and constants

​Auto-registration by the framework

​Error handling

​Working with the container effectively

​Related

What the container gives you

How it works

The Container class

Scopes

Constructor injection with `@inject`

Aliases and constants

Auto-registration by the framework

Error handling

Working with the container effectively

Related