@js-injection/service-provider

A lightweight, fully type-safe Dependency Injection (DI) container for TypeScript. Designed for reliability, developer experience, and minification safety.

Table of Contents

• Why this library?
• Installation
• Quick Start
• Core Features
• Cheatsheet
• Documentation
• Development
• License

Why this library?

• Strictly Typed: Full Intellisense and compile-time validation. If your code compiles, your dependencies are correctly mapped.
• Zero Runtime Dependencies: Ultra-lean with no external bloat.
• Minification Proof: Built-in stable identity system ensures resolution works even when class names are mangled.
• Modern Features: Built-in support for async factories, multiple lifetimes, circular dependency detection, and scoped resolution.
• Flexible resolution: Resolve by Class reference, string keys, or complex URI-style patterns.

Installation

npm install @js-injection/service-provider

Quick Start

1. Define your services

class Logger {
  log(msg: string) { console.log(msg); }
}

class UserService {
  constructor(private logger: Logger) {}
  greet() { this.logger.log("Hello!"); }
}

2. Create a Type Map

The TypeMap is your central contract. It maps keys to their resolved instance types.

interface MyMap {
  Logger: Logger;
  UserService: UserService;
}

3. Register and Resolve

import { ServiceCollection } from '@js-injection/service-provider';

const di = new ServiceCollection<MyMap>()
  .addSingletonClass(Logger)
  .addSingletonClass(UserService)
  .build();

const userService = di.getService(UserService);
userService.greet();

Core Features

Multiple Lifetimes

• Singleton: Created once and shared across the entire application.
• Scoped: Created once per scope (e.g., per HTTP request).

Registration API

Support for various registration methods to handle any dependency graph:

• Class Injection: addSingletonClass(Type, ...args)
  • args can be container keys, other classes, or raw values.
  • Example: .addSingletonClass(MyService, "static-api-key", OtherService)
• Factory Functions: addSingletonFactory(key, (c) => new Service(c.Other))
• Plain Functions: addSingletonFunc(key, myFunc, ...args)
• Static Values: addSingletonValue(key, { config: true })
• Service Groups: addSingletonGroup(key, ...types) (Multiple implementations for one key)

Async Support

Native support for asynchronous factories and functions.

.addSingletonFactory('db', async (c) => {
  const db = new Database();
  await db.connect();
  return db;
})

Resource Management

Support for IDisposable and IAsyncDisposable. Scopes track their own services and ensure they are cleaned up in reverse order of creation.

const scope = di.createAsyncScope();
// ... use services
await scope.disposeAsync();

Keyed Resolution & Routing

Resolve services or execute logic based on dynamic strings or URI-like patterns.

.map("GET:/users/{id:number}", (c, { id }) => c.UserService.findById(id))

const user = di.getKeyed("GET:/users/123");

Documentation

For a deep dive into all registration patterns and advanced features, see the Cheatsheet.

Development

• Build: npm run bundle
• Test: npm test
• Smoke Tests: npm run test:smoke (Runs end-to-end scenarios against minified code)

License

Licensed under ISC.

Copyright © 2026+ contributors