@hemia/common 0.0.5 → 0.0.7

package/README.md

@@ -1,4 +1,3 @@
-
 # @hemia/common
 
 Sistema de decoradores y utilidades para crear controladores HTTP con TypeScript usando metadata reflection.
@@ -241,6 +240,103 @@ externalRedirect() {
   // Redirige temporalmente
 }
 ```
+
+---
+
+## 🆕 Decoradores Avanzados
+
+### Validación y Transformación
+
+#### `@Validate(validatorFn)`
+Valida el parámetro usando una función personalizada.
+
+```typescript
+@Post('/')
+create(@Body() data: any, @Validate(validateUser) _: any) { /* ... */ }
+```
+
+#### `@Transform(transformFn)`
+Transforma el parámetro usando una función personalizada.
+
+```typescript
+@Post('/')
+create(@Body() data: any, @Transform(toUserDto) _: any) { /* ... */ }
+```
+
+#### `@Custom(key: string)`
+Extrae datos personalizados del request.
+
+```typescript
+@Get('/')
+handler(@Custom('customData') custom: any) { /* ... */ }
+```
+
+### Decoradores de Guardias y Autenticación
+
+#### `@ReqUser()`
+Inyecta el usuario autenticado (por ejemplo, desde JWTGuard).
+
+```typescript
+@Get('/profile')
+profile(@ReqUser() user: any) { /* ... */ }
+```
+
+#### `@ReqPermissions()`
+Inyecta los permisos del usuario.
+
+```typescript
+@Get('/admin')
+admin(@ReqPermissions() permissions: string[]) { /* ... */ }
+```
+
+#### `@ReqContext()`
+Inyecta el contexto de la solicitud.
+
+```typescript
+@Get('/context')
+context(@ReqContext() ctx: any) { /* ... */ }
+```
+
+#### `@Cookies(key?: string)`
+Extrae cookies de la petición.
+
+```typescript
+@Get('/')
+handler(@Cookies('token') token: string) { /* ... */ }
+```
+
+#### `@Files()`
+Extrae todos los archivos enviados en la solicitud.
+
+```typescript
+@Post('/upload')
+upload(@Files() files: any[]) { /* ... */ }
+```
+
+#### `@File(key?: string)`
+Extrae un archivo específico.
+
+```typescript
+@Post('/avatar')
+avatar(@File('avatar') avatar: any) { /* ... */ }
+```
+
+#### `@Locale()`
+Extrae el locale del usuario.
+
+```typescript
+@Get('/')
+handler(@Locale() locale: string) { /* ... */ }
+```
+
+#### `@ReqAuth()`
+Extrae datos de autenticación.
+
+```typescript
+@Get('/auth')
+auth(@ReqAuth() auth: any) { /* ... */ }
+```
+
 ---
 
 ## 🔍 Metadata Keys
@@ -288,4 +384,3 @@ ISC
 ## ✨ Generado con Hemia CLI
 
 Este paquete fue generado usando [Hemia CLI](https://www.npmjs.com/package/@hemia/cli).
-    

package/dist/hemia-common.esm.js

@@ -6,12 +6,16 @@ const METADATA_KEYS = {
     PARAMS: 'params',
     HEADERS: 'headers',
     REDIRECT: 'redirect',
+    COOKIES: 'cookies',
     GUARDS: 'hemia:guards',
     INTERCEPTORS: 'hemia:interceptors',
     CUSTOM: 'hemia:custom',
     SERIALIZE: 'hemia:serialize',
     ROLES: 'hemia:roles',
-    PERMISSIONS: 'hemia:permissions'
+    PERMISSIONS: 'hemia:permissions',
+    TRANSFORMERS: 'hemia:transformers',
+    VALIDATORS: 'hemia:validators',
+    CUSTOMS: 'hemia:customs',
 };
 
 const Controller = (basePath = '/') => {
@@ -43,6 +47,14 @@ var ParamType;
     ParamType["SESSION"] = "SESSION";
     ParamType["IP"] = "IP";
     ParamType["HOST"] = "HOST";
+    ParamType["COOKIES"] = "COOKIES";
+    ParamType["FILES"] = "FILES";
+    ParamType["FILE"] = "FILE";
+    ParamType["LOCALE"] = "LOCALE";
+    ParamType["AUTH"] = "AUTH";
+    ParamType["USER"] = "USER";
+    ParamType["PERMISSIONS"] = "PERMISSIONS";
+    ParamType["CONTEXT"] = "CONTEXT";
 })(ParamType || (ParamType = {}));
 
 const createMethodDecorator = (method) => {
@@ -71,18 +83,126 @@ const createParamDecorator = (type) => {
         };
     };
 };
+/**
+ * Inyecta el objeto Request completo.
+ * @example
+ * async handler(@Request() req) {}
+ */
 const Request = createParamDecorator(ParamType.REQUEST);
+/**
+ * Alias para Request.
+ * @example
+ * async handler(@Req() req) {}
+ */
 const Req = createParamDecorator(ParamType.REQUEST);
+/**
+ * Inyecta el objeto Response.
+ * @example
+ * async handler(@Response() res) {}
+ */
 const Response = createParamDecorator(ParamType.RESPONSE);
+/**
+ * Alias para Response.
+ * @example
+ * async handler(@Res() res) {}
+ */
 const Res = createParamDecorator(ParamType.RESPONSE);
+/**
+ * Inyecta el objeto Next para middlewares.
+ * @example
+ * async handler(@Next() next) {}
+ */
 const Next = createParamDecorator(ParamType.NEXT);
+/**
+ * Inyecta la sesión del usuario.
+ * @example
+ * async handler(@Session() session) {}
+ */
 const Session = createParamDecorator(ParamType.SESSION);
+/**
+ * Inyecta la IP del cliente.
+ * @example
+ * async handler(@Ip() ip) {}
+ */
 const Ip = createParamDecorator(ParamType.IP);
+/**
+ * Inyecta el host de la solicitud.
+ * @example
+ * async handler(@Host() host) {}
+ */
 const Host = createParamDecorator(ParamType.HOST);
+/**
+ * Inyecta el cuerpo de la solicitud.
+ * @example
+ * async handler(@Body() body) {}
+ */
 const Body = createParamDecorator(ParamType.BODY);
+/**
+ * Inyecta los parámetros de consulta (query).
+ * @example
+ * async handler(@Query('search') search) {}
+ */
 const Query = createParamDecorator(ParamType.QUERY);
+/**
+ * Inyecta los parámetros de la URL.
+ * @example
+ * async handler(@Param('id') id) {}
+ */
 const Param = createParamDecorator(ParamType.PARAM);
+/**
+ * Inyecta los encabezados de la solicitud.
+ * @example
+ * async handler(@Headers('authorization') auth) {}
+ */
 const Headers = createParamDecorator(ParamType.HEADERS);
+/**
+ * Inyecta los cookies de la solicitud.
+ * @example
+ * async handler(@Cookies('token') token) {}
+ */
+const Cookies = createParamDecorator(ParamType.COOKIES);
+/**
+ * Inyecta todos los archivos enviados en la solicitud.
+ * @example
+ * async handler(@Files() files) {}
+ */
+const Files = createParamDecorator(ParamType.FILES);
+/**
+ * Inyecta un archivo específico de la solicitud.
+ * @example
+ * async handler(@File('avatar') avatar) {}
+ */
+const File = createParamDecorator(ParamType.FILE);
+/**
+ * Inyecta el locale del usuario.
+ * @example
+ * async handler(@Locale() locale) {}
+ */
+const Locale = createParamDecorator(ParamType.LOCALE);
+/**
+ * Inyecta datos de autenticación.
+ * @example
+ * async handler(@ReqAuth() auth) {}
+ */
+const ReqAuth = createParamDecorator(ParamType.AUTH);
+/**
+ * Inyecta el usuario autenticado.
+ * @example
+ * async handler(@ReqUser() user) {}
+ */
+const ReqUser = createParamDecorator(ParamType.USER);
+/**
+ * Inyecta los permisos del usuario.
+ * @example
+ * async handler(@ReqPermissions() permissions) {}
+ */
+const ReqPermissions = createParamDecorator(ParamType.PERMISSIONS);
+/**
+ * Inyecta el contexto de la solicitud.
+ * @example
+ * async handler(@ReqContext() context) {}
+ */
+const ReqContext = createParamDecorator(ParamType.CONTEXT);
 
 const Header = (name, value) => {
     return (target, propertyKey, descriptor) => {
@@ -162,6 +282,60 @@ function Serialize(dto) {
     return SetMetadata(METADATA_KEYS.SERIALIZE, dto);
 }
 
+/**
+ * Decorador para extraer datos personalizados del request.
+ *
+ * @example
+ * // Extrae el valor de 'customData' del request
+ * @Custom('customData')
+ * async handler(@Custom() customData: any) {}
+ *
+ * @param key Clave personalizada a extraer del request.
+ */
+function Custom(key) {
+    return (target, propertyKey, parameterIndex) => {
+        const existingCustoms = Reflect.getMetadata(METADATA_KEYS.CUSTOMS, target, propertyKey || '') || [];
+        existingCustoms.push({ index: parameterIndex, key });
+        Reflect.defineMetadata(METADATA_KEYS.CUSTOMS, existingCustoms, target, propertyKey || '');
+    };
+}
+
+/**
+ * Decorador para validar datos de entrada en un controlador.
+ *
+ * @example
+ * // Valida el parámetro 'body' usando la función validateUser
+ * @Validate(validateUser)
+ * async create(@Body() body: any) {}
+ *
+ * @param validator Función de validación que recibe el valor y retorna booleano o lanza error.
+ */
+function Validate(validator) {
+    return (target, propertyKey, parameterIndex) => {
+        const existingValidators = Reflect.getMetadata(METADATA_KEYS.VALIDATORS, target, propertyKey || '') || [];
+        existingValidators.push({ index: parameterIndex, validator });
+        Reflect.defineMetadata(METADATA_KEYS.VALIDATORS, existingValidators, target, propertyKey || '');
+    };
+}
+
+/**
+ * Decorador para transformar datos de entrada en un controlador.
+ *
+ * @example
+ * // Transforma el parámetro 'body' usando la función toUserDto
+ * @Transform(toUserDto)
+ * async create(@Body() body: any) {}
+ *
+ * @param transformer Función de transformación que recibe el valor y retorna el nuevo valor.
+ */
+function Transform(transformer) {
+    return (target, propertyKey, parameterIndex) => {
+        const existingTransformers = Reflect.getMetadata(METADATA_KEYS.TRANSFORMERS, target, propertyKey || '') || [];
+        existingTransformers.push({ index: parameterIndex, transformer });
+        Reflect.defineMetadata(METADATA_KEYS.TRANSFORMERS, existingTransformers, target, propertyKey || '');
+    };
+}
+
 class ApiResponse {
     static success(data, message = 'OK', status = 200) {
         return {
@@ -250,4 +424,235 @@ class HttpErrorWithDetails extends HttpError {
     }
 }
 
-export { ApiResponse, BadRequestError, Body, ConflictError, Controller, CustomHttpError, Delete, ForbiddenError, GatewayTimeoutError, Get, Head, Header, Headers, Host, HttpError, HttpErrorWithDetails, HttpMethod, InternalServerError, Ip, METADATA_KEYS, Next, NotFoundError, Options, Param, ParamType, Patch, Post, Put, Query, Redirect, Req, Request, Res, Response, Serialize, ServiceUnavailableError, Session, SetMetadata, UnauthorizedError, UnprocessableEntityError, UseGuards, UseInterceptors, isRedirectResponse };
+class PersistenceError extends Error {
+    constructor(message, originalError) {
+        super(message);
+        this.originalError = originalError;
+        this.name = 'PersistenceError';
+    }
+}
+class DataNotFoundError extends PersistenceError {
+    constructor(entity, criteria, originalError) {
+        super(`${entity} not found with criteria: ${criteria}`, originalError);
+        this.name = 'DataNotFoundError';
+    }
+}
+class DataConflictError extends PersistenceError {
+    constructor(entity, criteria, originalError) {
+        super(`Data conflict for ${entity} with criteria: ${criteria}`, originalError);
+        this.name = 'DataConflictError';
+    }
+}
+class DataValidationError extends PersistenceError {
+    constructor(message, originalError) {
+        super(`Data Validation Error: ${message}`, originalError);
+        this.name = 'DataValidationError';
+    }
+}
+class TransactionError extends PersistenceError {
+    constructor(message, originalError) {
+        super(`Transaction Error: ${message}`, originalError);
+        this.name = 'TransactionError';
+    }
+}
+class QueryExecutionError extends PersistenceError {
+    constructor(query, originalError) {
+        super(`Query Execution Error for query: ${query}`, originalError);
+        this.name = 'QueryExecutionError';
+    }
+}
+class ConnectionError extends PersistenceError {
+    constructor(databaseType, originalError) {
+        super(`Connection Error to ${databaseType} database`, originalError);
+        this.name = 'ConnectionError';
+    }
+}
+class SchemaMismatchError extends PersistenceError {
+    constructor(expectedSchema, actualSchema, originalError) {
+        super(`Schema Mismatch Error: expected ${expectedSchema}, got ${actualSchema}`, originalError);
+        this.name = 'SchemaMismatchError';
+    }
+}
+class DataIntegrityError extends PersistenceError {
+    constructor(message, originalError) {
+        super(`Data Integrity Error: ${message}`, originalError);
+        this.name = 'DataIntegrityError';
+    }
+}
+class BackupError extends PersistenceError {
+    constructor(message, originalError) {
+        super(`Backup Error: ${message}`, originalError);
+        this.name = 'BackupError';
+    }
+}
+class RestoreError extends PersistenceError {
+    constructor(message, originalError) {
+        super(`Restore Error: ${message}`, originalError);
+        this.name = 'RestoreError';
+    }
+}
+class IndexingError extends PersistenceError {
+    constructor(indexName, originalError) {
+        super(`Indexing Error on index: ${indexName}`, originalError);
+        this.name = 'IndexingError';
+    }
+}
+class DataMigrationError extends PersistenceError {
+    constructor(migrationName, originalError) {
+        super(`Data Migration Error during migration: ${migrationName}`, originalError);
+        this.name = 'DataMigrationError';
+    }
+}
+class ResourceLimitError extends PersistenceError {
+    constructor(resourceType, limit, originalError) {
+        super(`Resource Limit Exceeded: ${resourceType} limit of ${limit} has been exceeded`, originalError);
+        this.name = 'ResourceLimitError';
+    }
+}
+
+/**
+ * Errores de lógica de negocio (Business Layer)
+ * No conocen HTTP, son agnósticos a la infraestructura
+ */
+class DomainError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DomainError';
+    }
+}
+class EntityNotFoundError extends DomainError {
+    constructor(entity, criteria) {
+        super(`${entity} not found with criteria: ${criteria}`);
+        this.name = 'EntityNotFoundError';
+    }
+}
+class DuplicateEntityError extends DomainError {
+    constructor(entity, criteria) {
+        super(`Duplicate ${entity} found with criteria: ${criteria}`);
+        this.name = 'DuplicateEntityError';
+    }
+}
+class ValidationError extends DomainError {
+    constructor(message) {
+        super(`Validation Error: ${message}`);
+        this.name = 'ValidationError';
+    }
+}
+class BusinessRuleViolationError extends DomainError {
+    constructor(message) {
+        super(`Business Rule Violation: ${message}`);
+        this.name = 'BusinessRuleViolationError';
+    }
+}
+class OperationNotAllowedError extends DomainError {
+    constructor(operation) {
+        super(`Operation not allowed: ${operation}`);
+        this.name = 'OperationNotAllowedError';
+    }
+}
+class DependencyError extends DomainError {
+    constructor(dependency, message) {
+        super(`Dependency Error in ${dependency}: ${message}`);
+        this.name = 'DependencyError';
+    }
+}
+class TimeoutError extends DomainError {
+    constructor(operation, timeout) {
+        super(`Timeout Error: Operation "${operation}" exceeded time limit of ${timeout}ms`);
+        this.name = 'TimeoutError';
+    }
+}
+class ResourceLimitExceededError extends DomainError {
+    constructor(resource, limit) {
+        super(`Resource Limit Exceeded: ${resource} limit of ${limit} has been exceeded`);
+        this.name = 'ResourceLimitExceededError';
+    }
+}
+class ConfigurationError extends DomainError {
+    constructor(message) {
+        super(`Configuration Error: ${message}`);
+        this.name = 'ConfigurationError';
+    }
+}
+
+class InfrastructureError extends Error {
+    constructor(message, originalError) {
+        super(message);
+        this.originalError = originalError;
+        this.name = 'InfrastructureError';
+    }
+}
+class InfraDatabaseConnectionError extends InfrastructureError {
+    constructor(dbType, originalError) {
+        super(`Failed to connect to the ${dbType} database`, originalError);
+        this.name = 'InfraDatabaseConnectionError';
+    }
+}
+class InfraCacheConnectionError extends InfrastructureError {
+    constructor(cacheType, originalError) {
+        super(`Failed to connect to the ${cacheType} cache`, originalError);
+        this.name = 'InfraCacheConnectionError';
+    }
+}
+class InfraMessageQueueError extends InfrastructureError {
+    constructor(queueType, originalError) {
+        super(`Message Queue Error in ${queueType}`, originalError);
+        this.name = 'InfraMessageQueueError';
+    }
+}
+class InfraExternalServiceError extends InfrastructureError {
+    constructor(serviceName, originalError) {
+        super(`External Service Error: ${serviceName}`, originalError);
+        this.name = 'InfraExternalServiceError';
+    }
+}
+class InfraConfigurationError extends InfrastructureError {
+    constructor(configItem, originalError) {
+        super(`Configuration Error: ${configItem}`, originalError);
+        this.name = 'InfraConfigurationError';
+    }
+}
+class InfraNetworkError extends InfrastructureError {
+    constructor(message, originalError) {
+        super(`Network Error: ${message}`, originalError);
+        this.name = 'InfraNetworkError';
+    }
+}
+class InfraTimeoutError extends InfrastructureError {
+    constructor(operation, timeout, originalError) {
+        super(`Timeout Error: Operation "${operation}" exceeded time limit of ${timeout}ms`, originalError);
+        this.name = 'InfraTimeoutError';
+    }
+}
+class InfraAuthenticationError extends InfrastructureError {
+    constructor(message, originalError) {
+        super(`Authentication Error: ${message}`, originalError);
+        this.name = 'InfraAuthenticationError';
+    }
+}
+class InfraAuthorizationError extends InfrastructureError {
+    constructor(message, originalError) {
+        super(`Authorization Error: ${message}`, originalError);
+        this.name = 'InfraAuthorizationError';
+    }
+}
+class InfraServiceUnavailableError extends InfrastructureError {
+    constructor(serviceName, originalError) {
+        super(`Service Unavailable: ${serviceName}`, originalError);
+        this.name = 'InfraServiceUnavailableError';
+    }
+}
+class InfraDataSerializationError extends InfrastructureError {
+    constructor(dataType, originalError) {
+        super(`Data Serialization Error for type: ${dataType}`, originalError);
+        this.name = 'InfraDataSerializationError';
+    }
+}
+class InfraDataDeserializationError extends InfrastructureError {
+    constructor(dataType, originalError) {
+        super(`Data Deserialization Error for type: ${dataType}`, originalError);
+        this.name = 'InfraDataDeserializationError';
+    }
+}
+
+export { ApiResponse, BackupError, BadRequestError, Body, BusinessRuleViolationError, ConfigurationError, ConflictError, ConnectionError, Controller, Cookies, Custom, CustomHttpError, DataConflictError, DataIntegrityError, DataMigrationError, DataNotFoundError, DataValidationError, Delete, DependencyError, DomainError, DuplicateEntityError, EntityNotFoundError, File, Files, ForbiddenError, GatewayTimeoutError, Get, Head, Header, Headers, Host, HttpError, HttpErrorWithDetails, HttpMethod, IndexingError, InfraAuthenticationError, InfraAuthorizationError, InfraCacheConnectionError, InfraConfigurationError, InfraDataDeserializationError, InfraDataSerializationError, InfraDatabaseConnectionError, InfraExternalServiceError, InfraMessageQueueError, InfraNetworkError, InfraServiceUnavailableError, InfraTimeoutError, InfrastructureError, InternalServerError, Ip, Locale, METADATA_KEYS, Next, NotFoundError, OperationNotAllowedError, Options, Param, ParamType, Patch, PersistenceError, Post, Put, Query, QueryExecutionError, Redirect, Req, ReqAuth, ReqContext, ReqPermissions, ReqUser, Request, Res, ResourceLimitError, ResourceLimitExceededError, Response, RestoreError, SchemaMismatchError, Serialize, ServiceUnavailableError, Session, SetMetadata, TimeoutError, TransactionError, Transform, UnauthorizedError, UnprocessableEntityError, UseGuards, UseInterceptors, Validate, ValidationError, isRedirectResponse };

package/dist/hemia-common.js

@@ -8,12 +8,16 @@ const METADATA_KEYS = {
     PARAMS: 'params',
     HEADERS: 'headers',
     REDIRECT: 'redirect',
+    COOKIES: 'cookies',
     GUARDS: 'hemia:guards',
     INTERCEPTORS: 'hemia:interceptors',
     CUSTOM: 'hemia:custom',
     SERIALIZE: 'hemia:serialize',
     ROLES: 'hemia:roles',
-    PERMISSIONS: 'hemia:permissions'
+    PERMISSIONS: 'hemia:permissions',
+    TRANSFORMERS: 'hemia:transformers',
+    VALIDATORS: 'hemia:validators',
+    CUSTOMS: 'hemia:customs',
 };
 
 const Controller = (basePath = '/') => {
@@ -45,6 +49,14 @@ exports.ParamType = void 0;
     ParamType["SESSION"] = "SESSION";
     ParamType["IP"] = "IP";
     ParamType["HOST"] = "HOST";
+    ParamType["COOKIES"] = "COOKIES";
+    ParamType["FILES"] = "FILES";
+    ParamType["FILE"] = "FILE";
+    ParamType["LOCALE"] = "LOCALE";
+    ParamType["AUTH"] = "AUTH";
+    ParamType["USER"] = "USER";
+    ParamType["PERMISSIONS"] = "PERMISSIONS";
+    ParamType["CONTEXT"] = "CONTEXT";
 })(exports.ParamType || (exports.ParamType = {}));
 
 const createMethodDecorator = (method) => {
@@ -73,18 +85,126 @@ const createParamDecorator = (type) => {
         };
     };
 };
+/**
+ * Inyecta el objeto Request completo.
+ * @example
+ * async handler(@Request() req) {}
+ */
 const Request = createParamDecorator(exports.ParamType.REQUEST);
+/**
+ * Alias para Request.
+ * @example
+ * async handler(@Req() req) {}
+ */
 const Req = createParamDecorator(exports.ParamType.REQUEST);
+/**
+ * Inyecta el objeto Response.
+ * @example
+ * async handler(@Response() res) {}
+ */
 const Response = createParamDecorator(exports.ParamType.RESPONSE);
+/**
+ * Alias para Response.
+ * @example
+ * async handler(@Res() res) {}
+ */
 const Res = createParamDecorator(exports.ParamType.RESPONSE);
+/**
+ * Inyecta el objeto Next para middlewares.
+ * @example
+ * async handler(@Next() next) {}
+ */
 const Next = createParamDecorator(exports.ParamType.NEXT);
+/**
+ * Inyecta la sesión del usuario.
+ * @example
+ * async handler(@Session() session) {}
+ */
 const Session = createParamDecorator(exports.ParamType.SESSION);
+/**
+ * Inyecta la IP del cliente.
+ * @example
+ * async handler(@Ip() ip) {}
+ */
 const Ip = createParamDecorator(exports.ParamType.IP);
+/**
+ * Inyecta el host de la solicitud.
+ * @example
+ * async handler(@Host() host) {}
+ */
 const Host = createParamDecorator(exports.ParamType.HOST);
+/**
+ * Inyecta el cuerpo de la solicitud.
+ * @example
+ * async handler(@Body() body) {}
+ */
 const Body = createParamDecorator(exports.ParamType.BODY);
+/**
+ * Inyecta los parámetros de consulta (query).
+ * @example
+ * async handler(@Query('search') search) {}
+ */
 const Query = createParamDecorator(exports.ParamType.QUERY);
+/**
+ * Inyecta los parámetros de la URL.
+ * @example
+ * async handler(@Param('id') id) {}
+ */
 const Param = createParamDecorator(exports.ParamType.PARAM);
+/**
+ * Inyecta los encabezados de la solicitud.
+ * @example
+ * async handler(@Headers('authorization') auth) {}
+ */
 const Headers = createParamDecorator(exports.ParamType.HEADERS);
+/**
+ * Inyecta los cookies de la solicitud.
+ * @example
+ * async handler(@Cookies('token') token) {}
+ */
+const Cookies = createParamDecorator(exports.ParamType.COOKIES);
+/**
+ * Inyecta todos los archivos enviados en la solicitud.
+ * @example
+ * async handler(@Files() files) {}
+ */
+const Files = createParamDecorator(exports.ParamType.FILES);
+/**
+ * Inyecta un archivo específico de la solicitud.
+ * @example
+ * async handler(@File('avatar') avatar) {}
+ */
+const File = createParamDecorator(exports.ParamType.FILE);
+/**
+ * Inyecta el locale del usuario.
+ * @example
+ * async handler(@Locale() locale) {}
+ */
+const Locale = createParamDecorator(exports.ParamType.LOCALE);
+/**
+ * Inyecta datos de autenticación.
+ * @example
+ * async handler(@ReqAuth() auth) {}
+ */
+const ReqAuth = createParamDecorator(exports.ParamType.AUTH);
+/**
+ * Inyecta el usuario autenticado.
+ * @example
+ * async handler(@ReqUser() user) {}
+ */
+const ReqUser = createParamDecorator(exports.ParamType.USER);
+/**
+ * Inyecta los permisos del usuario.
+ * @example
+ * async handler(@ReqPermissions() permissions) {}
+ */
+const ReqPermissions = createParamDecorator(exports.ParamType.PERMISSIONS);
+/**
+ * Inyecta el contexto de la solicitud.
+ * @example
+ * async handler(@ReqContext() context) {}
+ */
+const ReqContext = createParamDecorator(exports.ParamType.CONTEXT);
 
 const Header = (name, value) => {
     return (target, propertyKey, descriptor) => {
@@ -164,6 +284,60 @@ function Serialize(dto) {
     return SetMetadata(METADATA_KEYS.SERIALIZE, dto);
 }
 
+/**
+ * Decorador para extraer datos personalizados del request.
+ *
+ * @example
+ * // Extrae el valor de 'customData' del request
+ * @Custom('customData')
+ * async handler(@Custom() customData: any) {}
+ *
+ * @param key Clave personalizada a extraer del request.
+ */
+function Custom(key) {
+    return (target, propertyKey, parameterIndex) => {
+        const existingCustoms = Reflect.getMetadata(METADATA_KEYS.CUSTOMS, target, propertyKey || '') || [];
+        existingCustoms.push({ index: parameterIndex, key });
+        Reflect.defineMetadata(METADATA_KEYS.CUSTOMS, existingCustoms, target, propertyKey || '');
+    };
+}
+
+/**
+ * Decorador para validar datos de entrada en un controlador.
+ *
+ * @example
+ * // Valida el parámetro 'body' usando la función validateUser
+ * @Validate(validateUser)
+ * async create(@Body() body: any) {}
+ *
+ * @param validator Función de validación que recibe el valor y retorna booleano o lanza error.
+ */
+function Validate(validator) {
+    return (target, propertyKey, parameterIndex) => {
+        const existingValidators = Reflect.getMetadata(METADATA_KEYS.VALIDATORS, target, propertyKey || '') || [];
+        existingValidators.push({ index: parameterIndex, validator });
+        Reflect.defineMetadata(METADATA_KEYS.VALIDATORS, existingValidators, target, propertyKey || '');
+    };
+}
+
+/**
+ * Decorador para transformar datos de entrada en un controlador.
+ *
+ * @example
+ * // Transforma el parámetro 'body' usando la función toUserDto
+ * @Transform(toUserDto)
+ * async create(@Body() body: any) {}
+ *
+ * @param transformer Función de transformación que recibe el valor y retorna el nuevo valor.
+ */
+function Transform(transformer) {
+    return (target, propertyKey, parameterIndex) => {
+        const existingTransformers = Reflect.getMetadata(METADATA_KEYS.TRANSFORMERS, target, propertyKey || '') || [];
+        existingTransformers.push({ index: parameterIndex, transformer });
+        Reflect.defineMetadata(METADATA_KEYS.TRANSFORMERS, existingTransformers, target, propertyKey || '');
+    };
+}
+
 class ApiResponse {
     static success(data, message = 'OK', status = 200) {
         return {
@@ -252,13 +426,261 @@ class HttpErrorWithDetails extends HttpError {
     }
 }
 
+class PersistenceError extends Error {
+    constructor(message, originalError) {
+        super(message);
+        this.originalError = originalError;
+        this.name = 'PersistenceError';
+    }
+}
+class DataNotFoundError extends PersistenceError {
+    constructor(entity, criteria, originalError) {
+        super(`${entity} not found with criteria: ${criteria}`, originalError);
+        this.name = 'DataNotFoundError';
+    }
+}
+class DataConflictError extends PersistenceError {
+    constructor(entity, criteria, originalError) {
+        super(`Data conflict for ${entity} with criteria: ${criteria}`, originalError);
+        this.name = 'DataConflictError';
+    }
+}
+class DataValidationError extends PersistenceError {
+    constructor(message, originalError) {
+        super(`Data Validation Error: ${message}`, originalError);
+        this.name = 'DataValidationError';
+    }
+}
+class TransactionError extends PersistenceError {
+    constructor(message, originalError) {
+        super(`Transaction Error: ${message}`, originalError);
+        this.name = 'TransactionError';
+    }
+}
+class QueryExecutionError extends PersistenceError {
+    constructor(query, originalError) {
+        super(`Query Execution Error for query: ${query}`, originalError);
+        this.name = 'QueryExecutionError';
+    }
+}
+class ConnectionError extends PersistenceError {
+    constructor(databaseType, originalError) {
+        super(`Connection Error to ${databaseType} database`, originalError);
+        this.name = 'ConnectionError';
+    }
+}
+class SchemaMismatchError extends PersistenceError {
+    constructor(expectedSchema, actualSchema, originalError) {
+        super(`Schema Mismatch Error: expected ${expectedSchema}, got ${actualSchema}`, originalError);
+        this.name = 'SchemaMismatchError';
+    }
+}
+class DataIntegrityError extends PersistenceError {
+    constructor(message, originalError) {
+        super(`Data Integrity Error: ${message}`, originalError);
+        this.name = 'DataIntegrityError';
+    }
+}
+class BackupError extends PersistenceError {
+    constructor(message, originalError) {
+        super(`Backup Error: ${message}`, originalError);
+        this.name = 'BackupError';
+    }
+}
+class RestoreError extends PersistenceError {
+    constructor(message, originalError) {
+        super(`Restore Error: ${message}`, originalError);
+        this.name = 'RestoreError';
+    }
+}
+class IndexingError extends PersistenceError {
+    constructor(indexName, originalError) {
+        super(`Indexing Error on index: ${indexName}`, originalError);
+        this.name = 'IndexingError';
+    }
+}
+class DataMigrationError extends PersistenceError {
+    constructor(migrationName, originalError) {
+        super(`Data Migration Error during migration: ${migrationName}`, originalError);
+        this.name = 'DataMigrationError';
+    }
+}
+class ResourceLimitError extends PersistenceError {
+    constructor(resourceType, limit, originalError) {
+        super(`Resource Limit Exceeded: ${resourceType} limit of ${limit} has been exceeded`, originalError);
+        this.name = 'ResourceLimitError';
+    }
+}
+
+/**
+ * Errores de lógica de negocio (Business Layer)
+ * No conocen HTTP, son agnósticos a la infraestructura
+ */
+class DomainError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DomainError';
+    }
+}
+class EntityNotFoundError extends DomainError {
+    constructor(entity, criteria) {
+        super(`${entity} not found with criteria: ${criteria}`);
+        this.name = 'EntityNotFoundError';
+    }
+}
+class DuplicateEntityError extends DomainError {
+    constructor(entity, criteria) {
+        super(`Duplicate ${entity} found with criteria: ${criteria}`);
+        this.name = 'DuplicateEntityError';
+    }
+}
+class ValidationError extends DomainError {
+    constructor(message) {
+        super(`Validation Error: ${message}`);
+        this.name = 'ValidationError';
+    }
+}
+class BusinessRuleViolationError extends DomainError {
+    constructor(message) {
+        super(`Business Rule Violation: ${message}`);
+        this.name = 'BusinessRuleViolationError';
+    }
+}
+class OperationNotAllowedError extends DomainError {
+    constructor(operation) {
+        super(`Operation not allowed: ${operation}`);
+        this.name = 'OperationNotAllowedError';
+    }
+}
+class DependencyError extends DomainError {
+    constructor(dependency, message) {
+        super(`Dependency Error in ${dependency}: ${message}`);
+        this.name = 'DependencyError';
+    }
+}
+class TimeoutError extends DomainError {
+    constructor(operation, timeout) {
+        super(`Timeout Error: Operation "${operation}" exceeded time limit of ${timeout}ms`);
+        this.name = 'TimeoutError';
+    }
+}
+class ResourceLimitExceededError extends DomainError {
+    constructor(resource, limit) {
+        super(`Resource Limit Exceeded: ${resource} limit of ${limit} has been exceeded`);
+        this.name = 'ResourceLimitExceededError';
+    }
+}
+class ConfigurationError extends DomainError {
+    constructor(message) {
+        super(`Configuration Error: ${message}`);
+        this.name = 'ConfigurationError';
+    }
+}
+
+class InfrastructureError extends Error {
+    constructor(message, originalError) {
+        super(message);
+        this.originalError = originalError;
+        this.name = 'InfrastructureError';
+    }
+}
+class InfraDatabaseConnectionError extends InfrastructureError {
+    constructor(dbType, originalError) {
+        super(`Failed to connect to the ${dbType} database`, originalError);
+        this.name = 'InfraDatabaseConnectionError';
+    }
+}
+class InfraCacheConnectionError extends InfrastructureError {
+    constructor(cacheType, originalError) {
+        super(`Failed to connect to the ${cacheType} cache`, originalError);
+        this.name = 'InfraCacheConnectionError';
+    }
+}
+class InfraMessageQueueError extends InfrastructureError {
+    constructor(queueType, originalError) {
+        super(`Message Queue Error in ${queueType}`, originalError);
+        this.name = 'InfraMessageQueueError';
+    }
+}
+class InfraExternalServiceError extends InfrastructureError {
+    constructor(serviceName, originalError) {
+        super(`External Service Error: ${serviceName}`, originalError);
+        this.name = 'InfraExternalServiceError';
+    }
+}
+class InfraConfigurationError extends InfrastructureError {
+    constructor(configItem, originalError) {
+        super(`Configuration Error: ${configItem}`, originalError);
+        this.name = 'InfraConfigurationError';
+    }
+}
+class InfraNetworkError extends InfrastructureError {
+    constructor(message, originalError) {
+        super(`Network Error: ${message}`, originalError);
+        this.name = 'InfraNetworkError';
+    }
+}
+class InfraTimeoutError extends InfrastructureError {
+    constructor(operation, timeout, originalError) {
+        super(`Timeout Error: Operation "${operation}" exceeded time limit of ${timeout}ms`, originalError);
+        this.name = 'InfraTimeoutError';
+    }
+}
+class InfraAuthenticationError extends InfrastructureError {
+    constructor(message, originalError) {
+        super(`Authentication Error: ${message}`, originalError);
+        this.name = 'InfraAuthenticationError';
+    }
+}
+class InfraAuthorizationError extends InfrastructureError {
+    constructor(message, originalError) {
+        super(`Authorization Error: ${message}`, originalError);
+        this.name = 'InfraAuthorizationError';
+    }
+}
+class InfraServiceUnavailableError extends InfrastructureError {
+    constructor(serviceName, originalError) {
+        super(`Service Unavailable: ${serviceName}`, originalError);
+        this.name = 'InfraServiceUnavailableError';
+    }
+}
+class InfraDataSerializationError extends InfrastructureError {
+    constructor(dataType, originalError) {
+        super(`Data Serialization Error for type: ${dataType}`, originalError);
+        this.name = 'InfraDataSerializationError';
+    }
+}
+class InfraDataDeserializationError extends InfrastructureError {
+    constructor(dataType, originalError) {
+        super(`Data Deserialization Error for type: ${dataType}`, originalError);
+        this.name = 'InfraDataDeserializationError';
+    }
+}
+
 exports.ApiResponse = ApiResponse;
+exports.BackupError = BackupError;
 exports.BadRequestError = BadRequestError;
 exports.Body = Body;
+exports.BusinessRuleViolationError = BusinessRuleViolationError;
+exports.ConfigurationError = ConfigurationError;
 exports.ConflictError = ConflictError;
+exports.ConnectionError = ConnectionError;
 exports.Controller = Controller;
+exports.Cookies = Cookies;
+exports.Custom = Custom;
 exports.CustomHttpError = CustomHttpError;
+exports.DataConflictError = DataConflictError;
+exports.DataIntegrityError = DataIntegrityError;
+exports.DataMigrationError = DataMigrationError;
+exports.DataNotFoundError = DataNotFoundError;
+exports.DataValidationError = DataValidationError;
 exports.Delete = Delete;
+exports.DependencyError = DependencyError;
+exports.DomainError = DomainError;
+exports.DuplicateEntityError = DuplicateEntityError;
+exports.EntityNotFoundError = EntityNotFoundError;
+exports.File = File;
+exports.Files = Files;
 exports.ForbiddenError = ForbiddenError;
 exports.GatewayTimeoutError = GatewayTimeoutError;
 exports.Get = Get;
@@ -268,28 +690,59 @@ exports.Headers = Headers;
 exports.Host = Host;
 exports.HttpError = HttpError;
 exports.HttpErrorWithDetails = HttpErrorWithDetails;
+exports.IndexingError = IndexingError;
+exports.InfraAuthenticationError = InfraAuthenticationError;
+exports.InfraAuthorizationError = InfraAuthorizationError;
+exports.InfraCacheConnectionError = InfraCacheConnectionError;
+exports.InfraConfigurationError = InfraConfigurationError;
+exports.InfraDataDeserializationError = InfraDataDeserializationError;
+exports.InfraDataSerializationError = InfraDataSerializationError;
+exports.InfraDatabaseConnectionError = InfraDatabaseConnectionError;
+exports.InfraExternalServiceError = InfraExternalServiceError;
+exports.InfraMessageQueueError = InfraMessageQueueError;
+exports.InfraNetworkError = InfraNetworkError;
+exports.InfraServiceUnavailableError = InfraServiceUnavailableError;
+exports.InfraTimeoutError = InfraTimeoutError;
+exports.InfrastructureError = InfrastructureError;
 exports.InternalServerError = InternalServerError;
 exports.Ip = Ip;
+exports.Locale = Locale;
 exports.METADATA_KEYS = METADATA_KEYS;
 exports.Next = Next;
 exports.NotFoundError = NotFoundError;
+exports.OperationNotAllowedError = OperationNotAllowedError;
 exports.Options = Options;
 exports.Param = Param;
 exports.Patch = Patch;
+exports.PersistenceError = PersistenceError;
 exports.Post = Post;
 exports.Put = Put;
 exports.Query = Query;
+exports.QueryExecutionError = QueryExecutionError;
 exports.Redirect = Redirect;
 exports.Req = Req;
+exports.ReqAuth = ReqAuth;
+exports.ReqContext = ReqContext;
+exports.ReqPermissions = ReqPermissions;
+exports.ReqUser = ReqUser;
 exports.Request = Request;
 exports.Res = Res;
+exports.ResourceLimitError = ResourceLimitError;
+exports.ResourceLimitExceededError = ResourceLimitExceededError;
 exports.Response = Response;
+exports.RestoreError = RestoreError;
+exports.SchemaMismatchError = SchemaMismatchError;
 exports.Serialize = Serialize;
 exports.ServiceUnavailableError = ServiceUnavailableError;
 exports.Session = Session;
 exports.SetMetadata = SetMetadata;
+exports.TimeoutError = TimeoutError;
+exports.TransactionError = TransactionError;
+exports.Transform = Transform;
 exports.UnauthorizedError = UnauthorizedError;
 exports.UnprocessableEntityError = UnprocessableEntityError;
 exports.UseGuards = UseGuards;
 exports.UseInterceptors = UseInterceptors;
+exports.Validate = Validate;
+exports.ValidationError = ValidationError;
 exports.isRedirectResponse = isRedirectResponse;

package/dist/types/decorators/custom/custom.decorator.d.ts

@@ -0,0 +1,12 @@
+import 'reflect-metadata';
+/**
+ * Decorador para extraer datos personalizados del request.
+ *
+ * @example
+ * // Extrae el valor de 'customData' del request
+ * @Custom('customData')
+ * async handler(@Custom() customData: any) {}
+ *
+ * @param key Clave personalizada a extraer del request.
+ */
+export declare function Custom(key: string): ParameterDecorator;

package/dist/types/decorators/custom/index.d.ts

@@ -0,0 +1 @@
+export * from './custom.decorator';

package/dist/types/decorators/http/param.decorators.d.ts

@@ -1,13 +1,121 @@
 import 'reflect-metadata';
+/**
+ * Inyecta el objeto Request completo.
+ * @example
+ * async handler(@Request() req) {}
+ */
 export declare const Request: (data?: string) => ParameterDecorator;
+/**
+ * Alias para Request.
+ * @example
+ * async handler(@Req() req) {}
+ */
 export declare const Req: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta el objeto Response.
+ * @example
+ * async handler(@Response() res) {}
+ */
 export declare const Response: (data?: string) => ParameterDecorator;
+/**
+ * Alias para Response.
+ * @example
+ * async handler(@Res() res) {}
+ */
 export declare const Res: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta el objeto Next para middlewares.
+ * @example
+ * async handler(@Next() next) {}
+ */
 export declare const Next: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta la sesión del usuario.
+ * @example
+ * async handler(@Session() session) {}
+ */
 export declare const Session: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta la IP del cliente.
+ * @example
+ * async handler(@Ip() ip) {}
+ */
 export declare const Ip: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta el host de la solicitud.
+ * @example
+ * async handler(@Host() host) {}
+ */
 export declare const Host: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta el cuerpo de la solicitud.
+ * @example
+ * async handler(@Body() body) {}
+ */
 export declare const Body: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta los parámetros de consulta (query).
+ * @example
+ * async handler(@Query('search') search) {}
+ */
 export declare const Query: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta los parámetros de la URL.
+ * @example
+ * async handler(@Param('id') id) {}
+ */
 export declare const Param: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta los encabezados de la solicitud.
+ * @example
+ * async handler(@Headers('authorization') auth) {}
+ */
 export declare const Headers: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta los cookies de la solicitud.
+ * @example
+ * async handler(@Cookies('token') token) {}
+ */
+export declare const Cookies: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta todos los archivos enviados en la solicitud.
+ * @example
+ * async handler(@Files() files) {}
+ */
+export declare const Files: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta un archivo específico de la solicitud.
+ * @example
+ * async handler(@File('avatar') avatar) {}
+ */
+export declare const File: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta el locale del usuario.
+ * @example
+ * async handler(@Locale() locale) {}
+ */
+export declare const Locale: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta datos de autenticación.
+ * @example
+ * async handler(@ReqAuth() auth) {}
+ */
+export declare const ReqAuth: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta el usuario autenticado.
+ * @example
+ * async handler(@ReqUser() user) {}
+ */
+export declare const ReqUser: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta los permisos del usuario.
+ * @example
+ * async handler(@ReqPermissions() permissions) {}
+ */
+export declare const ReqPermissions: (data?: string) => ParameterDecorator;
+/**
+ * Inyecta el contexto de la solicitud.
+ * @example
+ * async handler(@ReqContext() context) {}
+ */
+export declare const ReqContext: (data?: string) => ParameterDecorator;

package/dist/types/decorators/index.d.ts

@@ -1,3 +1,6 @@
 export * from "./http";
 export * from "./metadata";
 export * from "./core";
+export * from "./custom";
+export * from "./validation";
+export * from "./transform";

package/dist/types/decorators/metadata.d.ts

@@ -4,10 +4,14 @@ export declare const METADATA_KEYS: {
     readonly PARAMS: "params";
     readonly HEADERS: "headers";
     readonly REDIRECT: "redirect";
+    readonly COOKIES: "cookies";
     readonly GUARDS: "hemia:guards";
     readonly INTERCEPTORS: "hemia:interceptors";
     readonly CUSTOM: "hemia:custom";
     readonly SERIALIZE: "hemia:serialize";
     readonly ROLES: "hemia:roles";
     readonly PERMISSIONS: "hemia:permissions";
+    readonly TRANSFORMERS: "hemia:transformers";
+    readonly VALIDATORS: "hemia:validators";
+    readonly CUSTOMS: "hemia:customs";
 };

package/dist/types/decorators/transform/index.d.ts

@@ -0,0 +1 @@
+export * from './transform.decorator';

package/dist/types/decorators/transform/transform.decorator.d.ts

@@ -0,0 +1,12 @@
+import 'reflect-metadata';
+/**
+ * Decorador para transformar datos de entrada en un controlador.
+ *
+ * @example
+ * // Transforma el parámetro 'body' usando la función toUserDto
+ * @Transform(toUserDto)
+ * async create(@Body() body: any) {}
+ *
+ * @param transformer Función de transformación que recibe el valor y retorna el nuevo valor.
+ */
+export declare function Transform(transformer: (value: any) => any): ParameterDecorator;

package/dist/types/decorators/validation/index.d.ts

@@ -0,0 +1 @@
+export * from "./validate.decorator";

package/dist/types/decorators/validation/validate.decorator.d.ts

@@ -0,0 +1,12 @@
+import 'reflect-metadata';
+/**
+ * Decorador para validar datos de entrada en un controlador.
+ *
+ * @example
+ * // Valida el parámetro 'body' usando la función validateUser
+ * @Validate(validateUser)
+ * async create(@Body() body: any) {}
+ *
+ * @param validator Función de validación que recibe el valor y retorna booleano o lanza error.
+ */
+export declare function Validate(validator: (value: any) => boolean | void): ParameterDecorator;

package/dist/types/enums/param-type.enum.d.ts

@@ -8,5 +8,13 @@ export declare enum ParamType {
     HEADERS = "HEADERS",
     SESSION = "SESSION",
     IP = "IP",
-    HOST = "HOST"
+    HOST = "HOST",
+    COOKIES = "COOKIES",
+    FILES = "FILES",
+    FILE = "FILE",
+    LOCALE = "LOCALE",
+    AUTH = "AUTH",
+    USER = "USER",
+    PERMISSIONS = "PERMISSIONS",
+    CONTEXT = "CONTEXT"
 }

package/dist/types/errors/index.d.ts

@@ -1 +1,4 @@
 export * from "./http.error";
+export * from "./persistence.error";
+export * from "./domain.error";
+export * from "./infrastructure.error";

package/dist/types/interfaces/configuration/smtp-configuration.interface.d.ts

@@ -0,0 +1,7 @@
+export interface SmtpConfiguration {
+    SMTP_HOST: string;
+    SMTP_PORT: number;
+    SMTP_USER: string;
+    SMTP_PASSWORD: string;
+    SMTP_SECURE: boolean;
+}

package/dist/types/interfaces/index.d.ts

@@ -12,3 +12,4 @@ export * from './configuration/mongo-db-configuration.interface';
 export * from './configuration/aws-s3-configuration.interface';
 export * from './configuration/drizzle-db-configuration.interface';
 export * from './configuration/olap-db-configuration.interface';
+export * from './configuration/smtp-configuration.interface';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hemia/common",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Paquete común para proyectos de Hemia",
   "main": "dist/hemia-common.js",
   "module": "dist/hemia-common.esm.js",