@veloxts/core 0.3.3 → 0.3.5

package/README.md

@@ -15,10 +15,10 @@ pnpm add @veloxts/core
 ## Quick Start
 
 ```typescript
-import { createVeloxApp } from '@veloxts/core';
+import { veloxApp } from '@veloxts/core';
 
 // Create application
-const app = await createVeloxApp({
+const app = await veloxApp({
   port: 3210,
   host: '0.0.0.0',
   logger: true,
@@ -31,7 +31,7 @@ console.log(`Server running on ${app.address}`);
 
 ## Core API
 
-### `createVeloxApp(config?)`
+### `veloxApp(config?)`
 
 Creates a new VeloxTS application instance with sensible defaults.
 
@@ -49,7 +49,7 @@ interface VeloxAppConfig {
 **Example:**
 
 ```typescript
-const app = await createVeloxApp({
+const app = await veloxApp({
   port: 4000,
   host: '127.0.0.1',
   logger: {
@@ -80,21 +80,21 @@ interface VeloxApp {
   start(): Promise<void>;         // Start the server
   stop(): Promise<void>;          // Stop the server gracefully
   register(plugin, options?): Promise<void>;  // Register a plugin
-  onShutdown(handler): void;      // Add shutdown handler
+  beforeShutdown(handler): void;  // Add shutdown handler
 }
 ```
 
 **Example:**
 
 ```typescript
-const app = await createVeloxApp();
+const app = await veloxApp();
 
 // Register plugins
 await app.register(databasePlugin);
 await app.register(routerPlugin);
 
 // Add shutdown hook
-app.onShutdown(async () => {
+app.beforeShutdown(async () => {
   console.log('Cleaning up resources...');
 });
 
@@ -205,7 +205,7 @@ declare module '@veloxts/core' {
 }
 
 // Use in app
-const app = await createVeloxApp();
+const app = await veloxApp();
 await app.register(databasePlugin);
 ```
 
@@ -392,7 +392,7 @@ app.server.get('/users/:id', async (request, reply) => {
 ### Environment-Based Configuration
 
 ```typescript
-const app = await createVeloxApp({
+const app = await veloxApp({
   port: Number(process.env.PORT) || 3210,
   host: process.env.HOST || '0.0.0.0',
   logger: process.env.NODE_ENV !== 'production',
@@ -405,7 +405,7 @@ const app = await createVeloxApp({
 ### Production Configuration
 
 ```typescript
-const app = await createVeloxApp({
+const app = await veloxApp({
   port: 3210,
   host: '0.0.0.0',
   logger: {
@@ -426,10 +426,10 @@ const app = await createVeloxApp({
 ### Graceful Shutdown
 
 ```typescript
-const app = await createVeloxApp();
+const app = await veloxApp();
 
 // Add custom shutdown handlers
-app.onShutdown(async () => {
+app.beforeShutdown(async () => {
   console.log('Cleaning up resources...');
   await database.disconnect();
   await cache.flush();
@@ -494,7 +494,7 @@ const fastify = Fastify({
   trustProxy: true,
 });
 
-const app = await createVeloxApp({ fastify });
+const app = await veloxApp({ fastify });
 ```
 
 ### Accessing Fastify Directly
@@ -502,7 +502,7 @@ const app = await createVeloxApp({ fastify });
 The underlying Fastify instance is available via `app.server`:
 
 ```typescript
-const app = await createVeloxApp();
+const app = await veloxApp();
 
 // Add Fastify plugins
 await app.server.register(fastifyCors, {
@@ -520,7 +520,7 @@ app.server.get('/custom', async (request, reply) => {
 ### Complete Application Setup
 
 ```typescript
-import { createVeloxApp } from '@veloxts/core';
+import { veloxApp } from '@veloxts/core';
 import { createDatabasePlugin } from '@veloxts/orm';
 import { registerRestRoutes } from '@veloxts/router';
 import { PrismaClient } from '@prisma/client';
@@ -528,7 +528,7 @@ import { userProcedures } from './procedures/users';
 
 // Initialize
 const prisma = new PrismaClient();
-const app = await createVeloxApp({
+const app = await veloxApp({
   port: Number(process.env.PORT) || 3210,
   logger: true,
 });
@@ -558,6 +558,687 @@ await app.start();
 console.log(`Server running at ${app.address}`);
 ```
 
+## Dependency Injection
+
+VeloxTS provides a powerful, type-safe dependency injection container inspired by Angular and NestJS. The DI system enables automatic constructor injection, lifecycle management, and clean separation of concerns.
+
+### Overview
+
+The DI container manages service creation, dependency resolution, and lifecycle:
+
+- **Automatic constructor injection** via TypeScript decorators
+- **Multiple provider types**: classes, factories, values, aliases
+- **Lifecycle scopes**: singleton, transient, request-scoped
+- **Type safety**: Full TypeScript inference without code generation
+- **Circular dependency detection**
+- **Fastify integration** for request-scoped services
+
+### Accessing the Container
+
+Every VeloxApp instance has a DI container available:
+
+```typescript
+const app = await veloxApp();
+
+// Access the container
+app.container.register({ /* ... */ });
+const service = app.container.resolve(MyService);
+```
+
+### Tokens
+
+Tokens are unique identifiers for services. VeloxTS supports three token types:
+
+#### Class Tokens
+
+Use the class itself as a token:
+
+```typescript
+@Injectable()
+class UserService {
+  getUsers() { /* ... */ }
+}
+
+// Register with class token
+app.container.register({
+  provide: UserService,
+  useClass: UserService
+});
+
+// Resolve with class token
+const userService = app.container.resolve(UserService);
+```
+
+#### String Tokens
+
+Use string literals for named services:
+
+```typescript
+import { token } from '@veloxts/core';
+
+interface DatabaseClient {
+  query(sql: string): Promise<unknown>;
+}
+
+const DATABASE = token<DatabaseClient>('DATABASE');
+
+app.container.register({
+  provide: DATABASE,
+  useFactory: () => createDatabaseClient()
+});
+
+const db = app.container.resolve(DATABASE);
+```
+
+#### Symbol Tokens
+
+Use symbols for guaranteed uniqueness:
+
+```typescript
+import { token } from '@veloxts/core';
+
+interface Logger {
+  log(message: string): void;
+}
+
+const LOGGER = token.symbol<Logger>('Logger');
+
+app.container.register({
+  provide: LOGGER,
+  useClass: ConsoleLogger
+});
+
+const logger = app.container.resolve(LOGGER);
+```
+
+### Provider Types
+
+The container supports four provider types for different use cases. For common patterns, VeloxTS provides succinct provider helpers that simplify registration.
+
+#### Succinct Provider Helpers
+
+VeloxTS provides convenient helpers for common provider patterns:
+
+```typescript
+import { singleton, scoped, transient, value, factory } from '@veloxts/core';
+
+// Singleton scope (one instance for entire app)
+app.container.register(singleton(ConfigService));
+
+// Request scope (one instance per HTTP request)
+app.container.register(scoped(UserContext));
+
+// Transient scope (new instance every time)
+app.container.register(transient(RequestIdGenerator));
+
+// Value provider (provide existing value)
+app.container.register(value(CONFIG, { port: 3210 }));
+
+// Factory provider (use factory function)
+app.container.register(
+  factory(DATABASE, (config: ConfigService) => {
+    return new PrismaClient({ datasources: { db: { url: config.databaseUrl } } });
+  }, [ConfigService])
+);
+```
+
+These helpers are equivalent to the full provider syntax but more concise and readable.
+
+#### Class Provider
+
+Instantiate a class with automatic dependency injection:
+
+```typescript
+@Injectable()
+class UserService {
+  constructor(
+    private db: DatabaseClient,
+    private logger: Logger
+  ) {}
+}
+
+// Using succinct helper (recommended)
+app.container.register(singleton(UserService));
+
+// Or using full syntax
+app.container.register({
+  provide: UserService,
+  useClass: UserService,
+  scope: Scope.SINGLETON
+});
+```
+
+#### Factory Provider
+
+Use a factory function to create instances:
+
+```typescript
+// Using succinct helper (recommended)
+app.container.register(
+  factory(DATABASE, (config: ConfigService) => {
+    return createDatabaseClient(config.databaseUrl);
+  }, [ConfigService])
+);
+
+// Or using full syntax
+app.container.register({
+  provide: DATABASE,
+  useFactory: (config: ConfigService) => {
+    return createDatabaseClient(config.databaseUrl);
+  },
+  inject: [ConfigService],
+  scope: Scope.SINGLETON
+});
+```
+
+#### Value Provider
+
+Provide an existing value directly:
+
+```typescript
+const CONFIG = token<AppConfig>('CONFIG');
+
+// Using succinct helper (recommended)
+app.container.register(
+  value(CONFIG, {
+    port: 3210,
+    host: 'localhost',
+    debug: true
+  })
+);
+
+// Or using full syntax
+app.container.register({
+  provide: CONFIG,
+  useValue: {
+    port: 3210,
+    host: 'localhost',
+    debug: true
+  }
+});
+```
+
+#### Existing Provider (Alias)
+
+Create an alias to another token:
+
+```typescript
+// Register concrete implementation
+app.container.register({
+  provide: ConsoleLogger,
+  useClass: ConsoleLogger
+});
+
+// Create an alias
+app.container.register({
+  provide: LOGGER,
+  useExisting: ConsoleLogger
+});
+
+// Both resolve to the same instance
+const logger1 = app.container.resolve(LOGGER);
+const logger2 = app.container.resolve(ConsoleLogger);
+// logger1 === logger2
+```
+
+### Lifecycle Scopes
+
+Scopes determine how service instances are created and shared.
+
+#### Singleton Scope
+
+One instance for the entire application (default):
+
+```typescript
+@Injectable({ scope: Scope.SINGLETON })
+class ConfigService {
+  // Shared across all requests
+}
+
+// Register using succinct helper
+app.container.register(singleton(ConfigService));
+```
+
+**Best for:**
+- Configuration services
+- Database connection pools
+- Cache clients
+- Stateless utility services
+
+#### Transient Scope
+
+New instance on every resolution:
+
+```typescript
+@Injectable({ scope: Scope.TRANSIENT })
+class RequestIdGenerator {
+  readonly id = crypto.randomUUID();
+}
+
+// Register using succinct helper
+app.container.register(transient(RequestIdGenerator));
+```
+
+**Best for:**
+- Services with mutable state
+- Factories that produce unique objects
+- Services where isolation is critical
+
+#### Request Scope
+
+One instance per HTTP request:
+
+```typescript
+@Injectable({ scope: Scope.REQUEST })
+class UserContext {
+  constructor(private request: FastifyRequest) {}
+
+  get userId(): string {
+    return this.request.user?.id;
+  }
+}
+
+// Register using succinct helper
+app.container.register(scoped(UserContext));
+```
+
+**Best for:**
+- User context/session data
+- Request-specific caching
+- Transaction management
+- Audit logging with request context
+
+**Note:** Request-scoped services require a Fastify request context. Resolving them outside a request handler throws an error.
+
+### Decorators
+
+Use TypeScript decorators for automatic dependency injection.
+
+#### Prerequisites
+
+Enable decorators in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+Import `reflect-metadata` at your app's entry point:
+
+```typescript
+import 'reflect-metadata';
+import { veloxApp } from '@veloxts/core';
+```
+
+#### @Injectable()
+
+Marks a class as injectable:
+
+```typescript
+@Injectable()
+class UserService {
+  constructor(private db: DatabaseClient) {}
+}
+
+@Injectable({ scope: Scope.REQUEST })
+class RequestLogger {
+  constructor(private request: FastifyRequest) {}
+}
+```
+
+#### @Inject()
+
+Explicitly specifies the injection token:
+
+```typescript
+const DATABASE = token<DatabaseClient>('DATABASE');
+
+@Injectable()
+class UserService {
+  constructor(
+    @Inject(DATABASE) private db: DatabaseClient,
+    private config: ConfigService // Auto-injected by class token
+  ) {}
+}
+```
+
+Use `@Inject()` when:
+- Injecting by string or symbol token
+- Injecting an interface (TypeScript interfaces are erased at runtime)
+- Automatic type resolution doesn't work
+
+#### @Optional()
+
+Marks a dependency as optional:
+
+```typescript
+@Injectable()
+class NotificationService {
+  constructor(
+    @Optional() private emailService?: EmailService,
+    @Optional() @Inject(SMS_SERVICE) private smsService?: SmsService
+  ) {}
+
+  notify(message: string) {
+    // Gracefully handle missing services
+    this.emailService?.send(message);
+    this.smsService?.send(message);
+  }
+}
+```
+
+If an optional dependency cannot be resolved, `undefined` is injected instead of throwing an error.
+
+### Container API
+
+#### Registering Services
+
+Register a single provider:
+
+```typescript
+// Using succinct helper (recommended)
+app.container.register(scoped(UserService));
+
+// Or using full syntax
+app.container.register({
+  provide: UserService,
+  useClass: UserService,
+  scope: Scope.REQUEST
+});
+```
+
+Register multiple providers:
+
+```typescript
+// Using succinct helpers (recommended)
+app.container.registerMany([
+  singleton(UserService),
+  singleton(PostService),
+  value(CONFIG, appConfig)
+]);
+
+// Or using full syntax
+app.container.registerMany([
+  { provide: UserService, useClass: UserService },
+  { provide: PostService, useClass: PostService },
+  { provide: CONFIG, useValue: appConfig }
+]);
+```
+
+#### Resolving Services
+
+Synchronous resolution:
+
+```typescript
+const userService = app.container.resolve(UserService);
+```
+
+Asynchronous resolution (for async factories):
+
+```typescript
+// Using succinct helper (recommended)
+app.container.register(
+  factory(DATABASE, async (config: ConfigService) => {
+    const client = createClient(config.dbUrl);
+    await client.connect();
+    return client;
+  }, [ConfigService])
+);
+
+const db = await app.container.resolveAsync(DATABASE);
+```
+
+Optional resolution (returns `undefined` if not found):
+
+```typescript
+const service = app.container.resolveOptional(OptionalService);
+if (service) {
+  service.doSomething();
+}
+```
+
+#### Request Context
+
+Resolve request-scoped services with context:
+
+```typescript
+app.server.get('/users', async (request, reply) => {
+  const ctx = Container.createContext(request);
+  const userContext = app.container.resolve(UserContext, ctx);
+
+  return { userId: userContext.userId };
+});
+```
+
+### Integration with VeloxApp
+
+The container is automatically attached to the Fastify server for request-scoped services:
+
+```typescript
+const app = await veloxApp();
+
+// Container is already attached to app.server
+// Request-scoped services work automatically
+
+@Injectable({ scope: Scope.REQUEST })
+class RequestLogger {
+  constructor(private request: FastifyRequest) {}
+}
+
+// Register using succinct helper
+app.container.register(scoped(RequestLogger));
+
+app.server.get('/log', async (request, reply) => {
+  const ctx = Container.createContext(request);
+  const logger = app.container.resolve(RequestLogger, ctx);
+  logger.log('Request received');
+  return { ok: true };
+});
+```
+
+### Practical Examples
+
+#### Complete Service Layer
+
+```typescript
+import 'reflect-metadata';
+import {
+  veloxApp,
+  Injectable,
+  Inject,
+  Scope,
+  token,
+  singleton,
+  scoped,
+  factory
+} from '@veloxts/core';
+import { PrismaClient } from '@prisma/client';
+
+// Define tokens
+const DATABASE = token<PrismaClient>('DATABASE');
+const CONFIG = token<AppConfig>('CONFIG');
+
+// Configuration service
+@Injectable()
+class ConfigService {
+  get databaseUrl(): string {
+    return process.env.DATABASE_URL!;
+  }
+}
+
+// Database service
+@Injectable()
+class DatabaseService {
+  constructor(@Inject(DATABASE) private db: PrismaClient) {}
+
+  async findUser(id: string) {
+    return this.db.user.findUnique({ where: { id } });
+  }
+}
+
+// Business logic service
+@Injectable({ scope: Scope.REQUEST })
+class UserService {
+  constructor(
+    private database: DatabaseService,
+    private config: ConfigService
+  ) {}
+
+  async getUser(id: string) {
+    return this.database.findUser(id);
+  }
+}
+
+// Create app
+const app = await veloxApp();
+
+// Register services using succinct helpers
+app.container.register(
+  factory(DATABASE, (config: ConfigService) => {
+    return new PrismaClient({
+      datasources: { db: { url: config.databaseUrl } }
+    });
+  }, [ConfigService])
+);
+
+app.container.register(singleton(ConfigService));
+app.container.register(singleton(DatabaseService));
+app.container.register(scoped(UserService));
+
+// Use in routes
+app.server.get('/users/:id', async (request, reply) => {
+  const ctx = Container.createContext(request);
+  const userService = app.container.resolve(UserService, ctx);
+
+  const user = await userService.getUser(request.params.id);
+  return user;
+});
+
+await app.start();
+```
+
+#### Testing with Child Containers
+
+```typescript
+import { createContainer, asClass } from '@veloxts/core';
+
+// Create a child container for testing
+const testContainer = app.container.createChild();
+
+// Override services with mocks
+class MockDatabaseService {
+  async findUser(id: string) {
+    return { id, name: 'Test User' };
+  }
+}
+
+testContainer.register({
+  provide: DatabaseService,
+  useClass: MockDatabaseService
+});
+
+// Test with mocked dependencies
+const userService = testContainer.resolve(UserService);
+const user = await userService.getUser('123');
+// user comes from MockDatabaseService
+```
+
+#### Auto-Registration
+
+Enable auto-registration to automatically register `@Injectable` classes:
+
+```typescript
+const app = await createVeloxApp();
+const autoContainer = createContainer({ autoRegister: true });
+
+@Injectable()
+class AutoService {}
+
+// No need to manually register
+const service = autoContainer.resolve(AutoService);
+// Automatically registers and resolves
+```
+
+### Advanced Features
+
+#### Circular Dependency Detection
+
+The container detects circular dependencies:
+
+```typescript
+@Injectable()
+class ServiceA {
+  constructor(private b: ServiceB) {}
+}
+
+@Injectable()
+class ServiceB {
+  constructor(private a: ServiceA) {}
+}
+
+// Throws: Circular dependency detected: ServiceA -> ServiceB -> ServiceA
+const service = app.container.resolve(ServiceA);
+```
+
+#### Container Hierarchy
+
+Create parent-child container hierarchies:
+
+```typescript
+const parentContainer = createContainer();
+parentContainer.register({
+  provide: ConfigService,
+  useClass: ConfigService
+});
+
+const childContainer = parentContainer.createChild();
+// Child inherits ConfigService from parent
+// Can override with its own providers
+
+childContainer.register({
+  provide: UserService,
+  useClass: UserService
+});
+```
+
+#### Debug Information
+
+Get container statistics:
+
+```typescript
+const info = app.container.getDebugInfo();
+console.log(info);
+// {
+//   providerCount: 5,
+//   providers: [
+//     'class(UserService, request)',
+//     'factory(DATABASE, singleton)',
+//     'value(CONFIG)',
+//     'existing(LOGGER => ConsoleLogger)'
+//   ],
+//   hasParent: false,
+//   autoRegister: false
+// }
+```
+
+### Best Practices
+
+1. **Use tokens for interfaces**: Create string or symbol tokens for interface types since TypeScript interfaces don't exist at runtime.
+
+2. **Prefer singleton scope**: Use `Scope.SINGLETON` by default for stateless services to improve performance.
+
+3. **Use request scope for user context**: Store user authentication, request-specific state, and transactions in request-scoped services.
+
+4. **Avoid circular dependencies**: Refactor shared logic into a third service to break circular dependencies.
+
+5. **Use `@Inject()` for clarity**: Explicitly specify tokens with `@Inject()` to make dependencies clear and avoid runtime type resolution issues.
+
+6. **Test with child containers**: Create child containers in tests to override services with mocks without affecting the main container.
+
 ## Related Packages
 
 - [@veloxts/router](/packages/router) - Procedure-based routing