16. Consultas, QueryBuilder, paginación y el problema N+1

// Firma simplificada (los genéricos se infieren; nunca los escribes a mano)
em.find<Entity, Hint, Fields, Excludes>(
  entityName: EntityName<Entity>,          // la clase: Task, User, Project…
  where: FilterQuery<Entity>,              // el objeto de condiciones (sección 16.4)
  options?: FindOptions<Entity, Hint, Fields, Excludes>,
): Promise<Loaded<Entity, Hint, Fields, Excludes>[]>;

import { EntityManager, NotFoundError, QueryOrder } from '@mikro-orm/core';
// 1 · find → lista (array vacío si no hay nada, nunca null)
const abiertas = await em.find(Task, { status: 'doing' });
// 2 · findOne → entidad o null
const tarea = await em.findOne(Task, { id: 42 });
if (!tarea) { /* decide tú qué significa */ }
// 3 · findOneOrFail → entidad o excepción (NotFoundError por defecto)
const obligatoria = await em.findOneOrFail(Task, { id: 42 });
// 4 · findAndCount → [página, total] en DOS consultas
const [items, total] = await em.findAndCount(Task, { status: 'todo' },
  { limit: 20, offset: 40, orderBy: { createdAt: QueryOrder.DESC } });
// 5 · findAll → sin argumento de condición; el where va dentro de las opciones
const todas = await em.findAll(Task, { orderBy: { id: 'asc' }, limit: 100 });
// 6 · count → solo el número, sin materializar entidades
const pendientes = await em.count(Task, { status: { $ne: 'done' } });
// 7 · findByCursor → paginación por keyset (sección 16.9)
const pagina = await em.findByCursor(Task, { status: 'todo' },
  { first: 20, orderBy: [{ createdAt: 'desc' }, { id: 'desc' }] });

-- 1 · find
select "t0".* from "task" as "t0" where "t0"."status" = $1;
-- 4 · findAndCount: SIEMPRE dos sentencias
select "t0".* from "task" as "t0" where "t0"."status" = $1
  order by "t0"."created_at" desc limit $2 offset $3;
select count(*) as "count" from "task" as "t0" where "t0"."status" = $1;
-- 6 · count
select count(*) as "count" from "task" as "t0" where "t0"."status" != $1;

import { NotFoundException } from '@nestjs/common';
async findOneForUser(id: number, userId: number): Promise<Task> {
  return this.em.findOneOrFail(
    Task,
    { id, assignee: userId },
    {
      populate: ['project', 'tags'],
      // failHandler recibe el nombre de la entidad y la condición usada.
      // Devuelve (no lanza) el Error que MikroORM lanzará por ti.
      failHandler: (entityName, where) =>
        new NotFoundException(`No se encontró ${entityName} con ${JSON.stringify(where)}`),
    },
  );
}

import { defineConfig } from '@mikro-orm/postgresql';
import { NotFoundException } from '@nestjs/common';
export default defineConfig({
  // ...
  // Se aplica a TODOS los findOneOrFail que no traigan su propio failHandler.
  findOneOrFailHandler: (entityName) =>
    new NotFoundException(`${entityName} no encontrado`),
  // Variante para findOneOrFail con { strict: true }, que además falla
  // si la condición devuelve MÁS de una fila.
  findExactlyOneOrFailHandler: (entityName) =>
    new NotFoundException(`${entityName} no identifica un único registro`),
});

const [tasks, total] = await this.em.findAndCount(
  Task,
  { project: { team: { members: { id: userId } } }, status: { $ne: 'done' } },
  {
    populate: ['assignee', 'tags'],
    fields: ['id', 'title', 'status', 'priority', 'dueDate', 'assignee.name', 'tags.name'],
    orderBy: [{ priority: 'desc' }, { dueDate: 'asc' }, { id: 'asc' }],
    limit: 25, offset: 0,
    strategy: LoadStrategy.SELECT_IN,
    cache: 5_000,                                   // 5 s de caché de resultado
    comment: 'GET /api/tasks · listado del panel',  // aparece en el log del motor
  },
);

/* GET /api/tasks · listado del panel */
select "t0"."id", "t0"."title", "t0"."status", "t0"."priority", "t0"."due_date", "t0"."assignee_id"
  from "task" as "t0"
  inner join "project" as "p1" on "t0"."project_id" = "p1"."id"
  inner join "team" as "t2" on "p1"."team_id" = "t2"."id"
  inner join "team_members" as "t3" on "t2"."id" = "t3"."team_id"
 where "t3"."user_id" = $1 and "t0"."status" != $2
 order by "t0"."priority" desc, "t0"."due_date" asc, "t0"."id" asc limit $3;
-- populate de assignee (SELECT_IN), solo los campos pedidos
select "u0"."id", "u0"."name" from "user" as "u0" where "u0"."id" in ($1, $2, $3);
-- populate de tags a través de la tabla puente
select "t1"."name", "t0"."task_id" as "fk__task_id", "t0"."tag_id" as "fk__tag_id"
  from "tag" as "t1" inner join "task_tags" as "t0" on "t1"."id" = "t0"."tag_id"
 where "t0"."task_id" in ($1, $2, $3);

// Igualdad simple: la forma más común
await em.find(Task, { status: 'todo' });
// varias claves = AND implícito
await em.find(Task, { status: 'todo', priority: 3 });
// Por clave primaria: tres formas equivalentes
await em.findOne(Task, 42);              // atajo: el escalar es la PK
await em.findOne(Task, { id: 42 });      // explícito
await em.findOne(Task, { id: [1, 2, 3] }); // un array en la PK equivale a $in
// Por relación: con la ENTIDAD, con el IDENTIFICADOR (sin cargar nada) o de forma explícita
await em.find(Task, { project: em.getReference(Project, 7) });
await em.find(Task, { project: 7 });
await em.find(Task, { project: { id: 7 } });
// Relación nula: tareas sin responsable asignado
await em.find(Task, { assignee: null });

select "t0".* from "task" as "t0" where "t0"."status" = $1 and "t0"."priority" = $2;
select "t0".* from "task" as "t0" where "t0"."id" in ($1, $2, $3);
select "t0".* from "task" as "t0" where "t0"."project_id" = $1;   -- las tres formas por relación
select "t0".* from "task" as "t0" where "t0"."assignee_id" is null;

// Rango: dos operadores sobre el MISMO campo, en el mismo objeto
await em.find(Task, { dueDate: { $gte: inicio, $lte: fin } });
// $or de bloques completos (con AND implícito dentro de cada rama)
await em.find(Task, { $or: [{ status: 'doing' }, { priority: 5, dueDate: { $lt: new Date() } }] });
// Anidamiento: (proyecto = 7) AND (título contiene 'api' OR etiqueta = 'api')
await em.find(Task, {
  project: 7,
  $or: [{ title: { $ilike: '%api%' } }, { tags: { name: 'api' } }],
});
// $and explícito: obligatorio cuando repites el mismo campo con distintas condiciones
await em.find(Task, {
  $and: [{ title: { $ilike: '%api%' } }, { title: { $not: { $ilike: '%deprecated%' } } }],
});
// $not niega un bloque entero
await em.find(Task, { $not: { status: { $in: ['done', 'archived'] } } });

select "t0".*
  from "task" as "t0"
  left join "task_tags" as "t2" on "t0"."id" = "t2"."task_id"
  left join "tag" as "t1" on "t2"."tag_id" = "t1"."id"
 where "t0"."project_id" = $1
   and ("t0"."title" ilike $2 or "t1"."name" = $3);

// Tareas cuyos proyectos pertenecen a un equipo del que es miembro este usuario,
// y cuyo propietario tiene un email de la organización.
const tasks = await em.find(Task, {
  project: {
    owner: { email: { $ilike: '%@acme.com' } },
    team: { members: { id: userId } },
  },
  status: { $ne: 'done' },
});

select "t0".*
  from "task" as "t0"
  inner join "project" as "p1" on "t0"."project_id" = "p1"."id"
  inner join "user"    as "u2" on "p1"."owner_id"   = "u2"."id"
  inner join "team"    as "t3" on "p1"."team_id"    = "t3"."id"
  inner join "team_members" as "t4" on "t3"."id"    = "t4"."team_id"
 where "u2"."email" ilike $1
   and "t4"."user_id" = $2
   and "t0"."status" != $3;

// $some: al menos una etiqueta llamada 'urgente'
await em.find(Task, { tags: { $some: { name: 'urgente' } } });
// $some sin condición: la colección tiene AL MENOS un elemento
await em.find(Task, { comments: { $some: {} } });
// $none: ninguna etiqueta 'interna'  ·  y con {}: colección VACÍA
await em.find(Task, { tags: { $none: { name: 'interna' } } });
await em.find(Task, { comments: { $none: {} } });      // tareas sin comentarios
// $every: TODAS las etiquetas están en la lista permitida
await em.find(Task, { tags: { $every: { name: { $in: ['api', 'bug', 'ux'] } } } });

-- $some
select "t0".* from "task" as "t0"
 where exists (
   select 1 from "task_tags" as "tt"
     inner join "tag" as "tg" on "tt"."tag_id" = "tg"."id"
    where "tt"."task_id" = "t0"."id" and "tg"."name" = $1
 );
-- $none con {} → tareas sin ningún comentario
select "t0".* from "task" as "t0"
 where not exists (select 1 from "comment" as "c" where "c"."task_id" = "t0"."id");
-- $every → "no existe ningún elemento que INCUMPLA"
select "t0".* from "task" as "t0"
 where not exists (
   select 1 from "task_tags" as "tt" inner join "tag" as "tg" on "tt"."tag_id" = "tg"."id"
    where "tt"."task_id" = "t0"."id" and not ("tg"."name" in ($1, $2, $3))
 );

// Igualdad sobre una clave del documento
await em.find(Task, { meta: { source: 'slack' } });
// Comparación numérica dentro del JSON
await em.find(Task, { meta: { slaHours: { $lte: 8 } } });
// Anidamiento y operadores de contención (PostgreSQL, jsonb)
await em.find(Task, { meta: { client: { tier: 'gold' } } });
await em.find(Task, { meta: { $contains: { labels: ['api'] } } });

select "t0".* from "task" as "t0" where "t0"."meta"->>'source' = $1;
select "t0".* from "task" as "t0" where ("t0"."meta"->>'slaHours')::numeric <= $1;
select "t0".* from "task" as "t0" where "t0"."meta"->'client'->>'tier' = $1;
select "t0".* from "task" as "t0" where "t0"."meta" @> $1;

import { Type } from 'class-transformer';
import { IsArray, IsEnum, IsInt, IsOptional, IsString, Max, Min } from 'class-validator';
export type TaskStatus = 'todo' | 'doing' | 'done' | 'archived';
const SORTABLE = ['createdAt', 'dueDate', 'priority', 'title'] as const;
export class ListTasksQuery {
  @IsOptional() @IsString() q?: string;
  @IsOptional() @IsArray() @IsEnum(['todo', 'doing', 'done', 'archived'], { each: true }) status?: TaskStatus[];
  // CRÍTICO: sin @Type, el valor llega como la CADENA "3" y la comparación falla o hace un cast implícito
  @IsOptional() @Type(() => Number) @IsInt() @Min(1) @Max(5) minPriority?: number;
  @IsOptional() @Type(() => Number) @IsInt() projectId?: number;
  @IsOptional() @Type(() => Date) dueBefore?: Date;
  @IsOptional() @IsArray() @IsString({ each: true }) tags?: string[];
  @IsOptional() @Type(() => Number) @IsInt() @Min(1) @Max(100) limit = 20;
  @IsOptional() @Type(() => Number) @IsInt() @Min(0) offset = 0;
  // Lista BLANCA de campos ordenables: nunca aceptes un nombre de columna arbitrario del cliente
  @IsOptional() @IsEnum(SORTABLE) sort: (typeof SORTABLE)[number] = 'createdAt';
  @IsOptional() @IsEnum(['asc', 'desc']) dir: 'asc' | 'desc' = 'desc';
}

import { EntityManager, FilterQuery, FindOptions } from '@mikro-orm/core';
export class TasksRepository {
  constructor(private readonly em: EntityManager) {}
  /** Traduce la consulta HTTP ya validada a una condición de MikroORM. Función PURA: testeable sin base de datos. */
  buildFilter(q: ListTasksQuery, viewerId: number): FilterQuery<Task> {
    // La primera condición SIEMPRE se aplica: el alcance del usuario no es opcional.
    const and: FilterQuery<Task>[] = [{ project: { team: { members: { id: viewerId } } } }];
    if (q.q) and.push({ title: { $ilike: `%${q.q}%` } });
    // Comprueba la LONGITUD, no solo la existencia: [] generaría "in ()" y no devolvería nada
    if (q.status?.length) and.push({ status: { $in: q.status } });
    // !== undefined, no truthy: el 0 es un valor legítimo
    if (q.minPriority !== undefined) and.push({ priority: { $gte: q.minPriority } });
    if (q.projectId !== undefined) and.push({ project: q.projectId });          // por id: sin join
    if (q.dueBefore) and.push({ dueDate: { $lte: q.dueBefore } });
    if (q.tags?.length) and.push({ tags: { $some: { name: { $in: q.tags } } } }); // EXISTS, no join
    return and.length === 1 ? and[0] : { $and: and };
  }
  buildOptions(q: ListTasksQuery): FindOptions<Task, 'assignee' | 'tags'> {
    return {
      populate: ['assignee', 'tags'],
      // Desempate por clave primaria: sin él, el orden entre iguales no es estable (16.9)
      orderBy: [{ [q.sort]: q.dir }, { id: 'asc' }],
      limit: q.limit, offset: q.offset, comment: 'GET /api/tasks',
    };
  }
  async list(q: ListTasksQuery, viewerId: number) {
    const [items, total] = await this.em.findAndCount(Task, this.buildFilter(q, viewerId), this.buildOptions(q));
    return { items, total };
  }
}

insert into "task" ("title", "status", "project_id", "assignee_id", "created_at")
values ($1, $2, $3, $4, $5)
returning "id", "created_at";

async update(id: number, dto: UpdateTaskDto): Promise<Task> {
  const task = await this.em.findOneOrFail(Task, id);
  this.em.assign(task, dto, {
    mergeObjectProperties: true,   // meta se fusiona, no se reemplaza
    onlyOwnProperties: true,       // descarta claves que no son propiedades de Task
  });
  await this.em.flush();           // UPDATE solo de lo que realmente cambió
  return task;
}

// insert: devuelve la clave primaria generada. No pasa por el Unit of Work.
const id = await em.insert(Task, { title: 'Importada', status: 'todo', project: 7 });
// insertMany: UNA sentencia con muchos VALUES. Ideal para importaciones masivas.
const ids = await em.insertMany(Task, rows);   // rows: 5.000 objetos planos
// nativeUpdate: devuelve el número de filas afectadas
const afectadas = await em.nativeUpdate(
  Task,
  { project: 7, status: 'doing' },
  { status: 'todo', assignee: null },
);
// nativeDelete: borrado en bloque
const borradas = await em.nativeDelete(Task, { status: 'archived', updatedAt: { $lt: hace1Ano } });

insert into "task" ("title", "status", "project_id") values ($1, $2, $3) returning "id";
-- insertMany: una sola sentencia, no 5.000
insert into "task" ("title", "status", "project_id")
values ($1, $2, $3), ($4, $5, $6), ($7, $8, $9) /* … */ returning "id";
update "task" set "status" = $1, "assignee_id" = $2 where "project_id" = $3 and "status" = $4;
delete from "task" where "status" = $1 and "updated_at" < $2;

// Un solo registro. Devuelve la entidad gestionada.
const tag = await em.upsert(Tag, { name: 'urgente', color: '#f00' });
// Con conflicto sobre una clave única que no es la primaria
const user = await em.upsert(User, { email: 'ana@acme.com', name: 'Ana' }, {
  onConflictFields: ['email'],       // qué columnas definen el conflicto
  onConflictAction: 'merge',         // 'merge' actualiza · 'ignore' no hace nada
  onConflictMergeFields: ['name'],   // y actualiza SOLO estas al haber conflicto
});
// Lote: una sola sentencia para N filas. La herramienta de las importaciones.
const tags = await em.upsertMany(Tag, [
  { name: 'api', color: '#08f' },
  { name: 'bug', color: '#f80' },
  { name: 'ux',  color: '#8f0' },
], { onConflictFields: ['name'], onConflictAction: 'merge' });

insert into "user" ("email", "name") values ($1, $2)
on conflict ("email") do update set "name" = excluded."name"
returning "id";
-- upsertMany: una sentencia para las tres etiquetas
insert into "tag" ("name", "color") values ($1, $2), ($3, $4), ($5, $6)
on conflict ("name") do update set "color" = excluded."color"
returning "id";
-- con onConflictAction: 'ignore'
insert into "tag" ("name", "color") values ($1, $2)
on conflict ("name") do nothing
returning "id";

// Camino gestionado: sin cargar la entidad completa, usando una referencia
em.remove(em.getReference(Task, id));
await em.flush();
// → delete from "task" where "id" = $1
// Purga nocturna: una sentencia, sin materializar nada
const n = await em.nativeDelete(Comment, { createdAt: { $lt: hace2Anos } });
// → delete from "comment" where "created_at" < $1

import { QueryOrder } from '@mikro-orm/core';
const qb = em.createQueryBuilder(Task, 't');    // alias 't' para la tabla raíz
const tasks = await qb
  .select(['t.id', 't.title', 't.status', 't.priority'])
  .addSelect('t.dueDate')                        // añade sin reemplazar la selección anterior
  .where({ status: { $ne: 'done' } })            // objeto: mismo FilterQuery de 16.4
  .andWhere('t.priority >= ?', [3])              // SQL con parámetro posicional ligado
  .orWhere({ dueDate: { $lt: new Date() } })
  .orderBy({ 't.priority': QueryOrder.DESC, 't.id': QueryOrder.ASC })
  .limit(20)
  .offset(40)
  .getResultList();

select "t"."id", "t"."title", "t"."status", "t"."priority", "t"."due_date"
  from "task" as "t"
 where ("t"."status" != $1 and "t"."priority" >= $2) or "t"."due_date" < $3
 order by "t"."priority" desc, "t"."id" asc
 limit $4 offset $5;

const qb = em.createQueryBuilder(Task, 't');
const tasks = await qb
  .select('t.*')
  // INNER JOIN: filtra. Solo tareas CON responsable.
  .innerJoin('t.assignee', 'u')
  // LEFT JOIN + SELECT: trae el proyecto y lo hidrata en la entidad
  .leftJoinAndSelect('t.project', 'p')
  // Join con CONDICIÓN ADICIONAL: solo los comentarios recientes
  .leftJoinAndSelect('t.comments', 'c', { 'c.createdAt': { $gte: hace7Dias } })
  // Alias explícitos para poder filtrar por columnas de las tablas unidas
  .where({ 'u.email': { $ilike: '%@acme.com' }, 'p.archived': false })
  .orderBy({ 'p.name': 'asc', 't.priority': 'desc' })
  .getResultList();

select "t".*,
       "p"."id" as "p__id", "p"."name" as "p__name", "p"."archived" as "p__archived",
       "c"."id" as "c__id", "c"."body" as "c__body", "c"."created_at" as "c__created_at"
  from "task" as "t"
 inner join "user"    as "u" on "t"."assignee_id" = "u"."id"
  left join "project" as "p" on "t"."project_id"  = "p"."id"
  left join "comment" as "c" on "t"."id" = "c"."task_id" and "c"."created_at" >= $1
 where "u"."email" ilike $2 and "p"."archived" = $3
 order by "p"."name" asc, "t"."priority" desc;

import { raw, sql } from '@mikro-orm/core';
// count con distinct: cuenta tareas, no filas del join
const total = await em.createQueryBuilder(Task, 't')
  .leftJoin('t.tags', 'tg')
  .where({ 'tg.name': 'urgente' })
  .count('t.id', true)          // true = distinct
  .execute('get');
// Varios agregados a la vez: declara el tipo del resultado, el QB no lo infiere
interface StatsRow { total: number; media: number; maximo: number; minimo: number; suma: number }
const [stats] = await em.createQueryBuilder(Task, 't')
  .select([raw('count(*) as total'), raw('avg(t.priority) as media'), raw('max(t.priority) as maximo'),
           raw('min(t.priority) as minimo'), raw('sum(coalesce(t.estimate_hours, 0)) as suma')])
  .where({ project: projectId })
  .execute<StatsRow[]>('all');
// El literal `sql` parametriza de forma segura lo que se interpola
const recientes = await em.createQueryBuilder(Task, 't')
  .select('t.*').where(sql`t.created_at >= now() - interval '7 days'`).getResultList();

select count(distinct "t"."id") as "count"
  from "task" as "t" left join "task_tags" as "t1" on "t"."id" = "t1"."task_id"
  left join "tag" as "tg" on "t1"."tag_id" = "tg"."id"
 where "tg"."name" = $1;
select count(*) as total, avg(t.priority) as media, max(t.priority) as maximo,
       min(t.priority) as minimo, sum(coalesce(t.estimate_hours, 0)) as suma
  from "task" as "t" where "t"."project_id" = $1;

// 1 · Subconsulta en el WHERE: tareas que tienen al menos 3 comentarios
const conMuchos = em.createQueryBuilder(Comment, 'c').select('c.task').groupBy('c.task').having('count(*) >= ?', [3]);
const tasks = await em.createQueryBuilder(Task, 't')
  .select('t.*').where({ id: { $in: conMuchos.getKnexQuery() } }).getResultList();
// 2 · Subconsulta en el SELECT: contador correlacionado por fila
const contador = em.createQueryBuilder(Comment, 'c2')
  .count('c2.id').where({ task: raw('t.id') });      // raw('t.id') correlaciona con la consulta externa
interface FilaConContador { id: number; title: string; comentarios: number }
const filas = await em.createQueryBuilder(Task, 't')
  .select(['t.id', 't.title', contador.as('comentarios')])
  .where({ project: projectId })
  .execute<FilaConContador[]>('all');
// 3 · EXISTS: el propio FilterQuery ya lo genera, y es la forma más eficiente de «tiene alguno»
const conUrgentes = await em.createQueryBuilder(Task, 't')
  .select('t.*').where({ tags: { $some: { name: 'urgente' } } }).getResultList();

-- 1 · IN con subconsulta agrupada
select "t".* from "task" as "t"
 where "t"."id" in (
   select "c"."task_id" from "comment" as "c"
    group by "c"."task_id" having count(*) >= $1
 );
-- 2 · subconsulta correlacionada en el SELECT
select "t"."id", "t"."title",
       (select count("c2"."id") from "comment" as "c2" where "c2"."task_id" = t.id) as "comentarios"
  from "task" as "t" where "t"."project_id" = $1;

const qb = em.createQueryBuilder(Task, 't')
  .select('t.*')
  .where({ status: 'todo', priority: { $gte: 3 } })
  .orderBy({ 't.createdAt': 'desc' })
  .limit(10);
console.log(qb.getQuery());
// select "t".* from "task" as "t" where "t"."status" = ? and "t"."priority" >= ?
//   order by "t"."created_at" desc limit ?
console.log(qb.getParams());          // [ 'todo', 3, 10 ]
console.log(qb.getFormattedQuery());
// select "t".* from "task" as "t" where "t"."status" = 'todo' and "t"."priority" >= 3
//   order by "t"."created_at" desc limit 10
const tasks = await qb.getResultList();   // el QB se puede reutilizar tras inspeccionarlo

export interface TasksByUserRow { userId: number; userName: string; status: TaskStatus; total: number; horas: number }
async tasksByStatusAndUser(projectId: number): Promise<TasksByUserRow[]> {
  const rows = await this.em.createQueryBuilder(Task, 't')
    .select(['u.id as "userId"', 'u.name as "userName"', 't.status as status',
             raw('count(*) as total'), raw('coalesce(sum(t.estimate_hours), 0) as horas')])
    .join('t.assignee', 'u')
    .where({ project: projectId })
    .groupBy(['u.id', 'u.name', 't.status'])
    .having('count(*) > ?', [0])
    .orderBy({ 'u.name': 'asc', 't.status': 'asc' })
    .execute<Array<Record<string, unknown>>>('all');
  // Frontera explícita: los tipos se normalizan aquí y en ningún otro sitio
  return rows.map((r) => ({
    userId: Number(r.userId), userName: String(r.userName), status: r.status as TaskStatus,
    total: Number(r.total), horas: Number(r.horas),
  }));
}

select "u"."id" as "userId", "u"."name" as "userName", "t"."status" as status,
       count(*) as total, coalesce(sum(t.estimate_hours), 0) as horas
  from "task" as "t"
 inner join "user" as "u" on "t"."assignee_id" = "u"."id"
 where "t"."project_id" = $1
 group by "u"."id", "u"."name", "t"."status"
having count(*) > $2
 order by "u"."name" asc, "t"."status" asc;

interface RankingRow { userId: number; name: string; completadas: number; posicion: number }
async rankingCompletadas(teamId: number, desde: Date): Promise<RankingRow[]> {
  const rows = await this.em.createQueryBuilder(User, 'u')
    .select(['u.id as "userId"', 'u.name as name', raw('count(t.id) as completadas'),
             raw('rank() over (order by count(t.id) desc) as posicion')])
    .join('u.teams', 'tm')
    // La condición va en el ON, no en el WHERE: así los usuarios con 0 aparecen
    .leftJoin('u.assignedTasks', 't', { 't.status': 'done', 't.updatedAt': { $gte: desde } })
    .where({ 'tm.id': teamId })
    .groupBy(['u.id', 'u.name'])
    .orderBy({ completadas: 'desc' })
    .execute<Array<Record<string, unknown>>>('all');
  return rows.map((r) => ({
    userId: Number(r.userId), name: String(r.name),
    completadas: Number(r.completadas), posicion: Number(r.posicion),
  }));
}

async search(q: ListTasksQuery, viewerId: number) {
  const qb = this.em.createQueryBuilder(Task, 't')
    .select('t.*')
    .leftJoinAndSelect('t.assignee', 'u')
    .join('t.project', 'p')
    .join('p.team', 'tm')
    .join('tm.members', 'm');
  // UN solo where con un objeto: sin ambigüedad de precedencia
  const and: FilterQuery<Task>[] = [{ 'm.id': viewerId } as FilterQuery<Task>];
  if (q.q) and.push({ $or: [{ title: { $ilike: `%${q.q}%` } }, { description: { $ilike: `%${q.q}%` } }] });
  if (q.status?.length)          and.push({ status: { $in: q.status } });
  if (q.minPriority !== undefined) and.push({ priority: { $gte: q.minPriority } });
  if (q.tags?.length)            and.push({ tags: { $some: { name: { $in: q.tags } } } });
  qb.where({ $and: and })
    .orderBy([{ [`t.${q.sort}`]: q.dir }, { 't.id': 'asc' }])
    .limit(q.limit, q.offset);
  // getResultAndCount reutiliza los filtros y joins para el count
  const [items, total] = await qb.getResultAndCount();
  return { items, total };
}

/** Tareas «doing» sin ningún comentario en los últimos 14 días: candidatas a revisión. */
async estancadas(projectId: number): Promise<Task[]> {
  const actividad = this.em.createQueryBuilder(Comment, 'c')
    .select('1')
    .where({ task: raw('t.id') })
    .andWhere(sql`c.created_at >= now() - interval '14 days'`);
  return this.em.createQueryBuilder(Task, 't')
    .select('t.*')
    .leftJoinAndSelect('t.assignee', 'u')
    .where({ project: projectId, status: 'doing' })
    .andWhere(`not exists (${actividad.getQuery()})`, actividad.getParams())
    .orderBy({ 't.updatedAt': 'asc' })
    .getResultList();
}

select "t".*, "u"."id" as "u__id", "u"."name" as "u__name"
  from "task" as "t"
  left join "user" as "u" on "t"."assignee_id" = "u"."id"
 where "t"."project_id" = $1 and "t"."status" = $2
   and not exists (
     select 1 from "comment" as "c"
      where "c"."task_id" = t.id and c.created_at >= now() - interval '14 days'
   )
 order by "t"."updated_at" asc;

// execute(sql, params, method): 'all' → filas · 'get' → una fila · 'run' → metadatos
const rows = await this.em.getConnection().execute<Array<{ semana: string; total: string }>>(
  `select date_trunc('week', t.created_at) as semana, count(*) as total
     from task t
     join project p on p.id = t.project_id
    where p.team_id = ? and t.created_at >= ?
    group by 1 order by 1 desc`,
  [teamId, desde],            // parámetros LIGADOS: el driver los envía aparte del SQL
  'all',
);
return rows.map((r) => ({ semana: new Date(r.semana), total: Number(r.total) }));

const filas = await em.getConnection().execute<Array<Record<string, unknown>>>(
  `select t.* from task t
    where t.id in (select task_id from comment group by task_id having count(*) > ?)`,
  [10], 'all',
);
// De fila plana a entidad: hidrata, convierte tipos y registra en el Identity Map
const tasks: Task[] = filas.map((fila) => em.map(Task, fila));
tasks[0].status = 'done';      // ya es una entidad gestionada: el flush la persistirá
await em.flush();

[query] select "t0".* from "task" as "t0" where "t0"."project_id" = 7 [took 3 ms]
[query] select "u0".* from "user" as "u0" where "u0"."id" = 12 [took 1 ms]
[query] select "u0".* from "user" as "u0" where "u0"."id" = 8  [took 1 ms]
[query] select "u0".* from "user" as "u0" where "u0"."id" = 12 [took 1 ms]   -- ¡repetida!
[query] select "u0".* from "user" as "u0" where "u0"."id" = 31 [took 1 ms]
-- … 196 líneas más, casi idénticas, con el id como único cambio

import { LoadStrategy } from '@mikro-orm/core';
const tasks = await em.find(Task, { project: 7 },
  { populate: ['assignee', 'tags'], strategy: LoadStrategy.SELECT_IN });

select "t0".* from "task" as "t0" where "t0"."project_id" = $1;
select "u0".* from "user" as "u0" where "u0"."id" in ($1, $2, $3, $4);
select "t1".*, "t0"."task_id" as "fk__task_id" from "tag" as "t1"
  inner join "task_tags" as "t0" on "t1"."id" = "t0"."tag_id" where "t0"."task_id" in ($1, $2, /* … */);

const tasks = await em.find(Task, { project: 7 },
  { populate: ['assignee', 'project'], strategy: LoadStrategy.JOINED });

select "t0".*,
       "a1"."id" as "a1__id", "a1"."name" as "a1__name", "a1"."email" as "a1__email",
       "p2"."id" as "p2__id", "p2"."name" as "p2__name"
  from "task" as "t0"
  left join "user"    as "a1" on "t0"."assignee_id" = "a1"."id"
  left join "project" as "p2" on "t0"."project_id"  = "p2"."id"
 where "t0"."project_id" = $1;

const tasks = await em.createQueryBuilder(Task, 't')
  .select('t.*')
  .leftJoinAndSelect('t.assignee', 'u')
  .leftJoinAndSelect('t.comments', 'c', { 'c.createdAt': { $gte: hace7Dias } })
  .where({ project: 7 })
  .getResultList();

// Opción a) columna desnormalizada, actualizada por un hook o un disparador
@Property({ default: 0 }) commentCount!: number;
const tasks = await em.find(Task, { project: 7 });   // commentCount ya viene: 1 consulta
// Opción b) subconsulta en el SELECT si el contador no se puede mantener (16.6.5)
// Opción c) loadCount() cuando solo necesitas el número de UNA colección concreta
const n = await tasks[0].comments.loadCount();       // select count(*) … where task_id = ?

describe('GET /api/tasks · presupuesto de consultas', () => {
  let queries: string[];
  beforeEach(async () => {
    queries = [];
    // MikroORM acepta un logger propio: aquí lo usamos como contador
    orm = await MikroORM.init({ ...testConfig, debug: ['query'], logger: (msg) => queries.push(msg) });
    await seed(orm, { tasks: 50, tagsPerTask: 3, comments: 5 });   // datos suficientes para que el N+1 se note
  });
  it('resuelve el listado con un número CONSTANTE de consultas', async () => {
    const res = await request(app.getHttpServer()).get('/api/tasks?limit=50').expect(200);
    expect(res.body.items).toHaveLength(50);
    // 1 lista + 1 count + 1 assignee + 1 tags = 4. Importa menos el número exacto
    // que el hecho de que NO crezca con el número de filas.
    expect(queries.filter((q) => q.includes('select'))).toHaveLength(4);
  });
});

const size = Math.min(q.size ?? 20, 100);          // techo obligatorio: nunca confíes en el cliente
const page = Math.max(q.page ?? 1, 1);
const [items, total] = await em.findAndCount(Task, { project: projectId }, {
  limit: size, offset: (page - 1) * size,
  orderBy: [{ createdAt: 'desc' }, { id: 'desc' }],   // el desempate por id es obligatorio
  populate: ['assignee'],
});
return { items, total, page, size, pages: Math.ceil(total / size) };

select "t0".* from "task" as "t0" where "t0"."project_id" = $1
 order by "t0"."created_at" desc, "t0"."id" desc limit 20 offset 9980;
select count(*) as "count" from "task" as "t0" where "t0"."project_id" = $1;

interface Cursor { createdAt: Date; id: number }
async function pagina(em: EntityManager, projectId: number, size: number, after?: Cursor) {
  // (createdAt, id) < (cursor.createdAt, cursor.id) en orden descendente:
  // o la fecha es estrictamente menor, o es igual y el id es menor.
  const keyset: FilterQuery<Task> | undefined = after && {
    $or: [
      { createdAt: { $lt: after.createdAt } },
      { createdAt: after.createdAt, id: { $lt: after.id } },
    ],
  };
  const items = await em.find(Task, { project: projectId, ...(keyset ?? {}) }, {
    orderBy: [{ createdAt: 'desc' }, { id: 'desc' }],   // DEBE coincidir con la condición
    limit: size + 1,                                    // una fila extra: ¿hay página siguiente?
    populate: ['assignee'],
  });
  const hasNext = items.length > size;
  const page = hasNext ? items.slice(0, size) : items;
  const last = page.at(-1);
  return { items: page, hasNext, nextCursor: last ? encode({ createdAt: last.createdAt, id: last.id }) : null };
}

select "t0".* from "task" as "t0"
 where "t0"."project_id" = $1
   and ("t0"."created_at" < $2 or ("t0"."created_at" = $2 and "t0"."id" < $3))
 order by "t0"."created_at" desc, "t0"."id" desc limit 21;
-- Con un índice sobre (project_id, created_at desc, id desc) el motor se posiciona
-- directamente y lee 21 filas, sea la página 1 o la 5.000.

const cursor = await em.findByCursor(Task, { project: projectId }, {
  first: 20,                 // hacia delante (last + before para ir hacia atrás)
  after: q.after,            // cursor opaco recibido del cliente, o undefined en la primera página
  orderBy: [{ createdAt: 'desc' }, { id: 'desc' }],   // obligatorio y con desempate único
  populate: ['assignee'],
});
return {
  items: cursor.items,             // las entidades de la página
  total: cursor.totalCount,        // total exacto (implica un count: úsalo solo si lo necesitas)
  endCursor: cursor.endCursor,     // cadena opaca para la siguiente petición
  hasNextPage: cursor.hasNextPage,
};

/** Paginación por desplazamiento: cuando el cliente necesita saltar a una página concreta. */
export interface OffsetPage<T> {
  items: T[];
  meta: { total: number; page: number; size: number; pages: number };
}
/** Paginación por cursor: para listas largas, infinitas o sincronización incremental. */
export interface CursorPage<T> {
  items: T[];
  meta: { endCursor: string | null; hasNextPage: boolean; total?: number };
}

import { CursorPage } from '@acme/shared';
private readonly cursor = signal<string | null>(null);
readonly items = signal<TaskListDto[]>([]);
cargarMas(): void {
  const params = { limit: 20, ...(this.cursor() ? { after: this.cursor()! } : {}) };
  this.http.get<CursorPage<TaskListDto>>('/api/tasks', { params }).subscribe((page) => {
    this.items.update((actual) => [...actual, ...page.items]);   // nueva referencia: la vista reacciona
    this.cursor.set(page.meta.hasNextPage ? page.meta.endCursor : null);
  });
}

// fields: solo estas columnas viajan. Admite rutas de relación.
const filas = await em.find(Task, { project: 7 }, {
  fields: ['id', 'title', 'status', 'assignee.name'],
  orderBy: { id: 'asc' },
});
// → select "t0"."id", "t0"."title", "t0"."status", "t0"."assignee_id", "a1"."name" …
// exclude: el complemento, cuando lo que sobra es una columna grande
const sinDescripcion = await em.find(Task, { project: 7 }, { exclude: ['description', 'meta'] });

// Exportar 500.000 filas: el Identity Map las retendría TODAS en memoria hasta el final
// de la petición, con la instantánea original de cada una. Fuga de memoria garantizada.
for (let offset = 0; ; offset += 5_000) {
  const lote = await em.find(Task, {}, {
    fields: ['id', 'title', 'status'],
    limit: 5_000, offset,
    disableIdentityMap: true,        // no se registran en el contexto
    orderBy: { id: 'asc' },
  });
  if (!lote.length) break;
  escribirCsv(lote);
}
// Alternativa aún mejor si el driver lo soporta: una consulta con cursor de servidor
// (streaming) para no cargar ni un lote completo en memoria.

import { serialize, wrap } from '@mikro-orm/core';
// wrap(entity) da acceso al envoltorio interno de la entidad
const plano = wrap(task).toObject();        // objeto plano, según los metadatos de serialización
const json  = wrap(task).toJSON();          // lo que usaría JSON.stringify
// serialize() da control fino y funciona también con arrays
const dto = serialize(task, {
  populate: ['assignee', 'tags'],           // qué relaciones incluir
  exclude: ['description', 'assignee.email'],  // qué quitar, con rutas anidadas
  forceObject: true,                        // relaciones SIEMPRE como objeto, nunca como id suelto
  skipNull: true,
});

@Entity()
export class User {
  @PrimaryKey() id!: number;
  @Property() email!: string;
  // hidden: nunca aparece en toObject()/toJSON(). Red de seguridad, NO la única defensa.
  @Property({ hidden: true }) passwordHash!: string;
  // persist: false → propiedad calculada que no existe como columna
  @Property({ persist: false }) get initials(): string { return this.name.slice(0, 2).toUpperCase(); }
  // serializer/serializedName: transforma el valor o renombra la clave en la salida
  @Property({ serializer: (v: Date) => v.toISOString().slice(0, 10), serializedName: 'alta' })
  createdAt!: Date;
}

export class TaskListDto {
  id!: number; title!: string; status!: TaskStatus; assignee!: { id: number; name: string } | null; tags!: string[];
  // El tipo Loaded exige en COMPILACIÓN que las relaciones estén cargadas:
  // es imposible construir este DTO provocando un N+1 sin que el compilador se queje.
  static from(t: Loaded<Task, 'assignee' | 'tags'>): TaskListDto {
    return {
      id: t.id, title: t.title, status: t.status,
      assignee: t.assignee ? { id: t.assignee.id, name: t.assignee.name } : null,
      tags: t.tags.getItems().map((g) => g.name),
    };
  }
}

// mikro-orm.config.ts
resultCache: { expiration: 5_000 /* ms por defecto */ /*, adapter: RedisCacheAdapter, options: {…} */ },
// 1 · activar con el TTL global
await em.find(Task, { status: 'todo' }, { cache: true });
// 2 · TTL explícito para esta consulta
await em.find(Task, { status: 'todo' }, { cache: 30_000 });
// 3 · clave explícita: la única forma de poder INVALIDARLA después
await em.find(Task, { status: 'todo' }, { cache: ['tasks:todo', 60_000] });
// invalidación al escribir
await em.flush();
await em.clearCache('tasks:todo');

export default defineConfig({
  // Log de consultas. En desarrollo, siempre. En producción, nunca 'query-params': imprime datos personales.
  debug: process.env.NODE_ENV === 'development' ? ['query', 'query-params'] : false,
  // Registra en WARN cualquier consulta que tarde más de 300 ms: tu detector de problemas en producción
  logger: (msg) => logger.debug(msg),
  // (el nombre y la forma de las opciones de umbral han cambiado entre versiones:
  //  consulta LoggerOptions en la documentación de la tuya antes de fijarlas)
});

const qb = em.createQueryBuilder(Task, 't').select('t.*').where({ status: 'todo' }).limit(20);
// getFormattedQuery() incrusta los valores: imprescindible para EXPLAIN, prohibido para ejecutar
// consultas normales (es exactamente el patrón de la inyección SQL).
const plan = await em.getConnection()
  .execute<Array<Record<string, string>>>(`explain (analyze, buffers) ${qb.getFormattedQuery()}`, [], 'all');
console.log(plan.map((r) => Object.values(r)[0]).join('\n'));

Limit  (cost=0.00..1842.31 rows=20 width=214) (actual time=0.019..412.884 rows=20 loops=1)
  ->  Seq Scan on task t  (cost=0.00..184231.00 rows=2001 width=214)
                          (actual time=0.018..412.870 rows=20 loops=1)
        Filter: ((status)::text = 'todo'::text)
        Rows Removed by Filter: 1998043            -- ← el síntoma: descartó 2 millones de filas
Planning Time: 0.104 ms
Execution Time: 412.912 ms                          -- ← 412 ms para devolver 20 filas
-- Diagnóstico: Seq Scan + "Rows Removed by Filter" enorme = falta un índice sobre status.
-- Tras crear el índice: Index Scan, "Rows Removed" ≈ 0 y Execution Time en el orden de 1 ms.