bootifyjs 0.1.0 → 0.1.1

package/README.md

@@ -2,6 +2,16 @@
 
 A Spring Boot inspired Node.js framework with TypeScript, Dependency Injection, and Validation.
 
+## Features
+
+- **Dependency Injection**: Automatic constructor injection with `@Injectable`, `@Service`, and `@Repository` decorators
+- **REST API**: Easy controller definition with `@Controller`, `@Get`, `@Post`, etc.
+- **Validation**: Request validation with Zod schemas
+- **Configuration**: Environment-based configuration with automatic mapping
+- **OpenAPI**: Automatic OpenAPI documentation generation
+- **Logging**: Comprehensive logging system with context tracking
+- **Event System**: Type-safe event system with middleware support
+
 ## Installation
 
 ```bash
@@ -44,130 +54,370 @@ async function main() {
 main().catch(console.error);
 ```
 
-## Simple Configuration Management
+## Core Concepts
+
+### Controllers
+
+Controllers handle HTTP requests and define your API endpoints.
 
-The framework provides a very simple configuration management system that automatically maps environment variables to nested configuration properties.
+```typescript
+import { Controller, Get, Post, Put, Delete, Param, Body, Query } from 'bootifyjs';
 
-### How It Works
+@Controller('/users')
+export class UserController {
+  constructor(private userService: UserService) {}
+  
+  @Get('/')
+  getAllUsers(@Query('limit') limit?: string) {
+    return this.userService.getAllUsers(limit ? parseInt(limit) : undefined);
+  }
+  
+  @Get('/:id')
+  getUserById(@Param('id') id: string) {
+    return this.userService.getUserById(id);
+  }
+  
+  @Post('/')
+  createUser(@Body() userData: CreateUserDto) {
+    return this.userService.createUser(userData);
+  }
+  
+  @Put('/:id')
+  updateUser(@Param('id') id: string, @Body() userData: UpdateUserDto) {
+    return this.userService.updateUser(id, userData);
+  }
+  
+  @Delete('/:id')
+  deleteUser(@Param('id') id: string) {
+    return this.userService.deleteUser(id);
+  }
+}
+```
 
-1. **Single Configuration Class**: Define one `AppConfig` class with your configuration structure
-2. **Automatic Mapping**: Environment variables with `BOOTIFY_` prefix are automatically mapped to nested properties
-3. **Type Conversion**: Values are automatically converted to numbers and booleans when possible
+### Services
 
-### Usage
+Services contain your business logic and can be injected into controllers or other services.
 
-**1. Define Your Configuration Structure:**
 ```typescript
-import { Config } from '../core/config';
+import { Service } from 'bootifyjs';
 
-@Config('BOOTIFY')
+@Service()
+export class UserService {
+  constructor(private userRepository: UserRepository) {}
+  
+  getAllUsers(limit?: number) {
+    return this.userRepository.findAll(limit);
+  }
+  
+  getUserById(id: string) {
+    return this.userRepository.findById(id);
+  }
+  
+  // More methods...
+}
+```
+
+### Repositories
+
+Repositories handle data access and can be injected into services.
+
+```typescript
+import { Repository } from 'bootifyjs';
+
+@Repository()
+export class UserRepository {
+  private users = []; // In a real app, this would be a database connection
+  
+  findAll(limit?: number) {
+    if (limit) {
+      return this.users.slice(0, limit);
+    }
+    return this.users;
+  }
+  
+  findById(id: string) {
+    return this.users.find(user => user.id === id);
+  }
+  
+  // More methods...
+}
+```
+
+### Validation
+
+Use Zod schemas to validate request data.
+
+```typescript
+import { z } from 'zod';
+import { Controller, Post, Body, ValidateBody } from 'bootifyjs';
+
+const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2).max(100),
+  age: z.number().min(18).optional()
+});
+
+@Controller('/users')
+export class UserController {
+  @Post('/')
+  @ValidateBody(createUserSchema)
+  createUser(@Body() userData: z.infer<typeof createUserSchema>) {
+    // userData is now validated and typed
+    return this.userService.createUser(userData);
+  }
+}
+```
+
+### Configuration
+
+Define your configuration structure and automatically map environment variables.
+
+```typescript
+import { Config, getConfigInstance } from 'bootifyjs';
+
+@Config('APP')
 export class AppConfig {
-  SERVICE_NAME: string = 'bootifyjs-app';
+  SERVICE_NAME: string = 'my-service';
   
   server: {
     port: number;
     host: string;
-    name?: string;
   } = {
     port: 3000,
     host: 'localhost'
   };
   
   database: {
-    host: string;
-    port: number;
-    name: string;
+    url: string;
+    poolSize: number;
   } = {
-    host: 'localhost',
-    port: 5432,
-    name: 'myapp'
+    url: 'postgres://localhost:5432/mydb',
+    poolSize: 10
   };
 }
+
+// Environment variables like APP_SERVER_PORT=8080 will be automatically mapped
+const config = getConfigInstance(AppConfig);
+console.log(config.server.port); // 8080
 ```
 
-**2. Set Environment Variables:**
-```bash
-# Maps to appConfig.SERVICE_NAME
-BOOTIFY_SERVICE_NAME=my-awesome-app
+### Event System
 
-# Maps to appConfig.server.port  
-BOOTIFY_SERVER_PORT=8080
+Create a type-safe event system for decoupled communication.
 
-# Maps to appConfig.server.host
-BOOTIFY_SERVER_HOST=0.0.0.0
+```typescript
+import { Event, EventEmitter, EventListener, EventHandler } from 'bootifyjs';
+
+// Define an event
+@Event('user.created')
+class UserCreatedEvent {
+  id: string;
+  email: string;
+  timestamp: Date = new Date();
+}
 
-# Maps to appConfig.server.name
-BOOTIFY_SERVER_NAME=my-server
+// Emit events from services
+@Service()
+@EventEmitter()
+class UserService {
+  private eventBus; // Injected by @EventEmitter
+  
+  async createUser(userData) {
+    const user = await this.userRepository.create(userData);
+    
+    // Emit event
+    await this.eventBus.emit('user.created', {
+      id: user.id,
+      email: user.email
+    });
+    
+    return user;
+  }
+}
+
+// Handle events
+@EventListener()
+class UserEventHandlers {
+  @EventHandler('user.created')
+  async onUserCreated(event: UserCreatedEvent) {
+    console.log(`User created: ${event.email}`);
+    // Send welcome email, update analytics, etc.
+  }
+}
+```
 
-# Maps to appConfig.database.host
-BOOTIFY_DATABASE_HOST=postgres-server
+### Logging
 
-# Maps to appConfig.database.port
-BOOTIFY_DATABASE_PORT=5432
+Comprehensive logging system with context tracking.
+
+```typescript
+import { Logger, Log } from 'bootifyjs';
+
+@Service()
+@Logger('UserService')
+export class UserService {
+  private logger; // Injected by @Logger
+  
+  @Log({ logArgs: true, logDuration: true })
+  async createUser(userData) {
+    this.logger.info('Creating new user', { email: userData.email });
+    
+    // Business logic...
+    
+    this.logger.info('User created successfully');
+    return user;
+  }
+}
 ```
 
-**3. Access Configuration:**
+## Bootstrapping Your Application
+
+There are two ways to bootstrap your application:
+
+### 1. Using createBootifyApp (Recommended)
+
 ```typescript
-import { getConfigInstance } from './core/config';
-import { AppConfig } from './config/app.config';
+import { createBootifyApp } from 'bootifyjs';
+import { UserController } from './controllers/user.controller';
 
-const appConfig = getConfigInstance(AppConfig);
+async function main() {
+  const { app, start, stop } = await createBootifyApp({
+    port: 3000,
+    controllers: [UserController],
+    enableSwagger: true,
+    enableCors: true
+  });
+  
+  await start();
+  console.log('Server running at http://localhost:3000');
+  console.log('API docs available at http://localhost:3000/api-docs');
+}
 
-console.log(appConfig.SERVICE_NAME);     // 'my-awesome-app'
-console.log(appConfig.server.port);      // 8080
-console.log(appConfig.server.host);      // '0.0.0.0'
-console.log(appConfig.database.host);    // 'postgres-server'
+main().catch(console.error);
 ```
 
-**4. Inject into Services:**
-```typescript
-import { InjectConfig } from './core/decorators';
+### 2. Manual Bootstrap
 
-@Service()
-export class MyService {
-  constructor(@InjectConfig(AppConfig) private config: AppConfig) {}
+```typescript
+import { 
+  Application, 
+  configureLogging, 
+  configureEventSystem,
+  corsMiddleware,
+  contextMiddleware,
+  createRequestLoggingMiddleware,
+  swaggerMiddleware,
+  OpenAPIGenerator
+} from 'bootifyjs';
+import { UserController } from './controllers/user.controller';
+
+async function bootstrap() {
+  // Initialize logging
+  const { logger, startupLogger } = configureLogging();
   
-  doSomething() {
-    console.log(`Service: ${this.config.SERVICE_NAME}`);
-    console.log(`Running on port: ${this.config.server.port}`);
-  }
+  // Initialize event system
+  const eventBus = configureEventSystem();
+  
+  // Generate OpenAPI documentation
+  const openApiGenerator = new OpenAPIGenerator({
+    title: 'My API',
+    version: '1.0.0',
+    description: 'My API description'
+  });
+  
+  const controllers = [UserController];
+  openApiGenerator.addControllers(controllers);
+  const openApiSpec = openApiGenerator.getSpec();
+  
+  // Create application
+  const app = new Application({
+    controllers,
+    middlewares: [
+      contextMiddleware,
+      corsMiddleware,
+      createRequestLoggingMiddleware(),
+      swaggerMiddleware(openApiSpec)
+    ],
+    port: 3000,
+    hostname: 'localhost'
+  });
+  
+  await app.start();
+  logger.info('Server started');
 }
+
+bootstrap().catch(console.error);
 ```
 
-### Environment Variable Mapping Rules
+## Middleware
 
-The system automatically converts environment variable names to nested property paths:
+Create custom middleware to handle cross-cutting concerns.
 
-- `BOOTIFY_SERVICE_NAME` → `appConfig.SERVICE_NAME`
-- `BOOTIFY_SERVER_PORT` → `appConfig.server.port`
-- `BOOTIFY_SERVER_HOST` → `appConfig.server.host`
-- `BOOTIFY_DATABASE_HOST` → `appConfig.database.host`
-- `BOOTIFY_DATABASE_PORT` → `appConfig.database.port`
+```typescript
+import { Middleware } from 'bootifyjs';
 
-### Automatic Type Conversion
+export const loggingMiddleware: Middleware = async (req, res, next) => {
+  const start = Date.now();
+  console.log(`${req.method} ${req.url} - Request started`);
+  
+  await next();
+  
+  const duration = Date.now() - start;
+  console.log(`${req.method} ${req.url} - Request completed in ${duration}ms`);
+};
+```
 
-- **Numbers**: `"8080"` → `8080`
-- **Booleans**: `"true"` → `true`, `"false"` → `false`
-- **Strings**: Everything else remains as string
+## OpenAPI Documentation
 
-### Getting Started
+BootifyJS automatically generates OpenAPI documentation for your API.
 
-1. Copy `example.env` to `.env` and modify values
-2. Set your environment variables following the `BOOTIFY_*` pattern
-3. Access your configuration using `getConfigInstance(AppConfig)`
+```typescript
+import { Controller, Get, ApiTags, ApiOperation, ApiResponse } from 'bootifyjs';
+
+@Controller('/health')
+@ApiTags('Health')
+export class HealthController {
+  @Get('/')
+  @ApiOperation({
+    summary: 'Health check',
+    description: 'Check if the API is running'
+  })
+  @ApiResponse(200, {
+    description: 'API is healthy',
+    schema: healthResponseSchema
+  })
+  health() {
+    return { status: 'OK', timestamp: new Date().toISOString() };
+  }
+}
+```
 
-That's it! No complex setup, no manual property mapping - just define your structure and set your environment variables.
+## Error Handling
 
-## Features
+BootifyJS provides built-in error classes for common HTTP errors.
 
-- **Dependency Injection**: Automatic constructor injection with `@Injectable`, `@Service`, and `@Repository` decorators
-- **REST API**: Easy controller definition with `@Controller`, `@Get`, `@Post`, etc.
-- **Validation**: Request validation with Zod schemas
-- **Configuration**: Environment-based configuration with automatic mapping
-- **OpenAPI**: Automatic OpenAPI documentation generation
-- **Logging**: Comprehensive logging system with context tracking
-- **Event System**: Type-safe event system with middleware support
+```typescript
+import { NotFoundError, ValidationError } from 'bootifyjs';
+
+@Service()
+export class UserService {
+  getUserById(id: string) {
+    const user = this.userRepository.findById(id);
+    if (!user) {
+      throw new NotFoundError(`User with id ${id} not found`);
+    }
+    return user;
+  }
+  
+  createUser(userData) {
+    if (!userData.email) {
+      throw new ValidationError('Email is required');
+    }
+    // ...
+  }
+}
+```
 
-## Documentation
+## License
 
-For more detailed documentation, please visit our [GitHub repository](https://github.com/bootifyjs/bootifyjs).
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bootifyjs",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Spring Boot inspired Node.js framework with custom DI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",