A lightweight, type-safe dependency injection container for TypeScript. Zero dependencies.
- 🎯 Type-Safe – Full TypeScript support with excellent type inference
- 🪶 Lightweight – Zero dependencies, minimal bundle size
- 🔄 Flexible – Classes, factories, values, and aliases
- 🎨 Optional decorators – Angular-style
@NodeInjectable()decorator - 🔗 Multi-Tokens – Built-in multi-provider support
- 🔌 Plugin System – Extensible architecture with custom middlewares, scanners, and diagnostics
- 🧪 Testkit – Utilities for easy unit testing and mocking
- 🌍 Universal – Node.js, Deno, browser, and Electron
npm install @illuma/coreAnything that supports ES2015+ (ES6+). Practically the library is compatible with Node.js (v14+) and all modern browsers. For older environments, consider using a transpiler like Babel or TypeScript or provide polyfills as needed.
import { NodeContainer, NodeInjectable, nodeInject } from '@illuma/core';
@NodeInjectable()
class Logger {
public log(message: string) {
console.log(`[LOG]: ${message}`);
}
}
@NodeInjectable()
class UserService {
private readonly logger = nodeInject(Logger);
public getUser(id: string) {
this.logger.log(`Fetching user ${id}`);
return { id, name: 'John Doe' };
}
}
const container = new NodeContainer();
container.provide([Logger, UserService]);
container.bootstrap();
const userService = container.get(UserService);Note: Requires
experimentalDecoratorsandemitDecoratorMetadatain tsconfig. See Getting Started for decorator-free alternatives.
import { NodeToken, MultiNodeToken, NodeContainer } from '@illuma/core';
// Single-value token
const CONFIG = new NodeToken<{ apiUrl: string }>('CONFIG');
// Multi-value token (when injected, returns array)
const PLUGINS = new MultiNodeToken<Plugin>('PLUGINS');
const container = new NodeContainer();
container.provide([
// Equivalent to:
// { provide: CONFIG, value: { apiUrl: 'https://api.example.com' } }
CONFIG.withValue({ apiUrl: 'https://api.example.com' }),
// Equivalent to:
// { provide: PLUGINS, useClass: AnalyticsPlugin }
PLUGINS.withClass(AnalyticsPlugin),
// Equivalent to:
// { provide: PLUGINS, useClass: LoggingPlugin }
PLUGINS.withClass(LoggingPlugin),
]);
container.bootstrap();
const config = container.get(CONFIG); // { apiUrl: string }
const plugins = container.get(PLUGINS); // Plugin[]: [AnalyticsPlugin, LoggingPlugin]See Tokens Guide for more details.
// Class provider
container.provide(MyService);
// Value provider
container.provide({ provide: CONFIG, value: { apiUrl: '...' } });
// Factory provider
container.provide({ provide: DATABASE, factory: () => {
const env = nodeInject(ENV);
return createDatabase(env.connectionString);
} });
// Class provider with custom implementation
container.provide({ provide: DATABASE, useClass: DatabaseImplementation });
// Alias provider
container.provide({ provide: Database, alias: ExistingDatabase });See Providers Guide for details.
import { createTestFactory } from '@illuma/core/testkit';
const createTest = createTestFactory({
target: UserService,
provide: [{ provide: Logger, useClass: MockLogger }],
});
it('should fetch user', () => {
const { instance } = createTest();
expect(instance.getUser('123')).toBeDefined();
});See Testing Guide for comprehensive examples.
| Guide | Description |
|---|---|
| Getting Started | Installation, setup, and basic usage |
| Providers | Value, factory, class, and alias providers |
| Tokens | NodeToken and MultiNodeToken |
| Async Injection | Lazy loading and sub-containers |
| Testing | Testkit and mocking |
| Plugins | Extending Illuma with custom scanners and diagnostics |
| Technical Overview | Deep dive into how Illuma works |
| API Reference | Complete API documentation |
| Troubleshooting | Error codes and solutions |
Illuma supports a plugin system for extending functionality. Check out these plugins:
- @illuma/reflect – Constructor metadata and property decorator injection support
See Plugins Guide for creating your own plugins.
MIT © bebrasmell