Typegoose com TypeScript: Guia Completo

Typegoose é uma poderosa biblioteca wrapper para o Mongoose que permite definir modelos MongoDB usando classes e decorators do TypeScript. Ela resolve um problema crucial no desenvolvimento com Node.js: a incompatibilidade entre a tipagem estrita do TypeScript e a natureza dinâmica do Mongoose. Em vez de duplicar manualmente tipos e schemas, o Typegoose permite descrever o modelo uma única vez — como uma classe TypeScript — e gera automaticamente o schema Mongoose a partir dela.

Por que usar isso? Primeiro, reduz drasticamente a quantidade de código repetitivo. Você não precisa mais escrever uma interface separada e um schema separado — a classe TypeScript cumpre ambas as funções. Segundo, o Typegoose garante segurança total de tipos em todas as etapas: desde a criação do documento até a execução de consultas. A IDE vai sugerir campos, métodos e seus tipos, praticamente eliminando erros relacionados a digitação incorreta de nomes de campos ou tipos de dados errados. Terceiro, a biblioteca suporta todos os recursos do Mongoose: campos virtuais, hooks (pre/post), índices, populate e middleware.

Typegoose é ideal para projetos grandes, onde a manutenibilidade do código é essencial, e para equipes que desejam aproveitar todos os benefícios da programação orientada a objetos (POO) em TypeScript. Ele se integra facilmente com NestJS, Express e outros frameworks, fornecendo um padrão único para descrição de dados.

Instalação

Para instalar o Typegoose e suas dependências, execute no terminal:

npm install @typegoose/typegoose mongoose
npm install -D @types/mongoose

Se você usa yarn:

yarn add @typegoose/typegoose mongoose
yarn add -D @types/mongoose

O Typegoose requer TypeScript versão 4.0 ou superior. Certifique-se de que as seguintes opções estejam habilitadas no seu tsconfig.json:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES2020",
    "module": "commonjs"
  }
}

Início Rápido

Vamos criar um modelo de usuário simples e salvá-lo no MongoDB.

import { prop, getModelForClass } from '@typegoose/typegoose';
import mongoose from 'mongoose';

// 1. Define a classe do modelo
class User {
  @prop({ required: true })
  public name!: string;

  @prop({ required: true, unique: true })
  public email!: string;

  @prop({ default: 0 })
  public age!: number;
}

// 2. Obtém o modelo Mongoose
const UserModel = getModelForClass(User);

// 3. Conecta ao banco e trabalha com os dados
async function main() {
  await mongoose.connect('mongodb://localhost:27017/test');

  // Cria um usuário
  const user = await UserModel.create({
    name: 'Alice',
    email: 'alice@example.com',
    age: 30,
  });

  console.log('Criado:', user);

  // Encontra um usuário
  const found = await UserModel.findOne({ email: 'alice@example.com' });
  console.log('Encontrado:', found);
}

main().catch(console.error);

Este exemplo mínimo demonstra a ideia principal: a classe User com o decorador @prop descreve o schema, e a função getModelForClass cria um modelo Mongoose pronto para uso.

Métodos e Funções Principais

1. @prop() — Decorador de Propriedade

Assinatura: @prop(options?: PropOptions)

Descrição: Define um campo no schema Mongoose. Aceita um objeto de opções semelhante às opções de campos do Mongoose (required, default, unique, ref, enum, etc.).

import { prop } from '@typegoose/typegoose';

class Product {
  @prop({ required: true, type: String })
  public title!: string;

  @prop({ default: 0, min: 0 })
  public price!: number;

  @prop({ enum: ['active', 'inactive'], default: 'active' })
  public status!: string;
}

2.