@hemia/common 0.0.12 → 0.0.13

package/dist/hemia-common.esm.js

@@ -10,6 +10,7 @@ const METADATA_KEYS = {
     COOKIES: 'cookies',
     GUARDS: 'hemia:guards',
     INTERCEPTORS: 'hemia:interceptors',
+    PIPES: 'hemia:pipes',
     CUSTOM: 'hemia:custom',
     SERIALIZE: 'hemia:serialize',
     ROLES: 'hemia:roles',
@@ -73,10 +74,15 @@ const Options = createMethodDecorator(HttpMethod.OPTIONS);
 const Head = createMethodDecorator(HttpMethod.HEAD);
 
 const createParamDecorator = (type) => {
-    return (data) => {
+    return (data, ...pipes) => {
         return (target, propertyKey, parameterIndex) => {
             const existingParams = Reflect.getMetadata(METADATA_KEYS.PARAMS, target, propertyKey || '') || [];
-            existingParams.push({ index: parameterIndex, type, data });
+            existingParams.push({
+                index: parameterIndex,
+                type,
+                data,
+                pipes: pipes.length > 0 ? pipes : undefined
+            });
             Reflect.defineMetadata(METADATA_KEYS.PARAMS, existingParams, target, propertyKey || '');
         };
     };
@@ -230,13 +236,12 @@ function extendArrayMetadata(key, metadata, target) {
  */
 function UseGuards(...guards) {
     return (target, key, descriptor) => {
-        guards.filter(guard => guard && (typeof guard === 'function' || typeof guard === 'object'));
+        const validGuards = guards.filter(guard => guard && (typeof guard === 'function' || typeof guard === 'object'));
         if (descriptor) {
-            extendArrayMetadata(METADATA_KEYS.GUARDS, guards, descriptor.value);
+            extendArrayMetadata(METADATA_KEYS.GUARDS, validGuards, descriptor.value);
             return descriptor;
         }
-        extendArrayMetadata(METADATA_KEYS.GUARDS, guards, target);
-        return target;
+        extendArrayMetadata(METADATA_KEYS.GUARDS, validGuards, target);
     };
 }
 
@@ -252,7 +257,21 @@ function UseInterceptors(...interceptors) {
             return descriptor;
         }
         extendArrayMetadata(METADATA_KEYS.INTERCEPTORS, validInterceptors, target);
-        return target;
+    };
+}
+
+/**
+ * Decorador que vincula Pipes al controlador o método.
+ * @param pipes Una lista de clases Pipe o instancias de Pipe.
+ */
+function UsePipes(...pipes) {
+    return (target, key, descriptor) => {
+        const validPipes = pipes.filter(pipe => pipe && (typeof pipe === 'function' || typeof pipe === 'object'));
+        if (descriptor) {
+            extendArrayMetadata(METADATA_KEYS.PIPES, validPipes, descriptor.value);
+            return descriptor;
+        }
+        extendArrayMetadata(METADATA_KEYS.PIPES, validPipes, target);
     };
 }
 
@@ -384,25 +403,6 @@ function Transform(transformer) {
     };
 }
 
-class ApiResponse {
-    static success(data, message = 'OK', status = 200) {
-        return {
-            success: true,
-            message,
-            data,
-            status,
-        };
-    }
-    static error(message, error = null, status = 500) {
-        return {
-            success: false,
-            message,
-            error,
-            status,
-        };
-    }
-}
-
 class HttpError extends Error {
     constructor(message, statusCode, error) {
         super(message);
@@ -699,4 +699,243 @@ class InfraDataDeserializationError extends InfrastructureError {
     }
 }
 
-export { ApiResponse, BackupError, BadRequestError, Body, BusinessRuleViolationError, ConfigurationError, ConflictError, ConnectionError, Controller, ControllerRegistry, 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, ManualRegister, Module, Next, NotFoundError, OperationNotAllowedError, Options, Param, ParamType, Patch, PersistenceError, Post, Put, Query, QueryExecutionError, Redirect, Repository, Req, ReqAuth, ReqContext, ReqPermissions, ReqUser, Request, Res, ResourceLimitError, ResourceLimitExceededError, Response, RestoreError, SchemaMismatchError, Serialize, Service, ServiceUnavailableError, Session, SetMetadata, TimeoutError, TransactionError, Transform, UnauthorizedError, UnprocessableEntityError, UseGuards, UseInterceptors, Validate, ValidationError, isRedirectResponse };
+/**
+ * Pipe de validación genérico que valida objetos contra un esquema de validación.
+ * Este es un ejemplo básico - en producción se usaría con librerías como class-validator o zod.
+ */
+class ValidationPipe {
+    async transform(value, metadata) {
+        if (value === undefined || value === null) {
+            throw new HttpError('Validation failed: value is required', 400);
+        }
+        // Aquí iría la lógica de validación real (ej: con class-validator)
+        // Por ahora solo verifica que el valor exista
+        return value;
+    }
+}
+
+/**
+ * Pipe que convierte un valor a número entero.
+ * Lanza una excepción si el valor no puede ser convertido.
+ */
+class ParseIntPipe {
+    transform(value, metadata) {
+        const val = parseInt(value, 10);
+        if (isNaN(val)) {
+            throw new HttpError(`Validation failed: "${value}" is not an integer`, 400);
+        }
+        return val;
+    }
+}
+
+/**
+ * Pipe que convierte un valor a número de punto flotante.
+ * Lanza una excepción si el valor no puede ser convertido.
+ */
+class ParseFloatPipe {
+    transform(value, metadata) {
+        const val = parseFloat(value);
+        if (isNaN(val)) {
+            throw new HttpError(`Validation failed: "${value}" is not a valid number`, 400);
+        }
+        return val;
+    }
+}
+
+/**
+ * Pipe que convierte un valor a booleano.
+ * Acepta: true, false, 1, 0, 'true', 'false', '1', '0'
+ */
+class ParseBoolPipe {
+    transform(value, metadata) {
+        if (typeof value === 'boolean') {
+            return value;
+        }
+        const normalizedValue = String(value).toLowerCase();
+        if (normalizedValue === 'true' || normalizedValue === '1') {
+            return true;
+        }
+        if (normalizedValue === 'false' || normalizedValue === '0') {
+            return false;
+        }
+        throw new HttpError(`Validation failed: "${value}" is not a boolean value`, 400);
+    }
+}
+
+/**
+ * Pipe que convierte un valor a array.
+ * Puede parsear strings separados por comas o validar que el valor ya sea un array.
+ */
+class ParseArrayPipe {
+    constructor(options) {
+        this.options = options;
+    }
+    async transform(value, metadata) {
+        if (!value) {
+            if (this.options?.optional) {
+                return [];
+            }
+            throw new HttpError('Validation failed: array is required', 400);
+        }
+        let array;
+        if (Array.isArray(value)) {
+            array = value;
+        }
+        else if (typeof value === 'string') {
+            const separator = this.options?.separator || ',';
+            array = value.split(separator).map(item => item.trim());
+        }
+        else {
+            throw new HttpError(`Validation failed: "${value}" is not an array`, 400);
+        }
+        // Si hay un pipe para los items, aplicarlo a cada elemento
+        if (this.options?.items) {
+            const transformed = [];
+            for (const item of array) {
+                transformed.push(await this.options.items.transform(item, metadata));
+            }
+            return transformed;
+        }
+        return array;
+    }
+}
+
+/**
+ * Pipe que valida que un valor sea un UUID válido.
+ * Soporta versiones 3, 4 y 5 de UUID.
+ */
+class ParseUUIDPipe {
+    constructor(version) {
+        this.version = version;
+        this.uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    }
+    transform(value, metadata) {
+        if (!value || typeof value !== 'string') {
+            throw new HttpError('Validation failed: UUID is required', 400);
+        }
+        if (!this.uuidRegex.test(value)) {
+            throw new HttpError(`Validation failed: "${value}" is not a valid UUID`, 400);
+        }
+        if (this.version) {
+            const uuidVersion = value.charAt(14);
+            if (uuidVersion !== this.version) {
+                throw new HttpError(`Validation failed: expected UUID v${this.version}, got v${uuidVersion}`, 400);
+            }
+        }
+        return value;
+    }
+}
+
+/**
+ * Pipe que valida que un valor pertenezca a un enum específico.
+ */
+class ParseEnumPipe {
+    constructor(enumType) {
+        this.enumType = enumType;
+    }
+    transform(value, metadata) {
+        const enumValues = Object.values(this.enumType);
+        if (!enumValues.includes(value)) {
+            const validValues = enumValues.join(', ');
+            throw new HttpError(`Validation failed: "${value}" is not a valid enum value. Valid values: ${validValues}`, 400);
+        }
+        return value;
+    }
+}
+
+/**
+ * Pipe que proporciona un valor por defecto si el valor de entrada es undefined o null.
+ */
+class DefaultValuePipe {
+    constructor(defaultValue) {
+        this.defaultValue = defaultValue;
+    }
+    transform(value, metadata) {
+        if (value === undefined || value === null || value === '') {
+            return this.defaultValue;
+        }
+        return value;
+    }
+}
+
+/**
+ * Pipe que valida archivos subidos.
+ * Puede validar tipo MIME, tamaño máximo y campos requeridos.
+ */
+class ParseFilePipe {
+    constructor(options) {
+        this.options = options;
+    }
+    transform(value, metadata) {
+        if (!value) {
+            throw new HttpError('Validation failed: file is required', 400);
+        }
+        // Validar tamaño
+        if (this.options?.maxSize && value.size > this.options.maxSize) {
+            const maxSizeMB = (this.options.maxSize / (1024 * 1024)).toFixed(2);
+            throw new HttpError(`Validation failed: file size exceeds maximum of ${maxSizeMB}MB`, 400);
+        }
+        // Validar tipo MIME
+        if (this.options?.allowedMimeTypes && value.mimetype) {
+            if (!this.options.allowedMimeTypes.includes(value.mimetype)) {
+                throw new HttpError(`Validation failed: file type "${value.mimetype}" is not allowed. Allowed types: ${this.options.allowedMimeTypes.join(', ')}`, 400);
+            }
+        }
+        // Validar campos requeridos
+        if (this.options?.requiredFields) {
+            for (const field of this.options.requiredFields) {
+                if (!value[field]) {
+                    throw new HttpError(`Validation failed: file is missing required field "${field}"`, 400);
+                }
+            }
+        }
+        return value;
+    }
+}
+
+/**
+ * Pipe que convierte un valor a Date.
+ * Acepta timestamps, strings de fecha ISO, o cualquier formato parseable por Date.
+ */
+class ParseDatePipe {
+    transform(value, metadata) {
+        if (!value) {
+            throw new HttpError('Validation failed: date is required', 400);
+        }
+        let date;
+        if (typeof value === 'number') {
+            date = new Date(value);
+        }
+        else if (typeof value === 'string') {
+            date = new Date(value);
+        }
+        else {
+            throw new HttpError(`Validation failed: "${value}" cannot be converted to Date`, 400);
+        }
+        if (isNaN(date.getTime())) {
+            throw new HttpError(`Validation failed: "${value}" is not a valid date`, 400);
+        }
+        return date;
+    }
+}
+
+class ApiResponse {
+    static success(data, message = 'OK', status = 200) {
+        return {
+            success: true,
+            message,
+            data,
+            status,
+        };
+    }
+    static error(message, error = null, status = 500) {
+        return {
+            success: false,
+            message,
+            error,
+            status,
+        };
+    }
+}
+
+export { ApiResponse, BackupError, BadRequestError, Body, BusinessRuleViolationError, ConfigurationError, ConflictError, ConnectionError, Controller, ControllerRegistry, Cookies, Custom, CustomHttpError, DataConflictError, DataIntegrityError, DataMigrationError, DataNotFoundError, DataValidationError, DefaultValuePipe, 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, ManualRegister, Module, Next, NotFoundError, OperationNotAllowedError, Options, Param, ParamType, ParseArrayPipe, ParseBoolPipe, ParseDatePipe, ParseEnumPipe, ParseFilePipe, ParseFloatPipe, ParseIntPipe, ParseUUIDPipe, Patch, PersistenceError, Post, Put, Query, QueryExecutionError, Redirect, Repository, Req, ReqAuth, ReqContext, ReqPermissions, ReqUser, Request, Res, ResourceLimitError, ResourceLimitExceededError, Response, RestoreError, SchemaMismatchError, Serialize, Service, ServiceUnavailableError, Session, SetMetadata, TimeoutError, TransactionError, Transform, UnauthorizedError, UnprocessableEntityError, UseGuards, UseInterceptors, UsePipes, Validate, ValidationError, ValidationPipe, isRedirectResponse };

package/dist/hemia-common.js

@@ -12,6 +12,7 @@ const METADATA_KEYS = {
     COOKIES: 'cookies',
     GUARDS: 'hemia:guards',
     INTERCEPTORS: 'hemia:interceptors',
+    PIPES: 'hemia:pipes',
     CUSTOM: 'hemia:custom',
     SERIALIZE: 'hemia:serialize',
     ROLES: 'hemia:roles',
@@ -75,10 +76,15 @@ const Options = createMethodDecorator(exports.HttpMethod.OPTIONS);
 const Head = createMethodDecorator(exports.HttpMethod.HEAD);
 
 const createParamDecorator = (type) => {
-    return (data) => {
+    return (data, ...pipes) => {
         return (target, propertyKey, parameterIndex) => {
             const existingParams = Reflect.getMetadata(METADATA_KEYS.PARAMS, target, propertyKey || '') || [];
-            existingParams.push({ index: parameterIndex, type, data });
+            existingParams.push({
+                index: parameterIndex,
+                type,
+                data,
+                pipes: pipes.length > 0 ? pipes : undefined
+            });
             Reflect.defineMetadata(METADATA_KEYS.PARAMS, existingParams, target, propertyKey || '');
         };
     };
@@ -232,13 +238,12 @@ function extendArrayMetadata(key, metadata, target) {
  */
 function UseGuards(...guards) {
     return (target, key, descriptor) => {
-        guards.filter(guard => guard && (typeof guard === 'function' || typeof guard === 'object'));
+        const validGuards = guards.filter(guard => guard && (typeof guard === 'function' || typeof guard === 'object'));
         if (descriptor) {
-            extendArrayMetadata(METADATA_KEYS.GUARDS, guards, descriptor.value);
+            extendArrayMetadata(METADATA_KEYS.GUARDS, validGuards, descriptor.value);
             return descriptor;
         }
-        extendArrayMetadata(METADATA_KEYS.GUARDS, guards, target);
-        return target;
+        extendArrayMetadata(METADATA_KEYS.GUARDS, validGuards, target);
     };
 }
 
@@ -254,7 +259,21 @@ function UseInterceptors(...interceptors) {
             return descriptor;
         }
         extendArrayMetadata(METADATA_KEYS.INTERCEPTORS, validInterceptors, target);
-        return target;
+    };
+}
+
+/**
+ * Decorador que vincula Pipes al controlador o método.
+ * @param pipes Una lista de clases Pipe o instancias de Pipe.
+ */
+function UsePipes(...pipes) {
+    return (target, key, descriptor) => {
+        const validPipes = pipes.filter(pipe => pipe && (typeof pipe === 'function' || typeof pipe === 'object'));
+        if (descriptor) {
+            extendArrayMetadata(METADATA_KEYS.PIPES, validPipes, descriptor.value);
+            return descriptor;
+        }
+        extendArrayMetadata(METADATA_KEYS.PIPES, validPipes, target);
     };
 }
 
@@ -386,25 +405,6 @@ function Transform(transformer) {
     };
 }
 
-class ApiResponse {
-    static success(data, message = 'OK', status = 200) {
-        return {
-            success: true,
-            message,
-            data,
-            status,
-        };
-    }
-    static error(message, error = null, status = 500) {
-        return {
-            success: false,
-            message,
-            error,
-            status,
-        };
-    }
-}
-
 class HttpError extends Error {
     constructor(message, statusCode, error) {
         super(message);
@@ -701,6 +701,245 @@ class InfraDataDeserializationError extends InfrastructureError {
     }
 }
 
+/**
+ * Pipe de validación genérico que valida objetos contra un esquema de validación.
+ * Este es un ejemplo básico - en producción se usaría con librerías como class-validator o zod.
+ */
+class ValidationPipe {
+    async transform(value, metadata) {
+        if (value === undefined || value === null) {
+            throw new HttpError('Validation failed: value is required', 400);
+        }
+        // Aquí iría la lógica de validación real (ej: con class-validator)
+        // Por ahora solo verifica que el valor exista
+        return value;
+    }
+}
+
+/**
+ * Pipe que convierte un valor a número entero.
+ * Lanza una excepción si el valor no puede ser convertido.
+ */
+class ParseIntPipe {
+    transform(value, metadata) {
+        const val = parseInt(value, 10);
+        if (isNaN(val)) {
+            throw new HttpError(`Validation failed: "${value}" is not an integer`, 400);
+        }
+        return val;
+    }
+}
+
+/**
+ * Pipe que convierte un valor a número de punto flotante.
+ * Lanza una excepción si el valor no puede ser convertido.
+ */
+class ParseFloatPipe {
+    transform(value, metadata) {
+        const val = parseFloat(value);
+        if (isNaN(val)) {
+            throw new HttpError(`Validation failed: "${value}" is not a valid number`, 400);
+        }
+        return val;
+    }
+}
+
+/**
+ * Pipe que convierte un valor a booleano.
+ * Acepta: true, false, 1, 0, 'true', 'false', '1', '0'
+ */
+class ParseBoolPipe {
+    transform(value, metadata) {
+        if (typeof value === 'boolean') {
+            return value;
+        }
+        const normalizedValue = String(value).toLowerCase();
+        if (normalizedValue === 'true' || normalizedValue === '1') {
+            return true;
+        }
+        if (normalizedValue === 'false' || normalizedValue === '0') {
+            return false;
+        }
+        throw new HttpError(`Validation failed: "${value}" is not a boolean value`, 400);
+    }
+}
+
+/**
+ * Pipe que convierte un valor a array.
+ * Puede parsear strings separados por comas o validar que el valor ya sea un array.
+ */
+class ParseArrayPipe {
+    constructor(options) {
+        this.options = options;
+    }
+    async transform(value, metadata) {
+        if (!value) {
+            if (this.options?.optional) {
+                return [];
+            }
+            throw new HttpError('Validation failed: array is required', 400);
+        }
+        let array;
+        if (Array.isArray(value)) {
+            array = value;
+        }
+        else if (typeof value === 'string') {
+            const separator = this.options?.separator || ',';
+            array = value.split(separator).map(item => item.trim());
+        }
+        else {
+            throw new HttpError(`Validation failed: "${value}" is not an array`, 400);
+        }
+        // Si hay un pipe para los items, aplicarlo a cada elemento
+        if (this.options?.items) {
+            const transformed = [];
+            for (const item of array) {
+                transformed.push(await this.options.items.transform(item, metadata));
+            }
+            return transformed;
+        }
+        return array;
+    }
+}
+
+/**
+ * Pipe que valida que un valor sea un UUID válido.
+ * Soporta versiones 3, 4 y 5 de UUID.
+ */
+class ParseUUIDPipe {
+    constructor(version) {
+        this.version = version;
+        this.uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    }
+    transform(value, metadata) {
+        if (!value || typeof value !== 'string') {
+            throw new HttpError('Validation failed: UUID is required', 400);
+        }
+        if (!this.uuidRegex.test(value)) {
+            throw new HttpError(`Validation failed: "${value}" is not a valid UUID`, 400);
+        }
+        if (this.version) {
+            const uuidVersion = value.charAt(14);
+            if (uuidVersion !== this.version) {
+                throw new HttpError(`Validation failed: expected UUID v${this.version}, got v${uuidVersion}`, 400);
+            }
+        }
+        return value;
+    }
+}
+
+/**
+ * Pipe que valida que un valor pertenezca a un enum específico.
+ */
+class ParseEnumPipe {
+    constructor(enumType) {
+        this.enumType = enumType;
+    }
+    transform(value, metadata) {
+        const enumValues = Object.values(this.enumType);
+        if (!enumValues.includes(value)) {
+            const validValues = enumValues.join(', ');
+            throw new HttpError(`Validation failed: "${value}" is not a valid enum value. Valid values: ${validValues}`, 400);
+        }
+        return value;
+    }
+}
+
+/**
+ * Pipe que proporciona un valor por defecto si el valor de entrada es undefined o null.
+ */
+class DefaultValuePipe {
+    constructor(defaultValue) {
+        this.defaultValue = defaultValue;
+    }
+    transform(value, metadata) {
+        if (value === undefined || value === null || value === '') {
+            return this.defaultValue;
+        }
+        return value;
+    }
+}
+
+/**
+ * Pipe que valida archivos subidos.
+ * Puede validar tipo MIME, tamaño máximo y campos requeridos.
+ */
+class ParseFilePipe {
+    constructor(options) {
+        this.options = options;
+    }
+    transform(value, metadata) {
+        if (!value) {
+            throw new HttpError('Validation failed: file is required', 400);
+        }
+        // Validar tamaño
+        if (this.options?.maxSize && value.size > this.options.maxSize) {
+            const maxSizeMB = (this.options.maxSize / (1024 * 1024)).toFixed(2);
+            throw new HttpError(`Validation failed: file size exceeds maximum of ${maxSizeMB}MB`, 400);
+        }
+        // Validar tipo MIME
+        if (this.options?.allowedMimeTypes && value.mimetype) {
+            if (!this.options.allowedMimeTypes.includes(value.mimetype)) {
+                throw new HttpError(`Validation failed: file type "${value.mimetype}" is not allowed. Allowed types: ${this.options.allowedMimeTypes.join(', ')}`, 400);
+            }
+        }
+        // Validar campos requeridos
+        if (this.options?.requiredFields) {
+            for (const field of this.options.requiredFields) {
+                if (!value[field]) {
+                    throw new HttpError(`Validation failed: file is missing required field "${field}"`, 400);
+                }
+            }
+        }
+        return value;
+    }
+}
+
+/**
+ * Pipe que convierte un valor a Date.
+ * Acepta timestamps, strings de fecha ISO, o cualquier formato parseable por Date.
+ */
+class ParseDatePipe {
+    transform(value, metadata) {
+        if (!value) {
+            throw new HttpError('Validation failed: date is required', 400);
+        }
+        let date;
+        if (typeof value === 'number') {
+            date = new Date(value);
+        }
+        else if (typeof value === 'string') {
+            date = new Date(value);
+        }
+        else {
+            throw new HttpError(`Validation failed: "${value}" cannot be converted to Date`, 400);
+        }
+        if (isNaN(date.getTime())) {
+            throw new HttpError(`Validation failed: "${value}" is not a valid date`, 400);
+        }
+        return date;
+    }
+}
+
+class ApiResponse {
+    static success(data, message = 'OK', status = 200) {
+        return {
+            success: true,
+            message,
+            data,
+            status,
+        };
+    }
+    static error(message, error = null, status = 500) {
+        return {
+            success: false,
+            message,
+            error,
+            status,
+        };
+    }
+}
+
 exports.ApiResponse = ApiResponse;
 exports.BackupError = BackupError;
 exports.BadRequestError = BadRequestError;
@@ -719,6 +958,7 @@ exports.DataIntegrityError = DataIntegrityError;
 exports.DataMigrationError = DataMigrationError;
 exports.DataNotFoundError = DataNotFoundError;
 exports.DataValidationError = DataValidationError;
+exports.DefaultValuePipe = DefaultValuePipe;
 exports.Delete = Delete;
 exports.DependencyError = DependencyError;
 exports.DomainError = DomainError;
@@ -760,6 +1000,14 @@ exports.NotFoundError = NotFoundError;
 exports.OperationNotAllowedError = OperationNotAllowedError;
 exports.Options = Options;
 exports.Param = Param;
+exports.ParseArrayPipe = ParseArrayPipe;
+exports.ParseBoolPipe = ParseBoolPipe;
+exports.ParseDatePipe = ParseDatePipe;
+exports.ParseEnumPipe = ParseEnumPipe;
+exports.ParseFilePipe = ParseFilePipe;
+exports.ParseFloatPipe = ParseFloatPipe;
+exports.ParseIntPipe = ParseIntPipe;
+exports.ParseUUIDPipe = ParseUUIDPipe;
 exports.Patch = Patch;
 exports.PersistenceError = PersistenceError;
 exports.Post = Post;
@@ -792,6 +1040,8 @@ exports.UnauthorizedError = UnauthorizedError;
 exports.UnprocessableEntityError = UnprocessableEntityError;
 exports.UseGuards = UseGuards;
 exports.UseInterceptors = UseInterceptors;
+exports.UsePipes = UsePipes;
 exports.Validate = Validate;
 exports.ValidationError = ValidationError;
+exports.ValidationPipe = ValidationPipe;
 exports.isRedirectResponse = isRedirectResponse;

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

@@ -1,5 +1,6 @@
 export * from "./use-guards.decorator";
 export * from "./use-interceptors.decorator";
+export * from "./use-pipes.decorator";
 export * from "./set-metadata.decorator";
 export * from "./serialize.decorator";
 export * from "./module.decorator";

package/dist/types/decorators/core/use-guards.decorator.d.ts

@@ -4,4 +4,4 @@ import { CanActivate, Type } from '../../interfaces';
  * Decorador que vincula Guards al controlador o método.
  * @param guards Una lista de clases Guard o instancias de Guard.
  */
-export declare function UseGuards(...guards: (Type<CanActivate> | CanActivate | Function)[]): (target: object | Function, key?: string | symbol, descriptor?: PropertyDescriptor) => object;
+export declare function UseGuards(...guards: (Type<CanActivate> | CanActivate | Function)[]): (target: object | Function, key?: string | symbol, descriptor?: PropertyDescriptor) => PropertyDescriptor | undefined;

package/dist/types/decorators/core/use-interceptors.decorator.d.ts

@@ -4,4 +4,4 @@ import { HemiaInterceptor, Type } from '../../interfaces';
  * Decorador que vincula Interceptores al controlador o método.
  * @param interceptors Una lista de clases Interceptor o instancias.
  */
-export declare function UseInterceptors(...interceptors: (Type<HemiaInterceptor> | HemiaInterceptor | Function)[]): (target: object | Function, key?: string | symbol, descriptor?: PropertyDescriptor) => object;
+export declare function UseInterceptors(...interceptors: (Type<HemiaInterceptor> | HemiaInterceptor | Function)[]): (target: object | Function, key?: string | symbol, descriptor?: PropertyDescriptor) => PropertyDescriptor | undefined;

package/dist/types/decorators/core/use-pipes.decorator.d.ts

@@ -0,0 +1,7 @@
+import 'reflect-metadata';
+import { PipeTransform, Type } from '../../interfaces';
+/**
+ * Decorador que vincula Pipes al controlador o método.
+ * @param pipes Una lista de clases Pipe o instancias de Pipe.
+ */
+export declare function UsePipes(...pipes: (Type<PipeTransform> | PipeTransform | Function)[]): (target: object | Function, key?: string | symbol, descriptor?: PropertyDescriptor) => PropertyDescriptor | undefined;

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

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

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

@@ -4,3 +4,4 @@ export * from "./core";
 export * from "./custom";
 export * from "./validation";
 export * from "./transform";
+export * from "./pipes";

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

@@ -7,6 +7,7 @@ export declare const METADATA_KEYS: {
     readonly COOKIES: "cookies";
     readonly GUARDS: "hemia:guards";
     readonly INTERCEPTORS: "hemia:interceptors";
+    readonly PIPES: "hemia:pipes";
     readonly CUSTOM: "hemia:custom";
     readonly SERIALIZE: "hemia:serialize";
     readonly ROLES: "hemia:roles";

package/dist/types/decorators/pipes/default-value.pipe.d.ts

@@ -0,0 +1,9 @@
+import { PipeTransform, ArgumentMetadata } from '../../interfaces';
+/**
+ * Pipe que proporciona un valor por defecto si el valor de entrada es undefined o null.
+ */
+export declare class DefaultValuePipe<T = any> implements PipeTransform<T, T> {
+    private readonly defaultValue;
+    constructor(defaultValue: T);
+    transform(value: T, metadata?: ArgumentMetadata): T;
+}

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

@@ -0,0 +1,10 @@
+export * from './validation.pipe';
+export * from './parse-int.pipe';
+export * from './parse-float.pipe';
+export * from './parse-bool.pipe';
+export * from './parse-array.pipe';
+export * from './parse-uuid.pipe';
+export * from './parse-enum.pipe';
+export * from './default-value.pipe';
+export * from './parse-file.pipe';
+export * from './parse-date.pipe';

package/dist/types/decorators/pipes/parse-array.pipe.d.ts

@@ -0,0 +1,15 @@
+import { PipeTransform, ArgumentMetadata } from '../../interfaces';
+export interface ParseArrayOptions {
+    items?: PipeTransform;
+    separator?: string;
+    optional?: boolean;
+}
+/**
+ * Pipe que convierte un valor a array.
+ * Puede parsear strings separados por comas o validar que el valor ya sea un array.
+ */
+export declare class ParseArrayPipe implements PipeTransform {
+    private readonly options?;
+    constructor(options?: ParseArrayOptions | undefined);
+    transform(value: any, metadata?: ArgumentMetadata): Promise<any[]>;
+}

package/dist/types/decorators/pipes/parse-bool.pipe.d.ts

@@ -0,0 +1,8 @@
+import { PipeTransform, ArgumentMetadata } from '../../interfaces';
+/**
+ * Pipe que convierte un valor a booleano.
+ * Acepta: true, false, 1, 0, 'true', 'false', '1', '0'
+ */
+export declare class ParseBoolPipe implements PipeTransform<string | boolean, boolean> {
+    transform(value: string | boolean, metadata?: ArgumentMetadata): boolean;
+}

package/dist/types/decorators/pipes/parse-date.pipe.d.ts

@@ -0,0 +1,8 @@
+import { PipeTransform, ArgumentMetadata } from '../../interfaces';
+/**
+ * Pipe que convierte un valor a Date.
+ * Acepta timestamps, strings de fecha ISO, o cualquier formato parseable por Date.
+ */
+export declare class ParseDatePipe implements PipeTransform<string | number, Date> {
+    transform(value: string | number, metadata?: ArgumentMetadata): Date;
+}

package/dist/types/decorators/pipes/parse-enum.pipe.d.ts

@@ -0,0 +1,9 @@
+import { PipeTransform, ArgumentMetadata } from '../../interfaces';
+/**
+ * Pipe que valida que un valor pertenezca a un enum específico.
+ */
+export declare class ParseEnumPipe<T extends Record<string, any>> implements PipeTransform<string, T[keyof T]> {
+    private readonly enumType;
+    constructor(enumType: T);
+    transform(value: string, metadata?: ArgumentMetadata): T[keyof T];
+}

package/dist/types/decorators/pipes/parse-file.pipe.d.ts

@@ -0,0 +1,15 @@
+import { PipeTransform, ArgumentMetadata } from '../../interfaces';
+export interface ParseFileOptions {
+    maxSize?: number;
+    allowedMimeTypes?: string[];
+    requiredFields?: string[];
+}
+/**
+ * Pipe que valida archivos subidos.
+ * Puede validar tipo MIME, tamaño máximo y campos requeridos.
+ */
+export declare class ParseFilePipe implements PipeTransform {
+    private readonly options?;
+    constructor(options?: ParseFileOptions | undefined);
+    transform(value: any, metadata?: ArgumentMetadata): any;
+}

package/dist/types/decorators/pipes/parse-float.pipe.d.ts

@@ -0,0 +1,8 @@
+import { PipeTransform, ArgumentMetadata } from '../../interfaces';
+/**
+ * Pipe que convierte un valor a número de punto flotante.
+ * Lanza una excepción si el valor no puede ser convertido.
+ */
+export declare class ParseFloatPipe implements PipeTransform<string, number> {
+    transform(value: string, metadata?: ArgumentMetadata): number;
+}

package/dist/types/decorators/pipes/parse-int.pipe.d.ts

@@ -0,0 +1,8 @@
+import { PipeTransform, ArgumentMetadata } from '../../interfaces';
+/**
+ * Pipe que convierte un valor a número entero.
+ * Lanza una excepción si el valor no puede ser convertido.
+ */
+export declare class ParseIntPipe implements PipeTransform<string, number> {
+    transform(value: string, metadata?: ArgumentMetadata): number;
+}

package/dist/types/decorators/pipes/parse-uuid.pipe.d.ts

@@ -0,0 +1,11 @@
+import { PipeTransform, ArgumentMetadata } from '../../interfaces';
+/**
+ * Pipe que valida que un valor sea un UUID válido.
+ * Soporta versiones 3, 4 y 5 de UUID.
+ */
+export declare class ParseUUIDPipe implements PipeTransform<string, string> {
+    private readonly version?;
+    private readonly uuidRegex;
+    constructor(version?: "3" | "4" | "5" | undefined);
+    transform(value: string, metadata?: ArgumentMetadata): string;
+}

package/dist/types/decorators/pipes/validation.pipe.d.ts

@@ -0,0 +1,8 @@
+import { PipeTransform, ArgumentMetadata } from '../../interfaces';
+/**
+ * Pipe de validación genérico que valida objetos contra un esquema de validación.
+ * Este es un ejemplo básico - en producción se usaría con librerías como class-validator o zod.
+ */
+export declare class ValidationPipe implements PipeTransform {
+    transform(value: any, metadata?: ArgumentMetadata): Promise<any>;
+}

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

@@ -7,6 +7,7 @@ export * from "./features/arguments-host.interface";
 export * from './type.interface';
 export * from './handler.interface';
 export * from './interceptor.interface';
+export * from './pipe.interface';
 export * from './configuration/redis-configuration.interface';
 export * from './configuration/mongo-db-configuration.interface';
 export * from './configuration/aws-s3-configuration.interface';

package/dist/types/interfaces/param.interface.d.ts

@@ -1,8 +1,10 @@
 import { ParamType } from "../enums/param-type.enum";
+import { PipeTransform, PType } from "./pipe.interface";
 export interface ParamMetadata {
     index: number;
     type: ParamType;
     data?: string;
+    pipes?: (PType<PipeTransform> | PipeTransform)[];
 }
 export interface HeaderMetadata {
     name: string;

package/dist/types/interfaces/pipe.interface.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Interface defining the contract for pipes.
+ * Pipes have two typical use cases:
+ * - transformation: transform input data to the desired form
+ * - validation: evaluate input data and if valid, pass it through unchanged; otherwise, throw an exception
+ */
+export interface PipeTransform<T = any, R = any> {
+    /**
+     * Method to implement a custom pipe. Called with two parameters
+     * @param value the currently processed input argument
+     * @param metadata optional metadata about the current argument
+     */
+    transform(value: T, metadata?: ArgumentMetadata): R | Promise<R>;
+}
+/**
+ * Metadata about the argument being processed by the pipe
+ */
+export interface ArgumentMetadata {
+    /**
+     * Indicates whether argument is a body, query, param, or custom parameter
+     */
+    type?: 'body' | 'query' | 'param' | 'custom';
+    /**
+     * Metatype of the argument (e.g., String, Number)
+     */
+    metatype?: PType<any>;
+    /**
+     * String value passed to the decorator (e.g., for @Param('id'), data would be 'id')
+     */
+    data?: string;
+}
+export interface PType<T = any> {
+    new (...args: any[]): T;
+}

package/package.json

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