injectkit 1.0.0

package/README.md

@@ -0,0 +1,457 @@
+# InjectKit
+
+[![codecov](https://codecov.io/github/MaroonedSoftware/InjectKit/graph/badge.svg?token=suXBzveqVf)](https://codecov.io/github/MaroonedSoftware/InjectKit)
+
+---
+
+<p align="center">
+  <strong>A lightweight, type-safe dependency injection container for TypeScript</strong>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#core-concepts">Core Concepts</a> •
+  <a href="#api-reference">API Reference</a> •
+  <a href="#license">License</a>
+</p>
+
+---
+
+## Features
+
+- 🎯 **Type-safe** — Full TypeScript support with strong typing throughout
+- 🪶 **Lightweight** — Minimal footprint with zero dependencies (except `reflect-metadata`)
+- 🔄 **Multiple lifetimes** — Singleton, transient, and scoped instance management
+- 🏭 **Flexible registration** — Classes, factories, or existing instances
+- 📦 **Collection support** — Register arrays and maps of implementations
+- 🔍 **Validation** — Automatic detection of missing and circular dependencies
+- 🧪 **Test-friendly** — Easy mocking with scoped container overrides
+
+## Installation
+
+```bash
+npm install injectkit reflect-metadata
+```
+
+```bash
+pnpm add injectkit reflect-metadata
+```
+
+```bash
+yarn add injectkit reflect-metadata
+```
+
+## Requirements
+
+- **Node.js** >= 20
+- **TypeScript** with the following compiler options enabled:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+- Import `reflect-metadata` **once** at your application entry point:
+
+```typescript
+import 'reflect-metadata';
+```
+
+## Quick Start
+
+```typescript
+import 'reflect-metadata';
+import { Injectable, InjectKitRegistry, Container } from 'injectkit';
+
+// 1. Decorate your classes with @Injectable()
+@Injectable()
+class Logger {
+  log(message: string) {
+    console.log(`[LOG] ${message}`);
+  }
+}
+
+@Injectable()
+class UserService {
+  constructor(private logger: Logger) {}
+
+  createUser(name: string) {
+    this.logger.log(`Creating user: ${name}`);
+    return { id: crypto.randomUUID(), name };
+  }
+}
+
+// 2. Create a registry and register your services
+const registry = new InjectKitRegistry();
+registry.register(Logger).useClass(Logger).asSingleton();
+registry.register(UserService).useClass(UserService).asSingleton();
+
+// 3. Build the container
+const container = registry.build();
+
+// 4. Resolve and use your services
+const userService = container.get(UserService);
+userService.createUser('Alice');
+```
+
+## Core Concepts
+
+### Registry
+
+The **Registry** is where you configure your services before runtime. It validates all registrations when building the container.
+
+```typescript
+const registry = new InjectKitRegistry();
+
+// Register services
+registry.register(MyService).useClass(MyService).asSingleton();
+
+// Check if registered
+registry.isRegistered(MyService); // true
+
+// Remove if needed
+registry.remove(MyService);
+
+// Build the container when ready
+const container = registry.build();
+```
+
+### Container
+
+The **Container** resolves and manages service instances at runtime. It automatically injects dependencies declared in constructors.
+
+```typescript
+// Resolve a service (dependencies are injected automatically)
+const service = container.get(MyService);
+
+// The Container itself can be resolved for factory patterns
+const container = container.get(Container);
+```
+
+### Identifier
+
+An **Identifier** is a class constructor or abstract class used to register and resolve services. This enables programming to interfaces:
+
+```typescript
+// Abstract class as identifier
+abstract class Repository {
+  abstract find(id: string): Promise<Entity>;
+}
+
+// Concrete implementation
+@Injectable()
+class PostgresRepository extends Repository {
+  async find(id: string) {
+    /* ... */
+  }
+}
+
+// Register abstract → concrete mapping
+registry.register(Repository).useClass(PostgresRepository).asSingleton();
+
+// Resolve using the abstract class
+const repo = container.get(Repository); // Returns PostgresRepository
+```
+
+### Lifetimes
+
+InjectKit supports three lifetime strategies:
+
+| Lifetime      | Behavior                                          |
+| ------------- | ------------------------------------------------- |
+| **Singleton** | One instance shared across the entire application |
+| **Transient** | New instance created on every `get()` call        |
+| **Scoped**    | One instance per scope, shared within that scope  |
+
+```typescript
+registry.register(ConfigService).useClass(ConfigService).asSingleton();
+registry.register(RequestId).useClass(RequestId).asScoped();
+registry.register(TempCalculation).useClass(TempCalculation).asTransient();
+```
+
+## API Reference
+
+### Registration Methods
+
+#### `useClass(constructor)`
+
+Register a service using its constructor. Dependencies are automatically resolved from constructor parameters.
+
+```typescript
+@Injectable()
+class EmailService {
+  constructor(
+    private config: ConfigService,
+    private logger: Logger,
+  ) {}
+}
+
+registry.register(EmailService).useClass(EmailService).asSingleton();
+```
+
+#### `useFactory(factory)`
+
+Register a service using a factory function. Useful for complex initialization or third-party libraries.
+
+```typescript
+registry
+  .register(DatabaseConnection)
+  .useFactory(container => {
+    const config = container.get(ConfigService);
+    return new DatabaseConnection({
+      host: config.dbHost,
+      port: config.dbPort,
+    });
+  })
+  .asSingleton();
+```
+
+#### `useInstance(instance)`
+
+Register an existing instance directly. Always behaves as a singleton.
+
+```typescript
+const config = new ConfigService({ env: 'production' });
+registry.register(ConfigService).useInstance(config);
+```
+
+#### `useArray(constructor)`
+
+Register a collection of implementations. Useful for plugin systems or strategy patterns.
+
+```typescript
+// Handler implementations
+@Injectable()
+class JsonHandler extends Handler {
+  /* ... */
+}
+
+@Injectable()
+class XmlHandler extends Handler {
+  /* ... */
+}
+
+// Array container
+@Injectable()
+class Handlers extends Array<Handler> {}
+
+// Registration
+registry.register(JsonHandler).useClass(JsonHandler).asSingleton();
+registry.register(XmlHandler).useClass(XmlHandler).asSingleton();
+registry.register(Handlers).useArray(Handlers).push(JsonHandler).push(XmlHandler);
+
+// Usage
+const handlers = container.get(Handlers);
+handlers.forEach(h => h.handle(data));
+```
+
+#### `useMap(constructor)`
+
+Register a keyed collection of implementations.
+
+```typescript
+@Injectable()
+class ProcessorMap extends Map<string, Processor> {}
+
+registry.register(ProcessorMap).useMap(ProcessorMap).set('fast', FastProcessor).set('accurate', AccurateProcessor);
+
+// Usage
+const processors = container.get(ProcessorMap);
+const processor = processors.get('fast');
+```
+
+### Container Methods
+
+#### `get<T>(identifier): T`
+
+Resolves an instance of the specified type.
+
+```typescript
+const service = container.get(MyService);
+```
+
+#### `createScopedContainer(): ScopedContainer`
+
+Creates a child container for scoped instance management.
+
+```typescript
+const requestScope = container.createScopedContainer();
+const requestService = requestScope.get(RequestScopedService);
+```
+
+#### `override<T>(identifier, instance): void`
+
+Overrides a registration within a scoped container. Perfect for testing.
+
+```typescript
+const testScope = container.createScopedContainer();
+
+// Override with a mock
+testScope.override(EmailService, {
+  send: vi.fn().mockResolvedValue(true),
+} as EmailService);
+
+// Tests use the mock
+const service = testScope.get(NotificationService);
+```
+
+### Registry Methods
+
+#### `register<T>(identifier): RegistrationType<T>`
+
+Starts a registration chain for a service.
+
+#### `remove<T>(identifier): void`
+
+Removes a registration from the registry.
+
+#### `isRegistered<T>(identifier): boolean`
+
+Checks if a service is already registered.
+
+#### `build(): Container`
+
+Builds the container, validating all registrations.
+
+## Scoped Containers
+
+Scoped containers enable request-scoped or unit-of-work patterns:
+
+```typescript
+@Injectable()
+class RequestContext {
+  readonly requestId = crypto.randomUUID();
+  readonly startTime = Date.now();
+}
+
+registry.register(RequestContext).useClass(RequestContext).asScoped();
+
+// Per-request handling
+app.use((req, res, next) => {
+  const scope = container.createScopedContainer();
+
+  // Same RequestContext instance throughout this request
+  const ctx = scope.get(RequestContext);
+  req.scope = scope;
+
+  next();
+});
+```
+
+### Scope Hierarchy
+
+Scoped containers inherit instances from parent scopes:
+
+```typescript
+const root = registry.build();
+const scope1 = root.createScopedContainer();
+const scope2 = scope1.createScopedContainer();
+
+// Instance created in scope1 is visible in scope2
+const instance1 = scope1.get(ScopedService);
+const instance2 = scope2.get(ScopedService);
+console.log(instance1 === instance2); // true
+```
+
+## Validation
+
+InjectKit validates your dependency graph when calling `build()`:
+
+### Missing Dependencies
+
+```typescript
+@Injectable()
+class UserService {
+  constructor(private db: DatabaseService) {} // Not registered!
+}
+
+registry.register(UserService).useClass(UserService).asSingleton();
+registry.build(); // ❌ Error: Missing dependencies for UserService: DatabaseService
+```
+
+### Circular Dependencies
+
+```typescript
+@Injectable()
+class ServiceA {
+  constructor(private b: ServiceB) {}
+}
+
+@Injectable()
+class ServiceB {
+  constructor(private a: ServiceA) {}
+}
+
+registry.register(ServiceA).useClass(ServiceA).asSingleton();
+registry.register(ServiceB).useClass(ServiceB).asSingleton();
+registry.build(); // ❌ Error: Circular dependency found: ServiceA -> ServiceB -> ServiceA
+```
+
+### Missing Decorator
+
+```typescript
+class ForgotDecorator {
+  constructor(private dep: SomeDependency) {}
+}
+
+registry.register(ForgotDecorator).useClass(ForgotDecorator).asSingleton();
+registry.build(); // ❌ Error: Service not decorated: ForgotDecorator
+```
+
+## Testing
+
+InjectKit makes testing easy with scoped overrides:
+
+```typescript
+import { describe, it, expect, beforeEach } from 'vitest';
+
+describe('UserService', () => {
+  let scope: ScopedContainer;
+  let mockDb: DatabaseService;
+
+  beforeEach(() => {
+    scope = container.createScopedContainer();
+
+    mockDb = {
+      query: vi.fn().mockResolvedValue([{ id: '1', name: 'Test' }]),
+    } as unknown as DatabaseService;
+
+    scope.override(DatabaseService, mockDb);
+  });
+
+  it('should fetch users', async () => {
+    const userService = scope.get(UserService);
+    const users = await userService.getUsers();
+
+    expect(users).toHaveLength(1);
+    expect(mockDb.query).toHaveBeenCalled();
+  });
+});
+```
+
+## TypeScript Configuration
+
+Recommended `tsconfig.json` settings:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "strict": true
+  }
+}
+```
+
+## License
+
+MIT

package/dist/container.d.ts

@@ -0,0 +1,63 @@
+import { Container, Identifier, Instance, ScopedContainer } from './interfaces.js';
+import { Registration } from './internal.js';
+/**
+ * Implementation of the dependency injection container.
+ * Manages service registrations and resolves instances based on their lifetime strategy.
+ */
+export declare class InjectKitContainer implements ScopedContainer, Container {
+    private readonly registrations;
+    private readonly parent?;
+    /** Map storing cached instances for singleton and scoped lifetimes. */
+    private readonly instances;
+    /**
+     * Creates a new container instance.
+     * @param registrations Map of registered services and their configurations.
+     * @param parent Optional parent container for scoped container hierarchies.
+     */
+    constructor(registrations: Map<Identifier<unknown>, Registration<unknown>>, parent?: InjectKitContainer | undefined);
+    /**
+     * Creates a new instance of the specified type based on its registration configuration.
+     * Handles constructor-based, factory-based, and instance-based registrations.
+     * Manages singleton and scoped instance caching.
+     * Also handles array and map collection dependencies by populating them with resolved instances.
+     * @template T The type of instance to create.
+     * @param id The identifier for the type to instantiate.
+     * @param registration The registration configuration containing creation strategy.
+     * @returns A new or cached instance of type T.
+     * @throws {Error} If the registration is invalid (no constructor, factory, or instance provided).
+     */
+    private createInstance;
+    /**
+     * Retrieves a cached scoped instance by traversing up the container hierarchy.
+     * For scoped lifetimes, instances are stored in the container where they were created.
+     * @template T The type of instance to retrieve.
+     * @param id The identifier for the type to retrieve.
+     * @returns The cached scoped instance, or undefined if not found.
+     */
+    private getScopedInstance;
+    /**
+     * Retrieves an instance of the specified type from the container.
+     * For singleton and scoped lifetimes, returns cached instances when available.
+     * For transient lifetimes, creates a new instance each time.
+     * @template T The type of instance to retrieve.
+     * @param id The identifier (constructor or abstract class) for the type to resolve.
+     * @returns An instance of type T.
+     * @throws {Error} If no registration is found for the specified identifier.
+     */
+    get<T>(id: Identifier<T>): T;
+    /**
+     * Creates a new scoped container that inherits all registrations from this container.
+     * Scoped containers allow for per-scope instance management, where scoped services
+     * are shared within a scope but isolated between different scopes.
+     * @returns A new scoped container instance with this container as its parent.
+     */
+    createScopedContainer(): ScopedContainer;
+    /**
+     * Overrides the instance of the specified type in the container.
+     * @template T The type of instance to override.
+     * @param id The identifier for the type to override.
+     * @param instance The instance to override.
+     */
+    override<T>(id: Identifier<T>, instance: Instance<T>): void;
+}
+//# sourceMappingURL=container.d.ts.map

package/dist/container.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,eAAe,EAAE,SAAS;IAUjE,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAV1B,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2C;IAErE;;;;OAIG;gBAEgB,aAAa,EAAE,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,EAC9D,MAAM,CAAC,EAAE,kBAAkB,YAAA;IAG9C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;IA8CtB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;;;;;;;OAQG;IACI,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC;IAgBnC;;;;;OAKG;IACI,qBAAqB,IAAI,eAAe;IAI/C;;;;;OAKG;IACI,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI;CAYnE"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './injectable.js';
+export * from './interfaces.js';
+export * from './registry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC"}