@navios/di 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,17 @@
 # Navios DI
 
-Navios DI is a library that implements the Dependency Injection pattern. It provides you with basic tools to create and manage your services
+A powerful, type-safe dependency injection library for TypeScript applications. Navios DI provides a modern, decorator-based approach to dependency injection with support for singletons, transients, factories, injection tokens, and service lifecycle management.
+
+## Features
+
+- 🎯 **Type-safe**: Full TypeScript support with compile-time type checking
+- 🏗️ **Decorator-based**: Clean, declarative syntax using decorators
+- 🔄 **Lifecycle Management**: Built-in support for service initialization and cleanup
+- 🏭 **Factory Pattern**: Create instances using factory classes
+- 🎫 **Injection Tokens**: Flexible token-based dependency resolution
+- 📦 **Scoped Instances**: Singleton and transient scopes
+- ⚡ **Async/Sync Injection**: Both synchronous and asynchronous dependency resolution
+- 🔧 **Container API**: Simple container-based API for dependency management
 
 ## Installation
 
@@ -10,72 +21,322 @@ npm install @navios/di
 yarn add @navios/di
 ```
 
-## Simple Usage example
+## Quick Start
 
-```ts
-import { inject, Injectable, syncInject } from '@navios/di'
+### Basic Usage
+
+```typescript
+import { Container, inject, Injectable } from '@navios/di'
 
 @Injectable()
-class GreeterService {
-  getFoo(user: string): string {
-    return `Hello ${user}`
+class DatabaseService {
+  async connect() {
+    return 'Connected to database'
   }
 }
 
 @Injectable()
 class UserService {
-  private readonly greeterService = syncInject(GreeterService)
+  private readonly db = inject(DatabaseService)
 
-  greet(user: string): string {
-    return this.greeterService.getFoo(user)
+  async getUsers() {
+    const connection = await this.db.connect()
+    return `Users from ${connection}`
   }
 }
 
-const userService = await inject(UserService)
+// Using Container
+const container = new Container()
+const userService = await container.get(UserService)
+console.log(await userService.getUsers()) // "Users from Connected to database"
+```
+
+## Core Concepts
+
+### Container
+
+The `Container` class provides a simplified API for dependency injection:
 
-console.log(userService.greet('World')) // Hello World
+```typescript
+import { Container } from '@navios/di'
+
+const container = new Container()
+
+// Get instances
+const service = await container.get(MyService)
+
+// Invalidate services and their dependencies
+await container.invalidate(service)
+
+// Wait for all pending operations
+await container.ready()
 ```
 
-## Usage with Injection Token
+### Injectable Decorator
 
-```ts
-import { inject, Injectable, InjectionToken, syncInject } from '@navios/di'
+The `@Injectable` decorator marks a class as injectable:
 
-import { z } from 'zod/v4'
+```typescript
+import { Injectable, InjectableScope } from '@navios/di'
 
-const schema = z.object({
-  user: z.string(),
-})
+// Singleton (default)
+@Injectable()
+class SingletonService {}
+
+// Transient (new instance each time)
+@Injectable({ scope: InjectableScope.Transient })
+class TransientService {}
 
-interface GreeterInterface {
-  getFoo(): string
+// With custom injection token
+@Injectable({ token: MyToken })
+class TokenizedService {}
+```
+
+### Injection Methods
+
+#### `inject` - Synchronous Injection
+
+Use `inject` for immediate access to dependencies:
+
+```typescript
+@Injectable()
+class EmailService {
+  sendEmail(message: string) {
+    return `Email sent: ${message}`
+  }
 }
 
-const token = new InjectionToken.create<GreeterInterface, typeof schema>(
-  Symbol.for('user'),
-  schema,
-)
+@Injectable()
+class NotificationService {
+  private readonly emailService = inject(EmailService)
+
+  notify(message: string) {
+    return this.emailService.sendEmail(message)
+  }
+}
+```
 
-@Injectable({
-  token,
+#### `asyncInject` - Asynchronous Injection
+
+Use `asyncInject` for async dependency resolution:
+
+```typescript
+@Injectable()
+class AsyncService {
+  private readonly emailService = asyncInject(EmailService)
+
+  async notify(message: string) {
+    const emailService = await this.emailService
+    return emailService.sendEmail(message)
+  }
+}
+```
+
+### Factory Decorator
+
+Create instances using factory classes:
+
+```typescript
+import { Factory } from '@navios/di'
+
+@Factory()
+class DatabaseConnectionFactory {
+  create() {
+    return {
+      host: 'localhost',
+      port: 5432,
+      connected: true,
+    }
+  }
+}
+
+// Usage
+const connection = await container.get(DatabaseConnectionFactory)
+console.log(connection) // { host: 'localhost', port: 5432, connected: true }
+```
+
+### Service Lifecycle
+
+Implement lifecycle hooks for initialization and cleanup:
+
+```typescript
+import { Injectable, OnServiceDestroy, OnServiceInit } from '@navios/di'
+
+@Injectable()
+class DatabaseService implements OnServiceInit, OnServiceDestroy {
+  private connection: any = null
+
+  async onServiceInit() {
+    console.log('Initializing database connection...')
+    this.connection = await this.connect()
+  }
+
+  async onServiceDestroy() {
+    console.log('Closing database connection...')
+    if (this.connection) {
+      await this.connection.close()
+    }
+  }
+
+  private async connect() {
+    // Database connection logic
+    return { connected: true }
+  }
+}
+```
+
+### Injection Tokens
+
+Use injection tokens for flexible dependency resolution:
+
+#### Basic Injection Token
+
+```typescript
+import { Container, Injectable, InjectionToken } from '@navios/di'
+
+import { z } from 'zod'
+
+const configSchema = z.object({
+  apiUrl: z.string(),
+  timeout: z.number(),
 })
-class GreeterService {
-  constructor(private readonly config: z.infer<typeof schema>) {}
 
-  getFoo(): string {
-    return `Hello ${this.config.user}`
+const CONFIG_TOKEN = InjectionToken.create<Config, typeof configSchema>(
+  'APP_CONFIG',
+  configSchema,
+)
+
+@Injectable({ token: CONFIG_TOKEN })
+class ConfigService {
+  constructor(private config: z.infer<typeof configSchema>) {}
+
+  getApiUrl() {
+    return this.config.apiUrl
   }
 }
 
-const greetWorld = await inject(token, {
-  user: 'World',
+// Usage
+const container = new Container()
+const config = await container.get(CONFIG_TOKEN, {
+  apiUrl: 'https://api.example.com',
+  timeout: 5000,
+})
+```
+
+#### Bound Injection Token
+
+Pre-bind values to injection tokens:
+
+```typescript
+const BoundConfig = InjectionToken.bound(CONFIG_TOKEN, {
+  apiUrl: 'https://api.example.com',
+  timeout: 5000,
 })
-const BoundGreeterService = InjectionToken.bound(token, {
-  user: 'Earth',
+
+// No need to provide arguments
+const container = new Container()
+
+const config = await container.get(BoundConfig)
+```
+
+#### Factory Injection Token
+
+Use factories to resolve token values:
+
+```typescript
+const FactoryConfig = InjectionToken.factory(CONFIG_TOKEN, async () => {
+  // Load config from environment or external source
+  return {
+    apiUrl: process.env.API_URL || 'https://api.example.com',
+    timeout: parseInt(process.env.TIMEOUT || '5000'),
+  }
 })
 
-const greetEarth = await inject(BoundGreeterService)
+const config = await container.get(FactoryConfig)
+```
+
+## Advanced Usage
+
+### Custom Registry
 
-console.log(greetWorld.getFoo()) // Hello World
-console.log(greetEarth.getFoo()) // Hello Earth
+```typescript
+import { Container, Registry } from '@navios/di'
+
+const customRegistry = new Registry()
+const container = new Container(customRegistry)
 ```
+
+### Error Handling
+
+```typescript
+try {
+  const service = await container.get(NonExistentService)
+} catch (error) {
+  console.error('Service not found:', error.message)
+}
+```
+
+### Service Invalidation
+
+```typescript
+// Invalidate a specific service and its dependencies
+await container.invalidate(myService)
+
+// The service will be recreated on next access
+const newService = await container.get(MyService)
+```
+
+## API Reference
+
+### Container
+
+- `get<T>(token: T): Promise<InstanceType<T>>` - Get an instance
+- `invalidate(service: unknown): Promise<void>` - Invalidate a service
+- `ready(): Promise<void>` - Wait for pending operations
+- `getServiceLocator(): ServiceLocator` - Get underlying service locator
+
+### Injectable Decorator
+
+- `@Injectable(options?: InjectableOptions)` - Mark class as injectable
+- Options:
+  - `scope?: InjectableScope` - Service scope (Singleton | Transient)
+  - `token?: InjectionToken` - Custom injection token
+  - `registry?: Registry` - Custom registry
+
+### Factory Decorator
+
+- `@Factory(options?: FactoryOptions)` - Mark class as factory
+- Options:
+  - `scope?: InjectableScope` - Factory scope
+  - `token?: InjectionToken` - Custom injection token
+  - `registry?: Registry` - Custom registry
+
+### Injection Methods
+
+- `inject<T>(token: T): T` - Synchronous injection
+- `asyncInject<T>(token: T): Promise<T>` - Asynchronous injection
+
+### Injection Tokens
+
+- `InjectionToken.create<T>(name: string | symbol): InjectionToken<T>`
+- `InjectionToken.create<T, S>(name: string | symbol, schema: S): InjectionToken<T, S>`
+- `InjectionToken.bound<T, S>(token: InjectionToken<T, S>, value: z.input<S>): BoundInjectionToken<T, S>`
+- `InjectionToken.factory<T, S>(token: InjectionToken<T, S>, factory: () => Promise<z.input<S>>): FactoryInjectionToken<T, S>`
+
+### Lifecycle Interfaces
+
+- `OnServiceInit` - Implement `onServiceInit(): Promise<void> | void`
+- `OnServiceDestroy` - Implement `onServiceDestroy(): Promise<void> | void`
+
+## Best Practices
+
+1. **Use `inject` for immediate dependencies** - When you need the dependency right away
+2. **Use `asyncInject` for async dependencies** - When the dependency might not be ready yet
+3. **Implement lifecycle hooks** - For proper resource management
+4. **Use injection tokens** - For configuration and interface-based dependencies
+5. **Prefer singletons** - Unless you specifically need new instances each time
+6. **Use factories** - For complex object creation logic
+
+## License
+
+MIT

package/docs/README.md

@@ -1,81 +1,154 @@
-# Navios DI
+# Navios DI Documentation
 
-Navios DI is a library that implements the Dependency Injection pattern. It provides you with basic tools to create and manage your services
+Welcome to the comprehensive documentation for Navios DI, a powerful dependency injection library for TypeScript applications.
 
-## Installation
+## Table of Contents
 
-```bash
-npm install @navios/di
-# or
-yarn add @navios/di
-```
+- [Getting Started](./getting-started.md) - Installation and basic setup
+- [Container](./container.md) - Container API and usage patterns
+- [Injectable Decorator](./injectable.md) - Service registration and configuration
+- [Factory Decorator](./factory.md) - Factory pattern implementation
+- [Injection Tokens](./injection-tokens.md) - Token-based dependency resolution
+- [Service Lifecycle](./lifecycle.md) - Initialization and cleanup hooks
+- [Scopes](./scopes.md) - Singleton and transient service scopes
+- [Advanced Patterns](./advanced-patterns.md) - Complex usage scenarios
+- [API Reference](./api-reference.md) - Complete API documentation
+- [Migration Guide](./migration.md) - Upgrading from older versions
+
+## Quick Links
+
+### Core Concepts
+
+- **[Container](./container.md)** - The main entry point for dependency injection
+- **[Injectable](./injectable.md)** - Decorator for marking classes as injectable services
+- **[Factory](./factory.md)** - Decorator for creating factory classes
+- **[Injection Tokens](./injection-tokens.md)** - Flexible token-based dependency resolution
+
+### Key Features
 
-## Simple Usage example
+- **Type Safety** - Full TypeScript support with compile-time checking
+- **Lifecycle Management** - Built-in hooks for service initialization and cleanup
+- **Multiple Scopes** - Singleton and transient service lifetimes
+- **Async/Sync Injection** - Both synchronous and asynchronous dependency resolution
+- **Factory Pattern** - Complex object creation with factory classes
 
-```ts
-import { inject, Injectable, syncInject } from '@navios/di'
+### Getting Started
+
+```typescript
+import { Container, inject, Injectable } from '@navios/di'
 
 @Injectable()
-class GreeterService {
-  getFoo(user: string): string {
-    return `Hello ${user}`
+class DatabaseService {
+  async connect() {
+    return 'Connected to database'
   }
 }
 
 @Injectable()
 class UserService {
-  private readonly greeterService = syncInject(GreeterService)
+  private readonly db = inject(DatabaseService)
 
-  greet(user: string): string {
-    return this.greeterService.getFoo(user)
+  async getUsers() {
+    const connection = await this.db.connect()
+    return `Users from ${connection}`
   }
 }
 
-const userService = await inject(UserService)
-
-console.log(userService.greet('World')) // Hello World
+// Using Container
+const container = new Container()
+const userService = await container.get(UserService)
+console.log(await userService.getUsers())
 ```
 
-## Usage with Injection Token
+## Architecture Overview
 
-```ts
-import { inject, Injectable, InjectionToken, syncInject } from '@navios/di'
+Navios DI follows a modern, decorator-based architecture:
 
-import { z } from 'zod/v4'
+1. **Services** are marked with `@Injectable()` decorator
+2. **Dependencies** are injected using `asyncInject()` or `inject()`
+3. **Container** manages service instances and their lifecycle
+4. **Injection Tokens** provide flexible dependency resolution
+5. **Factories** handle complex object creation
 
-const schema = z.object({
-  user: z.string(),
-})
+## Design Principles
+
+- **Type Safety First** - Leverage TypeScript's type system for compile-time safety
+- **Declarative Configuration** - Use decorators for clean, readable service definitions
+- **Flexible Resolution** - Support both class-based and token-based injection
+- **Lifecycle Awareness** - Built-in support for service initialization and cleanup
+- **Performance Optimized** - Efficient instance management and caching
 
-interface GreeterInterface {
-  getFoo(): string
+## Examples
+
+### Basic Service Injection
+
+```typescript
+@Injectable()
+class EmailService {
+  sendEmail(to: string, subject: string) {
+    return `Email sent to ${to}: ${subject}`
+  }
 }
 
-const token = new InjectionToken<GreeterInterface, typeof schema>(
-  Symbol.for('user'),
-  schema,
-)
+@Injectable()
+class NotificationService {
+  private readonly emailService = inject(EmailService)
+
+  notify(user: string, message: string) {
+    return this.emailService.sendEmail(user, `Notification: ${message}`)
+  }
+}
+```
+
+### Configuration with Injection Tokens
 
-@Injectable({
-  token,
+```typescript
+import { z } from 'zod'
+
+const configSchema = z.object({
+  apiUrl: z.string(),
+  timeout: z.number(),
 })
-class GreeterService {
-  constructor(private readonly config: z.infer<typeof schema>) {}
 
-  getFoo(): string {
-    return `Hello ${this.config.user}`
+const CONFIG_TOKEN = InjectionToken.create<Config, typeof configSchema>(
+  'APP_CONFIG',
+  configSchema,
+)
+
+@Injectable({ token: CONFIG_TOKEN })
+class ConfigService {
+  constructor(private config: z.infer<typeof configSchema>) {}
+
+  getApiUrl() {
+    return this.config.apiUrl
   }
 }
+```
 
-const greetWorld = await inject(token, {
-  user: 'World',
-})
-const BoundGreeterService = InjectionToken.bound(token, {
-  user: 'Earth',
-})
+### Service Lifecycle
+
+```typescript
+@Injectable()
+class DatabaseService implements OnServiceInit, OnServiceDestroy {
+  private connection: any = null
 
-const greetEarth = await inject(BoundGreeterService)
+  async onServiceInit() {
+    console.log('Initializing database...')
+    this.connection = await this.connect()
+  }
 
-console.log(greetWorld.getFoo()) // Hello World
-console.log(greetEarth.getFoo()) // Hello Earth
+  async onServiceDestroy() {
+    console.log('Closing database...')
+    if (this.connection) {
+      await this.connection.close()
+    }
+  }
+}
 ```
+
+## Need Help?
+
+- Check the [API Reference](./api-reference.md) for detailed method documentation
+- Look at [Advanced Patterns](./advanced-patterns.md) for complex scenarios
+- Review the [Migration Guide](./migration.md) if upgrading from older versions
+- See the [Examples](./examples/) folder for complete working examples