14. MikroORM: Data Mapper, Identity Map y Unit of Work

14.1 Qué vas a poder hacer al terminar

• Explicar con precisión, en una entrevista o en una revisión de diseño, qué es el desajuste objeto-relacional y qué parte de ese problema resuelve un ORM (y qué parte no resuelve jamás).
• Distinguir Data Mapper de Active Record, justificar por qué MikroORM eligió el primero y decidir con criterio cuál encaja en un proyecto concreto.
• Predecir cuándo el ORM va a ejecutar SQL y cuándo no: por qué dos findOne seguidos hacen una sola consulta, y por qué persist() no escribe nada en la base de datos.
• Describir un flush() paso a paso: cálculo de cambios, orden de commit, transacción, agrupación de sentencias y actualización del estado interno.
• Enumerar los estados de una entidad (transitoria, gestionada, separada, eliminada) y qué método provoca cada transición.
• Explicar por qué un EntityManager no puede compartirse entre peticiones concurrentes, cómo RequestContext lo resuelve con AsyncLocalStorage y cómo se arregla el error «Using global EntityManager instance methods for context specific actions is disallowed».
• Instalar y configurar MikroORM 6 con defineConfig, elegir el metadata provider adecuado y separar la configuración por entornos y para tests.
• Definir entidades con todas las opciones habituales de @Property, elegir el tipo de clave primaria correcto y saber cuándo conviene EntitySchema en lugar de decoradores.
• Comparar MikroORM con TypeORM, Prisma, Drizzle, Sequelize y Knex con honestidad, y elegir con argumentos técnicos en lugar de por moda.

14.2 El desajuste objeto-relacional

El problema no lo inventó ningún ORM: existe desde que los lenguajes orientados a objetos y las bases de datos relacionales convivieron por primera vez. Se conoce como object-relational impedance mismatch (desajuste de impedancia objeto-relacional, expresión tomada de la electrónica) y describe que los dos modelos organizan la información con reglas incompatibles.

   MUNDO DE OBJETOS (memoria)                MUNDO RELACIONAL (disco)
   ──────────────────────────                ────────────────────────

   task                                      TABLA task
    │  id: 7                                 ┌────┬────────────┬────────────┐
    │  title: 'Revisar PR'                   │ id │ title      │ project_id │
    │  done: false                           ├────┼────────────┼────────────┤
    │                                        │  7 │ Revisar PR │      3     │
    ├─ project ──► project                    └────┴────────────┴────────────┘
    │               │ id: 3
    │               │ name: 'Libro'          TABLA project
    │               └─ tasks: [task, …]      ┌────┬───────┐
    │                  (bidireccional)       │ id │ name  │
    │                                        ├────┼───────┤
    └─ tags: Collection[Tag, Tag]            │  3 │ Libro │
                                             └────┴───────┘
   Identidad:   a === b (referencia)
   Navegación:  task.project.name            TABLA task_tags  (tabla puente)
   Herencia:    class A extends B            ┌─────────┬────────┐
   Tipos:       Date, Map, enum, clases      │ task_id │ tag_id │
   Ciclos:      permitidos y normales        └─────────┴────────┘

                                             Identidad:   PRIMARY KEY
                                             Navegación:  JOIN … ON
                                             Herencia:    no existe
                                             Tipos:       int, varchar, timestamptz
                                             Ciclos:      hay que romperlos

14.2.1 Las cinco fricciones concretas

14.2.2 Qué resuelve un ORM y qué NO resuelve

14.2.3 Cuándo NO usar un ORM

Un profesional sabe también cuándo apartar su herramienta favorita. El coste de un ORM es la capa de abstracción: cuando esa capa no aporta nada, solo estorba.

14.3 Historia y contexto: de Fowler a MikroORM 6

14.4 Data Mapper frente a Active Record

Es la primera decisión arquitectónica de cualquier capa de persistencia, y determina cómo se verá tu código de dominio durante los próximos cinco años.

  ACTIVE RECORD  ·  el objeto sabe guardarse a sí mismo
  ─────────────────────────────────────────────────────────────────────
        ┌──────────────────────────────────────┐
        │              class Task              │
        │  ┌────────────────────────────────┐  │
        │  │ DATOS        title, done, …    │  │
        │  ├────────────────────────────────┤  │
        │  │ DOMINIO      completar()       │  │  ◄── tres responsabilidades
        │  ├────────────────────────────────┤  │      en la MISMA clase
        │  │ PERSISTENCIA save(), find(),   │  │
        │  │              remove(), count() │  │
        │  └────────────────────────────────┘  │
        └──────────────────┬───────────────────┘
                           │ SQL
                           ▼
                  ┌──────────────────┐
                  │  Base de datos   │
                  └──────────────────┘

  DATA MAPPER  ·  un mapeador externo traduce entre objetos y filas
  ─────────────────────────────────────────────────────────────────────
        ┌──────────────────────────────────────┐
        │              class Task              │   entidad POJO:
        │  DATOS        title, done, …         │   no conoce el ORM,
        │  DOMINIO      completar()            │   se instancia con `new`
        └──────────────────┬───────────────────┘   y se testea sin BD
                           │ la entidad NO conoce al mapeador
        ┌──────────────────▼───────────────────┐
        │   EntityManager                      │   el MAPEADOR:
        │   · Identity Map  · UnitOfWork       │   conoce tablas, columnas,
        │   · metadatos     · driver           │   claves foráneas y orden
        └──────────────────┬───────────────────┘
                           │ SQL
                           ▼
                  ┌──────────────────┐
                  │  Base de datos   │
                  └──────────────────┘

14.4.1 Definiciones precisas

Active Record (Fowler, PoEAA): «un objeto que envuelve una fila de una tabla, encapsula el acceso a la base de datos y añade lógica de dominio sobre esos datos». La clase contiene a la vez el estado, el comportamiento de negocio y los métodos de persistencia. Instanciar equivale casi a «tener una fila»; llamar a save() escribe inmediatamente.

Data Mapper (Fowler, PoEAA): «una capa de mapeadores que mueve datos entre los objetos y la base de datos manteniéndolos independientes entre sí, y también independientes del propio mapeador». La entidad es un objeto normal que no sabe que existe una base de datos. Otro componente —en MikroORM, el EntityManager— es el único que conoce el esquema y ejecuta SQL.

14.4.2 El mismo caso en los dos estilos

Caso de uso: «marcar una tarea como completada y registrar la fecha, solo si el proyecto está activo».

// La entidad hereda capacidades de persistencia.
// (Sintaxis ilustrativa al estilo TypeORM en modo AR / Eloquent.)
@Entity()
class Task extends BaseEntity {
  @PrimaryKey() id!: number;
  @Property() title!: string;
  @Property() done = false;
  @Property({ nullable: true }) doneAt?: Date;
  @ManyToOne() project!: Project;

  // Lógica de dominio Y persistencia mezcladas
  async completar(): Promise<void> {
    // La entidad consulta la base de datos por su cuenta
    const proyecto = await Project.findOneBy({ id: this.project.id });
    if (!proyecto?.active) throw new Error('Proyecto inactivo');
    this.done = true;
    this.doneAt = new Date();
    await this.save();          // ← escribe YA: UPDATE inmediato
  }
}

// Uso desde el servicio
const task = await Task.findOneBy({ id: 7 });
await task.completar();

// La entidad solo contiene datos y reglas de negocio puras.
@Entity()
export class Task {
  @PrimaryKey() id!: number;
  @Property() title!: string;
  @Property() done = false;
  @Property({ nullable: true }) doneAt?: Date;
  @ManyToOne(() => Project) project!: Project;

  // Regla de negocio sin E/S: testeable sin base de datos
  completar(ahora = new Date()): void {
    if (this.done) throw new TaskYaCompletada(this.id);
    this.done = true;
    this.doneAt = ahora;
  }
}

// El caso de uso orquesta; el EM persiste
@Injectable()
export class TasksService {
  constructor(private readonly em: EntityManager) {}

  async completar(id: number): Promise<void> {
    const task = await this.em.findOneOrFail(Task, id, {
      populate: ['project'],
    });
    if (!task.project.active) throw new ProyectoInactivo();

    task.completar();     // 0 consultas: solo memoria
    await this.em.flush();  // 1 UPDATE, en una transacción
  }
}

Fíjate en la diferencia real, que no es estética: en la versión Data Mapper, Task.completar() es una función pura sobre el estado del objeto. Se puede probar con new Task() en un test unitario de dos líneas, sin base de datos, sin contenedor de inyección y sin dobles. En la versión Active Record, probar completar() exige una base de datos o un mock del método estático findOneBy.

14.4.3 Comparación honesta

14.4.4 Por qué el Data Mapper encaja con DDD y hexagonal

La arquitectura hexagonal (Alistair Cockburn, 2005) establece que el núcleo de la aplicación no debe depender de detalles de infraestructura: las dependencias apuntan hacia dentro. La base de datos es un detalle, un «puerto» que se implementa con un «adaptador». En ese esquema, el dominio define la interfaz TaskRepository y la infraestructura la implementa con el EntityManager; la flecha de dependencia va de fuera hacia dentro, nunca al contrario. Un dominio Active Record no puede cumplir esa regla, porque la entidad es el adaptador: la clase que contiene tus invariantes de negocio importa el ORM y ejecuta SQL.

Con MikroORM tienes dos grados de pureza posibles, y conviene elegirlo de forma consciente:

• Pragmático (recomendado en la mayoría de proyectos): las entidades llevan decoradores de MikroORM, pero ninguna lógica de persistencia. El dominio depende de los decoradores, que son metadatos declarativos y no ejecutan E/S. Simple, directo y suficiente.
• Purista: las entidades son clases sin ningún decorador y el mapeo se declara aparte con EntitySchema (sección 14.9.6). El paquete de dominio no tiene ni una importación del ORM. Es la opción correcta cuando el dominio se publica como librería compartida o cuando hay una regla arquitectónica estricta. Lo veremos en detalle en el capítulo 20.

14.5 Identity Map

Definición (PoEAA): «un mapa que garantiza que cada objeto se cargue solo una vez, manteniendo cada objeto cargado en un mapa indexado por su identidad». En MikroORM vive dentro del UnitOfWork, que a su vez pertenece al EntityManager.

14.5.1 El problema que resuelve

Sin Identity Map, dos consultas que devuelven la misma fila producen dos objetos distintos. Y eso provoca dos problemas graves:

const t1 = await orm.findTask(7);      // objeto A
const t2 = await orm.findTask(7);      // objeto B, otra instancia de la MISMA fila

t1.title = 'Nuevo título';

console.log(t2.title);                 // 'Título viejo'  ← incoherencia en memoria
console.log(t1 === t2);                // false

await orm.save(t1);
await orm.save(t2);                    // ¿cuál gana? Sobrescritura silenciosa

// Y en el caso realmente peligroso:
const proyecto = await orm.findProject(3);              // trae sus tareas
const tarea    = proyecto.tasks.find((t) => t.id === 7); // objeto C
const otra     = await orm.findTask(7);                 // objeto D
otra.done = true;
// el objeto C sigue diciendo done = false: la vista y la respuesta HTTP mienten

Los dos síntomas son: objetos incoherentes en memoria (la misma fila con estados distintos, con riesgo de perder cambios al escribir) y consultas repetidas por la misma fila dentro de una única petición.

14.5.2 Cómo funciona internamente

El Identity Map es, literalmente, un mapa cuya clave se compone del nombre de la entidad y su clave primaria serializada, y cuyo valor es la instancia. Junto a él, el Unit of Work mantiene un segundo mapa con la instantánea original de cada entidad cargada, que es lo que permite el seguimiento de cambios (sección 14.6).

                     EntityManager (fork de esta petición)
   ┌────────────────────────────────────────────────────────────────────┐
   │  UnitOfWork                                                        │
   │  ┌──────────────────────────────────────────────────────────────┐  │
   │  │  IDENTITY MAP            clave  ──►  instancia               │  │
   │  ├──────────────────────────────────────────────────────────────┤  │
   │  │  Task-7      ──►  Task    { id: 7,  title: 'Revisar PR' }    │  │
   │  │  Task-9      ──►  Task    { id: 9,  title: 'Escribir cap.' } │  │
   │  │  Project-3   ──►  Project { id: 3,  name: 'Libro' }          │  │
   │  │  User-12     ──►  User    { id: 12, email: 'ana@ejemplo' }   │  │
   │  └──────────────────────────────────────────────────────────────┘  │
   │  ┌──────────────────────────────────────────────────────────────┐  │
   │  │  INSTANTÁNEAS ORIGINALES  (base del change tracking)         │  │
   │  ├──────────────────────────────────────────────────────────────┤  │
   │  │  Task-7      ──►  { title: 'Revisar PR', done: false, … }    │  │
   │  └──────────────────────────────────────────────────────────────┘  │
   └────────────────────────────────────────────────────────────────────┘

   em.findOne(Task, 7)
        │
        ▼
   ¿existe la clave Task-7 en el mapa?
        │
   ┌────┴──────────────────────────────┐
   │ SÍ                                │ NO
   ▼                                   ▼
   devuelve la MISMA instancia         SELECT … FROM task WHERE id = 7
   0 consultas SQL                     hidrata la instancia,
                                       la registra en el mapa
                                       y guarda su instantánea

14.5.3 Demostración con código

const em = orm.em.fork();   // contexto limpio, con su propio Identity Map

// ── Caso 1: búsqueda por clave primaria dos veces ────────────────────────
const t1 = await em.findOne(Task, 7);
// SQL: select "t0".* from "task" as "t0" where "t0"."id" = 7 limit 1

const t2 = await em.findOne(Task, 7);
// SQL: (ninguno) ← la clave Task-7 ya está en el Identity Map

console.log(t1 === t2);   // true  ← MISMA instancia, no una copia igual

// ── Caso 2: búsqueda por otra propiedad ──────────────────────────────────
const t3 = await em.findOne(Task, { title: 'Revisar PR' });
// SQL: select "t0".* from "task" as "t0" where "t0"."title" = 'Revisar PR' limit 1
//      SÍ se ejecuta: el mapa está indexado por clave primaria, no por título.
//      Pero al recibir la fila, el ORM ve que id = 7 ya está en el mapa y,
//      en lugar de crear otro objeto, DEVUELVE EL EXISTENTE.
console.log(t1 === t3);   // true  ← una consulta más, pero una sola instancia

// ── Caso 3: la misma fila alcanzada por dos caminos distintos ────────────
const proyecto = await em.findOneOrFail(Project, 3, { populate: ['tasks'] });
const desdeLaColeccion = proyecto.tasks.getItems().find((t) => t.id === 7);
console.log(t1 === desdeLaColeccion);   // true  ← coherencia garantizada

// ── Consecuencia práctica ────────────────────────────────────────────────
t1.title = 'Título nuevo';
console.log(t3.title);                  // 'Título nuevo'
console.log(desdeLaColeccion!.title);   // 'Título nuevo'
// No hay forma de tener la fila 7 en dos estados distintos dentro de este EM.

14.5.4 Efectos: caché de primer nivel, memoria y em.clear()

• Es la «caché de primer nivel» (terminología heredada de Hibernate). Su alcance es el EntityManager, es decir, normalmente una petición. No se comparte entre peticiones, no se invalida y no tiene tiempo de expiración: se destruye con el contexto.
• Hace que flush() pueda funcionar sin persist(): al vaciar, el ORM recorre el Identity Map y compara cada entidad gestionada con su instantánea.
• Crece de forma monótona. Cada entidad cargada permanece referenciada hasta que se limpia el contexto. En una petición HTTP normal es irrelevante; en un proceso largo (un worker, una migración de datos, un cron que recorre un millón de filas) es una fuga de memoria garantizada.
• em.clear() vacía el Identity Map y la cola de cambios pendientes: todas las entidades pasan a estar separadas. Es la herramienta correcta en procesos por lotes. Ojo: los cambios no vaciados se pierden, así que se llama después de flush().
• Un EM compartido entre peticiones es un fallo de seguridad, no solo de memoria. Lo vemos en la sección 14.7.

// Recorre 2 millones de tareas para exportarlas.
// El Identity Map acumula 2 millones de entidades
// MÁS 2 millones de instantáneas originales.
// Resultado: "JavaScript heap out of memory".
async exportarTodo() {
  const tareas = await this.em.find(Task, {});   // 1) todo en memoria de golpe
  for (const t of tareas) {
    await this.escribirLinea(t);
  }
}

// Variante igual de mala: paginar sin limpiar el contexto
async exportarPaginado() {
  for (let offset = 0; ; offset += 500) {
    const lote = await this.em.find(Task, {}, { limit: 500, offset });
    if (!lote.length) break;
    for (const t of lote) await this.escribirLinea(t);
    // falta em.clear(): el mapa sigue creciendo lote a lote
  }
}

// Lotes + limpieza del contexto: memoria constante.
async exportarTodo() {
  const em = this.orm.em.fork();          // contexto propio del job
  let offset = 0;
  const TAM = 500;

  for (;;) {
    const lote = await em.find(Task, {}, {
      limit: TAM,
      offset,
      orderBy: { id: 'asc' },             // orden estable: sin filas repetidas
    });
    if (lote.length === 0) break;

    for (const t of lote) await this.escribirLinea(t);

    await em.flush();   // si hubiera cambios, primero se persisten
    em.clear();         // y AHORA se libera el Identity Map
    offset += TAM;
  }
}

// Alternativa aún mejor cuando solo lees: no hidrates entidades.
// Sin objetos gestionados no hay Identity Map que crezca.
const filas = await em.find(Task, {}, {
  fields: ['id', 'title'],   // carga parcial
  disableIdentityMap: true,  // no registrar en el mapa
});

14.6 Unit of Work

Definición (PoEAA): «mantiene una lista de los objetos afectados por una transacción de negocio y coordina la escritura de los cambios y la resolución de problemas de concurrencia». En una frase: es un cuaderno de notas donde el ORM apunta todo lo que hay que hacer y, cuando le dices flush(), lo ejecuta de golpe, en el orden correcto y dentro de una transacción.

14.6.1 Change tracking: la instantánea original

La pregunta natural en un Data Mapper puro es: si la entidad no sabe que existe una base de datos y nadie llama a save(), ¿cómo sabe el ORM qué cambió? La respuesta es sencilla y no usa proxies ni setters mágicos: cuando el ORM hidrata una entidad, guarda una copia plana de sus valores (la instantánea original) en el Unit of Work. En el flush(), compara la entidad con su instantánea campo a campo y genera un UPDATE solo con las columnas que hayan cambiado.

const task = await em.findOneOrFail(Task, 7);
// Instantánea guardada: { id: 7, title: 'Revisar PR', done: false, priority: 3, … }

task.done = true;             // el objeto cambia; la instantánea NO

// La instantánea es accesible (API interna, útil para depurar):
console.log(em.getUnitOfWork().getOriginalEntityData(task));
// { id: 7, title: 'Revisar PR', done: false, priority: 3, … }

await em.flush();
// El diff detecta un único campo modificado:
// SQL: update "task" set "done" = true where "id" = 7
//      ↑ no se envían title ni priority: menos tráfico y menos conflictos
// Tras el commit, la instantánea se ACTUALIZA: la entidad vuelve a estar "limpia".

await em.flush();   // 0 consultas: no hay diferencias que persistir

14.6.2 Anatomía de un flush(), paso a paso

   await em.flush()
        │
        ▼
  ┌─ 1 ─ CÁLCULO DE CAMBIOS (compute change sets) ──────────────────────┐
  │  Recorre las entidades gestionadas y las marcadas con persist():    │
  │     · nueva (sin instantánea)  ──►  ChangeSet CREATE                │
  │     · gestionada con diff      ──►  ChangeSet UPDATE (solo campos   │
  │                                     sucios)                        │
  │     · marcada con remove()     ──►  ChangeSet DELETE                │
  │  Propaga cascadas (persist/remove) por el grafo de relaciones y     │
  │  recorre las colecciones para detectar altas y bajas.               │
  └───────────────────────────────┬─────────────────────────────────────┘
                                  │ ¿algún cambio?
                                  │   NO ──►  return   (0 sentencias SQL)
                                  ▼ SÍ
  ┌─ 2 ─ ORDEN DE COMMIT (commit order) ────────────────────────────────┐
  │  Orden topológico del grafo de dependencias de claves foráneas:     │
  │     Project  antes de  Task  antes de  TaskTag                      │
  │  Los DELETE se ejecutan en orden INVERSO al de los INSERT.          │
  │  Los ciclos se rompen con "extra updates" diferidos.                │
  └───────────────────────────────┬─────────────────────────────────────┘
                                  ▼
  ┌─ 3 ─ APERTURA DE TRANSACCIÓN ───────────────────────────────────────┐
  │  BEGIN        (transacción implícita; implicitTransactions)          │
  │  Evento beforeFlush / onFlush de los EventSubscriber                │
  └───────────────────────────────┬─────────────────────────────────────┘
                                  ▼
  ┌─ 4 ─ EJECUCIÓN AGRUPADA (batching) ─────────────────────────────────┐
  │  @BeforeCreate  ──►  insert into project (…) values (…), (…), (…)   │
  │  @AfterCreate                    ↑ un solo INSERT para N filas      │
  │  @BeforeUpdate  ──►  update task set … where id = …  (por lotes)    │
  │  @AfterUpdate                                                       │
  │  @BeforeDelete  ──►  delete from task_tags where …                  │
  │  @AfterDelete   ──►  delete from task where id in (…)               │
  └───────────────────────────────┬─────────────────────────────────────┘
                                  ▼
  ┌─ 5 ─ CIERRE DE TRANSACCIÓN ─────────────────────────────────────────┐
  │  COMMIT      ·  si algo falla: ROLLBACK y se relanza el error       │
  └───────────────────────────────┬─────────────────────────────────────┘
                                  ▼
  ┌─ 6 ─ SINCRONIZACIÓN DEL ESTADO EN MEMORIA ──────────────────────────┐
  │  · Se rellenan los valores generados por la BD (id, version,        │
  │    defaults, columnas calculadas)                                   │
  │  · Se ACTUALIZAN LAS INSTANTÁNEAS: las entidades quedan "limpias"   │
  │  · Las entidades nuevas pasan a GESTIONADAS y entran al mapa        │
  │  · Las eliminadas salen del Identity Map                            │
  │  · Se vacía la cola de cambios (el Identity Map se CONSERVA)        │
  │  · Evento afterFlush                                                │
  └─────────────────────────────────────────────────────────────────────┘

14.6.3 persist() no escribe; flush() sí

Es el malentendido número uno de quien llega a MikroORM. em.persist(entity) es una operación síncrona que no devuelve una promesa y no habla con la base de datos: solo apunta la entidad en el cuaderno del Unit of Work. La escritura ocurre en em.flush().

async crear(dto: CreateTaskDto): Promise<number> {
  const task = new Task(dto.title);
  this.em.persist(task);       // no escribe NADA todavía

  return task.id;
  // ⇒ undefined: el id lo genera la base de datos
  //   y aquí no ha habido ningún INSERT.
}

async crearMuchas(dtos: CreateTaskDto[]) {
  for (const dto of dtos) {
    const task = new Task(dto.title);
    // Un flush por iteración: N transacciones,
    // N viajes de red, N recálculos de cambios.
    await this.em.persistAndFlush(task);
  }
}

async completarTodas(ids: number[]) {
  const tareas = await this.em.find(Task, { id: { $in: ids } });
  tareas.forEach((t) => t.completar());
  // Falta el flush: la petición responde 200
  // y en la base de datos no ha cambiado nada.
}

async crear(dto: CreateTaskDto): Promise<number> {
  const task = new Task(dto.title);
  this.em.persist(task);
  await this.em.flush();      // INSERT dentro de una transacción

  return task.id;             // ahora sí: el ORM ha rellenado el id
}

async crearMuchas(dtos: CreateTaskDto[]) {
  for (const dto of dtos) {
    this.em.persist(new Task(dto.title));
  }
  // UN solo flush: una transacción y, con batching,
  // un único INSERT con múltiples filas.
  await this.em.flush();
}

async completarTodas(ids: number[]) {
  const tareas = await this.em.find(Task, { id: { $in: ids } });
  tareas.forEach((t) => t.completar());
  // Las entidades ya están GESTIONADAS: no hace falta persist().
  await this.em.flush();      // UPDATE por lotes
}

14.6.4 Estados de una entidad y transiciones

                     em.persist(e)  ·  em.create(Type, {…})
     ┌───────────────┐  ─────────────────────────────────►  ┌───────────────┐
     │  TRANSITORIA  │                                      │  GESTIONADA   │ ◄── em.find()
     │    (new)      │                                      │   (managed)   │     em.findOne()
     │  objeto normal│                                      │ en Identity   │     hidratación
     │  sin id, fuera│                                      │ Map, con      │     desde la BD
     │  del mapa     │                                      │ instantánea   │
     └───────────────┘                                      └───┬───────┬───┘
                                                                 │       │
                          em.clear() · em.fork() · fin de la     │       │ em.remove(e)
                          petición                                │       │
     ┌───────────────┐  ◄────────────────────────────────────────┘       │
     │   SEPARADA    │                                                    ▼
     │  (detached)   │                                            ┌───────────────┐
     │ existe en la  │  ───────────────────────────────────────►  │   ELIMINADA   │
     │ BD, ningún EM │            em.merge(e)  (vuelve a          │   (removed)   │
     │ la vigila     │             estar gestionada)              │ marcada para  │
     └───────────────┘                                            │ DELETE        │
                                                                  └───────┬───────┘
                                                                          │ em.flush()
                                                                          ▼
                                                            DELETE ejecutado y salida
                                                            del Identity Map

14.6.5 La API del Unit of Work que usarás a diario

14.6.6 Flush modes: cuándo puede vaciar el ORM por su cuenta

El modo de vaciado determina si el ORM puede decidir vaciar antes de una consulta para que esa consulta vea tus cambios pendientes. Se configura globalmente con flushMode, por EM con em.setFlushMode(), por fork, por transacción o por consulta.

14.6.7 Ventajas e inconvenientes del Unit of Work

14.7 El EntityManager

El EntityManager es la fachada del ORM y el corazón del Data Mapper: es el mapeador. Es el único objeto que conoce a la vez tus entidades, los metadatos del mapeo, el Identity Map, el Unit of Work y el driver de la base de datos. Todo lo que hagas contra la base de datos pasa por él, directamente o a través de un repositorio.

14.7.1 Qué contiene y cuál es su ciclo de vida

   ┌──────────────────────────── MikroORM (singleton) ────────────────────────────┐
   │  · configuración validada        · MetadataStorage (metadatos de entidades)  │
   │  · driver + pool de conexiones   · caché de metadatos                        │
   │  · orm.em  ──► EntityManager GLOBAL: solo sirve para hacer fork()            │
   └──────────────────────────────────┬───────────────────────────────────────────┘
                                      │ orm.em.fork()  (una vez por petición)
                                      ▼
   ┌──────────────────────── EntityManager (por petición) ────────────────────────┐
   │  UnitOfWork ─── Identity Map ─── instantáneas ─── cola de cambios            │
   │  EntityRepository<T> (uno por entidad, en caché)                             │
   │  transacción activa (si hay)   ·   flushMode   ·   filtros activos           │
   │  COMPARTE el pool de conexiones con el resto de la aplicación                │
   └──────────────────────────────────────────────────────────────────────────────┘

Ciclo de vida. El objeto MikroORM se crea una vez al arrancar el proceso (MikroORM.init()) y se destruye al apagarlo (orm.close(), enganchado al cierre ordenado de Nest). El EntityManager, en cambio, es barato y desechable: se crea uno por unidad de trabajo —normalmente una petición HTTP, un mensaje de cola o una ejecución de cron— y se abandona al terminar. No hay que cerrarlo: cuando nadie lo referencia, el recolector de basura se lleva con él su Identity Map. Lo que no se duplica es el pool de conexiones: todos los forks comparten el mismo, y las conexiones se piden y devuelven por consulta o por transacción.

14.7.2 Por qué NO puede compartirse entre peticiones

Un EntityManager lleva estado mutable con nombre y apellidos: el Identity Map y la cola de cambios. Compartirlo entre peticiones concurrentes significa compartir ese estado. En Node, donde un solo proceso atiende cientos de peticiones intercaladas en el mismo hilo, las consecuencias van del desperdicio de memoria a la fuga de datos entre usuarios.

@Injectable()
export class ReportsCron {
  constructor(private readonly orm: MikroORM) {}

  @Cron('0 3 * * *')
  async generar() {
    // Usa el EM GLOBAL: fuera de una petición no hay
    // contexto asíncrono, así que el ORM lanza:
    //
    // ValidationError: Using global EntityManager instance
    // methods for context specific actions is disallowed.
    // If you need to work with the global instance's
    // identity map, use `allowGlobalContext` configuration
    // option or `fork()` instead.
    const tareas = await this.orm.em.find(Task, {});
    // ...
  }
}

// Y el "arreglo" que NO hay que copiar del primer
// resultado de búsqueda que encuentres:
//   allowGlobalContext: true
// Silencia el aviso y te devuelve exactamente el
// problema de memoria y de fuga de datos que describe
// la sección anterior.

import { CreateRequestContext, MikroORM } from '@mikro-orm/core';

@Injectable()
export class ReportsCron {
  // El decorador necesita encontrar MikroORM, EntityManager
  // o un EntityRepository en el propio objeto.
  constructor(private readonly orm: MikroORM) {}

  @Cron('0 3 * * *')
  @CreateRequestContext()          // crea un contexto (y un fork) propio
  async generar() {
    // this.orm.em resuelve al fork del contexto: seguro.
    const tareas = await this.orm.em.find(Task, {});
    // ...
    await this.orm.em.flush();
  }
}

// Alternativa explícita, sin decoradores, igual de válida
// y a veces más clara en scripts:
async generarManual() {
  const em = this.orm.em.fork();
  const tareas = await em.find(Task, {});
  await em.flush();
}

14.7.3 em.fork(): qué copia y qué no

14.7.4 RequestContext y AsyncLocalStorage

Aquí se cierra el círculo con el capítulo 1. El problema es de diseño: la inyección de dependencias de Nest entrega, por defecto, la misma instancia de cada provider a todas las peticiones. Si el EntityManager inyectado fuera el global, tendríamos exactamente el problema de la sección 14.7.2. Y pasar el EM como parámetro por todas las capas sería insoportable.

La solución es AsyncLocalStorage del núcleo de Node: un almacén que acompaña a toda la cadena de await de una operación asíncrona, aislado por «ejecución». MikroORM lo envuelve en el helper RequestContext. Con eso, el orm.em global se convierte en un proxy: cada método que toca el Identity Map llama antes a em.getContext(), que busca el fork del contexto actual y delega en él.

   PETICIÓN A (usuario Ana)                    PETICIÓN B (usuario Luis)
        │                                            │
        ▼                                            ▼
   MikroOrmMiddleware                           MikroOrmMiddleware
   RequestContext.create(orm.em, next)          RequestContext.create(orm.em, next)
        │                                            │
        ▼                                            ▼
   orm.em.fork()  ──►  EM-A                    orm.em.fork()  ──►  EM-B
        │   Identity Map propio                      │   Identity Map propio
        │   UnitOfWork propio                        │   UnitOfWork propio
        ▼                                            ▼
   AsyncLocalStorage.run(EM-A, …)               AsyncLocalStorage.run(EM-B, …)
        │  todo el árbol de await de A                │
        │  ve EM-A, sin pasar parámetros              │
        ▼                                            ▼
   TasksController                              (idéntico, aislado)
        │
        ▼
   TasksService  ──►  this.em  (¡el global inyectado por Nest!)
        │
        ▼  em.getContext()
   RequestContext.getEntityManager()  ──►  EM-A
        │
        ▼
   await em.flush()   ──►   BEGIN … INSERT/UPDATE … COMMIT
        │                   (transacción propia de A)
        ▼
   fin de la petición: EM-A queda sin referencias
   y el recolector libera su Identity Map

import { MikroOrmModule } from '@mikro-orm/nestjs';

@Module({
  imports: [
    // Sin argumentos, lee el mikro-orm.config.ts declarado para el CLI.
    // Registra AUTOMÁTICAMENTE MikroOrmMiddleware, que llama a
    // RequestContext.create() en cada petición.
    // Con registerRequestContext: false lo desactivas para gestionarlo tú.
    MikroOrmModule.forRoot(),

    // Expone los EntityRepository<T> inyectables de estas entidades
    MikroOrmModule.forFeature([Task, Project]),
  ],
})
export class AppModule {}

@Injectable()
export class TasksService {
  // Nest inyecta el EntityManager global una sola vez, al arrancar.
  // No importa: cada llamada resuelve al fork de SU petición.
  constructor(private readonly em: EntityManager) {}

  async listar(): Promise<Task[]> {
    return this.em.find(Task, {});   // usa EM-A o EM-B según quién pregunte
  }
}

14.7.5 EntityRepository: qué es realmente

Conviene desmontar un malentendido muy extendido: en MikroORM, un EntityRepository<T> no es una capa de abstracción sobre la base de datos. Es, literalmente, una fachada tipada sobre el mismo EntityManager: guarda una referencia al EM y el nombre de la entidad, y reenvía las llamadas rellenando ese primer argumento por ti.

const repo = em.getRepository(Task);

await repo.find({ done: false });        //  ═  em.find(Task, { done: false })
await repo.findOneOrFail(7);             //  ═  em.findOneOrFail(Task, 7)
repo.getEntityManager() === em.getContext();   // true: es el MISMO EM

// En la v6 se ELIMINARON del repositorio los métodos de persistencia
// (persist, persistAndFlush, remove, removeAndFlush, flush) porque daban la
// falsa impresión de ser un contexto propio de la entidad. Ahora:
em.persist(task);
await em.flush();

import { EntityRepository } from '@mikro-orm/postgresql';

export class TaskRepository extends EntityRepository<Task> {
  // Consulta con nombre del dominio: el "por qué" queda en el nombre
  async buscarVencidas(hasta: Date): Promise<Task[]> {
    return this.find(
      { done: false, dueDate: { $lt: hasta } },
      { populate: ['project'], orderBy: { dueDate: 'asc' } },
    );
  }

  // Encapsula SQL avanzado sin filtrarlo al servicio
  async contarPorProyecto(): Promise<{ projectId: number; total: number }[]> {
    return this.createQueryBuilder('t')
      .select(['t.project as projectId', 'count(t.id) as total'])
      .where({ done: false })
      .groupBy('t.project')
      .execute();
  }
}

// Se enlaza con la entidad mediante la opción `repository`
@Entity({ repository: () => TaskRepository })
export class Task {
  // Este símbolo hace que em.getRepository(Task) devuelva TaskRepository TIPADO
  [EntityRepositoryType]?: TaskRepository;
  // ...
}

14.8 Instalación y configuración

14.8.1 Paquetes

# Núcleo + driver. El paquete del driver RE-EXPORTA todo @mikro-orm/core,
# así que en la v6 lo idiomático es importar SIEMPRE desde el driver.
npm i @mikro-orm/core @mikro-orm/postgresql

# Integración con NestJS (módulo, middleware de contexto, @InjectRepository)
npm i @mikro-orm/nestjs

# Extensiones (v6: hay que declararlas en `extensions` de la configuración)
npm i @mikro-orm/migrations        # migraciones versionadas (capítulo 17)
npm i @mikro-orm/seeder            # datos de prueba y factorías

# Herramientas de desarrollo
npm i -D @mikro-orm/cli            # comando `mikro-orm`
npm i -D @mikro-orm/entity-generator  # generar entidades desde una BD existente
npm i -D @mikro-orm/reflection     # TsMorphMetadataProvider (opcional)
npm i -D @mikro-orm/sqlite         # driver para los tests

# Comprobación rápida de que el CLI encuentra tu configuración
npx mikro-orm debug

14.8.2 Drivers soportados y sus particularidades

14.8.3 mikro-orm.config.ts con defineConfig

import { defineConfig, UnderscoreNamingStrategy } from '@mikro-orm/postgresql';
import { Migrator } from '@mikro-orm/migrations';
import { SeedManager } from '@mikro-orm/seeder';
import { TsMorphMetadataProvider } from '@mikro-orm/reflection';
import 'dotenv/config';   // v6: los .env YA NO se cargan solos (solo las MIKRO_ORM_*)

const esProd = process.env.NODE_ENV === 'production';

// defineConfig() viene del PAQUETE DEL DRIVER: fija el driver y tipa las
// opciones específicas del motor. Sustituye a la antigua opción `type: 'postgresql'`,
// que hacía un require() dinámico y rompía webpack, Vite y Next.
export default defineConfig({
  // ── Conexión ────────────────────────────────────────────────────────────
  clientUrl: process.env.DATABASE_URL,   // o host/port/user/password/dbName
  dbName: process.env.DB_NAME ?? 'tasks',
  schema: 'public',

  // ── Entidades ───────────────────────────────────────────────────────────
  // Opción A (recomendada): importación explícita. Funciona con cualquier
  // bundler, es analizable estáticamente y falla al compilar si te equivocas.
  entities: [Task, Project, User, TaskTag],

  // Opción B: descubrimiento por rutas. Cómodo en proyectos grandes, pero exige
  // mantener DOS listas coherentes y no sobrevive a un empaquetado agresivo:
  // entities: ['./dist/**/*.entity.js'], entitiesTs: ['./src/**/*.entity.ts'],

  // ── Metadatos ───────────────────────────────────────────────────────────
  metadataProvider: TsMorphMetadataProvider,   // ver 14.8.4
  metadataCache: { enabled: true, pretty: !esProd },

  // ── Extensiones (v6: explícitas) ────────────────────────────────────────
  extensions: [Migrator, SeedManager],
  migrations: { path: './dist/migrations', pathTs: './src/migrations', snapshot: true },
  seeder:     { path: './dist/seeders',    pathTs: './src/seeders' },

  // ── Registro y depuración ───────────────────────────────────────────────
  debug: esProd ? false : ['query', 'query-params'],
  logger: (mensaje) => logger.debug({ orm: true }, mensaje),  // integra tu logger
  highlighter: esProd ? undefined : new SqlHighlighter(),

  // ── Pool de conexiones ──────────────────────────────────────────────────
  pool: {
    min: 2,
    max: 10,                       // regla: max × réplicas ≤ max_connections del motor
    acquireTimeoutMillis: 30_000,  // cuánto esperar por una conexión libre
    idleTimeoutMillis: 30_000,
  },

  // ── Opciones que van directas al driver ─────────────────────────────────
  driverOptions: {
    connection: { ssl: esProd ? { rejectUnauthorized: true } : false },
  },

  // ── Convenciones de nombres ─────────────────────────────────────────────
  // Por defecto en SQL: createdAt ──► created_at, TaskTag ──► task_tag
  namingStrategy: UnderscoreNamingStrategy,

  // ── Fechas y validación ─────────────────────────────────────────────────
  forceUtcTimezone: true,   // guarda las fechas en UTC (por defecto desde la v7)
  validate: true,           // valida los tipos de propiedad antes de persistir
  strict: true,             // ...y NO los convierte en silencio: lanza error
  validateRequired: true,   // (por defecto) exige las propiedades obligatorias

  // ── Caché de resultados ─────────────────────────────────────────────────
  resultCache: { expiration: 5_000, global: false },  // opt-in por consulta

  // ── Contexto ────────────────────────────────────────────────────────────
  allowGlobalContext: false,  // NUNCA true en producción (ver 14.7.2)
});

14.8.4 Metadata provider: la decisión menos obvia y más importante

MikroORM necesita saber el tipo de cada propiedad para elegir el tipo de columna y para convertir valores. Hay dos formas de averiguarlo, y no son equivalentes.

14.8.5 El CLI

{
  "scripts": {
    "orm": "mikro-orm",
    "migration:create": "mikro-orm migration:create",
    "migration:up": "mikro-orm migration:up"
  },
  "mikro-orm": {
    "useTsNode": true,
    "configPaths": [
      "./src/mikro-orm.config.ts",
      "./dist/mikro-orm.config.js"
    ]
  }
}

npx mikro-orm debug                  # ¿qué config lee? ¿qué entidades descubre?
npx mikro-orm schema:create --dump   # imprime el DDL SIN ejecutarlo
npx mikro-orm schema:update --dump   # diferencia entre entidades y BD real
npx mikro-orm schema:fresh --run --seed   # recrea el esquema (¡solo en desarrollo!)

npx mikro-orm migration:create       # genera la migración con el diff detectado
npx mikro-orm migration:up           # aplica las pendientes
npx mikro-orm migration:down         # revierte la última
npx mikro-orm migration:list         # estado de cada migración

npx mikro-orm seeder:run             # ejecuta los seeders
npx mikro-orm cache:generate         # precalcula la caché de metadatos (CI/Docker)
npx mikro-orm generate-entities --dump  # entidades a partir de una BD existente

14.8.6 Configuración por entorno y para tests

import { defineConfig as postgres } from '@mikro-orm/postgresql';
import { defineConfig as sqlite } from '@mikro-orm/sqlite';

const comun = {
  entities: [Task, Project, User, TaskTag],
  forceUtcTimezone: true,
  namingStrategy: UnderscoreNamingStrategy,
};

export const configDesarrollo = postgres({
  ...comun,
  clientUrl: process.env.DATABASE_URL,
  debug: ['query', 'query-params'],
  extensions: [Migrator, SeedManager],
});

export const configProduccion = postgres({
  ...comun,
  clientUrl: process.env.DATABASE_URL,
  debug: false,
  pool: { min: 2, max: 10 },
  metadataCache: { enabled: true },
  driverOptions: { connection: { ssl: { rejectUnauthorized: true } } },
  extensions: [Migrator],
});

// Tests unitarios y de integración rápidos: SQLite en memoria.
// Cada suite arranca con un esquema limpio y sin contenedores.
export const configTest = sqlite({
  ...comun,
  dbName: ':memory:',
  debug: false,
  // Única excepción legítima: en los tests no hay peticiones HTTP
  // y no queremos un fork() en cada línea.
  allowGlobalContext: true,
});

import { MikroORM } from '@mikro-orm/sqlite';

let orm: MikroORM;

beforeAll(async () => {
  orm = await MikroORM.init(configTest);
  await orm.schema.createSchema();     // crea las tablas a partir de las entidades
});
beforeEach(async () => {
  await orm.schema.clearDatabase();    // aislamiento: base limpia en cada test
  orm.em.clear();                      // ...y contexto limpio
});
afterAll(async () => {
  await orm.close(true);   // cierra el pool: si no, Jest se queda colgado
});

14.9 Entidades: lo esencial

Aquí solo cubrimos las entidades «planas». Relaciones, herencia, embeddables y colecciones tienen capítulo propio (el 15).

14.9.1 Anatomía de una entidad

import {
  Entity, PrimaryKey, Property, Enum, Index, Unique, Formula, Opt,
} from '@mikro-orm/postgresql';

export enum TaskStatus {
  PENDING = 'pending',
  IN_PROGRESS = 'in_progress',
  DONE = 'done',
}

@Entity({ tableName: 'tasks' })          // sin tableName: 'task' (naming strategy)
@Index({ properties: ['status', 'dueDate'] })   // índice compuesto
export class Task {
  @PrimaryKey()
  id!: number;                            // serial / identity

  @Property({ length: 200 })
  title!: string;                         // varchar(200) not null

  @Property({ type: 'text', nullable: true })
  description?: string;                   // text null

  @Enum({ items: () => TaskStatus, nativeEnumName: 'task_status' })
  status: TaskStatus = TaskStatus.PENDING;

  @Property({ type: 'decimal', precision: 10, scale: 2, nullable: true })
  estimatedHours?: string;                // decimal: NO uses number (pierde precisión)

  @Property({ nullable: true })
  dueDate?: Date;                         // timestamptz null

  // Se rellenan solos: onCreate/onUpdate se ejecutan durante el flush.
  // `Opt` (v6) le dice a TypeScript que no hace falta pasarlo a em.create().
  @Property({ onCreate: () => new Date() })
  createdAt!: Date & Opt;

  @Property({ onUpdate: () => new Date(), nullable: true })
  updatedAt?: Date;

  @Property({ version: true })
  version!: number;                       // bloqueo optimista (capítulo 17)

  @Property({ hidden: true, nullable: true })
  internalNotes?: string;                 // nunca aparece en toObject()/toJSON()

  @Property({ persist: false })
  urlPublica?: string;                    // vive en memoria; no existe como columna

  @Formula((alias) => `(${alias}.due_date < now() and ${alias}.status != 'done')`)
  overdue?: boolean;                      // lo calcula el SELECT, no JavaScript

  // Getter puro: no es una columna y no se serializa por defecto
  get resumen(): string {
    return `[${this.status}] ${this.title}`;
  }
}

14.9.2 Tipos de clave primaria

// 1) Autoincremental: el defecto. Compacta (4-8 bytes), ordenada, índices densos.
//    Inconveniente: es adivinable y revela volumen ("enumeración de recursos").
@PrimaryKey()
id!: number;

// 2) UUID v4 generado en la aplicación: opaco y generable sin ir a la base de datos.
@PrimaryKey({ type: 'uuid' })
id: string = randomUUID();               // node:crypto

// 3) UUID v4 generado por PostgreSQL
@PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
id!: string;

// 4) UUID v7: LA OPCIÓN RECOMENDADA hoy si necesitas identificadores opacos.
//    Los 48 bits más significativos son una marca de tiempo en milisegundos,
//    así que los valores son MONÓTONAMENTE CRECIENTES.
@PrimaryKey({ type: 'uuid' })
id: string = uuidv7();                   // paquete `uuidv7`

// 5) Clave compuesta: varias @PrimaryKey y el símbolo PrimaryKeyProp (v6),
//    que en la v5 se llamaba PrimaryKeyType y admitía una unión.
@Entity()
export class TaskAssignment {
  @ManyToOne(() => Task, { primary: true })    task!: Task;
  @ManyToOne(() => User, { primary: true })    user!: User;
  [PrimaryKeyProp]?: ['task', 'user'];         // el ORDEN importa
  @Property() assignedAt: Date = new Date();
}

// 6) Clave natural: un valor del dominio que ya identifica de forma única.
@Entity()
export class Country {
  @PrimaryKey({ length: 2 })
  code!: string;             // 'ES', 'PT', 'FR'
}

14.9.3 Índices, unicidad y restricciones

@Entity()
// Índice compuesto: el ORDEN de las propiedades determina qué consultas aprovecha.
// (status, dueDate) sirve para filtrar por status, o por status Y dueDate;
// NO sirve para filtrar solo por dueDate.
@Index({ properties: ['status', 'dueDate'], name: 'idx_task_status_due' })
// Unicidad compuesta: no puede haber dos tareas con el mismo título en un proyecto
@Unique({ properties: ['project', 'title'] })
// Índice parcial (solo PostgreSQL): mucho más pequeño y más rápido si la mayoría
// de las filas no cumplen la condición. Requiere expresión SQL literal.
@Index({
  name: 'idx_task_pending',
  expression: 'create index idx_task_pending on tasks (due_date) where status = \'pending\'',
})
// Restricción de comprobación a nivel de tabla
@Check({ expression: 'estimated_hours is null or estimated_hours > 0' })
export class Task { /* ... */ }

14.9.4 Clases base abstractas

// abstract: true ⇒ NO genera tabla; sus propiedades se copian a cada hija.
// No confundir con la herencia de tabla única (capítulo 15).
@Entity({ abstract: true })
export abstract class BaseEntity {
  @PrimaryKey({ type: 'uuid' })
  id: string = uuidv7();

  @Property({ onCreate: () => new Date() })
  createdAt!: Date & Opt;

  @Property({ onUpdate: () => new Date(), nullable: true })
  updatedAt?: Date;

  @Property({ version: true })
  version!: number;
}

@Entity()
export class Task extends BaseEntity {
  @Property() title!: string;      // hereda id, createdAt, updatedAt y version
}

14.9.5 EntitySchema: entidades sin decoradores

// El DOMINIO: una clase de TypeScript sin una sola importación de MikroORM.
// Se puede publicar en un paquete compartido con el frontend.
export class Task {
  id!: number;
  title!: string;
  status: TaskStatus = TaskStatus.PENDING;
  createdAt!: Date;
  project!: Project;

  completar(): void { this.status = TaskStatus.DONE; }
}

// La INFRAESTRUCTURA: el mapeo, declarado aparte y tipado contra la clase.
import { EntitySchema } from '@mikro-orm/postgresql';

export const TaskSchema = new EntitySchema<Task>({
  class: Task,
  tableName: 'tasks',
  properties: {
    id:        { type: 'number', primary: true },
    title:     { type: 'string', length: 200 },
    status:    { enum: true, items: () => TaskStatus, default: TaskStatus.PENDING },
    createdAt: { type: 'Date', onCreate: () => new Date() },
    // En la v6 la clase de relación se declara con `kind` (antes `reference`)
    project:   { kind: 'm:1', entity: () => Project },
  },
  indexes: [{ properties: ['status', 'createdAt'] }],
});

// En la configuración se registra el ESQUEMA, no la clase
export default defineConfig({ entities: [TaskSchema, ProjectSchema] });

14.9.6 strictPropertyInitialization y el operador !

Como vimos en el capítulo 1, con strict: true el compilador exige que toda propiedad no opcional se inicialice. En una entidad, el valor lo pone el ORM al hidratar desde la base de datos, no tu código, así que se usa el operador de aserción de asignación definida: id!: number. Es correcto y esperado; no es el ! abusivo que oculta errores de lógica.

@Entity()
export class Task {
  // Marcar como opcional lo que en la BD es NOT NULL:
  // el tipo miente y contagia comprobaciones inútiles
  // (`task.title?.toUpperCase()`) a toda la aplicación.
  @Property()
  title?: string;

  // Valor por defecto falso solo para callar al compilador:
  // si el ORM lo hidrata, se sobrescribe; si no, tienes
  // una cadena vacía viajando por el dominio.
  @Property()
  status: string = '';

  // `any` para esquivar el problema del tipo
  @Property()
  dueDate: any;
}

@Entity()
export class Task {
  // NOT NULL y lo rellena el ORM ⇒ aserción definida
  @Property()
  title!: string;

  // Con valor por defecto REAL del dominio: sin `!`.
  // `Opt` le indica a em.create() que no es obligatorio pasarlo.
  @Property()
  status: TaskStatus & Opt = TaskStatus.PENDING;

  // Columna anulable ⇒ opcional en TypeScript. Los dos coinciden.
  @Property({ nullable: true })
  dueDate?: Date;

  // Constructor con lo imprescindible: garantiza invariantes
  // y permite `new Task('título')` en los tests.
  constructor(title: string) {
    this.title = title;
  }
}

14.9.7 wrap(entity) y el WrappedEntity

Las entidades no llevan métodos del ORM (Data Mapper puro), así que las utilidades sobre una entidad viven en un objeto envoltorio al que se accede con wrap().

import { wrap } from '@mikro-orm/postgresql';

// getReference() crea un PROXY no inicializado: solo conoce la clave primaria.
// No hay ninguna consulta: sirve para asignar relaciones sin cargar la fila.
const ref = em.getReference(Project, 3);
console.log(wrap(ref).isInitialized());   // false

// init() lo materializa (SELECT) y devuelve la entidad ya cargada
await wrap(ref).init();
console.log(wrap(ref).isInitialized());   // true
console.log(ref.name);                    // ahora sí está disponible

// toObject(): DTO plano respetando `hidden` y las pistas de populate.
// toJSON() hace lo mismo (es lo que usa JSON.stringify).
const dto = wrap(task).toObject();

// assign(): aplica cambios parciales con validación de tipos.
// Es la base de un PATCH y respeta el change tracking.
wrap(task).assign({ title: 'Nuevo título', status: TaskStatus.DONE });
// equivalente: em.assign(task, { ... })

// Clave primaria de forma genérica (útil con claves compuestas)
console.log(wrap(task).getPrimaryKey());

// Acceso a los internos (segundo parámetro true): para depurar
const h = wrap(task, true);
console.log(h.__initialized, h.__managed, h.__originalEntityData);

14.9.8 Hooks de entidad y EventSubscriber

@Entity()
export class Task {
  // Se ejecutan DENTRO del flush, alrededor del INSERT/UPDATE/DELETE
  // correspondiente, y por tanto dentro de la transacción.
  @BeforeCreate()
  @BeforeUpdate()
  normalizar(): void {
    this.title = this.title.trim();
    this.slug = slugify(this.title);
  }

  @AfterCreate()
  registrarCreacion(args: EventArgs<Task>): void {
    // args.em está disponible, pero NO hagas flush aquí (ver más abajo)
  }

  // @OnInit se dispara al CREAR LA INSTANCIA, incluidas las referencias
  // no inicializadas: la entidad puede no tener datos todavía.
  @OnInit()
  inicializar(): void {
    this.uiState ??= {};
  }

  // @OnLoad se dispara cuando la entidad está COMPLETAMENTE cargada.
  // Puede ser asíncrono.
  @OnLoad()
  async trasCargar(args: EventArgs<Task>): Promise<void> { /* ... */ }
}

// Un subscriber es una clase externa: sirve para varias entidades y, sobre todo,
// tiene acceso a los eventos GLOBALES del flush, que los hooks no tienen.
export class AuditSubscriber implements EventSubscriber {
  // Sin este método, se suscribe a TODAS las entidades
  getSubscribedEntities(): EntityName<AnyEntity>[] {
    return [Task, Project];
  }

  // beforeFlush: el ÚNICO punto donde todavía puedes añadir entidades
  // o modificar otras y contar con que se persistan en el mismo flush,
  // porque los change sets aún no están calculados.
  async beforeFlush(args: FlushEventArgs): Promise<void> {
    for (const cs of args.uow.getChangeSets()) {
      if (cs.type === ChangeSetType.UPDATE) {
        args.em.persist(new AuditLog(cs.name, cs.getPrimaryKey(), cs.payload));
      }
    }
  }

  // afterFlush: ya está confirmado. Aquí es seguro publicar eventos
  // de dominio o encolar trabajos, no antes.
  async afterFlush(args: FlushEventArgs): Promise<void> {
    await this.bus.publicarPendientes();
  }
}

// v6: el decorador @Subscriber() se eliminó. Se registran en la configuración,
// que además admite la clase, no solo una instancia.
export default defineConfig({ subscribers: [AuditSubscriber] });

@Entity()
export class Task {
  @AfterUpdate()
  async notificar(args: EventArgs<Task>): Promise<void> {
    // 1) Un flush DENTRO de un flush: reentrada,
    //    cambios que no se detectan y, en el mejor
    //    de los casos, un comportamiento impredecible.
    await args.em.flush();

    // 2) Llamada HTTP dentro de la transacción: la
    //    mantiene abierta y bloqueando filas mientras
    //    espera a un tercero. Si el COMMIT falla luego,
    //    el correo ya se envió: efecto irreversible.
    await this.mailer.enviar(this.assignee.email);

    // 3) Da por hecho que la relación está cargada:
    //    TypeError si `assignee` es una referencia.
    console.log(this.assignee.name);
  }
}

// El hook queda solo para lo trivial y síncrono
@Entity()
export class Task {
  @BeforeCreate()
  @BeforeUpdate()
  normalizar(): void {
    this.title = this.title.trim();
  }
}

// Los efectos externos, DESPUÉS del commit y en el caso de uso
@Injectable()
export class TasksService {
  async completar(id: number): Promise<void> {
    const task = await this.em.findOneOrFail(Task, id, {
      populate: ['assignee'],
    });
    task.completar();

    await this.em.flush();          // transacción cerrada y confirmada

    // Ahora sí: si esto falla, el estado en la BD ya es correcto
    // y el reintento es responsabilidad de la cola.
    await this.cola.encolar('task.completed', { id: task.id });
  }
}

14.10 Primer CRUD completo y comentado

@Injectable()
export class TasksService {
  constructor(private readonly em: EntityManager) {}

  // ─── CREATE ────────────────────────────────────────────────────────────
  async crear(dto: CreateTaskDto): Promise<Task> {
    // getReference no consulta: crea un proxy con la clave primaria.
    // Suficiente para establecer la clave foránea.
    const project = this.em.getReference(Project, dto.projectId);

    // em.create() valida los tipos, aplica los valores por defecto y
    // llama a persist() automáticamente (persistOnCreate: true).
    const task = this.em.create(Task, {
      title: dto.title,
      description: dto.description,
      project,
      status: TaskStatus.PENDING,
    });

    await this.em.flush();
    // BEGIN
    // insert into "tasks" ("title", "description", "project_id", "status",
    //                      "created_at", "version")
    //   values ($1, $2, $3, 'pending', $4, 1)
    //   returning "id", "created_at", "version"
    // COMMIT
    //   ↑ RETURNING: PostgreSQL devuelve los valores generados en la MISMA
    //     ida y vuelta. En MySQL harían falta dos pasos.

    return task;   // ya tiene id, createdAt y version rellenos
  }

  // ─── READ (uno) ────────────────────────────────────────────────────────
  async porId(id: number): Promise<Task> {
    return this.em.findOneOrFail(Task, id, { populate: ['project'] });
    // select "t0".*,
    //        ("t0"."due_date" < now() and "t0"."status" != 'done') as "overdue",
    //        "p1"."id" as "p1__id", "p1"."name" as "p1__name"
    //   from "tasks" as "t0"
    //   left join "projects" as "p1" on "t0"."project_id" = "p1"."id"
    //   where "t0"."id" = $1
    //   limit 1
    //   ↑ estrategia JOINED (la de por defecto en la v6 para SQL): una sola
    //     consulta. Con SELECT_IN serían dos: la tarea y luego el proyecto.
    //   ↑ @Formula viaja como expresión calculada en el SELECT.
    // findOneOrFail lanza NotFoundError si no hay fila: evita el `if (!x) throw`.
  }

  // ─── READ (lista paginada) ─────────────────────────────────────────────
  async listar(q: ListTasksQuery): Promise<{ items: Task[]; total: number }> {
    const [items, total] = await this.em.findAndCount(
      Task,
      { status: q.status, project: q.projectId },
      { limit: q.limit, offset: q.offset, orderBy: { createdAt: 'desc' } },
    );
    // select … from "tasks" as "t0"
    //   where "t0"."status" = $1 and "t0"."project_id" = $2
    //   order by "t0"."created_at" desc limit $3 offset $4
    // select count(*) from "tasks" as "t0" where …
    //   ↑ dos consultas: los datos y el total. Ojo: `offset` grande es lento;
    //     en el capítulo 16 verás la paginación por cursor.
    return { items, total };
  }

  // ─── UPDATE ────────────────────────────────────────────────────────────
  async actualizar(id: number, dto: UpdateTaskDto): Promise<Task> {
    const task = await this.em.findOneOrFail(Task, id);
    // select … from "tasks" where "id" = $1 limit 1
    //   ↑ imprescindible para el change tracking: sin instantánea no hay diff.

    this.em.assign(task, dto);   // aplica solo los campos presentes en el DTO

    await this.em.flush();
    // BEGIN
    // update "tasks"
    //    set "title" = $1, "updated_at" = $2, "version" = 2
    //  where "id" = $3 and "version" = 1
    // COMMIT
    //   ↑ solo las columnas MODIFICADAS.
    //   ↑ `and version = 1` es el bloqueo optimista: si otra petición ya
    //     actualizó la fila, afecta a 0 filas y el ORM lanza
    //     OptimisticLockError en lugar de perder el cambio ajeno.
    return task;
  }

  // ─── DELETE ────────────────────────────────────────────────────────────
  async borrar(id: number): Promise<void> {
    // Borrado sin SELECT previo: una referencia basta.
    this.em.remove(this.em.getReference(Task, id));
    await this.em.flush();
    // BEGIN
    // delete from "tasks" where "id" = $1
    // COMMIT
    //   ↑ Sin cargar la entidad NO se ejecutan los hooks @BeforeDelete que
    //     dependan de sus datos, ni las cascadas que requieran el grafo
    //     cargado. Si los necesitas, carga la entidad primero.
  }

  // ─── Operación masiva: cuando NO quieres el Unit of Work ───────────────
  async archivarAntiguas(antesDe: Date): Promise<number> {
    // nativeUpdate NO pasa por el Unit of Work: no hidrata entidades,
    // no lanza hooks y no actualiza el Identity Map. Es un UPDATE directo.
    return this.em.nativeUpdate(
      Task,
      { status: TaskStatus.DONE, updatedAt: { $lt: antesDe } },
      { archived: true },
    );
    // update "tasks" set "archived" = true
    //  where "status" = 'done' and "updated_at" < $1
    //   ↑ una sentencia para N filas. A cambio: si esas entidades ya estaban
    //     en el Identity Map, quedan DESACTUALIZADAS en memoria.
    //     Tras un nativeUpdate, considera em.clear() o em.refresh().
  }
}

14.11 MikroORM frente a los demás ORM de Node

Ninguna de estas herramientas es «la mejor»: resuelven problemas distintos con compromisos distintos. Esta tabla intenta ser justa, incluso cuando eso significa reconocer que MikroORM no es la respuesta.

14.11.1 Lo que hacen mejor los demás

• Prisma tiene mejor experiencia de desarrollo, sin discusión. El esquema declarativo en un solo fichero, el cliente generado, el autocompletado y la calidad de la documentación no tienen rival. Si tu problema es «necesito una API sobre estas doce tablas y quiero estar en producción el viernes», Prisma es probablemente la respuesta correcta y defender MikroORM sería dogmatismo. Sus límites reales aparecen con dominios ricos: no hay Identity Map ni Unit of Work, así que la coordinación de escrituras complejas la orquestas tú, y el modelo de datos vive en un lenguaje propio en lugar de en tus clases, lo que dificulta las entidades con comportamiento.
• Drizzle es más rápido y más ligero. No hay hidratación de entidades, ni instantáneas, ni metadatos que descubrir: eso se nota en el arranque en frío y en el consumo de memoria, dos cosas críticas en serverless y en el edge. Su API es tan cercana al SQL que casi no hay traducción mental. Lo que no te da es precisamente lo que enseña este capítulo: si escribes un caso de uso que toca ocho entidades relacionadas, el orden de inserción, la transacción y la coherencia en memoria son tu responsabilidad.
• Knex y Kysely son insustituibles para informes y procesos por lotes, incluso teniendo un ORM. No compiten: complementan.
• TypeORM y Sequelize tienen más material didáctico y más respuestas en foros, simplemente por antigüedad. Con un equipo junior y sin tiempo de formación, eso pesa.

14.12 Errores comunes y cómo solucionarlos

14.13 Buenas y malas prácticas

14.14 Preguntas frecuentes

14.15 Ejercicios

// ── CORRECTO: un solo flush ────────────────────────────────────────────────
async crearProyectoConTareas(nombre: string, titulos: string[]) {
  const project = this.em.create(Project, { name: nombre, active: true });

  for (const title of titulos) {
    // No necesitamos el id del proyecto: pasamos la REFERENCIA al objeto.
    // El Unit of Work insertará primero el proyecto y propagará su clave.
    this.em.create(Task, { title, project, status: TaskStatus.PENDING });
  }

  await this.em.flush();
}

begin;
insert into "projects" ("name", "active") values ('Libro', true) returning "id";
insert into "tasks" ("title", "status", "project_id", "created_at") values
  ('Cap. 14', 'pending', 3, now()),
  ('Cap. 15', 'pending', 3, now()),
  ('Cap. 16', 'pending', 3, now())
  returning "id";
commit;

async recorrerTodo(): Promise<void> {
  // 1) Contexto propio: no contaminamos ni heredamos el de nadie
  const em = this.orm.em.fork();
  const TAM = 500;
  let offset = 0;

  for (;;) {
    // 2) orderBy estable: sin un orden determinista, la paginación por
    //    offset puede repetir u omitir filas si hay escrituras concurrentes
    const lote = await em.find(Task, {}, {
      limit: TAM,
      offset,
      orderBy: { id: 'asc' },
    });
    if (lote.length === 0) break;

    for (const t of lote) {
      t.slug = slugify(t.title);   // cambio detectado por el change tracking
    }

    // 3) Primero persistir...
    await em.flush();
    // 4) ...y SOLO DESPUÉS liberar. Al revés, los cambios se perderían
    //    en silencio: em.clear() no avisa de que había trabajo pendiente.
    em.clear();

    offset += TAM;
    // 5) Opcional: ceder el event loop para no monopolizar el proceso
    await new Promise((r) => setImmediate(r));
  }
}

14.16 Resumen del capítulo

14.17 Recursos adicionales

• MikroORM · Identity Map and Request Context — la referencia oficial de este capítulo, incluidos los dos problemas del EM compartido.
• MikroORM · Unit of Work and Transactions — detección de cambios, transacciones implícitas y modos de vaciado.
• MikroORM · Entity Manager — la API completa que hemos recorrido.
• MikroORM · Configuration — todas las opciones, con sus valores por defecto por versión.
• MikroORM · Defining Entities — decoradores, EntitySchema y opciones de propiedad.
• MikroORM · Upgrading from v5 to v6 — imprescindible para interpretar tutoriales antiguos.
• MikroORM · Usage with NestJS — el módulo, el middleware de contexto y @InjectRepository.
• Martin Fowler · Catálogo de PoEAA — las fichas originales de Data Mapper, Identity Map, Unit of Work y Active Record; el libro Patterns of Enterprise Application Architecture (2002) sigue siendo la mejor lectura sobre esto.
• Doctrine ORM · Unit of Work — la documentación en la que se inspira MikroORM; útil cuando busques comportamientos internos.
• Node.js · AsyncLocalStorage — el mecanismo que hace posible RequestContext.
• MikroORM · Notas de versión — la fuente fiable para saber en qué versión entró cada cosa.