1. ¿Qué es y para qué sirve?

Mikro-ORM es una biblioteca moderna de mapeo objeto-relacional (ORM) para TypeScript y JavaScript (Node.js) que implementa los patrones Identity Map y Unit of Work. A diferencia de ORMs clásicos como TypeORM o Sequelize, Mikro-ORM está inspirada en Doctrine (PHP) y Hibernate (Java), ofreciendo una gestión más predecible del estado de las entidades y su sincronización con la base de datos.

¿Para qué sirve? En aplicaciones web típicas, los desarrolladores suelen enfrentarse al problema de datos "sucios", cuando un mismo registro se carga dos veces en diferentes partes del código, generando conflictos al guardar. Mikro-ORM resuelve esto con Identity Map: para cada clave primaria existe una única instancia de entidad dentro de un mismo contexto (EntityManager). Esto garantiza que siempre trabajes con la versión actualizada del objeto y que todos los cambios se rastreen automáticamente.

La biblioteca soporta múltiples bases de datos (PostgreSQL, MySQL, SQLite, MongoDB, MariaDB) y ofrece potentes herramientas: migraciones, soporte integrado para transacciones, operaciones en cascada, carga de relaciones (eager/lazy), validador de esquemas incorporado y generador de entidades desde una base de datos existente. Mikro-ORM es ideal para modelos de dominio complejos y arquitecturas de microservicios donde la consistencia de datos es crítica.

2. Instalación

Para instalar Mikro-ORM y el controlador de base de datos necesario, ejecuta el siguiente comando con npm (o yarn/pnpm):

# Instalación del núcleo de la biblioteca
npm install @mikro-orm/core

# Instalación del controlador para tu BD (elige uno):
npm install @mikro-orm/sqlite    # SQLite
npm install @mikro-orm/postgresql # PostgreSQL
npm install @mikro-orm/mysql      # MySQL / MariaDB
npm install @mikro-orm/mongodb    # MongoDB

# Adicional: CLI para migraciones y generación de esquemas
npm install @mikro-orm/cli
npm install @mikro-orm/migrations  # para migraciones

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

npm install reflect-metadata

Añade esto a tu tsconfig.json:

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

3. Inicio rápido — ejemplo mínimo funcional

Creemos una aplicación simple con SQLite y una entidad User.

Paso 1. Definir la entidad (entities/User.ts):

import { Entity, PrimaryKey, Property } from '@mikro-orm/core';

@Entity()
export class User {
  @PrimaryKey()
  id!: number;

  @Property()
  name!: string;

  @Property()
  email!: string;

  @Property()
  createdAt: Date = new Date();
}

Paso 2. Configurar Mikro-ORM (index.ts):

import 'reflect-metadata';
import { MikroORM } from '@mikro-orm/core';
import { SqliteDriver } from '@mikro-orm/sqlite';
import { User } from './entities/User';

async function main() {
  const orm = await MikroORM.init({
    entities: [User],
    dbName: 'test.db',
    driver: SqliteDriver,
    debug: true, // registra consultas SQL
  });

  // Crear el esquema (en modo desarrollo)
  await orm.getSchemaGenerator().createSchema();

  // Obtener el EntityManager
  const em = orm.em.fork();

  // Crear un usuario
  const user = em.create(User, {
    name: 'Juan',
    email: 'juan@example.com',
  });
  await em.flush(); // guardar en la BD

  // Leer el usuario
  const found = await em.findOne(User, { email: 'juan@example.com' });
  console.log('Encontrado:', found);

  // Actualizar
  found!.name = 'Carlos';