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 configurations with internal types and composite modules. With zero dependencies, advanced scope management (including local scope data), 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, internal types, composite modules;
• Advanced scope management — auto-dispose, local scope data, sealed & isolated scopes;
• Lifecycle management — singleton, lazy, scope, transient;
• Middleware — resolution stack, alias hooks, typed TypeMap extension;
• Named bindings, aliases, conflict resolution strategies, alias search;
• Zero dependencies, runs on pure JS, only ~9Kb (~3.7Kb 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.

Recent Improvements (v1.2.0)

• Internal module types — hide implementation details within modules; types marked internal are inaccessible outside the module at runtime;
• Module composition — group modules with staticModule("id").compose(A, B, C) for reusable, hierarchical configurations;
• Local scope data — attach immutable, context-specific data to scopes (e.g. request URI, session ID);
• Resolution stack — middleware hooks onRequest and onResolve receive the full resolution chain for diagnostics and instrumentation;
• Alias hooks & search — onBindAlias middleware hook and findAlias builder method for alias introspection.

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
  • Resolving Instances
    • Type Enumeration
    • Get Instance of Type
    • Getting optional instances
    • Getting all instances of a type
    • Provider Functions
    • Phantom Instance
  • Modules
    • Static Modules
    • Module Dependencies
    • Internal Module Types
    • Module Composition
• Advanced
  • Container Builder
    • Container Builder Default Options
    • Enforcing Type Bindings
    • Injecting Dependencies into Existing Services
    • Binding Metadata

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-solid	SpireX/DI for SolidJS - provides Solid integration for injecting dependencies into components via context and useInject.
@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.
@spirex/di-shared	DIFacade DI for migration — safely use DI globally while tracking and eliminating it during migration.

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.