We have released Wyrly DI, a dependency injection toolkit for TypeScript.
Wyrly DI is designed for modern TypeScript applications that want dependency
injection without relying on reflect-metadata
, emitDecoratorMetadata
, legacy
decorators, or parameter decorators.
It focuses on:
- standard decorators
- type-safe tokens
- explicit dependency definitions
- request scopes for web applications
- inspectable and validatable dependency graphs
In this article, "standard decorators" means TC39 decorators supported by
TypeScript 5.0 and later. This is different from the older
experimentalDecorators
model that many existing DI libraries were built
around.
Links #
Why another DI toolkit? #
Many TypeScript DI libraries use runtime metadata to infer constructor
dependencies.
That can be convenient, but it also means important dependency information can
become hidden behind runtime metadata and decorator behavior.
Wyrly DI takes a more explicit approach.
import { Injectable, token } from "@wyrly/core";
type User = {
id: string;
name: string;
};
interface UserRepository {
findById(id: string): Promise<User | null>;
}
const UserRepositoryToken = token<UserRepository>("UserRepository");
@Injectable({
deps: [UserRepositoryToken],
lifetime: "scoped",
})
class GetUserUseCase {
constructor(private readonly users: UserRepository) {}
execute(id: string) {
return this.users.findById(id);
}
}
By declaring deps
, dependencies remain visible to code review, static
analysis, CI, and AI-assisted development tools.
With standard decorators, Wyrly DI does not try to read constructor parameter
types from reflect-metadata
. You can still use normal constructor injection,
such as constructor(private readonly users: UserRepository)
, but the
dependency mapping is declared explicitly with deps
.
In the example above, UserRepositoryToken
is used because TypeScript
interfaces do not exist at runtime. When the dependency is a class, the class
itself can also be used as a token. In other words, you can use typed tokens for
interfaces and class tokens for classes.
Type-safe tokens #
TypeScript interfaces disappear at runtime, so interface-based dependencies need
a runtime token.
Wyrly DI provides typed tokens for that purpose.
const UserRepositoryToken = token<UserRepository>("UserRepository");
const users = scope.resolve(UserRepositoryToken);
// users: UserRepository
The resolved value is inferred as UserRepository
, so interface-based
dependencies can still be used in a type-safe way.
Request scopes #
Web applications often need dependencies that are different for each request.
For example:
- current user
- request
- response
- unit of work
- Data
- request-scoped cache
Wyrly DI's web adapters are built around this model:
1 HTTP request = 1 DI scope
1 GraphQL request = 1 DI scope
Request scope is not the only supported lifetime. The core package supports
singleton
, scoped
, and transient
, so you can model application-wide
dependencies, per-request dependencies, and dependencies that should be created
on every resolution.
For example, the Hono adapter creates a scope per request in middleware, then
lets handlers resolve dependencies from that scope.
import { Hono } from "hono";
import { createContainer } from "@wyrly/core";
import { di, getDI, type HonoDIVariables } from "@wyrly/hono";
const app = new Hono<{ Variables: HonoDIVariables }>();
const container = createContainer();
app.use(di(container));
app.get("/users/:id", async (c) => {
const scope = getDI(c);
const usecase = scope.resolve(GetUserUseCase);
return c.json(await usecase.execute(c.req.param("id")));
});
Inspecting and validating the dependency graph #
Wyrly DI can inspect and validate the dependency graph.
const graph = container.inspect();
const result = container.validate();
For example, validation can detect dangerous lifetime relationships, such as a
singleton depending on a scoped dependency.
singleton -> scoped dependency
That kind of relationship can cause subtle bugs, such as request-specific data
being held by a singleton.
You can also put graph validation in a test and fail CI when the composition
root becomes invalid.
import { assertEquals } from "@std/assert";
Deno.test("DI graph is valid", () => {
const result = container.validate();
assertEquals(
result.ok,
true,
result.issues.map((issue) => issue.message).join("\n"),
);
});
This may be unnecessary for very small applications.
But in applications that care about boundaries, such as DDD or Clean
Architecture style codebases, dependency problems become more expensive to fix
when they are discovered late.
For example:
-
a singleton service accidentally depends on a request-scoped
CurrentUser -
an application use case becomes too coupled to infrastructure details
-
a composition root grows without anyone noticing an invalid dependency relationship
Validating the graph in CI helps catch those structural problems before they
become normal parts of the codebase.
Published packages #
The following packages are available:
@wyrly/core
@wyrly/next
@wyrly/express
@wyrly/hono
@wyrly/fresh
@wyrly/graphql
Use JSR for Deno:
deno add jsr:@wyrly/core
Use npm for Node.js and Bun:
npm install @wyrly/core
Install adapters as needed:
npm install @wyrly/hono
npm install @wyrly/next
npm install @wyrly/graphql
When Wyrly DI may be a good fit #
Wyrly DI may fit your project if you want to:
-
avoid
reflect-metadata -
use DI with TypeScript standard decorators
-
make a composition root explicit in DDD or Clean Architecture
-
use request scopes with Next.js, Hono, Express, or GraphQL
-
make the dependency graph visible in review and CI
When another tool may be a better fit #
Another tool may be a better fit if you want:
- a full-stack framework with controllers, modules, authentication, and configuration management
- automatic scanning and registration as the primary workflow
- parameter decorator-based injection
- compatibility with an existing app that deeply depends on
reflect-metadata
Wyrly DI intentionally separates a small explicit DI core from framework
adapters.
Examples #
The repository includes runnable examples for:
- DDD composition root
- Hono API
- Express API
- Next.js App Router
- GraphQL request scope
- Data pattern
- dependency graph validation
See the examples here:
github.com/valid-lab/wyrly/tree/main/examples
Closing #
Wyrly DI is a toolkit for making TypeScript dependency injection explicit,
analyzable, and practical for request-scoped web applications.
The design principles are:
- explicit dependency definitions over implicit auto-resolution
- inspectable structure over hidden behavior
- standard decorators over legacy decorators
- type-safe tokens over string-only tokens
- composition roots over automatic scanning
If that sounds useful for your project, start with @wyrly/core
and the example
closest to your framework.