di-framework

🚀 Overview

di-framework is a modern, decorator-driven TypeScript Dependency Injection container and comprehensive suite of application companion packages. Designed for maximum performance, minimal footprint, and zero third-party runtime dependencies in core modules, it works seamlessly with TypeScript's native decorator support, SWC, bun, and esbuild.

Key Highlights

• ⚡ Zero External Dependencies: @di-framework/core and @di-framework/auth carry zero third-party runtime dependencies.
• 🎯 Native Decorator First: Elegant @Container(), @Component(), @Publisher(), @Subscriber(), and @Telemetry() decorators.
• 🔒 Type-Safe Resolution: Complete TypeScript type inference across singletons, transient services, and factory registrations.
• 🌐 Modular Ecosystem: Dedicated companion packages for HTTP, GraphQL, WebSockets/Sockets, RPC, AI, Auth, AuthZ, Configuration, Events, and Repositories.
• 🛠️ Developer Experience: Built-in CLI (@di-framework/cli) for scaffolding, typechecking (init, check, build), and custom ttsc emit-time parameter guards (@di-framework/tsc).

🗂️ Organization Projects

Public repositories in the organization:

| Project | Description | Site | | :--- | :--- | :--- | | di-framework | Core monorepo: DI, HTTP, GraphQL, events, auth, RPC, queues, actors, and the app CLI | di-framework.dev | | ai | AI clients, tools, agents, and Agent Skills (@di-framework/ai, @di-framework/ai-utils) | — | | platform | Operated wasmCloud platform: Pulumi installer, guest bindings, and the Cloud Foundry adapter | — | | cli-extensions | Installable command groups (@di-framework/cli-plugin-platform) | — | | examples | Sample applications for the framework, platform, and adapters | — | | kube | CLI for provisioning isolated Kubesolo clusters with the wasmCloud runtime operator | — | | docs | Versioned documentation and search | docs.di-framework.dev | | plugin | Agent plugin and MCP server for coding assistants | — | | .github | Organization profile and community health defaults | — |

📦 Ecosystem Packages

| Package | Description | Version | | :--- | :--- | :--- | | @di-framework/core | Core DI container, decorator metadata, and service resolver | | | @di-framework/cli | Developer CLI tool (init, check, build, maintainer mx) | | | @di-framework/cli-extension | CLI extension authoring API, command types, and manifest contract | | | @di-framework/cli-plugin-platform | CLI extension to build, serve, and deploy apps as wasmCloud WebAssembly components (di-framework platform) | | | @di-framework/platform | Cluster install: Pulumi, CRDs, controller, tenancy, and backing services | | | @di-framework/bindings | Application guest bindings and workload metadata. Through 5.x this was @di-framework/wasmcloud | | | @di-framework/tsc | TypeScript compiler transform (ttsc) for emit-time type guards | | | @di-framework/http | Type-safe HTTP routing & build-time OpenAPI 3.1 generation | | | @di-framework/graphql | Object-oriented, decorator-driven GraphQL schema generation | | | @di-framework/events | Event bus bridging @Publisher/@Subscriber to Kafka, NATS, Memory | | | @di-framework/socket | Security-first WebCrypto WebSocket, TCP, and UDP communication | | | @di-framework/rpc | Decorator-generated JSON-RPC & per-method gRPC with typed clients | | | @di-framework/config | Typed, validated configuration injection from env/files | | | @di-framework/cloudfoundry | Cloud Foundry service discovery, application metadata, and automatic DI bindings | | | @di-framework/auth | Sessions, JWT, OAuth2/OIDC, and WebAuthn passkeys on WebCrypto | | | @di-framework/authz | Resource-level authorization policies, EBNF rules & HTTP bindings | | | @di-framework/ai | Annotation-driven Chat, Tools, RAG, MCP, and AI Agents | | | @di-framework/ai-utils | Agent Skills (SKILL.md) toolbox (SkillsAgent.builder) | | | @di-framework/repo | Storage-agnostic repository abstractions and standardized data access | | | @di-framework/codegen | Contract-driven code generation for typed service interfaces | |

💻 Quick Example

import { Container, Publisher, Subscriber } from '@di-framework/core/decorators';

@Container()
class UserService {
  @Publisher('user.created')
  createUser(name: string) {
    return { id: 1, name };
  }
}

@Container()
class AuditService {
  @Subscriber('user.created')
  onUserCreated(event: any) {
    console.log('User created:', event.result);
  }
}

🛠️ Getting Started

Scaffold a new project in seconds using the CLI:

bun x @di-framework/cli init my-app
# or
npx @di-framework/cli init my-app

Check and build your application:

bun run check
bun run build

🤖 Build AI Applications

The AI repository contains chat clients, tool calling, conversation memory, RAG, MCP, and agent workflows. Use the fluent APIs directly or wire them into the DI container. Add @di-framework/ai-utils for Agent Skills and repository tools.

Chat with a model

Install the AI package and its peers. AI packages use version 6; core and auth peers remain on version 5.

bun add @di-framework/ai@^6 @di-framework/core@^5 @di-framework/auth@^5
bun add --dev typescript@^5

Save this as chat.ts:

import { ChatClient, createChatModel } from '@di-framework/ai';

const client = ChatClient.builder(createChatModel())
  .defaultSystem('You are a concise, helpful assistant.')
  .build();

const answer = await client
  .prompt('Explain dependency injection in two sentences.')
  .call()
  .content();

console.log(answer);

Set your provider's API key in the environment, then run with Bun:

# Requires OPENAI_API_KEY:
PROVIDER=openai AUTH=api bun chat.ts

# Or, with ANTHROPIC_API_KEY:
PROVIDER=anthropic AUTH=api bun chat.ts

Set MODEL to select a model explicitly. To try the client without credentials, import FakeChatModel and replace createChatModel() with new FakeChatModel('Hello!').

Give an agent a skill

bun add @di-framework/ai-utils@^6

Create .agents/skills/code-reviewer/SKILL.md in your project:

---
name: code-reviewer
description: Review TypeScript code for correctness. Use when asked to review code.
---

# Code review

1. Read the requested file.
2. Identify correctness issues and explain their impact.
3. Suggest a concrete fix for each issue.

Save this as review.ts and run it from your project directory with the same provider environment as the chat example. Replace src/index.ts with the file you want reviewed.

import { createChatModel } from '@di-framework/ai';
import { SkillsAgent } from '@di-framework/ai-utils';

const agent = SkillsAgent.builder()
  .chatModel(createChatModel())
  .system('Help review TypeScript code. Use the code-reviewer skill when reviewing.')
  .workspace(process.cwd())
  .addSkillsDirectory('.agents/skills')
  .build();

const reply = await agent.chat('Review src/index.ts.');
console.log(reply.content);

Skills expose descriptions first and load their full instructions when activated. The default toolbox includes file-reading tools; writing, editing, and shell execution are opt-in.

See the AI usage guide, AI package documentation, and skills and utilities documentation for more examples. The di-framework agent and di-framework skills CLI commands remain in the core monorepo.

📚 Documentation & Resources

• 📖 Documentation: docs.di-framework.dev
• 🏠 Website: di-framework.dev
• 📦 Monorepo Repository: github.com/di-framework/di-framework
• 📝 Migration Guide: MIGRATION_GUIDE.md
• 📄 Packaging Policy: PACKAGING.md
• 🔒 Security Policy: SECURITY.md

📄 License

Dual-licensed under either the MIT License or the Apache License (Version 2.0).