di-framework

A lightweight, type-safe dependency injection framework for TypeScript, plus companion packages for common application concerns. The core automatically manages service instantiation, dependency resolution, and lifecycle management.

Published docs at docs.di-framework.dev include a header version switcher (versions.json) so you can open /latest/ or a frozen /vX.Y/ snapshot from a release tag. In-page search is scoped to the snapshot you are reading.

Features

Zero Dependencies: No external dependencies required. Works with SWC and TypeScript's native decorator support.
Type-Safe: Full TypeScript support with type inference for all injected dependencies.
Automatic Resolution: Dependencies are automatically resolved and injected.
Lifecycle Management: Built-in support for singleton and transient service lifecycles.
Factory Functions: Register services using factory functions for complex initialization.
Event-Driven: Decouple service communication with @Publisher and @Subscriber decorators.
Telemetry: Built-in support for method tracking and monitoring with @Telemetry and @TelemetryListener.
Error Detection: Detects circular dependencies and unregistered services at runtime.
Testing Support: Easy to test with mock service registration.
Repository Abstraction: Includes @di-framework/repo for standardized data access, storage-agnostic repositories, and decorator/SQL/manifest database migrations.
HTTP Routing & OpenAPI: Type-safe HTTP routing and build-time OpenAPI 3.1 generation with @di-framework/http.
GraphQL: Object-oriented, decorator-driven GraphQL with @di-framework/graphql — domain classes become the schema.
Events: Bridge @Publisher/@Subscriber to Kafka, NATS, or in-memory transports with @di-framework/events.
Configuration: Typed, validated config from env, JSON, YAML, and TOML files injected via DI with @di-framework/config, including {profile}.config.{ext} overlays via @WithProfile.
Authentication: Sessions, JWT, OAuth2/OIDC, and WebAuthn passkeys on WebCrypto with @di-framework/auth — zero runtime dependencies.
Resource Authorization: Decorator-authored policies, EBNF interchange, DI resource providers, and fail-closed HTTP controller bindings with @di-framework/authz.
Sockets: Security-first WebSocket, TCP, and UDP with a WebCrypto secure channel via @di-framework/socket (network I/O — distinct from the in-process event bus).
RPC: Decorator-generated JSON-RPC and per-method gRPC with a typed client via @di-framework/rpc — the same service over memory, HTTP, sockets, and Connect / gRPC.
Private service bindings: @ExportService/@ServiceBinding grant named in-process callers access to a contract without a URL or HTTP route.
Scheduling: @Cron runs DI-managed methods on a 5-field expression or millisecond interval; wasmCloud deployments disable in-process timers and apply Kubernetes CronJobs.
Durable queues: @di-framework/queues persists jobs with at-least-once delivery, retries, and dead-letter inspection.
Actors: @di-framework/actors provides a local virtual-actor runtime with serialized mailboxes and typed references. No Wasm host is required for local use.
AI: Annotation-driven chat, tools, RAG, MCP, and agents with @di-framework/ai (OpenAI-compatible and Anthropic HTTP adapters, plus Cloudflare Workers AI and Vectorize). Agent Skills (SKILL.md), plugin discovery (.agents/plugins), and the skills toolbox live in @di-framework/ai-utils. Both publish at 6.x from di-framework/ai and peer @di-framework/core@^5.
Unified CLI: di-framework is the only public executable. Built-in application, HTTP, and monorepo commands ship in @di-framework/cli. Agent configuration and Agent Skills commands install as @di-framework/cli-plugin-ai (di-framework ai) from di-framework/cli-extensions.
Schema codegen: @di-framework/codegen turns versioned schema manifests into validation helpers, @Controller routes with OpenAPI @Endpoint metadata, @EventBridge routes, and opt-in RPC services and AI tools, with an ownership ledger and CI drift check (di-framework generate).
Runtime type checks: ttsc transform @di-framework/tsc injects parameter guards from TypeScript types at emit time (di-framework init wires this by default).
Biome plugins: @di-framework/biome flags framework mistakes in Biome — removed decorators and packages, binding secrets, cron expressions, and decorator compiler flags. See Biome plugins.
Platform backing services: Tenant-scoped Redis, NATS, blobstore, dedicated PostgreSQL, and egress through BackingService requests, with protected ServiceBinding configuration. Redis and NATS landed in 5.3.6; PostgreSQL, blobstore, egress, tenant kubeconfigs, and the HTTP gateway ship in the published platform 6.x line (current release 6.0.7). See backing services.
WebAssembly deployment: Build WASI 0.3 HTTP components with @di-framework/cli-plugin-platform (di-framework platform) and consume native service bindings from @di-framework/bindings. Both publish at 6.x. The kube platform provides a local cluster and live verification examples.

Why Use This Framework?

Traditional dependency injection requires manual service instantiation and wiring, which becomes error-prone and difficult to maintain as your application grows. This framework eliminates that complexity:

Without di-framework:

const createServerContext = (env, ctx) => {
  if (!instanceState.member) {
    const contextInstance = Context.create({
      contactService: ContactService.create({}),
      assetService: AssetService.create({}),
      transactionService: TransactionService.create({}),
      // ... 20+ more services manually created and wired
    });
    instanceState.member = contextInstance;
  }

  instanceState.member.setEnv(env);
  instanceState.member.setCtx(ctx);
  // ... manual dependency wiring
  return instanceState.member;
};

With di-framework:

@Container()
export class ApplicationContext {
  constructor(
    @Component(ContactService) private contactService: ContactService,
    @Component(AssetService) private assetService: AssetService,
    @Component(TransactionService)
    private transactionService: TransactionService,
    // ... all services automatically injected
  ) {}
}

// Usage
const container = useContainer();
const appContext = container.resolve(ApplicationContext);

Benefits:

No manual service instantiation
No manual dependency wiring
Automatic singleton management
Type-safe dependency resolution
Easier to test (mock services simply by registering test implementations)
Scales better as services grow

Quick Example

import { Container, Component } from '@di-framework/core/decorators';
import { useContainer } from '@di-framework/core/container';

// Define a service
@Container()
export class DatabaseService {
  connect(): void {
    console.log('Connected to database');
  }
}

// Use it in another service
@Container()
export class UserService {
  @Component(DatabaseService)
  private db!: DatabaseService;

  getUser(id: string) {
    return this.db.query(`SELECT * FROM users WHERE id = '${id}'`);
  }
}

// Resolve and use
const container = useContainer();
const userService = container.resolve<UserService>(UserService);
userService.getUser('123');

Next Steps

Installation - Set up the framework in your project
Quick Start - Learn the basics with simple examples
CLI - Complete command tree, output contract, and package ownership
Deployment - Cloud Foundry, Cloudflare Workers, the platform, and local Kubernetes with di-framework-kube
Runtime type checks - Emit-time parameter guards (@di-framework/tsc; wired by init)
Biome plugins - GritQL rules for framework mistakes (@di-framework/biome)
Schema codegen - Generate HTTP, event, RPC, and tool surfaces from schema manifests (@di-framework/codegen)
HTTP Router - Type-safe routes and OpenAPI generation
GraphQL - Domain classes as a GraphQL schema
Events - Bridge container events to Kafka / NATS / memory
Sockets - WebSocket, TCP, UDP with a secure channel (@di-framework/socket)
RPC - JSON-RPC and per-method gRPC with a typed client (@di-framework/rpc)
Configuration - Typed config from env, JSON, YAML, and TOML via DI
Authentication - Sessions, JWT, OAuth2/OIDC, and passkeys
Resource Authorization - Declarative policies and HTTP resource enforcement
AI - Chat, tools, RAG, MCP, and agents with @di-framework/ai
Agent Skills - SKILL.md, plugins, builders, and jailed tools in @di-framework/ai-utils
AI CLI - di-framework ai commands from @di-framework/cli-plugin-ai
Repositories - Standardized data access with @di-framework/repo
API Reference - Complete API documentation
Advanced Usage - Learn advanced patterns and techniques

Last modified: 03 November 2026