SpireX/DI

@spirex/di is a powerful, lightweight, and predictable dependency injection library for JavaScript and TypeScript.

It enforces strict TypeScript typing through a TypeMap, uses an immutable container built via a fluent builder API, and supports modular, reusable configurations. With zero dependencies, advanced scope management, and extensible middleware, it keeps your code clean, testable, and flexible without imposing any runtime boilerplate.

Fully plug & play and production-ready, SpireX/DI is ideal for enterprise projects, helping teams manage complex service graphs effortlessly while simplifying long-term maintenance.

Features

• Immutable container — no hidden runtime mutations;
• Maximum type safety — full autocompletion & compile-time checks;
• Modular — static & dynamic modules;
• Advanced scope management with auto-dispose;
• Lifecycle management — singleton, lazy, scope, transient;
• Middleware support;
• Named bindings, aliases & conflict resolution strategies;
• Zero dependencies, runs on pure JS, only ~9.3KB (~3.4kb gzipped).

Installing

# npm
npm i @spirex/di

# yarn
yarn add @spirex/di

Quick Start

import { diBuilder, factoryOf } from "@spirex/di";

class Gateway { ... }

class Service {
    static inject = ['gateway'] as const
    constructor(gateway: Gateway) {...}
    doSomething(): void { ... }
}

// Create a DI container with strict type mapping
const container = diBuilder<{
    gateway: Gateway; // Key 'gateway' maps to Gateway instance
    service: Service; // Key 'service' maps to Service instance
}>()
    // Bind 'service' to a factory
    // that resolves its dependencies from the container
    .bindFactory("service", factoryOf(Service))

    // Bind 'gateway' to a Gateway factory
    .bindFactory("gateway", factoryOf(Gateway))

    // Build the container;
    // after this, it becomes immutable & ready to use
    .build();

// Retrieve the 'service' instance from the container
const service = container.get("service");

Explanation:

1. We define Gateway and Service classes. Service depends on Gateway.
2. We create a strictly typed container using diBuilder().
3. .bindFactory is used to register services with dependencies.
4. .build() finalizes the container.
5. .get("service") returns the fully constructed Service with Gateway automatically injected.

Documentation

• Introduction
• Philosophy
• Installation
• Getting Started
• Basics
  • Container Configuration
    • Container Builder
    • About TypeMap
    • Instance Binding
    • Factory Binding
    • Safe Factory Binding
    • Class Factory
    • Named Binding
    • Binding Conflicts
    • Multiple Binding
    • Lifecycles
    • Aliases
    • Container Build
  • Modules
    • Static Modules
    • Module Dependencies
  • Resolving Instances
    • Type Enumeration
    • Get Instance of Type
    • Getting optional instances
    • Getting all instances of a type
    • Provider Functions
    • Phantom Instance
• Advanced
  • Container Builder
    • Container Builder Default Options
    • Enforcing Type Bindings
    • Injecting Dependencies into Existing Services

Documentation is a work in progress! Some topics are not yet covered. For the most up-to-date documentation, please refer to the repository.

Integrations & Extensions

Container is designed to be fully extensible and works seamlessly with additional packages to enhance functionality:

| Package | Description | | ------- | ----------- | | @spirex/di-dynamic | SpireX/DI Dynamic Modules - allowing you to load parts of your container asynchronously at runtime. | | @spirex/di-react | SpireX/DI for React - provides a fully typed, declarative, and scoped DI system built on top of the React Context API and hooks. | | @spirex/di-svelte | SpireX/DI for Svelte - provides Svelte integration for injecting dependencies into components.| | @spirex/di-angular-bridge | Using SpireX/DI as a domain-level service container with standard Angular DI access. | | @spirex/di-config | SpireX/DI Config - provides a middleware that configures services right after they are created. |

License

@spirex/di is released under the MIT License.

You are free to use, modify, and distribute the library in both personal and commercial projects.