@djodjonx/neo-syringe 1.2.0 → 1.2.2

package/docs/guide/parent-container.md

@@ -0,0 +1,321 @@
+# Parent Container
+
+Build hierarchical container architectures with `useContainer`.
+
+## Overview
+
+Neo-Syringe supports parent containers for:
+
+- **SharedKernel pattern**: Core services shared across bounded contexts
+- **Modular architecture**: Each module has its own container
+- **Testing**: Override production services with mocks
+
+## Basic Usage
+
+```typescript
+import { defineBuilderConfig, useInterface } from '@djodjonx/neo-syringe';
+
+// Parent container
+const sharedKernel = defineBuilderConfig({
+  name: 'SharedKernel',
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger },
+    { token: useInterface<IEventBus>(), provider: InMemoryEventBus }
+  ]
+});
+
+// Child container
+const userModule = defineBuilderConfig({
+  name: 'UserModule',
+  useContainer: sharedKernel,  // 👈 Inherit from parent
+  injections: [
+    { token: UserRepository },
+    { token: UserService }     // Can use ILogger and IEventBus!
+  ]
+});
+```
+
+## Resolution Order
+
+When you call `resolve()`, Neo-Syringe looks up the token in this order:
+
+```
+1. Local container (this container's injections)
+   └── Found? → Return instance
+   └── Not found? ↓
+
+2. Parent container (useContainer)
+   └── Found? → Return instance
+   └── Not found? ↓
+
+3. Throw "Service not found" error
+```
+
+## SharedKernel Architecture
+
+Perfect for Domain-Driven Design with shared infrastructure:
+
+```typescript
+// shared-kernel/container.ts
+export interface ILogger {
+  log(msg: string): void;
+}
+
+export interface IEventBus {
+  publish(event: any): void;
+}
+
+class ConsoleLogger implements ILogger {
+  log(msg: string) { console.log(`[LOG] ${msg}`); }
+}
+
+class InMemoryEventBus implements IEventBus {
+  publish(event: any) { console.log('Event:', event); }
+}
+
+export const sharedKernel = defineBuilderConfig({
+  name: 'SharedKernel',
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger },
+    { token: useInterface<IEventBus>(), provider: InMemoryEventBus }
+  ]
+});
+```
+
+```typescript
+// user-module/container.ts
+import { sharedKernel, ILogger, IEventBus } from '../shared-kernel';
+
+class UserRepository {
+  constructor(private logger: ILogger) {}
+  
+  findById(id: string) {
+    this.logger.log(`Finding user ${id}`);
+    return { id, name: 'John' };
+  }
+}
+
+class UserService {
+  constructor(
+    private logger: ILogger,      // From SharedKernel
+    private eventBus: IEventBus,  // From SharedKernel
+    private repo: UserRepository  // Local
+  ) {}
+  
+  createUser(name: string) {
+    const user = { id: crypto.randomUUID(), name };
+    this.logger.log(`Creating user: ${name}`);
+    this.eventBus.publish({ type: 'UserCreated', user });
+    return user;
+  }
+}
+
+export const userModule = defineBuilderConfig({
+  name: 'UserModule',
+  useContainer: sharedKernel,
+  injections: [
+    { token: UserRepository },
+    { token: UserService }
+  ]
+});
+```
+
+```typescript
+// order-module/container.ts
+import { sharedKernel, ILogger } from '../shared-kernel';
+
+class OrderService {
+  constructor(private logger: ILogger) {}  // From SharedKernel
+}
+
+export const orderModule = defineBuilderConfig({
+  name: 'OrderModule',
+  useContainer: sharedKernel,
+  injections: [
+    { token: OrderService }
+  ]
+});
+```
+
+```typescript
+// main.ts
+import { userModule } from './user-module/container';
+import { orderModule } from './order-module/container';
+
+// Both modules share the same ILogger and IEventBus instances!
+const userService = userModule.resolve(UserService);
+const orderService = orderModule.resolve(OrderService);
+```
+
+## Multi-Level Hierarchy
+
+Chain containers for complex architectures:
+
+```typescript
+// Level 1: Infrastructure
+const infrastructure = defineBuilderConfig({
+  name: 'Infrastructure',
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger },
+    { token: useInterface<IDatabase>(), provider: PostgresDatabase }
+  ]
+});
+
+// Level 2: Domain (inherits Infrastructure)
+const domain = defineBuilderConfig({
+  name: 'Domain',
+  useContainer: infrastructure,
+  injections: [
+    { token: UserRepository },
+    { token: OrderRepository }
+  ]
+});
+
+// Level 3: Application (inherits Domain + Infrastructure)
+const application = defineBuilderConfig({
+  name: 'Application',
+  useContainer: domain,  // Gets Domain AND Infrastructure!
+  injections: [
+    { token: UserService },
+    { token: OrderService }
+  ]
+});
+
+// Resolution traverses the chain
+application.resolve(UserService);      // Local
+application.resolve(UserRepository);   // From Domain
+application.resolve(useInterface<ILogger>()); // From Infrastructure
+```
+
+## Validation
+
+Neo-Syringe validates parent containers at compile-time:
+
+### Duplicate Detection
+
+```typescript
+const parent = defineBuilderConfig({
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger }
+  ]
+});
+
+// ❌ Error: Duplicate registration
+const child = defineBuilderConfig({
+  useContainer: parent,
+  injections: [
+    { token: useInterface<ILogger>(), provider: FileLogger }
+  ]
+});
+```
+
+**Solution**: Use `scoped: true` for intentional overrides.
+
+### Missing Dependencies
+
+```typescript
+const parent = defineBuilderConfig({
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger }
+  ]
+});
+
+class UserService {
+  constructor(
+    private logger: ILogger,
+    private db: IDatabase  // Not in parent!
+  ) {}
+}
+
+// ❌ Error: Missing binding 'IDatabase'
+const child = defineBuilderConfig({
+  useContainer: parent,
+  injections: [
+    { token: UserService }
+  ]
+});
+```
+
+## Generated Code
+
+The parent relationship is preserved in generated code:
+
+```typescript
+// Configuration
+export const child = defineBuilderConfig({
+  name: 'ChildContainer',
+  useContainer: parent,
+  injections: [
+    { token: UserService }
+  ]
+});
+
+// Generated code
+import { parent } from './parent';
+
+class NeoContainer {
+  constructor(
+    private parent = parent  // 👈 Reference to parent
+  ) {}
+
+  resolve(token) {
+    const local = this.resolveLocal(token);
+    if (local !== undefined) return local;
+
+    // Delegate to parent
+    if (this.parent) {
+      return this.parent.resolve(token);
+    }
+
+    throw new Error('Service not found');
+  }
+}
+
+export const child = new NeoContainer();
+```
+
+## Best Practices
+
+### 1. Name Your Containers
+
+Names appear in error messages for easier debugging:
+
+```typescript
+defineBuilderConfig({
+  name: 'UserModule',  // ✅ Shows in errors
+  // ...
+});
+
+// Error: [UserModule] Service not found: XYZ
+```
+
+### 2. Keep SharedKernel Minimal
+
+Only put truly shared services in the SharedKernel:
+
+```typescript
+// ✅ Good: Cross-cutting concerns
+{ token: useInterface<ILogger>() }
+{ token: useInterface<IEventBus>() }
+{ token: useInterface<IDateTime>() }
+
+// ❌ Bad: Domain-specific services
+{ token: UserService }
+{ token: OrderService }
+```
+
+### 3. Use Scoped for Overrides
+
+When you need a different implementation locally:
+
+```typescript
+const child = defineBuilderConfig({
+  useContainer: parent,
+  injections: [
+    { token: useInterface<ILogger>(), provider: FileLogger, scoped: true }
+  ]
+});
+```
+
+See [Scoped Injections](/guide/scoped-injections) for details.
+

package/docs/guide/scoped-injections.md

@@ -0,0 +1,271 @@
+# Scoped Injections
+
+Override parent container tokens with local resolution using `scoped: true`.
+
+## The Problem
+
+When you use a parent container with `useContainer`, you might want to **override** a token for your specific module:
+
+```typescript
+const parent = defineBuilderConfig({
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger }
+  ]
+});
+
+// ❌ This throws an error!
+const child = defineBuilderConfig({
+  useContainer: parent,
+  injections: [
+    { token: useInterface<ILogger>(), provider: FileLogger }  // Duplicate!
+  ]
+});
+// Error: Duplicate registration: 'ILogger' is already registered in parent
+```
+
+## The Solution: `scoped: true`
+
+Use `scoped: true` to tell Neo-Syringe that this token should be **resolved locally** instead of delegating to the parent:
+
+```typescript
+const child = defineBuilderConfig({
+  useContainer: parent,
+  injections: [
+    { 
+      token: useInterface<ILogger>(), 
+      provider: FileLogger,
+      scoped: true  // ✅ Resolved in THIS container
+    }
+  ]
+});
+```
+
+## How It Works
+
+### Without `scoped: true`
+
+Resolution delegates to the parent:
+
+```
+child.resolve(ILogger)
+        │
+        ▼
+   Not found locally
+        │
+        ▼
+   Delegate to parent
+        │
+        ▼
+   parent.resolve(ILogger)
+        │
+        ▼
+   Returns ConsoleLogger
+```
+
+### With `scoped: true`
+
+Resolution stays local:
+
+```
+child.resolve(ILogger)
+        │
+        ▼
+   Found locally (scoped)
+        │
+        ▼
+   Returns FileLogger ✅
+```
+
+## Visual Comparison
+
+```
+Without scoped: true                    With scoped: true
+┌─────────────────────┐                ┌─────────────────────┐
+│    ChildContainer   │                │    ChildContainer   │
+│  resolve(ILogger)   │                │  resolve(ILogger)   │
+│         │           │                │         │           │
+│         ▼           │                │    ┌────▼────┐      │
+│   Not found locally │                │    │ LOCAL   │      │
+│         │           │                │    │FileLogger│      │
+│         ▼           │                │    └─────────┘      │
+│  ┌──────────────┐   │                │  ✅ Returns local   │
+│  │ Delegate to  │   │                │     instance        │
+│  │    Parent    │   │                └─────────────────────┘
+│  └──────┬───────┘   │
+│         ▼           │
+│  ConsoleLogger      │
+│  from parent        │
+└─────────────────────┘
+```
+
+## Behavior Summary
+
+| Aspect | Without `scoped` | With `scoped: true` |
+|--------|------------------|---------------------|
+| Token in parent | ❌ Duplicate error | ✅ Override allowed |
+| Resolution | Delegates to parent | **Resolved locally** |
+| Instance | Parent's instance | Container's own instance |
+| Lifecycle | Parent's lifecycle | Can define different lifecycle |
+
+## Use Cases
+
+### 🧪 Testing
+
+Override production services with mocks:
+
+```typescript
+// Production container
+const production = defineBuilderConfig({
+  injections: [
+    { token: useInterface<IDatabase>(), provider: PostgresDatabase },
+    { token: useInterface<IEmailService>(), provider: SendGridService },
+    { token: UserService }
+  ]
+});
+
+// Test container - override external services
+const testing = defineBuilderConfig({
+  useContainer: production,
+  injections: [
+    { token: useInterface<IDatabase>(), provider: InMemoryDatabase, scoped: true },
+    { token: useInterface<IEmailService>(), provider: MockEmailService, scoped: true }
+  ]
+});
+
+// UserService uses mocked dependencies
+const userService = testing.resolve(UserService);
+```
+
+### 🔧 Module Isolation
+
+Each module has its own instance of a shared token:
+
+```typescript
+const sharedKernel = defineBuilderConfig({
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger }
+  ]
+});
+
+// User module - wants file logging
+const userModule = defineBuilderConfig({
+  useContainer: sharedKernel,
+  injections: [
+    { token: useInterface<ILogger>(), provider: FileLogger, scoped: true },
+    { token: UserService }  // Uses FileLogger
+  ]
+});
+
+// Order module - wants console logging (from parent)
+const orderModule = defineBuilderConfig({
+  useContainer: sharedKernel,
+  injections: [
+    { token: OrderService }  // Uses ConsoleLogger from parent
+  ]
+});
+```
+
+### ⚙️ Different Lifecycle
+
+Parent uses singleton, child uses transient:
+
+```typescript
+const parent = defineBuilderConfig({
+  injections: [
+    { token: useInterface<IRequestContext>(), provider: RequestContext, lifecycle: 'singleton' }
+  ]
+});
+
+// Child needs new instance per request
+const requestScoped = defineBuilderConfig({
+  useContainer: parent,
+  injections: [
+    { 
+      token: useInterface<IRequestContext>(), 
+      provider: RequestContext,
+      lifecycle: 'transient',  // Different lifecycle!
+      scoped: true
+    }
+  ]
+});
+```
+
+### 🔒 Encapsulation
+
+Keep a local version without affecting other consumers:
+
+```typescript
+const shared = defineBuilderConfig({
+  injections: [
+    { token: useInterface<ICache>(), provider: RedisCache }
+  ]
+});
+
+// This module needs its own cache
+const isolatedModule = defineBuilderConfig({
+  useContainer: shared,
+  injections: [
+    { 
+      token: useInterface<ICache>(), 
+      provider: MemoryCache,  // Local cache only
+      scoped: true
+    },
+    { token: SensitiveService }
+  ]
+});
+
+// Other modules still use RedisCache
+const otherModule = defineBuilderConfig({
+  useContainer: shared,
+  injections: [
+    { token: OtherService }  // Uses RedisCache
+  ]
+});
+```
+
+## Multi-Level Hierarchy
+
+`scoped: true` works at any level:
+
+```typescript
+// Level 1: Infrastructure
+const infrastructure = defineBuilderConfig({
+  injections: [
+    { token: useInterface<ILogger>(), provider: ConsoleLogger },
+    { token: useInterface<IDatabase>(), provider: PostgresDatabase }
+  ]
+});
+
+// Level 2: Domain (inherits all)
+const domain = defineBuilderConfig({
+  useContainer: infrastructure,
+  injections: [
+    { token: UserRepository }
+  ]
+});
+
+// Level 3: Test (overrides only ILogger)
+const test = defineBuilderConfig({
+  useContainer: domain,
+  injections: [
+    { token: useInterface<ILogger>(), provider: MockLogger, scoped: true }
+    // IDatabase still comes from infrastructure
+  ]
+});
+
+test.resolve(useInterface<ILogger>());    // MockLogger (scoped)
+test.resolve(useInterface<IDatabase>());  // PostgresDatabase (from infrastructure)
+test.resolve(UserRepository);              // From domain
+```
+
+## Error Messages
+
+When you forget `scoped: true`:
+
+```
+Error: Duplicate registration: 'ILogger' is already registered in the parent container.
+Use 'scoped: true' to override the parent's registration intentionally.
+```
+
+The error message tells you exactly what to do! ✅
+