@navios/core 0.4.0 → 0.5.1

package/docs/modules.md

@@ -0,0 +1,377 @@
+# Modules
+
+Modules in Navios are the primary building blocks for organizing your application. They provide a way to group related controllers, services, and other providers into cohesive units that can be easily managed and imported.
+
+## What is a Module?
+
+A module is a TypeScript class decorated with the `@Module()` decorator. It serves as a container for controllers, other modules, and shared guards. Modules help organize your application into logical boundaries and enable dependency injection across the application.
+
+## Creating a Module
+
+### Basic Module
+
+```typescript
+import { Module } from '@navios/core'
+
+@Module()
+export class AppModule {}
+```
+
+### Module with Controllers
+
+```typescript
+import { Module } from '@navios/core'
+
+import { ProductController } from './product.controller'
+import { UserController } from './user.controller'
+
+@Module({
+  controllers: [UserController, ProductController],
+})
+export class AppModule {}
+```
+
+### Module with Imports
+
+```typescript
+import { Module } from '@navios/core'
+
+import { AuthModule } from './auth/auth.module'
+import { UserModule } from './user/user.module'
+
+@Module({
+  imports: [UserModule, AuthModule],
+})
+export class AppModule {}
+```
+
+### Module with Guards
+
+```typescript
+import { Module } from '@navios/core'
+
+import { AuthGuard } from './auth.guard'
+import { UserController } from './user.controller'
+
+@Module({
+  controllers: [UserController],
+  guards: [AuthGuard], // Applied to all controllers in this module
+})
+export class UserModule {}
+```
+
+## Module Options
+
+The `@Module()` decorator accepts the following options:
+
+### `controllers`
+
+- **Type**: `ClassType[] | Set<ClassType>`
+- **Description**: Array of controller classes that belong to this module
+- **Example**:
+
+```typescript
+@Module({
+  controllers: [UserController, PostController],
+})
+export class UserModule {}
+```
+
+### `imports`
+
+- **Type**: `ClassType[] | Set<ClassType>`
+- **Description**: Array of other modules to import into this module
+- **Example**:
+
+```typescript
+@Module({
+  imports: [DatabaseModule, AuthModule],
+})
+export class AppModule {}
+```
+
+### `guards`
+
+- **Type**: `ClassType[] | Set<ClassType>`
+- **Description**: Array of guard classes that will be applied to all controllers in this module
+- **Example**:
+
+```typescript
+@Module({
+  guards: [AuthGuard, RoleGuard],
+})
+export class ProtectedModule {}
+```
+
+## Module Lifecycle
+
+Modules in Navios follow a specific lifecycle:
+
+1. **Registration**: Modules are registered with the dependency injection container
+2. **Import Resolution**: Imported modules are loaded recursively
+3. **Controller Registration**: Controllers are registered and their endpoints discovered
+4. **Guard Application**: Module-level guards are applied to all controllers
+5. **Initialization**: Module initialization hooks are called
+
+## Module Lifecycle Methods
+
+### `onModuleInit`
+
+The `onModuleInit` lifecycle method is called after the module has been initialized and all its dependencies have been resolved. This is useful for performing setup tasks, initializing connections, or running startup logic.
+
+#### Interface
+
+```typescript
+interface NaviosModule {
+  onModuleInit(): void | Promise<void>
+}
+```
+
+#### Usage
+
+To use the `onModuleInit` lifecycle method, implement the `NaviosModule` interface in your module class:
+
+```typescript
+import { Module, NaviosModule } from '@navios/core'
+
+@Module({
+  controllers: [UserController],
+})
+export class UserModule implements NaviosModule {
+  onModuleInit() {
+    console.log('UserModule has been initialized')
+    // Perform initialization logic here
+  }
+}
+```
+
+#### Async Initialization
+
+The `onModuleInit` method can be asynchronous, allowing you to perform async setup tasks:
+
+```typescript
+import { Module, NaviosModule } from '@navios/core'
+
+@Module({
+  controllers: [DatabaseController],
+})
+export class DatabaseModule implements NaviosModule {
+  async onModuleInit() {
+    console.log('Initializing database connection...')
+    await this.connectToDatabase()
+    console.log('Database connection established')
+  }
+
+  private async connectToDatabase() {
+    // Database connection logic
+    return new Promise((resolve) => setTimeout(resolve, 1000))
+  }
+}
+```
+
+#### Common Use Cases
+
+- **Database Connections**: Initialize database connections or verify connectivity
+- **Cache Warming**: Pre-populate caches with frequently accessed data
+- **External Service Setup**: Initialize connections to external APIs or services
+- **Configuration Validation**: Validate required configuration settings
+- **Background Tasks**: Start background processes or scheduled tasks
+
+```typescript
+import { Module, NaviosModule } from '@navios/core'
+
+@Module({
+  controllers: [CacheController],
+})
+export class CacheModule implements NaviosModule {
+  private cache = new Map<string, any>()
+
+  async onModuleInit() {
+    // Warm up the cache with initial data
+    await this.warmUpCache()
+
+    // Validate configuration
+    this.validateConfiguration()
+
+    console.log('CacheModule initialized successfully')
+  }
+
+  private async warmUpCache() {
+    // Pre-populate cache with frequently accessed data
+    this.cache.set('app:config', await this.loadAppConfig())
+    this.cache.set('user:defaults', await this.loadUserDefaults())
+  }
+
+  private validateConfiguration() {
+    if (!process.env.CACHE_TTL) {
+      throw new Error('CACHE_TTL environment variable is required')
+    }
+  }
+
+  private async loadAppConfig() {
+    // Load application configuration
+    return { theme: 'dark', language: 'en' }
+  }
+
+  private async loadUserDefaults() {
+    // Load default user settings
+    return { notifications: true, theme: 'auto' }
+  }
+}
+```
+
+#### Execution Order
+
+The `onModuleInit` methods are called in dependency order:
+
+1. **Imported modules first**: All imported modules' `onModuleInit` methods are called before the current module
+2. **Current module last**: The current module's `onModuleInit` method is called after all its dependencies
+
+```typescript
+@Module({
+  imports: [DatabaseModule, CacheModule], // These initialize first
+})
+export class AppModule implements NaviosModule {
+  onModuleInit() {
+    // This runs after DatabaseModule and CacheModule have been initialized
+    console.log('AppModule initialized - all dependencies are ready')
+  }
+}
+```
+
+## Module Metadata
+
+Each module decorated with `@Module()` has associated metadata that Navios uses internally:
+
+```typescript
+export interface ModuleMetadata {
+  controllers: Set<ClassType>
+  imports: Set<ClassType>
+  guards: Set<ClassType>
+  attributes: Map<symbol, unknown>
+}
+```
+
+## Best Practices
+
+### 1. Feature-Based Organization
+
+Organize modules around business features rather than technical layers:
+
+```typescript
+// ✅ Good - Feature-based
+@Module({
+  controllers: [UserController],
+  imports: [UserDatabaseModule],
+})
+export class UserModule {}
+
+// ❌ Avoid - Layer-based
+@Module({
+  controllers: [UserController, ProductController, OrderController],
+})
+export class ControllersModule {}
+```
+
+### 2. Single Responsibility
+
+Each module should have a single, well-defined responsibility:
+
+```typescript
+// ✅ Good - Single responsibility
+@Module({
+  controllers: [AuthController],
+  imports: [JwtModule],
+})
+export class AuthModule {}
+
+// ❌ Avoid - Multiple responsibilities
+@Module({
+  controllers: [AuthController, UserController, ProductController],
+})
+export class EverythingModule {}
+```
+
+### 3. Explicit Dependencies
+
+Always explicitly import the modules you depend on:
+
+```typescript
+// ✅ Good - Explicit imports
+@Module({
+  imports: [AuthModule, DatabaseModule],
+  controllers: [UserController],
+})
+export class UserModule {}
+```
+
+### 4. Module Composition
+
+Build complex applications by composing smaller, focused modules:
+
+```typescript
+@Module({
+  imports: [AuthModule, UserModule, ProductModule, OrderModule],
+})
+export class AppModule {}
+```
+
+## Advanced Usage
+
+### Conditional Module Loading
+
+You can conditionally include modules based on environment or configuration:
+
+```typescript
+import { Module } from '@navios/core'
+
+const imports = [CoreModule]
+if (process.env.NODE_ENV === 'development') {
+  imports.push(DevToolsModule)
+}
+
+@Module({
+  imports,
+  controllers: [AppController],
+})
+export class AppModule {}
+```
+
+### Module with Complex Guard Setup
+
+```typescript
+import { Module } from '@navios/core'
+
+import { AuthGuard, RoleGuard, ThrottleGuard } from './guards'
+
+@Module({
+  guards: [
+    AuthGuard, // Applied first
+    RoleGuard, // Applied second
+    ThrottleGuard, // Applied last
+  ],
+  controllers: [AdminController],
+})
+export class AdminModule {}
+```
+
+## Testing Modules
+
+When testing modules, you can create test-specific module configurations:
+
+```typescript
+import { Module } from '@navios/core'
+
+import { MockUserService } from './mocks/user.service'
+import { UserController } from './user.controller'
+
+@Module({
+  controllers: [UserController],
+  // Use mock services for testing
+})
+export class TestUserModule {}
+```
+
+## Module Discovery
+
+Navios automatically discovers and registers modules through the module tree starting from your root application module.

package/docs/quick-start.md

@@ -0,0 +1,295 @@
+# Quick Start Guide
+
+This guide will help you get up and running with Navios quickly.
+
+## Prerequisites
+
+Before starting, make sure you have:
+
+- Node.js 18+ or Bun runtime
+- TypeScript knowledge
+- Basic understanding of HTTP APIs
+
+## Step 1: Install Dependencies
+
+Navios requires an HTTP adapter to function. Choose one based on your runtime:
+
+### For Node.js (Fastify Adapter)
+
+```bash
+npm install @navios/core @navios/builder @navios/adapter-fastify zod fastify
+```
+
+### For Bun Runtime (Bun Adapter)
+
+```bash
+npm install @navios/core @navios/builder @navios/adapter-bun zod
+```
+
+## Step 2: Define Your API
+
+Create a shared API definition file (`api/index.ts`):
+
+```ts
+import { builder } from '@navios/builder'
+
+import { z } from 'zod'
+
+export const api = builder({
+  useDiscriminatorResponse: true,
+})
+
+export const createUserEndpoint = api.declareEndpoint({
+  method: 'post',
+  url: '/users',
+  requestSchema: z.object({
+    name: z.string().min(1),
+    email: z.string().email(),
+  }),
+  responseSchema: z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string(),
+    createdAt: z.date(),
+  }),
+})
+
+export const getUserEndpoint = api.declareEndpoint({
+  method: 'get',
+  url: '/users/$id',
+  requestSchema: z.object({
+    id: z.string(),
+  }),
+  responseSchema: z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string(),
+    createdAt: z.date(),
+  }),
+})
+```
+
+## Step 3: Create a Service
+
+Create a user service (`services/user.service.ts`):
+
+```ts
+import { Injectable } from '@navios/core'
+
+export interface User {
+  id: string
+  name: string
+  email: string
+  createdAt: Date
+}
+
+@Injectable()
+export class UserService {
+  private users: User[] = []
+  private idCounter = 1
+
+  async createUser(name: string, email: string): Promise<User> {
+    const user: User = {
+      id: this.idCounter.toString(),
+      name,
+      email,
+      createdAt: new Date(),
+    }
+    this.users.push(user)
+    this.idCounter++
+    return user
+  }
+
+  async getUserById(id: string): Promise<User | undefined> {
+    return this.users.find((user) => user.id === id)
+  }
+
+  async getAllUsers(): Promise<User[]> {
+    return this.users
+  }
+}
+```
+
+## Step 4: Create a Controller
+
+Create a user controller (`controllers/user.controller.ts`):
+
+```ts
+import type { EndpointParams } from '@navios/core'
+
+import {
+  Controller,
+  Endpoint,
+  NotFoundException,
+  syncInject,
+} from '@navios/core'
+
+import { createUserEndpoint, getUserEndpoint } from '../api/index.js'
+import { UserService } from '../services/user.service.js'
+
+@Controller()
+export class UserController {
+  private userService = syncInject(UserService)
+
+  @Endpoint(createUserEndpoint)
+  async createUser(request: EndpointParams<typeof createUserEndpoint>) {
+    const { name, email } = request
+    return await this.userService.createUser(name, email)
+  }
+
+  @Endpoint(getUserEndpoint)
+  async getUser(request: EndpointParams<typeof getUserEndpoint>) {
+    const { id } = request
+    const user = await this.userService.getUserById(id)
+
+    if (!user) {
+      throw new NotFoundException('User not found')
+    }
+
+    return user
+  }
+}
+```
+
+## Step 5: Create an App Module
+
+Create your application module (`app.module.ts`):
+
+```ts
+import { Module } from '@navios/core'
+
+import { UserController } from './controllers/user.controller.js'
+import { UserService } from './services/user.service.js'
+
+@Module({
+  controllers: [UserController],
+  providers: [UserService],
+})
+export class AppModule {}
+```
+
+## Step 6: Create the Server
+
+Create your server entry point (`server.ts`):
+
+### Using Fastify Adapter (Node.js)
+
+```ts
+import { defineFastifyEnvironment } from '@navios/adapter-fastify'
+import { NaviosFactory } from '@navios/core'
+
+import { AppModule } from './app.module.js'
+
+async function bootstrap() {
+  const app = await NaviosFactory.create(AppModule, {
+    adapter: defineFastifyEnvironment(), // Required!
+  })
+
+  // Optional: Configure CORS
+  app.enableCors({
+    methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
+  })
+
+  // Optional: Set global prefix
+  app.setGlobalPrefix('/api')
+
+  await app.init()
+  await app.listen({ port: 3000, host: '0.0.0.0' })
+
+  console.log('Server running on http://localhost:3000')
+}
+
+bootstrap().catch(console.error)
+```
+
+### Using Bun Adapter (Bun Runtime)
+
+```ts
+import { defineBunEnvironment } from '@navios/adapter-bun'
+import { NaviosFactory } from '@navios/core'
+
+import { AppModule } from './app.module.js'
+
+async function bootstrap() {
+  const app = await NaviosFactory.create(AppModule, {
+    adapter: defineBunEnvironment(), // Required!
+  })
+
+  // Optional: Configure CORS
+  app.enableCors({
+    methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
+  })
+
+  // Optional: Set global prefix
+  app.setGlobalPrefix('/api')
+
+  await app.init()
+  await app.listen({ port: 3000, host: '0.0.0.0' })
+
+  console.log('Server running on http://localhost:3000')
+}
+
+bootstrap().catch(console.error)
+```
+
+## Step 7: Run Your Server
+
+### With Node.js
+
+```bash
+npx tsx server.ts
+```
+
+### With Bun
+
+```bash
+bun run server.ts
+```
+
+## Step 8: Test Your API
+
+Your server is now running! Test the endpoints:
+
+### Create a user
+
+```bash
+curl -X POST http://localhost:3000/api/users \
+  -H "Content-Type: application/json" \
+  -d '{"name": "John Doe", "email": "john@example.com"}'
+```
+
+### Get a user
+
+```bash
+curl http://localhost:3000/api/users/1
+```
+
+## Next Steps
+
+Now that you have a basic Navios server running:
+
+1. **Add more endpoints** - Extend your API definition
+2. **Add authentication** - Use guards for protecting endpoints
+3. **Add validation** - Leverage Zod schemas for complex validation
+4. **Add database integration** - Connect to your preferred database
+5. **Add error handling** - Use Navios exceptions for consistent error responses
+6. **Add testing** - Write unit and integration tests for your API
+
+## Common Gotchas
+
+1. **Missing Adapter**: The most common error is forgetting to install and configure an adapter. Navios will not work without one!
+
+2. **Import Paths**: Make sure to use the correct file extensions (`.js` or `.mjs`) in your imports for TypeScript compilation.
+
+3. **Async/Await**: Remember to use `async/await` in your endpoint handlers for proper error handling.
+
+4. **Type Safety**: Leverage TypeScript fully by using the provided types from Navios.
+
+## Help and Resources
+
+- [Full Documentation](./README.md)
+- [Adapter Guide](./adapters.md)
+- [GitHub Repository](https://github.com/Arilas/navios)
+- [Examples](../../examples/)
+
+Happy coding with Navios! 🚀