Typegoose para TypeScript: Guía completa

Typegoose es una potente biblioteca envoltorio para Mongoose que permite definir modelos de MongoDB utilizando clases y decoradores de TypeScript. Resuelve un problema clave en el desarrollo con Node.js: la falta de coincidencia entre el tipado estricto de TypeScript y la naturaleza dinámica de Mongoose. En lugar de duplicar manualmente tipos y esquemas, Typegoose te permite describir el modelo una sola vez —como una clase de TypeScript— y genera automáticamente el esquema de Mongoose a partir de ella.

¿Por qué es útil? Primero, reduce significativamente la cantidad de código repetitivo. Ya no necesitas escribir una interfaz separada y un esquema aparte: la clase TypeScript cumple ambas funciones. Segundo, Typegoose garantiza total seguridad de tipos en todas las etapas: desde la creación de un documento hasta la ejecución de consultas. El IDE te sugerirá campos, métodos y sus tipos, eliminando prácticamente los errores por nombres mal escritos o tipos de datos incorrectos. Tercero, la biblioteca soporta todas las funcionalidades de Mongoose: campos virtuales, hooks (pre/post), índices, populate y middleware.

Typegoose es ideal para proyectos grandes donde la mantenibilidad del código es crucial, así como para equipos que quieren aprovechar al máximo la programación orientada a objetos en TypeScript. Se integra fácilmente con NestJS, Express y otros frameworks, proporcionando un estándar unificado para la descripción de datos.

Instalación

Para instalar Typegoose y sus dependencias, ejecuta en la terminal:

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

Si usas yarn:

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

Typegoose requiere TypeScript versión 4.0 o superior. Asegúrate de que tu archivo tsconfig.json incluya las siguientes opciones:

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

Inicio rápido

Vamos a crear un modelo simple de usuario y guardarlo en MongoDB.

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

// 1. Definimos la clase del modelo
class User {
  @prop({ required: true })
  public name!: string;

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

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

// 2. Obtenemos el modelo de Mongoose
const UserModel = getModelForClass(User);

// 3. Nos conectamos a la BD y trabajamos
async function main() {
  await mongoose.connect('mongodb://localhost:27017/test');

  // Creamos un usuario
  const user = await UserModel.create({
    name: 'Alice',
    email: 'alice@example.com',
    age: 30,
  });

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

  // Buscamos un usuario
  const found = await UserModel.findOne({ email: 'alice@example.com' });
  console.log('Encontrado:', found);
}

main().catch(console.error);

Este ejemplo mínimo muestra la idea principal: la clase User con el decorador @prop describe el esquema, y la función getModelForClass crea un modelo de Mongoose listo para usar.

Métodos y funciones principales

1. @prop() — decorador de propiedad

Firma: @prop(options?: PropOptions)

Descripción: Define un campo en el esquema de Mongoose. Acepta un objeto de opciones similar a las opciones de campos en 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.