class-transformer TypeScript: métodos, exemplos…

Introdução ao class-transformer: o que é e para que serve

\n\n

class-transformer é uma biblioteca poderosa para TypeScript e JavaScript que permite transformar objetos JavaScript comuns (plain) em instâncias de classes e vice-versa. Ela resolve um problema fundamental: ao trabalhar com dados de APIs, bancos de dados ou arquivos JSON, você obtém objetos simples sem métodos e tipos. O class-transformer "dá vida" a esses dados, transformando-os em objetos de classe completos com validação, transformação e serialização.

\n\n

Principais cenários de uso:

Transformação de JSON de API em objetos de classe tipados — por exemplo, após receber uma resposta de uma API REST, você pode transformar automaticamente o JSON em instâncias dos seus modelos.
Validação e transformação de dados — com decoradores, você pode especificar quais campos são obrigatórios, quais precisam ser transformados (por exemplo, string em número ou data).
Serialização de objetos em JSON — a transformação inversa de instâncias de classe em objetos simples para envio ao cliente ou armazenamento.
Trabalho com objetos e arrays aninhados — a biblioteca consegue transformar recursivamente estruturas de dados aninhadas.

\n\n

O class-transformer é frequentemente usado junto com class-validator (para validação) e frameworks populares como NestJS, TypeORM e MikroORM.

\n\n

Instalação

\n\n

A instalação da biblioteca é feita via npm ou yarn:

\n\n

npm install class-transformer --save

\n\n

Ou, se você usa yarn:

\n\n

yarn add class-transformer

\n\n

Para trabalhar com decoradores no TypeScript, é necessário ativar o suporte a decoradores experimentais no arquivo tsconfig.json:

\n\n

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

\n\n

Também é recomendável instalar o reflect-metadata para o funcionamento correto dos decoradores:

\n\n

npm install reflect-metadata --save

\n\n

E importá-lo no início da sua aplicação (geralmente no arquivo principal index.ts ou main.ts):

\n\n

import 'reflect-metadata';

\n\n

Início rápido com exemplo de código

\n\n

Vamos criar um modelo de usuário simples e transformar dados JSON em uma instância de classe.

\n\n

import { plainToClass, Expose, Type } from 'class-transformer';\nimport 'reflect-metadata';\n\n// Definindo a classe 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 da classe — disponível apenas após a transformação\n    getFullName(): string {\n        return `${this.firstName} ${this.lastName}`;\n    }\n}\n\n// Exemplo de dados da API (plain object)\nconst plainUser = {\n    id: 1,\n    firstName: 'João',\n    lastName: 'Silva',\n    createdAt: '2024-01-15T10:30:00Z'\n};\n\n// Transformando plain object em instância da classe User\nconst userInstance = plainToClass(User, plainUser);\n\nconsole.log(userInstance instanceof User); // true\nconsole.log(userInstance.getFullName());   // "João Silva"\nconsole.log(userInstance.createdAt);       // Date object: Tue Jan 15 2024 13:30:00 GMT+0300\n

\n\n

Como você pode ver, obtivemos um objeto de classe completo com métodos e tipos corretamente transformados (a string de data tornou-se um objeto Date).

\n\n