Wyrly DI: Type-safe Dependency Injection for Modern TypeScript

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

• GitHub repository
• @wyrly/core on JSR
• @wyrly/core on npm
• Examples

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
• DataLoader
• 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
• DataLoader 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.

• GitHub
• JSR
• npm