class-transformer TypeScript: métodos, ejemplos…

Introducción a class-transformer: qué es y para qué sirve

\n\n

class-transformer es una potente biblioteca para TypeScript y JavaScript que permite convertir objetos JavaScript simples (plain) en instancias de clases y viceversa. Resuelve un problema fundamental: al trabajar con datos de APIs, bases de datos o archivos JSON, obtienes objetos simples sin métodos ni tipos. class-transformer «da vida» a estos datos, transformándolos en objetos de clase completos con validación, transformación y serialización.

\n\n

Casos de uso principales:

Conversión de JSON de API en objetos de clase tipados — por ejemplo, después de recibir una respuesta de una API REST, puedes convertir automáticamente el JSON en instancias de tus modelos.
Validación y transformación de datos — mediante decoradores puedes indicar qué campos son obligatorios y cuáles deben transformarse (por ejemplo, una cadena a número o fecha).
Serialización de objetos a JSON — la conversión inversa de instancias de clase a objetos simples para enviar al cliente o guardar.
Trabajo con objetos y arrays anidados — la biblioteca puede transformar recursivamente estructuras de datos anidadas.

\n\n

class-transformer se usa a menudo junto con class-validator (para validación) y frameworks populares como NestJS, TypeORM y MikroORM.

\n\n

Instalación

\n\n

La instalación de la biblioteca se realiza mediante npm o yarn:

\n\n

npm install class-transformer --save

\n\n

O, si usas yarn:

\n\n

yarn add class-transformer

\n\n

Para trabajar con decoradores en TypeScript, es necesario habilitar el soporte de decoradores experimentales en el archivo tsconfig.json:

\n\n

{\n  "compilerOptions": {\n    "experimentalDecorators": true,\n    "emitDecoratorMetadata": true\n  }\n}

\n\n

También se recomienda instalar reflect-metadata para el correcto funcionamiento de los decoradores:

\n\n

npm install reflect-metadata --save

\n\n

E importarlo al inicio de tu aplicación (generalmente en el archivo principal index.ts o main.ts):

\n\n

import 'reflect-metadata';

\n\n

Inicio rápido con ejemplo de código

\n\n

Vamos a crear un modelo de usuario simple y convertir datos JSON en una instancia de clase.

\n\n

import { plainToClass, Expose, Type } from 'class-transformer';\nimport 'reflect-metadata';\n\n// Definimos la clase User\nclass User {\n    @Expose()\n    id: number;\n\n    @Expose()\n    firstName: string;\n\n    @Expose()\n    lastName: string;\n\n    @Expose()\n    @Type(() => Date)\n    createdAt: Date;\n\n    // Método de clase — disponible solo después de la transformación\n    getFullName(): string {\n        return `${this.firstName} ${this.lastName}`;\n    }\n}\n\n// Ejemplo de datos de una API (plain object)\nconst plainUser = {\n    id: 1,\n    firstName: 'Iván',\n    lastName: 'Petrov',\n    createdAt: '2024-01-15T10:30:00Z'\n};\n\n// Convertimos el plain object en una instancia de la clase User\nconst userInstance = plainToClass(User, plainUser);\n\nconsole.log(userInstance instanceof User); // true\nconsole.log(userInstance.getFullName());   // "Iván Petrov"\nconsole.log(userInstance.createdAt);       // Date object: Tue Jan 15 2024 13:30:00 GMT+0300\n

\n\n

Como puedes ver, obtuvimos un objeto de clase completo con métodos y tipos correctamente transformados (la cadena de fecha se convirtió en un objeto Date).

\n\n