@groundbrick/express-adapter 0.0.1

package/README.md

@@ -0,0 +1,449 @@
+# @groundbrick/express-adapter
+
+Express.js integration adapter para o microframework TypeScript com middleware estruturado, controllers base e tratamento de erros.
+
+## Features Implementadas
+
+- **🚀 ExpressApp Class** - Classe principal com configuração Express pré-configurada
+- **📋 BaseController** - Controller base com async handlers e utilitários
+- **🛡️ Middleware Stack** - Error handling, request logging e response formatting
+- **🔐 JWT Authentication** - Middleware de autenticação JWT com role-based access
+- **📊 Response Helpers** - Formatação padronizada de respostas da API  
+- **✅ Validation Utilities** - Helpers de validação e sanitização
+- **📄 Pagination Support** - Utilitários de paginação e ordenação
+
+## Instalação
+
+```bash
+npm install @groundbrick/express-adapter
+```
+
+### Peer Dependencies
+
+```bash
+npm install express cors helmet compression express-rate-limit jsonwebtoken
+npm install --save-dev @types/express @types/cors @types/compression @types/jsonwebtoken
+```
+
+## Quick Start
+
+### 1. Configuração Básica da Aplicação
+
+```typescript
+// src/server.ts
+import { ExpressApp } from '@groundbrick/express-adapter';
+import { createLogger } from '@groundbrick/logger';
+
+const app = new ExpressApp({
+  port: 3000,
+  host: '0.0.0.0',
+  cors: {
+    origin: process.env.CORS_ORIGIN || 'http://localhost:5173',
+    credentials: true
+  },
+  trustProxy: true,
+  security: {
+    helmet: true,
+    rateLimit: {
+      windowMs: 15 * 60 * 1000,
+      max: 100
+    }
+  }
+});
+
+app.start().then(() => {
+  console.log('Server started successfully');
+});
+```
+
+### 2. JWT Authentication Setup
+
+```typescript
+// src/middleware/auth.ts
+import { JwtMiddleware } from '@groundbrick/express-adapter';
+import { createLogger } from '@groundbrick/logger';
+
+const logger = createLogger({ context: 'auth' });
+
+export const jwtAuth = new JwtMiddleware({
+  secret: process.env.JWT_SECRET || 'your-secret-key',
+  algorithms: ['HS256'],
+  skipPaths: ['/auth/login', '/auth/register', '/health'],
+  headerName: 'authorization',
+  cookieName: 'token'
+}, logger);
+
+// Usage in routes
+import { Router } from 'express';
+const router = Router();
+
+// Protected route
+router.get('/profile', jwtAuth.authenticate, userController.getProfile);
+
+// Optional auth (user context if token present)
+router.get('/public', jwtAuth.optional, contentController.getPublicContent);
+
+// Role-based access
+router.delete('/admin/users/:id', 
+  jwtAuth.authenticate, 
+  jwtAuth.requireRole(['admin', 'super-admin']), 
+  adminController.deleteUser
+);
+```
+
+### 3. Controller Implementation
+
+```typescript
+// src/controllers/UserController.ts
+import { Request, Response, NextFunction } from 'express';
+import { BaseController, AuthenticatedRequest } from '@groundbrick/express-adapter';
+import { Logger } from '@groundbrick/logger';
+import { ServiceResult } from '@groundbrick/service-base';
+
+export class UserController extends BaseController {
+  constructor(logger: Logger, private userService: UserService) {
+    super(logger);
+  }
+
+  getProfile = this.asyncHandler(async (req: AuthenticatedRequest, res: Response): Promise<ServiceResult<User>> => {
+    const userId = req.user!.userId; // Safe because of JWT middleware
+    const user = await this.userService.getUserById(userId);
+    return ServiceResult.success(user);
+  });
+
+  login = this.asyncHandler(async (req: Request, res: Response): Promise<ServiceResult<LoginResponse>> => {
+    const { email, password } = req.body;
+    
+    const user = await this.userService.authenticateUser(email, password);
+    const token = JwtMiddleware.generateToken(
+      { userId: user.id, email: user.email, roles: user.roles },
+      process.env.JWT_SECRET!,
+      '24h'
+    );
+
+    return ServiceResult.success({ user, token });
+  });
+}
+```
+
+### 4. Login/Logout Implementation
+
+```typescript
+// src/controllers/AuthController.ts
+export class AuthController extends BaseController {
+  login = this.asyncHandler(async (req: Request, res: Response): Promise<void> => {
+    const { email, password } = req.body;
+    
+    const user = await this.authService.login(email, password);
+    const token = JwtMiddleware.generateToken(
+      { 
+        userId: user.id, 
+        email: user.email, 
+        roles: user.roles || []
+      },
+      process.env.JWT_SECRET!,
+      '24h'
+    );
+
+    // Set as cookie (optional)
+    res.cookie('token', token, {
+      httpOnly: true,
+      secure: process.env.NODE_ENV === 'production',
+      maxAge: 24 * 60 * 60 * 1000 // 24 hours
+    });
+
+    res.json({
+      success: true,
+      data: { user, token },
+      meta: { timestamp: new Date().toISOString() }
+    });
+  });
+
+  logout = this.asyncHandler(async (req: Request, res: Response): Promise<void> => {
+    res.clearCookie('token');
+    res.json({
+      success: true,
+      message: 'Logged out successfully',
+      meta: { timestamp: new Date().toISOString() }
+    });
+  });
+}
+```
+
+## API Reference
+
+### JwtMiddleware
+
+```typescript
+interface JwtMiddlewareConfig {
+  secret?: string;
+  algorithms?: string[];
+  skipPaths?: string[];
+  cookieName?: string;
+  headerName?: string;
+  onTokenExpired?: (req: Request, res: Response) => void;
+  onTokenInvalid?: (req: Request, res: Response) => void;
+}
+
+class JwtMiddleware {
+  constructor(config: JwtMiddlewareConfig, logger: Logger);
+  
+  // Required authentication
+  authenticate: RequestHandler;
+  
+  // Optional authentication
+  optional: RequestHandler;
+  
+  // Role-based access control
+  requireRole(roles: string | string[]): RequestHandler;
+  
+  // Static helpers
+  static generateToken(payload: JwtPayload, secret: string, expiresIn?: string): string;
+  static decodeToken(token: string): JwtPayload | null;
+}
+```
+
+### JWT Payload Structure
+
+```typescript
+interface JwtPayload {
+  userId: number;
+  email: string;
+  roles?: string[];
+  [key: string]: unknown;
+}
+```
+
+### Authentication Patterns
+
+```typescript
+// 1. Basic protected route
+router.get('/protected', jwtAuth.authenticate, controller.method);
+
+// 2. Optional authentication
+router.get('/mixed', jwtAuth.optional, (req: AuthenticatedRequest, res) => {
+  if (req.user) {
+    // User is authenticated
+  } else {
+    // Anonymous access
+  }
+});
+
+// 3. Role-based access
+router.post('/admin', 
+  jwtAuth.authenticate,
+  jwtAuth.requireRole('admin'),
+  adminController.method
+);
+
+// 4. Multiple roles
+router.delete('/resource/:id',
+  jwtAuth.authenticate,
+  jwtAuth.requireRole(['admin', 'moderator']),
+  controller.method
+);
+```
+
+### ExpressApp
+
+```typescript
+interface ExpressConfig {
+  port?: number;
+  host?: string;
+  cors?: {
+    origin?: string | string[] | boolean;
+    credentials?: boolean;
+    methods?: string[];
+    allowedHeaders?: string[];
+  };
+  security?: {
+    helmet?: boolean;
+    rateLimit?: {
+      windowMs?: number;
+      max?: number;
+      message?: string;
+    };
+  };
+  compression?: boolean;
+  bodyParser?: {
+    json?: { limit?: string };
+    urlencoded?: { limit?: string; extended?: boolean };
+  };
+  logger?: Partial<LoggerConfig>;
+  trustProxy?: boolean;
+}
+```
+
+### BaseController
+
+```typescript
+abstract class BaseController {
+  constructor(logger: Logger);
+  
+  protected asyncHandler(handler: RouteHandler): RouteHandler;
+  protected getIdFromParams(req: Request, paramName?: string): string;
+  protected getQueryParam(req: Request, paramName: string, defaultValue?: string): string | undefined;
+  protected getQueryParamAsNumber(req: Request, paramName: string, defaultValue?: number): number | undefined;
+  protected getPaginationParams(req: Request): { page: number; limit: number; offset: number };
+}
+```
+
+### Response Helpers
+
+```typescript
+// Success responses
+ResponseHelper.success(res, data, 'Operation successful');
+ResponseHelper.created(res, newUser, 'User created');
+ResponseHelper.noContent(res);
+
+// Error responses  
+ResponseHelper.error(res, 'Something went wrong', 400);
+ResponseHelper.notFound(res, 'User not found');
+ResponseHelper.unauthorized(res, 'Invalid credentials');
+ResponseHelper.forbidden(res, 'Access denied');
+
+// Authentication responses
+ResponseHelper.unauthorized(res); // 401
+ResponseHelper.forbidden(res);    // 403
+```
+
+## Authentication Error Responses
+
+JWT middleware returns standardized error responses:
+
+```typescript
+// No token provided
+{
+  "success": false,
+  "error": {
+    "message": "No token provided",
+    "code": "NO_TOKEN"
+  },
+  "meta": {
+    "timestamp": "2024-01-15T10:30:00.000Z",
+    "requestId": "abc123"
+  }
+}
+
+// Token expired
+{
+  "success": false,
+  "error": {
+    "message": "Token has expired",
+    "code": "TOKEN_EXPIRED"
+  }
+}
+
+// Invalid token
+{
+  "success": false,
+  "error": {
+    "message": "Invalid token", 
+    "code": "TOKEN_INVALID"
+  }
+}
+
+// Insufficient permissions
+{
+  "success": false,
+  "error": {
+    "message": "Insufficient permissions",
+    "code": "INSUFFICIENT_PERMISSIONS",
+    "details": {
+      "requiredRoles": ["admin"],
+      "userRoles": ["user"]
+    }
+  }
+}
+```
+
+## Middleware Stack Automático
+
+A classe `ExpressApp` configura automaticamente:
+
+- **Security**: Helmet para headers de segurança
+- **Rate Limiting**: Proteção contra ataques de força bruta
+- **CORS**: Configuração de Cross-Origin Resource Sharing
+- **Compression**: Compressão gzip/deflate
+- **Body Parsing**: JSON e URL-encoded parsing
+- **Request Logging**: Log automático de requests com timing
+- **Response Formatting**: Formatação padronizada de respostas
+- **Error Handling**: Tratamento global de erros
+
+## Exemplo Completo com Autenticação
+
+```typescript
+// src/server.ts
+import { ExpressApp, JwtMiddleware } from '@groundbrick/express-adapter';
+import { createLogger } from '@groundbrick/logger';
+import { UserController } from './controllers/UserController';
+import { AuthController } from './controllers/AuthController';
+
+const logger = createLogger({ context: 'api-server' });
+
+// JWT Setup
+const jwtAuth = new JwtMiddleware({
+  secret: process.env.JWT_SECRET!,
+  skipPaths: ['/auth/login', '/auth/register', '/health'],
+  algorithms: ['HS256']
+}, logger);
+
+// Express App
+const app = new ExpressApp({
+  port: 3000,
+  cors: { origin: true, credentials: true },
+  trustProxy: true
+});
+
+// Auth routes (no JWT required)
+app.addRoutes([
+  { method: 'post', path: '/auth/login', handler: authController.login },
+  { method: 'post', path: '/auth/register', handler: authController.register },
+  { method: 'post', path: '/auth/logout', handler: authController.logout }
+]);
+
+// Protected routes
+app.addRoutes([
+  { 
+    method: 'get', 
+    path: '/api/profile', 
+    handler: userController.getProfile,
+    middleware: [jwtAuth.authenticate]
+  },
+  { 
+    method: 'get', 
+    path: '/api/admin/users', 
+    handler: userController.getAllUsers,
+    middleware: [jwtAuth.authenticate, jwtAuth.requireRole('admin')]
+  }
+]);
+
+app.start();
+```
+
+## Integração com Outros Packages
+
+Este adapter funciona perfeitamente com:
+
+- `@groundbrick/logger` - Sistema de logging (obrigatório)
+- `@groundbrick/service-base` - Base classes para services (obrigatório)
+- `@groundbrick/db-core` - Abstração de banco de dados
+
+## Dependencies
+
+### Required
+- `@groundbrick/logger` - Logging functionality
+- `@groundbrick/service-base` - Service base classes
+- `@groundbrick/db-core` - Database core abstractions
+
+### Peer Dependencies
+- `express` - Express.js framework
+- `cors` - CORS middleware
+- `helmet` - Security middleware
+- `compression` - Response compression
+- `express-rate-limit` - Rate limiting
+- `jsonwebtoken` - JWT token handling
+
+## License
+
+MIT

package/dist/core/BaseController.d.ts

@@ -0,0 +1,23 @@
+import type { Request } from 'express';
+import { Logger } from '@groundbrick/logger';
+import { RouteHandler } from '../types/RouteHandler.js';
+import { IBaseController } from '../types/Controller.js';
+export declare abstract class BaseController implements IBaseController {
+    readonly logger: Logger;
+    constructor(logger: Logger);
+    /**
+     * Wraps a request handler with error handling and async support
+     * @param handler The route handler function
+     * @returns A wrapped handler function
+     */
+    readonly asyncHandler: (handler: RouteHandler) => RouteHandler;
+    protected getIdFromParams(req: Request, paramName?: string): string;
+    protected getQueryParam(req: Request, paramName: string, defaultValue?: string): string | undefined;
+    protected getQueryParamAsNumber(req: Request, paramName: string, defaultValue?: number): number | undefined;
+    protected getPaginationParams(req: Request): {
+        page: number;
+        limit: number;
+        offset: number;
+    };
+}
+//# sourceMappingURL=BaseController.d.ts.map

package/dist/core/BaseController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseController.d.ts","sourceRoot":"","sources":["../../src/core/BaseController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA0B,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,8BAAsB,cAAe,YAAW,eAAe;IAC3D,SAAgB,MAAM,EAAE,MAAM,CAAC;gBAEnB,MAAM,EAAE,MAAM;IAI1B;;;;OAIG;IACH,SAAgB,YAAY,GAAI,SAAS,YAAY,KAAG,YAAY,CAUlE;IAEF,SAAS,CAAC,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,GAAE,MAAa,GAAG,MAAM;IAQzE,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAInG,SAAS,CAAC,qBAAqB,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAY3G,SAAS,CAAC,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;CAO/F"}

package/dist/core/BaseController.js

@@ -0,0 +1,50 @@
+export class BaseController {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Wraps a request handler with error handling and async support
+     * @param handler The route handler function
+     * @returns A wrapped handler function
+     */
+    asyncHandler = (handler) => {
+        return async (req, res, next) => {
+            try {
+                const result = await handler(req, res, next);
+                // If the result is a Response object or void, it means the response has been handled
+                return result;
+            }
+            catch (error) {
+                next(error);
+            }
+        };
+    };
+    getIdFromParams(req, paramName = 'id') {
+        const id = req.params[paramName];
+        if (!id) {
+            throw new Error(`Missing required parameter: ${paramName}`);
+        }
+        return id;
+    }
+    getQueryParam(req, paramName, defaultValue) {
+        return req.query[paramName] || defaultValue;
+    }
+    getQueryParamAsNumber(req, paramName, defaultValue) {
+        const value = req.query[paramName];
+        if (!value)
+            return defaultValue;
+        const num = parseInt(value, 10);
+        if (isNaN(num)) {
+            throw new Error(`Invalid number format for parameter: ${paramName}`);
+        }
+        return num;
+    }
+    getPaginationParams(req) {
+        const page = Math.max(1, this.getQueryParamAsNumber(req, 'page', 1) || 1);
+        const limit = Math.min(100, Math.max(1, this.getQueryParamAsNumber(req, 'limit', 10) || 10));
+        const offset = (page - 1) * limit;
+        return { page, limit, offset };
+    }
+}
+//# sourceMappingURL=BaseController.js.map

package/dist/core/BaseController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseController.js","sourceRoot":"","sources":["../../src/core/BaseController.ts"],"names":[],"mappings":"AAMA,MAAM,OAAgB,cAAc;IAChB,MAAM,CAAS;IAE/B,YAAY,MAAc;QACtB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACa,YAAY,GAAG,CAAC,OAAqB,EAAgB,EAAE;QACnE,OAAO,KAAK,EAAE,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAE,EAAE;YAC7D,IAAI,CAAC;gBACD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;gBAC7C,qFAAqF;gBACrF,OAAO,MAAM,CAAC;YAClB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACb,IAAI,CAAC,KAAK,CAAC,CAAC;YAChB,CAAC;QACL,CAAC,CAAC;IACN,CAAC,CAAC;IAEQ,eAAe,CAAC,GAAY,EAAE,YAAoB,IAAI;QAC5D,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACjC,IAAI,CAAC,EAAE,EAAE,CAAC;YACN,MAAM,IAAI,KAAK,CAAC,+BAA+B,SAAS,EAAE,CAAC,CAAC;QAChE,CAAC;QACD,OAAO,EAAE,CAAC;IACd,CAAC;IAES,aAAa,CAAC,GAAY,EAAE,SAAiB,EAAE,YAAqB;QAC1E,OAAO,GAAG,CAAC,KAAK,CAAC,SAAS,CAAW,IAAI,YAAY,CAAC;IAC1D,CAAC;IAES,qBAAqB,CAAC,GAAY,EAAE,SAAiB,EAAE,YAAqB;QAClF,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,SAAS,CAAW,CAAC;QAC7C,IAAI,CAAC,KAAK;YAAE,OAAO,YAAY,CAAC;QAEhC,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAChC,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,wCAAwC,SAAS,EAAE,CAAC,CAAC;QACzE,CAAC;QAED,OAAO,GAAG,CAAC;IACf,CAAC;IAES,mBAAmB,CAAC,GAAY;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1E,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,qBAAqB,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC7F,MAAM,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC;QAElC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IACnC,CAAC;CACJ"}

package/dist/core/ExpressApp.d.ts

@@ -0,0 +1,20 @@
+import { Express } from 'express';
+import { ExpressConfig } from '../types/ExpressConfig.js';
+import { RouteDefinition } from '../types/RouteHandler.js';
+export declare class ExpressApp {
+    private app;
+    private logger;
+    private config;
+    private errorHandler;
+    private requestLogger;
+    constructor(config?: ExpressConfig);
+    private setupMiddleware;
+    private setupStaticFiles;
+    private setupRoutes;
+    addRoutes(routes: RouteDefinition[]): void;
+    addRoute(route: RouteDefinition): void;
+    getApp(): Express;
+    setupErrorHandling(): void;
+    start(): Promise<void>;
+}
+//# sourceMappingURL=ExpressApp.d.ts.map

package/dist/core/ExpressApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpressApp.d.ts","sourceRoot":"","sources":["../../src/core/ExpressApp.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,OAAO,EAAqB,MAAM,SAAS,CAAC;AAO9D,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAK3D,qBAAa,UAAU;IACnB,OAAO,CAAC,GAAG,CAAU;IACrB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,aAAa,CAAgB;gBAEzB,MAAM,GAAE,aAAkB;IAqCtC,OAAO,CAAC,eAAe;IA6DvB,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,WAAW;IAoBZ,SAAS,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,IAAI;IAS1C,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAItC,MAAM,IAAI,OAAO;IAIjB,kBAAkB,IAAI,IAAI;IAoB1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CA6BhC"}