🔥 Illuma – Angular-style Dependency Injection for TypeScript

A lightweight, type-safe dependency injection container for TypeScript. Zero dependencies.

[!NOTE] This package is in early development. Expect API changes in minor versions. Planned stable release: v2.0.0

✨ Features

• 🎯 Type-Safe – Full TypeScript support with excellent type inference
• 🪶 Lightweight – Zero dependencies, minimal bundle size
• 🔄 Flexible – Classes, factories, values, and aliases
• 🎨 Decorators – Optional Angular-style @NodeInjectable() decorator
• 🔗 Multi-Tokens – Built-in multi-provider support
• 🔌 Plugin System – Extensible architecture with custom scanners and diagnostics
• 🌍 Universal – Node.js, Deno, browser, and Electron

📦 Installation

npm install @zodyac/illuma

🚀 Quick Start

import { NodeContainer, NodeInjectable, nodeInject } from '@zodyac/illuma';

@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 experimentalDecorators and emitDecoratorMetadata in tsconfig. See Getting Started for decorator-free alternatives.

🏷️ Using Tokens

import { NodeToken, MultiNodeToken, NodeContainer } from '@zodyac/illuma';

// 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.

🎨 Provider Types

// 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.

🧪 Testing

import { createTestFactory } from '@zodyac/illuma/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.

📚 Documentation

| 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 |

🔌 Plugins

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.

📄 License

MIT © bebrasmell

🔗 Links

• GitHub
• NPM
• Issues