Preguntas frecuentes

Encuentra respuestas a preguntas comunes sobre el uso de la biblioteca. Haz clic en una pregunta para mostrar la respuesta.

1. Primeros pasos

P: ¿Qué es el proyecto express-cargo?

R: Es un middleware diseñado para automatizar el procesamiento repetitivo y tedioso de datos de solicitudes (req.body, req.query, etc.) en Express.js usando un enfoque basado en clases. Al utilizar decoradores de TypeScript, puedes manejar el enlace de datos y la validación de forma declarativa en un solo lugar.

P: ¿Hay precauciones para la instalación?

R: Se recomienda Node.js versión 20 o superior. Está diseñado para integrarse de forma flexible en proyectos Express existentes como middleware estándar.

P: ¿La configuración de TypeScript es obligatoria?

R: Sí. Como usa decoradores, las siguientes dos opciones deben establecerse en true en tu tsconfig.json:

• experimentalDecorators: true
• emitDecoratorMetadata: true

Además, el paquete reflect-metadata debe estar instalado para leer información de tipos en tiempo de ejecución.

2. Enlace de datos y decoradores

P: ¿Cuál es la diferencia entre @Body y @Query?

R: La diferencia está en la fuente de extracción de los datos:

• @Body: Extrae datos del cuerpo de la solicitud HTTP. Se usa principalmente para solicitudes POST y PUT.
• @Query: Extrae parámetros de la cadena de consulta de la URL (por ejemplo, ?id=1&name=test). Se usa principalmente para filtrado u ordenamiento en solicitudes GET.
• También puedes enlazar otros datos de la solicitud usando @Params() (o @Uri()), @Header() y @Session().

P: ¿Qué es @Uri()? ¿Es diferente de @Params()?

R: @Uri() es un alias de @Params(). Puedes elegir entre ellos según tu preferencia de legibilidad al enlazar parámetros de ruta de URL (por ejemplo, /:id).

P: ¿Cómo recupero los datos enlazados?

R: Después de pasar el middleware bindingCargo(ClassName) en tu router, puedes recuperar la instancia dentro del handler llamando a la función getCargo<ClassName>(req).

3. Validación y transformación

P: ¿Cómo se manejan los fallos de validación?

R: La validación se realiza internamente usando decoradores como @Min, @Max y @Length. Si se detectan datos inválidos, el middleware devuelve automáticamente una respuesta de error o lanza una excepción.

P: ¿Cómo puedo procesar o transformar valores de campos?

R: Usa el decorador @Transform(). Por ejemplo, escribir @Transform(v => v.trim()) te permite transformar los datos de entrada al formato deseado antes del enlace.

P: ¿Cómo evito errores si falta un campo específico?

R: Usa el decorador @Optional(). El campo se enlazará correctamente aunque el valor sea null o undefined, omitiendo la validación para ese campo.

4. Compatibilidad con frameworks

P: ¿Puedo usarlo con Fastify o NestJS?

R: Esta biblioteca está diseñada específicamente como middleware exclusivo para Express.js.

• NestJS: NestJS tiene su propio ValidationPipe y decoradores, que pueden solaparse en funcionalidad. Aunque técnicamente es posible si se usa el adaptador Express, el objetivo principal de esta biblioteca es mejorar la experiencia de desarrollo en entornos Express puros.
• Fastify: Actualmente no está soportado oficialmente.

5. Resolución de problemas

P: ¿Por qué los datos de mi instancia de clase devuelven undefined?

R: Revisa estos dos puntos:

• ¿Un middleware de análisis del body como express.json() está declarado antes de bindingCargo?
• ¿reflect-metadata está importado al principio del punto de entrada de tu aplicación?

P: ¿Se realiza conversión automática de tipos?

R: Sí. Intenta convertir los valores automáticamente según los tipos definidos en los campos de la clase (string, number, boolean, etc.). Por ejemplo, una cadena "123" proveniente de @Query() se convertirá automáticamente a número si el tipo del campo está definido como number.

6. Miscelánea

P: ¿Puedo usarlo gratis en proyectos comerciales?

R: Esta biblioteca está licenciada bajo la Licencia MIT. Puedes usarla, modificarla y distribuirla incluso con fines comerciales sin restricciones.