ampulla

ampulla is a modern dependency injection (DI) library designed for TypeScript, prioritizing type safety and simplicity reminiscent of NestJS without the overhead of a framework. This library offers a robust and ergonomic solution for those looking to manage dependencies in their applications with confidence, ensuring every component is well typed.

Key Features:

• End-to-End Type Safety: With ampulla, fetching a service returns the correct type, greatly reducing the chance of runtime errors. For example:

  const userService = container.get(MyService);  // userService is typed as MyService
  

  Type mismatches are detected at compile time, preventing potential runtime issues.

• No reflect-metadata: The library utilizes TC39 Stage 3 decorators, eliminating reliance on experimental decorators and ensuring compatibility with future updates in TypeScript metadata output.

• Zero Dependencies: The framework is built to be independent, with type-only adapters for popular libraries like Hono and H3. This means that only the necessary runtime components are included, avoiding unnecessary bloat in applications.

• Tree-shakeable Architecture: Each HTTP adapter is separated into distinct entry points. If an adapter is not imported, it is excluded from the final bundle, reducing the application's footprint.

• Module-Scoped Visibility: Unlike global registries, ampulla restricts the visibility of providers to their respective modules, enhancing encapsulation and modularization in applications.

• Built-In Testing Capabilities: The library includes a TestingContainer, making it easy to create isolated modules for unit testing without needing complex setup. This allows for rapid development and verification of service behaviors.

Usage Example:

To declare and utilize services, ampulla provides a straightforward API. Here’s how one might set up a basic application:

import { Container, Module, Injectable, injection, useValue } from "ampulla";

const DB_URL = injection<string>("DB_URL");

@Injectable(DB_URL)
class UserService {
  constructor(private readonly url: string) {}
  findAll() {
    return fetch(`${this.url}/users`).then((r) => r.json());
  }
}

@Module({
  providers: [useValue(DB_URL, "https://api.example.com"), UserService],
  exports: [UserService],
})
class AppModule {}

const container = await Container.create(AppModule);
const users = container.get(UserService); // injected typing guaranteed

In the example above, the UserService is injected with the DB_URL, and TypeScript ensures that the provided type is accurate.

Additional Features:

• Dependency Injection Tokens: Create tokens for non-class dependencies using injection<T>(). This enhances the flexibility and reusability of service declarations.
• Lifecycle Hooks: Utilize lifecycle hooks to coordinate service initialization and cleanup, ensuring that dependencies are fully operational when needed.
• Support for HTTP Adapters: Quickly configure services with built-in support for Hono and H3, allowing developers to seamlessly integrate ampulla with their web applications.

For comprehensive documentation on usage and advanced features, check the Core Concepts of ampulla. This library is ideal for TypeScript developers seeking a streamlined, powerful, and type-safe dependency injection solution.