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). Agent Skills (SKILL.md), plugin discovery (.agents/plugins), and the skills toolbox live in @di-framework/ai-utils.
Unified CLI: di-framework is the only public executable for application, skills, HTTP, agent, and monorepo workflows.
Runtime type checks: ttsc transform @di-framework/tsc injects parameter guards from TypeScript types at emit time (di-framework init wires this by default).
wasmCloud backing services: Tenant-scoped Redis/NATS provisioning through BackingService requests, with protected ServiceBinding configuration and Kubernetes admission policies in 5.3.6. See backing services.
WebAssembly deployment: Build WASI 0.3 HTTP components with the wasmCloud CLI extension and consume native service bindings. 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, wasmCloud, and local Kubernetes with di-framework-kube
Runtime type checks - Emit-time parameter guards (@di-framework/tsc; wired by init)
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
Repositories - Standardized data access with @di-framework/repo
API Reference - Complete API documentation
Advanced Usage - Learn advanced patterns and techniques

Last modified: 15 September 2026