TypeORM en NestJS

TypeORM es el ORM (Object-Relational Mapping) más utilizado en el ecosistema de NestJS para gestionar bases de datos relacionales. Esta herramienta permite trabajar con bases de datos utilizando objetos JavaScript en lugar de escribir consultas SQL directamente, proporcionando una capa de abstracción que simplifica significativamente el desarrollo de aplicaciones.

¿Qué es un ORM?

Un Object-Relational Mapping es una técnica de programación que permite mapear datos entre sistemas incompatibles utilizando lenguajes de programación orientados a objetos. En el contexto de bases de datos, un ORM traduce las tablas de la base de datos en clases de JavaScript, las filas en instancias de objetos y las columnas en propiedades de estos objetos.

TypeORM destaca por su arquitectura basada en decoradores, que se integra perfectamente con el sistema de decoradores de NestJS. Esta integración permite definir entidades, relaciones y configuraciones de base de datos de manera declarativa y elegante.

Integración con NestJS

NestJS proporciona el módulo @nestjs/typeorm que facilita la integración nativa con TypeORM. Esta integración aprovecha el sistema de inyección de dependencias de NestJS para gestionar conexiones a la base de datos, repositorios y transacciones de manera automática.

La configuración se realiza típicamente en el módulo raíz de la aplicación, donde se establece la conexión a la base de datos y se registran las entidades que formarán parte del modelo de datos:

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: 'postgres',
      host: 'localhost',
      port: 5432,
      username: 'usuario',
      password: 'contraseña',
      database: 'mi_base_datos',
      entities: [__dirname + '/**/*.entity{.ts,.js}'],
      synchronize: true,
    }),
  ],
})
export class AppModule {}

Entidades y decoradores

Las entidades en TypeORM son clases que representan tablas en la base de datos. Se definen utilizando decoradores que especifican la estructura y comportamiento de cada tabla:

import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';

@Entity()
export class Usuario {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  nombre: string;

  @Column({ unique: true })
  email: string;

  @Column({ default: true })
  activo: boolean;
}

Los decoradores principales incluyen @Entity() para marcar una clase como entidad, @PrimaryGeneratedColumn() para claves primarias auto-incrementales, y @Column() para definir columnas con sus respectivas opciones de configuración.

Repositorios y patrones de acceso a datos

TypeORM utiliza el patrón Repository para encapsular la lógica de acceso a datos. Los repositorios proporcionan métodos predefinidos para operaciones CRUD básicas y permiten definir consultas personalizadas:

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { Usuario } from './usuario.entity';

@Injectable()
export class UsuarioService {
  constructor(
    @InjectRepository(Usuario)
    private usuarioRepository: Repository<Usuario>,
  ) {}

  async crearUsuario(datosUsuario: Partial<Usuario>): Promise<Usuario> {
    const usuario = this.usuarioRepository.create(datosUsuario);
    return await this.usuarioRepository.save(usuario);
  }

  async obtenerUsuarios(): Promise<Usuario[]> {
    return await this.usuarioRepository.find();
  }
}

Query Builder y consultas avanzadas

Para consultas más complejas, TypeORM proporciona el Query Builder, una interfaz fluida que permite construir consultas SQL de manera programática manteniendo la seguridad de tipos:

async buscarUsuariosActivos(limite: number): Promise<Usuario[]> {
  return await this.usuarioRepository
    .createQueryBuilder('usuario')
    .where('usuario.activo = :activo', { activo: true })
    .orderBy('usuario.nombre', 'ASC')
    .limit(limite)
    .getMany();
}

Relaciones entre entidades

TypeORM soporta todos los tipos de relaciones de base de datos: uno a uno (@OneToOne), uno a muchos (@OneToMany), muchos a uno (@ManyToOne) y muchos a muchos (@ManyToMany). Estas relaciones se definen mediante decoradores y permiten navegar entre entidades relacionadas:

@Entity()
export class Pedido {
  @PrimaryGeneratedColumn()
  id: number;

  @ManyToOne(() => Usuario, usuario => usuario.pedidos)
  usuario: Usuario;

  @OneToMany(() => DetallePedido, detalle => detalle.pedido)
  detalles: DetallePedido[];
}

Migraciones y sincronización

Las migraciones en TypeORM permiten versionar y aplicar cambios en el esquema de la base de datos de manera controlada. Aunque la opción synchronize: true es útil durante el desarrollo, en producción se recomienda utilizar migraciones para mantener un control preciso sobre los cambios del esquema.

TypeORM genera automáticamente las migraciones comparando el estado actual de las entidades con el esquema de la base de datos, creando los scripts SQL necesarios para sincronizar ambos estados.

Transacciones y gestión de errores

El manejo de transacciones es fundamental para mantener la integridad de los datos. TypeORM proporciona varios enfoques para trabajar con transacciones, desde el uso de decoradores hasta la gestión manual mediante el EntityManager:

async transferirFondos(origenId: number, destinoId: number, cantidad: number) {
  await this.usuarioRepository.manager.transaction(async manager => {
    await manager.decrement(Usuario, { id: origenId }, 'saldo', cantidad);
    await manager.increment(Usuario, { id: destinoId }, 'saldo', cantidad);
  });
}

La gestión de errores en operaciones de base de datos requiere atención especial, ya que TypeORM puede lanzar diferentes tipos de excepciones según el tipo de error (violación de restricciones, errores de conexión, etc.).