22. Ejercicios, retos y proyecto integrador

export const PRIORIDADES = ['baja', 'media', 'alta'] as const;
export type Prioridad = (typeof PRIORIDADES)[number];   // 'baja' | 'media' | 'alta'

export interface Tarea {
  id: number;
  titulo: string;
  prioridad: Prioridad;
  etiquetas: string[];
  vence?: string;
}

// Guarda auxiliar: convierte unknown en un diccionario indexable SIN usar `as`.
function esObjeto(x: unknown): x is Record<string, unknown> {
  return typeof x === 'object' && x !== null && !Array.isArray(x);
}

function esPrioridad(x: unknown): x is Prioridad {
  // El ensanchamiento a readonly string[] es necesario porque includes() de una
  // tupla `as const` solo acepta miembros de la propia unión.
  return typeof x === 'string' && (PRIORIDADES as readonly string[]).includes(x);
}

function esArrayDeStrings(x: unknown): x is string[] {
  return Array.isArray(x) && x.every((e) => typeof e === 'string');
}

export function esTarea(x: unknown): x is Tarea {
  if (!esObjeto(x)) return false;                       // descarta null, arrays y primitivos
  if (typeof x['id'] !== 'number' || !Number.isInteger(x['id'])) return false;
  if (typeof x['titulo'] !== 'string' || x['titulo'].trim() === '') return false;
  if (!esPrioridad(x['prioridad'])) return false;
  if (!esArrayDeStrings(x['etiquetas'])) return false;
  if (x['vence'] !== undefined && typeof x['vence'] !== 'string') return false;
  return true;
}

Por qué así. Tres detalles marcan la diferencia. Primero, typeof null === 'object' es un fallo histórico de JavaScript: sin la comprobación x !== null la guarda acepta null. Segundo, un array también es 'object', y sin !Array.isArray(x) la guarda aceptaría []. Tercero, el campo opcional se valida contra undefined, no con 'vence' in x: un objeto puede traer vence: undefined explícito y sigue siendo válido.

Trampa del predicado. x is Tarea es una promesa que tú le haces al compilador: si la implementación miente, TypeScript no te avisará nunca. Por eso las guardas escritas a mano son el punto más peligroso de una base de código tipada, y por eso en producción conviene delegar en un validador con esquema (Zod, class-validator, TypeBox) que genere el tipo y la validación de una sola fuente. Ver capítulo 10.

export function indexarPor<T, K extends keyof T>(items: readonly T[], clave: K): Map<T[K], T> {
  const mapa = new Map<T[K], T>();
  for (const item of items) mapa.set(item[clave], item);
  return mapa;
}

export function agruparPor<T, K extends PropertyKey>(
  items: readonly T[],
  clave: (item: T) => K,
): Record<K, T[]> {
  // Partial + aserción controlada: el objeto se llena por completo antes de devolverse,
  // pero el compilador no puede saberlo porque K es un tipo abierto.
  const salida: Partial<Record<K, T[]>> = {};
  for (const item of items) {
    const k = clave(item);
    (salida[k] ??= []).push(item);            // ??= crea el array solo la primera vez
  }
  return salida as Record<K, T[]>;
}

La clave del ejercicio es K extends keyof T. Sin la restricción, clave sería string y item[clave] no compilaría; con ella, TypeScript propaga el tipo concreto del literal 'id' y deduce T[K] = number automáticamente. Es exactamente el mecanismo que usan Pick, Omit y los selects tipados de MikroORM.

Sobre el as final. Es uno de los pocos casos donde una aserción es legítima: el invariante («al terminar el bucle todas las claves producidas están presentes») es cierto pero no expresable en el sistema de tipos. Lo correcto es aislarlo en una línea y documentarlo, no esparcir as por toda la función. Si quieres evitarlo del todo, devuelve un Map<K, T[]>: es más honesto y además admite claves que no son cadenas.

export interface Usuario {
  id: string;
  email: string;
  password: string;
  nombre: string;
  rol: 'admin' | 'miembro';
  creadoEn: Date;
}

/** Lo que el cliente puede enviar al crear: ni id ni fecha, que los pone el servidor. */
export type CrearUsuarioDto = Omit<Usuario, 'id' | 'creadoEn'>;

/** Distribuye sobre cada clave: exige exactamente una obligatoria y el resto opcionales. */
export type AlMenosUno<T, K extends keyof T = keyof T> =
  K extends unknown ? Required<Pick<T, K>> & Partial<Omit<T, K>> : never;

/** Actualización parcial: nunca se cambian id, fecha ni contraseña por esta vía. */
export type ActualizarUsuarioDto = AlMenosUno<Omit<Usuario, 'id' | 'creadoEn' | 'password'>>;

/** Vista pública: la contraseña jamás sale del servidor. */
export type UsuarioPublico = Omit<Usuario, 'password'>;

/** Extra: el mismo tipo pero serializable a JSON (Date se convierte en string ISO). */
export type Serializado<T> = {
  [K in keyof T]: T[K] extends Date ? string : T[K] extends object ? Serializado<T[K]> : T[K];
};
export type UsuarioPublicoJson = Serializado<UsuarioPublico>;   // creadoEn: string

Cómo funciona AlMenosUno. Cuando el parámetro de un tipo condicional es un tipo genérico desnudo (K extends unknown ? ... : ...), TypeScript distribuye la condición sobre cada miembro de la unión. Con K = 'email' | 'nombre' | 'rol' el resultado es la unión de tres objetos: uno con email obligatorio, otro con nombre obligatorio y otro con rol obligatorio. El objeto vacío no encaja en ninguno, que es justo lo que queremos.

Por qué importa en producción. El caso d —un PATCH con cuerpo vacío— es un error real que suele llegar hasta la base de datos y ejecutar un UPDATE sin columnas o, peor, sobrescribir campos con undefined. Codificar la regla en el tipo la hace imposible en el cliente TypeScript; recuerda que en el servidor sigue siendo obligatorio validarla en runtime, porque los tipos se borran al compilar.

/** Recursivo: desenvuelve promesas anidadas hasta llegar al valor real. */
export type Desempaqueta<T> = T extends Promise<infer U> ? Desempaqueta<U> : T;

/** readonly (infer U)[] cubre tanto T[] como ReadonlyArray<T>. */
export type ElementoDe<T> = T extends readonly (infer U)[] ? U : never;

/** Se usa unknown[] en los parámetros para aceptar cualquier aridad. */
export type RetornoAsync<F> =
  F extends (...args: never[]) => Promise<infer R> ? R : never;

/** El resto de parámetros se descarta con ...never[]. */
export type PrimerParametro<F> =
  F extends (primero: infer A, ...resto: never[]) => unknown ? A : never;

/** Tipo mapeado con `as`: las claves que no cumplen se reescriben a never y desaparecen. */
export type ClavesDeTipo<T, V> = {
  [K in keyof T as T[K] extends V ? K : never]: T[K];
}[keyof T] extends never ? never : keyof {
  [K in keyof T as T[K] extends V ? K : never]: T[K];
};

/** Versión más legible y equivalente del anterior. */
export type ClavesConTipo<T, V> = {
  [K in keyof T]-?: T[K] extends V ? K : never;
}[keyof T];

Qué hace infer. Declara una variable de tipo dentro de la condición y la vincula por unificación estructural: «si T encaja con la forma Promise<algo>, llama U a ese algo». Es el equivalente en el mundo de los tipos al pattern matching de lenguajes funcionales.

Por qué never[] y no any[] en los parámetros. Los parámetros de función son contravariantes: una firma que acepta never[] es supertipo de cualquier otra, así que el patrón encaja con cualquier función sin necesidad de any. Con any[] también funciona, pero introduce any en tu base de código y desactiva reglas de ESLint razonables.

Dónde lo verás. ReturnType, Parameters, Awaited y InstanceType de la librería estándar están escritos exactamente así. Angular usa el mismo patrón para deducir el tipo de un Signal<T> y MikroORM para deducir el tipo de una relación poblada.

/** Reasignación de claves con `as` + Capitalize (tipo intrínseco del compilador). */
export type Manejadores<T> = {
  [K in keyof T & string as `on${Capitalize<K>}`]: (payload: T[K]) => void;
};

type Hoja = string | number | boolean | Date | null | undefined | ((...a: never[]) => unknown);

/** Recorre el objeto y concatena la clave con las rutas de su valor. */
export type RutasDe<T> = T extends Hoja
  ? never
  : {
      [K in keyof T & string]: T[K] extends Hoja
        ? K
        : K | `${K}.${Extract<RutasDe<T[K]>, string>}`;
    }[keyof T & string];

/** Camino inverso: dada una ruta, obtener el tipo del valor. */
export type ValorEn<T, R extends string> =
  R extends `${infer Cabeza}.${infer Resto}`
    ? Cabeza extends keyof T
      ? ValorEn<T[Cabeza], Resto>
      : never
    : R extends keyof T
      ? T[R]
      : never;

/** Función real que aprovecha los tipos: acceso seguro por ruta. */
export function leerRuta<T extends object, R extends Extract<RutasDe<T>, string>>(
  objeto: T,
  ruta: R,
): ValorEn<T, R> {
  let actual: unknown = objeto;
  for (const parte of ruta.split('.')) {
    actual = (actual as Record<string, unknown>)[parte];
  }
  return actual as ValorEn<T, R>;
}

Los tres ingredientes. (1) keyof T & string filtra las claves numéricas y de tipo símbolo, que no se pueden interpolar en una plantilla. (2) La cláusula as de un tipo mapeado permite renombrar claves; si la expresión resulta never, la clave desaparece. (3) Capitalize, Uppercase, Lowercase y Uncapitalize son tipos intrínsecos implementados en el compilador, no en lib.d.ts.

Límites que debes conocer. RutasDe sobre un tipo con recursión infinita (interface Nodo { hijos: Nodo[] }) agota el limitador de profundidad del compilador y produce el error «Type instantiation is excessively deep». La solución habitual es añadir un contador de profundidad como parámetro de tipo. Además, este RutasDe trata los arrays como hojas; extenderlo a índices numéricos ('items.0.nombre') es un buen ejercicio adicional.

export type DeepReadonly<T> =
  T extends (...args: never[]) => unknown ? T                       // funciones: tal cual
  : T extends Date ? T                                              // valores «atómicos»
  : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<DeepReadonly<K>, DeepReadonly<V>>
  : T extends ReadonlySet<infer U> ? ReadonlySet<DeepReadonly<U>>
  : T extends readonly (infer U)[] ? ReadonlyArray<DeepReadonly<U>>
  : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
  : T;                                                              // primitivos

/** La versión de runtime: Object.freeze es superficial, esta no. */
export function congelarProfundo<T>(valor: T, vistos = new WeakSet<object>()): DeepReadonly<T> {
  if (valor === null || typeof valor !== 'object') return valor as DeepReadonly<T>;
  if (vistos.has(valor)) return valor as DeepReadonly<T>;           // corta ciclos
  vistos.add(valor);
  for (const clave of Reflect.ownKeys(valor)) {
    congelarProfundo((valor as Record<PropertyKey, unknown>)[clave], vistos);
  }
  return Object.freeze(valor) as DeepReadonly<T>;
}

El orden de las ramas importa. Las funciones y Date van primero porque también son object: si la rama genérica los capturase, obtendrías un objeto con las propiedades de Date en solo lectura pero sin sus métodos utilizables. Del mismo modo, ReadonlyMap se comprueba antes que object porque un Map con propiedades en solo lectura seguiría permitiendo set().

El WeakSet no es adorno. Sin él, un objeto con una referencia circular (a.hijo.padre === a, habitual en entidades de MikroORM con relaciones bidireccionales) provoca recursión infinita y desbordamiento de pila.

Aplicación real. Es el tipo que usarías para exponer el estado de un store de señales: el componente puede leer todo el árbol pero no mutarlo, y las mutaciones se canalizan por métodos que crean referencias nuevas, que es lo que la detección de cambios de Angular necesita.

export type Result<T, E = Error> =
  | { readonly ok: true; readonly valor: T }
  | { readonly ok: false; readonly error: E };

export const ok = <T>(valor: T): Result<T, never> => ({ ok: true, valor });
export const fallo = <E>(error: E): Result<never, E> => ({ ok: false, error });

export function mapear<T, U, E>(r: Result<T, E>, f: (t: T) => U): Result<U, E> {
  return r.ok ? ok(f(r.valor)) : r;           // el caso de error se propaga sin tocarlo
}

export function encadenar<T, U, E, F>(
  r: Result<T, E>,
  f: (t: T) => Result<U, F>,
): Result<U, E | F> {
  return r.ok ? f(r.valor) : r;               // la unión de errores crece: E | F
}

export function desempaquetarO<T, E>(r: Result<T, E>, porDefecto: T): T {
  return r.ok ? r.valor : porDefecto;
}

export function intentar<T>(fn: () => T): Result<T, Error> {
  try {
    return ok(fn());
  } catch (e) {
    return fallo(e instanceof Error ? e : new Error(String(e)));
  }
}

export async function intentarAsync<T>(p: Promise<T>): Promise<Result<T, Error>> {
  try {
    return ok(await p);
  } catch (e) {
    return fallo(e instanceof Error ? e : new Error(String(e)));
  }
}

type ErrorValidacion =
  | { tipo: 'email-invalido'; valor: string }
  | { tipo: 'password-corta'; minimo: number }
  | { tipo: 'email-duplicado'; email: string };

const validarEmail = (e: string): Result<string, ErrorValidacion> =>
  /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(e) ? ok(e) : fallo({ tipo: 'email-invalido', valor: e });

const validarPassword = (p: string): Result<string, ErrorValidacion> =>
  p.length >= 12 ? ok(p) : fallo({ tipo: 'password-corta', minimo: 12 });

export function registrar(email: string, password: string): Result<{ email: string }, ErrorValidacion> {
  return encadenar(validarEmail(email), (e) =>
    mapear(validarPassword(password), () => ({ email: e })),
  );
}

const r = registrar('ana@ejemplo.com', '123');
if (r.ok) {
  console.log(r.valor.email);       // aquí `error` no existe
} else {
  // El switch es exhaustivo: si añades un tipo de error, el compilador te obliga a tratarlo.
  switch (r.error.tipo) {
    case 'email-invalido':  console.error('Email inválido:', r.error.valor); break;
    case 'password-corta':  console.error('Mínimo', r.error.minimo); break;
    case 'email-duplicado': console.error('Ya existe', r.error.email); break;
  }
}

Por qué esto y no excepciones. Una excepción es invisible en la firma: nada te obliga a capturarla y nada te dice qué puede lanzarse. Con Result, el fallo forma parte del tipo de retorno y el compilador impide leer valor sin comprobar antes ok. Es el mismo modelo de Rust y de Go, y encaja perfectamente con las uniones discriminadas de TypeScript.

Cuándo NO usarlo. Para errores inesperados (fallo de red, base de datos caída, error de programación) las excepciones siguen siendo lo correcto: quieres que suban hasta el filtro global y se registren. La regla práctica es: Result para errores de dominio que forman parte del contrato («el email ya existe»), excepciones para lo que no debería pasar nunca.

export function tuberia<A, B>(ab: (a: A) => B): (a: A) => B;
export function tuberia<A, B, C>(ab: (a: A) => B, bc: (b: B) => C): (a: A) => C;
export function tuberia<A, B, C, D>(ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D): (a: A) => D;
export function tuberia<A, B, C, D, E>(
  ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E,
): (a: A) => E;
// Implementación (no visible desde fuera): una sola reducción.
export function tuberia(...fns: Array<(x: unknown) => unknown>) {
  return (entrada: unknown) => fns.reduce((acc, f) => f(acc), entrada);
}

type Rebotada<F extends (...args: never[]) => void> = ((...args: Parameters<F>) => void) & {
  cancelar(): void;
  ejecutarYa(...args: Parameters<F>): void;
};

export function rebotar<F extends (...args: never[]) => void>(fn: F, ms: number): Rebotada<F> {
  let temporizador: ReturnType<typeof setTimeout> | undefined;

  const envoltorio = (...args: Parameters<F>) => {
    if (temporizador !== undefined) clearTimeout(temporizador);
    temporizador = setTimeout(() => {
      temporizador = undefined;
      fn(...args);
    }, ms);
  };

  envoltorio.cancelar = () => {
    if (temporizador !== undefined) clearTimeout(temporizador);
    temporizador = undefined;
  };
  envoltorio.ejecutarYa = (...args: Parameters<F>) => {
    envoltorio.cancelar();
    fn(...args);
  };

  return envoltorio;
}

Por qué sobrecargas y no un tipo variádico. Se puede escribir tuberia con tuplas variádicas y tipos recursivos, pero el mensaje de error que produce cuando dos funciones no encajan es ilegible. Las sobrecargas dan errores claros («no se puede asignar string a number en el argumento 3») y son lo que hacen RxJS y Redux en su código real. Regla: optimiza el sistema de tipos para el mensaje de error, no para la elegancia.

El detalle de ReturnType<typeof setTimeout>. En el navegador setTimeout devuelve number y en Node un objeto Timeout. Escribir let temporizador: number compila en un entorno y falla en el otro; esta forma funciona en los dos y es lo correcto en código isomorfo.

interface Entrada { expira: number; valor: unknown }

/**
 * Versión con `experimentalDecorators: true`, que es la que usan NestJS y Angular.
 * La caché vive en un WeakMap indexado por instancia: cuando la instancia se recolecta,
 * su caché desaparece con ella y no hay fuga de memoria.
 */
export function Cachear(ttlMs = 5_000): MethodDecorator {
  const porInstancia = new WeakMap<object, Map<string, Entrada>>();

  return (_objetivo, _clave, descriptor: PropertyDescriptor) => {
    const original = descriptor.value as (...args: unknown[]) => unknown;

    descriptor.value = function (this: object, ...args: unknown[]) {
      let cache = porInstancia.get(this);
      if (!cache) { cache = new Map(); porInstancia.set(this, cache); }

      const clave = JSON.stringify(args);
      const ahora = Date.now();
      const entrada = cache.get(clave);
      if (entrada && entrada.expira > ahora) return entrada.valor;

      const valor = original.apply(this, args);
      cache.set(clave, { expira: ahora + ttlMs, valor });

      // Si es asíncrono, guardamos la promesa (eso resuelve la estampida)
      // pero la retiramos si acaba en error: no se cachean los fallos.
      if (valor instanceof Promise) {
        valor.catch(() => { cache.delete(clave); });
      }
      return valor;
    };

    return descriptor;
  };
}

export function Cachear2(ttlMs = 5_000) {
  const porInstancia = new WeakMap<object, Map<string, Entrada>>();

  return function <This extends object, Args extends unknown[], Ret>(
    metodo: (this: This, ...args: Args) => Ret,
    _contexto: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Ret>,
  ) {
    return function (this: This, ...args: Args): Ret {
      let cache = porInstancia.get(this);
      if (!cache) { cache = new Map(); porInstancia.set(this, cache); }
      const clave = JSON.stringify(args);
      const entrada = cache.get(clave);
      if (entrada && entrada.expira > Date.now()) return entrada.valor as Ret;

      const valor = metodo.call(this, ...args);
      cache.set(clave, { expira: Date.now() + ttlMs, valor });
      if (valor instanceof Promise) valor.catch(() => { cache.delete(clave); });
      return valor;
    };
  };
}

Las cuatro trampas del ejercicio. (1) Usar una función flecha para descriptor.value rompe this: hay que usar function y apply. (2) Una caché en el closure del decorador es compartida por todas las instancias de la clase, lo que en un servicio con estado de usuario es una filtración de datos entre peticiones; de ahí el WeakMap por instancia. (3) Guardar la promesa y no el valor resuelto es lo que evita la estampida: las dos llamadas simultáneas reciben el mismo objeto Promise. (4) Sin el catch que limpia, un fallo transitorio de red queda cacheado durante todo el TTL.

Limitación de JSON.stringify como clave. No distingue el orden de las propiedades de un objeto, no serializa undefined, Map, Set ni BigInt, y falla con referencias circulares. En producción se usa una función de clave inyectable (@Cachear({ ttlMs, clave: (id) => \`tarea:\${id}\` })) o una caché externa como Redis, que es lo que verás en el ejercicio NEST-10.

import { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';

export interface ContextoPeticion {
  correlacionId: string;
  usuarioId?: string;
  inicio: number;
}

const almacen = new AsyncLocalStorage<ContextoPeticion>();

export function ejecutarEnContexto<T>(ctx: ContextoPeticion, fn: () => T): T {
  return almacen.run(ctx, fn);
}

export function contextoActual(): ContextoPeticion | undefined {
  return almacen.getStore();
}

export function registrar(mensaje: string, extra: Record<string, unknown> = {}): void {
  const ctx = contextoActual();
  const linea = {
    ts: new Date().toISOString(),
    correlacionId: ctx?.correlacionId ?? 'sin-contexto',
    usuarioId: ctx?.usuarioId,
    msDesdeInicio: ctx ? Date.now() - ctx.inicio : undefined,
    mensaje,
    ...extra,
  };
  console.log(JSON.stringify(linea));
}

/** Middleware de Express: crea el contexto y lo mantiene durante toda la petición. */
export function middlewareCorrelacion(
  req: { header(n: string): string | undefined },
  res: { setHeader(n: string, v: string): void },
  next: () => void,
): void {
  const correlacionId = req.header('x-correlation-id') ?? randomUUID();
  res.setHeader('x-correlation-id', correlacionId);
  ejecutarEnContexto({ correlacionId, inicio: Date.now() }, next);
}

import { setTimeout as dormir } from 'node:timers/promises';
import { expect, it } from 'vitest';
import { contextoActual, ejecutarEnContexto } from './ts-10-contexto.js';

const trabajo = async (etiqueta: string) => {
  await dormir(Math.random() * 20);
  await Promise.all([dormir(5), dormir(1)]);
  return `${etiqueta}:${contextoActual()?.correlacionId}`;
};

it('no mezcla contextos entre ejecuciones concurrentes', async () => {
  const [a, b] = await Promise.all([
    ejecutarEnContexto({ correlacionId: 'A', inicio: Date.now() }, () => trabajo('a')),
    ejecutarEnContexto({ correlacionId: 'B', inicio: Date.now() }, () => trabajo('b')),
  ]);
  expect(a).toBe('a:A');
  expect(b).toBe('b:B');
});

Qué está pasando por dentro. AsyncLocalStorage se apoya en async_hooks, el mecanismo por el que Node etiqueta cada recurso asíncrono con el identificador del contexto que lo creó. Cuando una continuación se ejecuta, Node restaura el store asociado. Es el equivalente al ThreadLocal de Java, pero para el modelo de un solo hilo con muchas tareas.

Dónde falla. El contexto se pierde si el trabajo sale del árbol asíncrono actual: colas propias que guardan callbacks en un array y los ejecutan después, pools de conexiones que reutilizan recursos creados en otra petición, o código que usa EventEmitter con listeners registrados fuera del contexto. En esos casos hay que capturar el store explícitamente y volver a entrar con almacen.run().

En NestJS este patrón está detrás de @mikro-orm/nestjs (que crea un EntityManager por petición sin pasarlo por parámetros), de nestjs-cls y de la mayoría de los sistemas de tracing. Es la respuesta correcta a «¿cómo consigo el usuario actual en una capa profunda sin ensuciar todas las firmas?».

export async function mapaConcurrente<T, R>(
  items: readonly T[],
  limite: number,
  fn: (item: T, indice: number) => Promise<R>,
): Promise<R[]> {
  if (!Number.isInteger(limite) || limite < 1) {
    throw new RangeError('El límite de concurrencia debe ser un entero >= 1');
  }
  const resultados = new Array<R>(items.length);
  let siguiente = 0;                                  // índice compartido, sin carrera: un solo hilo

  // Cada «trabajador» toma el siguiente índice libre hasta que se agotan.
  // Esto mantiene el pool SIEMPRE lleno, a diferencia de trocear en tandas.
  const trabajador = async (): Promise<void> => {
    while (siguiente < items.length) {
      const i = siguiente++;
      resultados[i] = await fn(items[i] as T, i);
    }
  };

  const trabajadores = Array.from({ length: Math.min(limite, items.length) }, trabajador);
  await Promise.all(trabajadores);
  return resultados;
}

/** Variante tolerante a fallos: nunca rechaza, informa por elemento. */
export async function mapaConcurrenteSettled<T, R>(
  items: readonly T[],
  limite: number,
  fn: (item: T, indice: number) => Promise<R>,
): Promise<Array<{ ok: true; valor: R } | { ok: false; error: unknown }>> {
  return mapaConcurrente(items, limite, async (item, i) => {
    try {
      return { ok: true as const, valor: await fn(item, i) };
    } catch (error) {
      return { ok: false as const, error };
    }
  });
}

El error clásico es trocear en tandas con slice y hacer un Promise.all por tanda. Funciona, pero es hasta un 40 % más lento: cada tanda espera a su elemento más lento antes de empezar la siguiente, así que el pool se vacía continuamente. El patrón de «N trabajadores compitiendo por un índice compartido» mantiene siempre N tareas en vuelo.

Por qué no hay condición de carrera en siguiente++: JavaScript es de un solo hilo y el incremento es síncrono, así que no puede interrumpirse. Este mismo código en Java o Go necesitaría un mutex o un contador atómico.

Nota sobre el fallo rápido. mapaConcurrente rechaza en cuanto una tarea falla, pero las tareas ya lanzadas siguen ejecutándose: Promise.all no cancela nada. Si necesitas cancelación real, pasa un AbortSignal a fn y dispáralo en el catch. Esto es exactamente lo que ocurre con las peticiones HTTP y por lo que hace falta HttpClient + switchMap en Angular, que sí aborta la petición anterior.

import { setTimeout as dormir } from 'node:timers/promises';

export class ErrorHttp extends Error {
  constructor(readonly estado: number, mensaje = `HTTP ${estado}`) {
    super(mensaje);
    this.name = 'ErrorHttp';
  }
}

export interface OpcionesReintento {
  intentos?: number;
  baseMs?: number;
  maxMs?: number;
  factor?: number;
  senal?: AbortSignal;
  reintentable?: (error: unknown) => boolean;
  alReintentar?: (error: unknown, intento: number, esperaMs: number) => void;
}

const REINTENTABLE_POR_DEFECTO = (e: unknown): boolean =>
  e instanceof ErrorHttp ? e.estado >= 500 || e.estado === 429 : true;   // errores de red: sí

export async function conReintentos<T>(
  fn: (senal?: AbortSignal) => Promise<T>,
  opciones: OpcionesReintento = {},
): Promise<T> {
  const {
    intentos = 3, baseMs = 200, maxMs = 10_000, factor = 2,
    senal, reintentable = REINTENTABLE_POR_DEFECTO, alReintentar,
  } = opciones;

  let ultimoError: unknown;

  for (let intento = 0; intento < intentos; intento++) {
    senal?.throwIfAborted();
    try {
      return await fn(senal);
    } catch (error) {
      ultimoError = error;

      const esUltimo = intento === intentos - 1;
      if (esUltimo || !reintentable(error)) break;    // no esperes si no vas a reintentar

      // «Full jitter» (AWS): espera aleatoria dentro del techo exponencial.
      // Evita que mil clientes reintenten a la vez y tumben el servicio que se recupera.
      const techo = Math.min(maxMs, baseMs * factor ** intento);
      const esperaMs = Math.round(Math.random() * techo);

      alReintentar?.(error, intento + 1, esperaMs);
      await dormir(esperaMs, undefined, { signal: senal });
    }
  }

  throw ultimoError;
}

Las cuatro decisiones que separan esta versión de la ingenua.

• No reintentar los errores del cliente. Un 400 o un 422 fallará igual las cinco veces: reintentarlo solo añade latencia y carga. Un 429, en cambio, sí se reintenta (respetando Retry-After si viene).
• Jitter obligatorio. Sin aleatoriedad, todos los clientes que fallaron en el mismo instante reintentan sincronizados y provocan un thundering herd que impide al servicio recuperarse. La variante «full jitter» de AWS es la que mejor se comporta en las simulaciones publicadas.
• Techo máximo. Sin maxMs, el octavo intento con base 200 ms esperaría 25 segundos.
• Cancelación. throwIfAborted() al inicio de cada vuelta y la señal propagada al sleep evitan que un usuario que ha cerrado la pantalla siga generando peticiones durante medio minuto.

Lo que le falta para un sistema grande: un circuit breaker. Si el servicio lleva caído dos minutos, reintentar es contraproducente; lo correcto es abrir el circuito, fallar de inmediato durante un tiempo y probar con una petición de sondeo. En Angular el equivalente de este ejercicio es el operador retry({ count, delay }) de RxJS, y en NestJS suele resolverse con una biblioteca como cockatiel.

import {ChangeDetectionStrategy, Component, booleanAttribute, input, output} from '@angular/core';
import {DatePipe} from '@angular/common';

@Component({
  selector: 'tf-tarjeta-tarea',
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [DatePipe],
  template: `
    <article class="tarjeta" [class.compacta]="compacta()">
      <h3>{{ tarea().titulo }}</h3>
      <p class="vence">{{ tarea().vence | date: 'shortDate' }}</p>
      @if (!tarea().completada) {
        <button type="button" (click)="completar.emit(tarea().id)">Completar</button>
      }
    </article>`,
})
export class TarjetaTareaComponent {
  readonly tarea = input.required<Tarea>();
  // booleanAttribute permite <tf-tarjeta-tarea compacta> sin valor, como los atributos nativos.
  readonly compacta = input(false, {transform: booleanAttribute});
  readonly completar = output<number>();
}

Con OnPush el componente solo se revisa si cambia la referencia de una entrada, si se dispara un evento suyo o si una señal leída en su plantilla se modifica. Como aquí las entradas son señales, la revisión es automática y precisa.

import {Pipe, PipeTransform} from '@angular/core';

@Pipe({name: 'tiempoRelativo'})   // puro por defecto: se recalcula solo si cambia la entrada
export class TiempoRelativoPipe implements PipeTransform {
  // Instanciar Intl es caro: se crea UNA vez, no en cada transform().
  private readonly formateador = new Intl.RelativeTimeFormat('es-ES', {numeric: 'auto'});
  private readonly unidades: ReadonlyArray<[Intl.RelativeTimeFormatUnit, number]> = [
    ['year', 31_536_000], ['month', 2_592_000], ['week', 604_800],
    ['day', 86_400], ['hour', 3_600], ['minute', 60], ['second', 1],
  ];

  transform(valor: Date | string | null | undefined, ahora: number = Date.now()): string {
    if (valor === null || valor === undefined || valor === '') return '';
    const fecha = valor instanceof Date ? valor : new Date(valor);
    if (Number.isNaN(fecha.getTime())) return '';

    const segundos = (fecha.getTime() - ahora) / 1000;
    for (const [unidad, factor] of this.unidades) {
      if (Math.abs(segundos) >= factor || unidad === 'second') {
        return this.formateador.format(Math.round(segundos / factor), unidad);
      }
    }
    return '';
  }
}

El parámetro ahora es lo que hace el pipe testable: puedes fijar el instante de referencia sin falsear el reloj global. Ojo con un detalle sutil: un pipe puro no se recalcula con el paso del tiempo, así que «hace 1 minuto» se quedará congelado. Si necesitas que refresque, expón una señal de reloj en un servicio y léela en la plantilla.

import {Injectable, computed, signal} from '@angular/core';

export type Filtro = 'todas' | 'pendientes' | 'hechas';

@Injectable({providedIn: 'root'})
export class TareasStore {
  // Estado privado escribible; fuera solo se ve la versión de solo lectura.
  private readonly _tareas = signal<readonly Tarea[]>([]);
  private readonly _filtro = signal<Filtro>('todas');

  readonly tareas = this._tareas.asReadonly();
  readonly filtro = this._filtro.asReadonly();

  readonly visibles = computed(() => {
    const f = this._filtro();
    if (f === 'todas') return this._tareas();
    return this._tareas().filter((t) => (f === 'hechas' ? t.completada : !t.completada));
  });
  readonly pendientes = computed(() => this._tareas().filter((t) => !t.completada).length);
  readonly progreso = computed(() => {
    const total = this._tareas().length;
    return total === 0 ? 0 : Math.round(((total - this.pendientes()) / total) * 100);
  });

  cargar(tareas: readonly Tarea[]): void { this._tareas.set(tareas); }
  filtrar(f: Filtro): void { this._filtro.set(f); }

  alternar(id: number): void {
    // Inmutable: nuevo array y nuevo objeto para el elemento modificado.
    this._tareas.update((ts) =>
      ts.map((t) => (t.id === id ? {...t, completada: !t.completada} : t)));
  }
}

Tres reglas se cumplen aquí: el estado escribible nunca sale del servicio (asReadonly()), todo lo derivable es computed y no un segundo signal sincronizado a mano, y las actualizaciones son inmutables. Mutar this._tareas()[0].completada = true no notificaría a nadie: la referencia del array no cambia.

import {ChangeDetectionStrategy, Component, inject, signal} from '@angular/core';
import {toObservable, toSignal} from '@angular/core/rxjs-interop';
import {debounceTime, distinctUntilChanged, of, startWith, switchMap} from 'rxjs';

@Component({
  selector: 'tf-buscador',
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <input type="search" [value]="termino()" (input)="termino.set($any($event.target).value)"
           placeholder="Buscar tareas" />
    @for (t of resultados(); track t.id) { <p>{{ t.titulo }}</p> }`,
})
export class BuscadorComponent {
  private readonly api = inject(TareasApi);
  readonly termino = signal('');

  readonly resultados = toSignal(
    toObservable(this.termino).pipe(
      debounceTime(300),               // espera a que el usuario pare de teclear
      distinctUntilChanged(),          // 'ana' -> 'an' -> 'ana' no repite la búsqueda
      switchMap((q) => (q.trim().length < 2 ? of([]) : this.api.buscar(q))),
      startWith([] as Tarea[]),
    ),
    {initialValue: [] as Tarea[]},
  );
}

Por qué switchMap y no mergeMap. switchMap cancela la suscripción anterior antes de crear la nueva, y HttpClient traduce esa cancelación en un abort() real de la petición. Con mergeMap conviven todas las peticiones y, si la de «an» tarda más que la de «ana», el usuario ve resultados obsoletos: es la carrera clásica de todo buscador mal hecho. Con la API de recursos el equivalente sería rxResource({params: () => terminoDebounced(), stream: ({params}) => api.buscar(params)}), que cancela igual.

import {AbstractControl, AsyncValidatorFn, FormBuilder, ValidationErrors, ValidatorFn, Validators}
  from '@angular/forms';
import {catchError, first, map, of, switchMap, timer} from 'rxjs';

/** Validador de grupo: compara dos controles hermanos. */
export const rangoDeFechas: ValidatorFn = (grupo: AbstractControl): ValidationErrors | null => {
  const inicio = grupo.get('inicio')?.value as string | null;
  const fin = grupo.get('fin')?.value as string | null;
  if (!inicio || !fin) return null;                       // sin datos no se valida
  return new Date(inicio) <= new Date(fin) ? null : {rangoInvalido: true};
};

/** Validador asíncrono con su propio debounce y sin propagar errores de red. */
export function emailDisponible(api: UsuariosApi): AsyncValidatorFn {
  return (control) => {
    if (!control.value) return of(null);
    return timer(400).pipe(
      switchMap(() => api.existeEmail(control.value as string)),
      map((existe) => (existe ? {emailDuplicado: true} : null)),
      catchError(() => of(null)),   // si la API cae, no bloquees el formulario
      first(),                      // OBLIGATORIO: debe completar o el control queda en PENDING
    );
  };
}

// Uso en el componente
private readonly fb = inject(FormBuilder);
readonly formulario = this.fb.nonNullable.group(
  {
    titulo: ['', [Validators.required, Validators.maxLength(120)]],
    inicio: [''],
    fin: [''],
    email: this.fb.nonNullable.control('', {
      validators: [Validators.required, Validators.email],
      asyncValidators: [emailDisponible(inject(UsuariosApi))],
      updateOn: 'blur',            // una petición al salir del campo, no una por tecla
    }),
  },
  {validators: rangoDeFechas},
);

El first() es el fallo más frecuente de los validadores asíncronos: si el observable no completa, el control se queda para siempre en estado PENDING y el botón de enviar nunca se habilita. El catchError es la segunda trampa: sin él, un 500 del servidor deja el control en un estado inconsistente.

import {ChangeDetectionStrategy, Component, forwardRef, signal} from '@angular/core';
import {ControlValueAccessor, NG_VALUE_ACCESSOR} from '@angular/forms';

@Component({
  selector: 'tf-input-etiquetas',
  changeDetection: ChangeDetectionStrategy.OnPush,
  providers: [{
    provide: NG_VALUE_ACCESSOR,
    useExisting: forwardRef(() => InputEtiquetasComponent),   // la clase aún no existe al evaluar
    multi: true,
  }],
  template: `
    <div class="chips" (focusout)="alPerderFoco()">
      @for (e of etiquetas(); track e) {
        <span class="chip">{{ e }}
          <button type="button" [disabled]="deshabilitado()" (click)="quitar(e)">&times;</button>
        </span>
      }
      <input #campo type="text" [disabled]="deshabilitado()"
             (keydown.enter)="$event.preventDefault(); anadir(campo.value); campo.value = ''" />
    </div>`,
})
export class InputEtiquetasComponent implements ControlValueAccessor {
  readonly etiquetas = signal<readonly string[]>([]);
  readonly deshabilitado = signal(false);

  private alCambiar: (valor: readonly string[]) => void = () => {};
  private alTocar: () => void = () => {};

  writeValue(valor: readonly string[] | null): void { this.etiquetas.set(valor ?? []); }
  registerOnChange(fn: (valor: readonly string[]) => void): void { this.alCambiar = fn; }
  registerOnTouched(fn: () => void): void { this.alTocar = fn; }
  setDisabledState(deshabilitado: boolean): void { this.deshabilitado.set(deshabilitado); }

  anadir(texto: string): void {
    const limpio = texto.trim().toLowerCase();
    if (limpio === '' || this.etiquetas().includes(limpio)) return;
    this.etiquetas.update((e) => [...e, limpio]);
    this.alCambiar(this.etiquetas());     // notifica al FormControl
  }
  quitar(etiqueta: string): void {
    this.etiquetas.update((e) => e.filter((x) => x !== etiqueta));
    this.alCambiar(this.etiquetas());
  }
  alPerderFoco(): void { this.alTocar(); }   // sin esto, el control nunca pasa a «touched»
}

Los cuatro métodos de la interfaz no son opcionales en la práctica: olvidar setDisabledState hace que formulario.disable() no tenga efecto visual, y olvidar registerOnTouched impide que los mensajes de error aparezcan al abandonar el campo. forwardRef es necesario porque el array providers se evalúa antes de que la clase esté definida.

import {Component, computed, input, signal} from '@angular/core';

type Columna = 'titulo' | 'prioridad' | 'vence';

@Component({selector: 'tf-tabla-tareas', /* … plantilla … */})
export class TablaTareasComponent {
  readonly datos = input.required<readonly Tarea[]>();

  readonly texto = signal('');
  readonly columna = signal<Columna>('vence');
  readonly ascendente = signal(true);
  readonly pagina = signal(1);
  readonly tamano = signal(20);

  // Cadena de derivaciones: filtrar -> ordenar -> paginar. Cada paso se memoriza
  // y solo se recalcula si cambia alguna de sus dependencias.
  private readonly filtradas = computed(() => {
    const q = this.texto().trim().toLowerCase();
    return q === '' ? this.datos() : this.datos().filter((t) => t.titulo.toLowerCase().includes(q));
  });

  private readonly ordenadas = computed(() => {
    const col = this.columna();
    const signo = this.ascendente() ? 1 : -1;
    // toSorted no muta el array de origen (Node 20+ / navegadores modernos).
    return this.filtradas().toSorted((a, b) =>
      signo * String(a[col] ?? '').localeCompare(String(b[col] ?? ''), 'es'));
  });

  readonly totalPaginas = computed(() => Math.max(1, Math.ceil(this.ordenadas().length / this.tamano())));
  readonly visibles = computed(() => {
    const desde = (this.pagina() - 1) * this.tamano();
    return this.ordenadas().slice(desde, desde + this.tamano());
  });

  ordenarPor(col: Columna): void {
    if (this.columna() === col) this.ascendente.update((a) => !a);
    else { this.columna.set(col); this.ascendente.set(true); }
    this.pagina.set(1);           // cambiar el orden invalida la página actual
  }
}

La razón de no llamar a un método desde la plantilla ({{ filtrar(datos) }}) es que se ejecutaría en cada ciclo de detección de cambios. Un computed se recalcula solo cuando alguna señal de la que depende cambia, y cachea el resultado.

import {Directive, TemplateRef, ViewContainerRef, effect, inject, input} from '@angular/core';

@Directive({selector: '[hasRole]'})
export class HasRoleDirective {
  private readonly vista = inject(ViewContainerRef);
  private readonly plantilla = inject<TemplateRef<unknown>>(TemplateRef);
  private readonly sesion = inject(SesionStore);
  private incrustada = false;

  // El nombre del input debe coincidir con el selector para la sintaxis *hasRole="…".
  readonly hasRole = input.required<string | readonly string[]>();

  constructor() {
    effect(() => {
      const requeridos = [this.hasRole()].flat();
      const permitido = requeridos.some((r) => this.sesion.roles().includes(r));

      if (permitido && !this.incrustada) {
        this.vista.createEmbeddedView(this.plantilla);
        this.incrustada = true;
      } else if (!permitido && this.incrustada) {
        this.vista.clear();
        this.incrustada = false;
      }
    });
  }
}

El indicador incrustada evita el fallo más típico: sin él, cada ejecución del efecto crearía una vista nueva y acabarías con el botón repetido diez veces. Advertencia de seguridad: esto es presentación, no autorización. Ocultar un botón no impide llamar al endpoint; la comprobación real vive en el servidor (ver NEST-04).

import {inject} from '@angular/core';
import {CanActivateFn, Router} from '@angular/router';

export const autenticadoGuard: CanActivateFn = (_ruta, estado) => {
  const sesion = inject(SesionStore);
  const router = inject(Router);
  if (sesion.autenticado()) return true;

  // Devolver un UrlTree redirige de forma atómica: mejor que router.navigate() + return false,
  // que provoca dos eventos de navegación y puede dejar la URL a medias.
  return router.createUrlTree(['/login'], {queryParams: {returnUrl: estado.url}});
};

// En el componente de login, tras autenticarse:
private readonly ruta = inject(ActivatedRoute);
private readonly router = inject(Router);

async entrar(credenciales: Credenciales): Promise<void> {
  await this.auth.login(credenciales);
  const destino = this.ruta.snapshot.queryParamMap.get('returnUrl') ?? '/';
  // parseUrl conserva los query params y el fragmento del destino original.
  await this.router.navigateByUrl(this.router.parseUrl(destino));
}

estado.url incluye los parámetros de consulta, así que parseUrl los restaura tal cual. Un detalle de seguridad que se olvida siempre: valida que returnUrl sea una ruta interna. Si aceptas returnUrl=https://malicioso.example has construido un open redirect, que es una vulnerabilidad real de phishing.

import {HttpErrorResponse, HttpInterceptorFn, HttpRequest} from '@angular/common/http';
import {inject} from '@angular/core';
import {Observable, catchError, finalize, shareReplay, switchMap, tap, throwError} from 'rxjs';

@Injectable({providedIn: 'root'})
export class RefrescoService {
  private readonly api = inject(AuthApi);
  private readonly sesion = inject(SesionStore);
  // Se guarda en el servicio, no en una variable de módulo: así no hay estado compartido
  // entre peticiones distintas en renderizado en servidor (SSR).
  private enCurso: Observable<string> | null = null;

  refrescar(): Observable<string> {
    this.enCurso ??= this.api.refrescar(this.sesion.refreshToken()).pipe(
      tap((token) => this.sesion.establecerAcceso(token)),
      catchError((e: unknown) => { this.sesion.cerrar(); return throwError(() => e); }),
      finalize(() => { this.enCurso = null; }),          // permite un refresco futuro
      shareReplay({bufferSize: 1, refCount: false}),      // TODOS comparten la misma llamada
    );
    return this.enCurso;
  }
}

const SIN_AUTH = ['/auth/login', '/auth/refresh', '/auth/registro'];

export const authInterceptor: HttpInterceptorFn = (req, next) => {
  const sesion = inject(SesionStore);
  const refresco = inject(RefrescoService);

  // Excluir el endpoint de refresco es lo que rompe el bucle infinito.
  if (SIN_AUTH.some((r) => req.url.includes(r))) return next(req);

  const conToken = (r: HttpRequest<unknown>, token: string | null) =>
    token ? r.clone({setHeaders: {Authorization: `Bearer ${token}`}}) : r;

  return next(conToken(req, sesion.accessToken())).pipe(
    catchError((error: unknown) => {
      if (!(error instanceof HttpErrorResponse) || error.status !== 401) {
        return throwError(() => error);
      }
      return refresco.refrescar().pipe(
        switchMap((token) => next(conToken(req, token))),  // un solo reintento
      );
    }),
  );
};

Las tres piezas críticas: ??= más shareReplay hacen que diez 401 simultáneos compartan un único POST /auth/refresh; finalize limpia la referencia para que el siguiente 401, dentro de una hora, vuelva a refrescar; y la lista de exclusión evita que el 401 del propio refresco se intercepte a sí mismo, que es la causa exacta del caso DEBUG-07.

@defer (on viewport; prefetch on idle) {
  <tf-grafico-progreso [datos]="metricas()" />
} @placeholder (minimum 300ms) {
  <div class="esqueleto" style="height:320px"></div>
} @loading (after 150ms; minimum 500ms) {
  <tf-spinner />
} @error {
  <p role="alert">No se pudo cargar el gráfico. <button (click)="recargar()">Reintentar</button></p>
}

Cada umbral tiene una razón medida: after 150ms evita el parpadeo del spinner en conexiones rápidas (si carga en 80 ms, el usuario no ve nada raro); minimum 500ms impide que el spinner aparezca y desaparezca de golpe, que se percibe como un fallo; minimum 300ms en el placeholder evita saltos de maquetación. prefetch on idle descarga el fragmento cuando el navegador está ocioso, de modo que al llegar al viewport el cambio es instantáneo. Comprueba en dist/ que aparece un chunk nuevo: si el componente también está importado de forma estática en otro sitio, Angular no puede separarlo y el @defer no sirve de nada.

import {ScrollingModule} from '@angular/cdk/scrolling';

@Component({
  selector: 'tf-lista-virtual',
  imports: [ScrollingModule, FilaTareaComponent],
  changeDetection: ChangeDetectionStrategy.OnPush,
  styles: `.visor { height: 70vh; } .fila { height: 56px; }`,
  template: `
    <cdk-virtual-scroll-viewport itemSize="56" class="visor">
      <tf-fila-tarea class="fila" *cdkVirtualFor="let t of tareas(); trackBy: porId" [tarea]="t" />
    </cdk-virtual-scroll-viewport>`,
})
export class ListaVirtualComponent {
  readonly tareas = input.required<readonly Tarea[]>();
  porId = (_i: number, t: Tarea) => t.id;
}

track en @for resuelve un problema distinto: evita recrear nodos al reordenar, pero sigue creando 50.000 nodos la primera vez. El virtual scroll mantiene en el DOM solo las filas visibles (unas 15) más un pequeño margen, y simula la altura total con un espaciador. La consecuencia práctica: el DOM pasa de ~600.000 nodos a ~200 y el tiempo de renderizado inicial de varios segundos a unas decenas de milisegundos. Requisito imprescindible: la altura de fila debe ser fija y coincidir con itemSize; con alturas variables necesitas una estrategia personalizada o autosize del experimental.

import {HttpErrorResponse, provideHttpClient} from '@angular/common/http';
import {HttpTestingController, provideHttpClientTesting} from '@angular/common/http/testing';
import {TestBed} from '@angular/core/testing';

describe('TareasApi', () => {
  let api: TareasApi;
  let http: HttpTestingController;

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [provideHttpClient(), provideHttpClientTesting(), TareasApi],
    });
    api = TestBed.inject(TareasApi);
    http = TestBed.inject(HttpTestingController);
  });

  // Falla el test si quedó alguna petición sin atender: detecta fugas y peticiones duplicadas.
  afterEach(() => http.verify());

  it('envía los parámetros de paginación y mapea la respuesta', () => {
    let recibidas: readonly Tarea[] | undefined;
    api.listar({pagina: 2, tamano: 20}).subscribe((r) => (recibidas = r.datos));

    const peticion = http.expectOne((r) => r.url === '/api/tareas');
    expect(peticion.request.method).toBe('GET');
    expect(peticion.request.params.get('pagina')).toBe('2');
    expect(peticion.request.params.get('tamano')).toBe('20');

    peticion.flush({datos: [{id: 1, titulo: 'Escribir tests'}], total: 1});
    expect(recibidas?.length).toBe(1);
  });

  it('propaga el 500 como HttpErrorResponse', () => {
    let error: unknown;
    api.listar({pagina: 1, tamano: 20}).subscribe({error: (e: unknown) => (error = e)});

    http.expectOne((r) => r.url === '/api/tareas')
        .flush('boom', {status: 500, statusText: 'Internal Server Error'});

    expect((error as HttpErrorResponse).status).toBe(500);
  });
});

http.verify() en el afterEach es lo que convierte este test en una red de seguridad de verdad: detecta el caso en que un cambio introduce una segunda petición inesperada (por ejemplo, al perder un shareReplay).

export class AntesComponent implements OnInit, OnDestroy {
  private readonly filtro$ = new BehaviorSubject('');
  private readonly pagina$ = new BehaviorSubject(1);
  tareas: Tarea[] = [];
  private sub?: Subscription;

  ngOnInit(): void {
    this.sub = combineLatest([this.filtro$, this.pagina$])
      .pipe(switchMap(([f, p]) => this.api.listar(f, p)))
      .subscribe((t) => { this.tareas = t; this.cdr.markForCheck(); });
  }
  ngOnDestroy(): void { this.sub?.unsubscribe(); }

  buscar(f: string) { this.filtro$.next(f); this.pagina$.next(1); }
}

export class DespuesComponent {
  private readonly api = inject(TareasApi);
  readonly filtro = signal('');
  readonly pagina = signal(1);

  // El HTTP sigue siendo RxJS: es un flujo con tiempo y cancelación.
  readonly tareas = rxResource({
    params: () => ({f: this.filtro(), p: this.pagina()}),
    stream: ({params}) => this.api.listar(params.f, params.p),
  });

  buscar(f: string): void {
    this.filtro.set(f);
    this.pagina.set(1);
  }
}

Qué desaparece: ngOnInit, ngOnDestroy, la suscripción manual, el markForCheck y los dos BehaviorSubject. Además obtienes tareas.isLoading() y tareas.error() gratis.

Qué debe seguir siendo RxJS: todo lo que tenga tiempo o cancelación. Peticiones HTTP, debounce, reintentos con retroceso, WebSockets, eventos del router y valueChanges de los formularios reactivos. La regla mental: las señales modelan estado; los observables modelan eventos en el tiempo. Convertir de uno a otro con toSignal y toObservable en la frontera es lo correcto; intentar hacerlo todo con uno solo, no.

// 1) El puerto: contrato del dominio, sin dependencias de infraestructura.
export interface Notificador {
  enviar(destino: string, asunto: string, cuerpo: string): Promise<void>;
}
// 2) El token: un Symbol evita colisiones que sí ocurren con tokens de tipo string.
export const NOTIFICADOR = Symbol('NOTIFICADOR');

// 3) Adaptadores
@Injectable()
export class SmtpNotificador implements Notificador {
  private readonly logger = new Logger(SmtpNotificador.name);
  constructor(private readonly config: ConfigService) {}
  async enviar(destino: string, asunto: string, cuerpo: string): Promise<void> {
    // … nodemailer con this.config.getOrThrow('SMTP_URL')
  }
}

@Injectable()
export class NotificadorEnMemoria implements Notificador {
  readonly enviadas: Array<{destino: string; asunto: string; cuerpo: string}> = [];
  async enviar(destino: string, asunto: string, cuerpo: string): Promise<void> {
    this.enviadas.push({destino, asunto, cuerpo});
  }
}

// 4) El módulo decide la implementación; nadie más lo sabe.
@Module({
  providers: [
    SmtpNotificador,
    NotificadorEnMemoria,
    {
      provide: NOTIFICADOR,
      inject: [ConfigService, SmtpNotificador, NotificadorEnMemoria],
      useFactory: (c: ConfigService, smtp: SmtpNotificador, memoria: NotificadorEnMemoria) =>
        c.get('NODE_ENV') === 'production' ? smtp : memoria,
    },
  ],
  exports: [NOTIFICADOR],
})
export class NotificacionesModule {}

// 5) Consumo: el servicio depende de la abstracción, no de SMTP.
@Injectable()
export class TareasService {
  constructor(@Inject(NOTIFICADOR) private readonly notificador: Notificador) {}
}

Esto es el principio de inversión de dependencias de SOLID aplicado literalmente: el dominio define el contrato y la infraestructura lo implementa. El beneficio inmediato es que en los tests inyectas NotificadorEnMemoria y compruebas notificador.enviadas sin levantar un servidor de correo.

import {Transform, Type} from 'class-transformer';
import {ArrayMaxSize, ArrayMinSize, IsArray, IsBoolean, IsEmail, IsISO8601, IsIn,
  IsInt, IsOptional, IsString, Length, Max, Min, ValidateNested, Validate} from 'class-validator';

export class AjustesDto {
  @IsBoolean() publico!: boolean;
  @IsInt() @Min(1) @Max(365) diasRetencion!: number;
}

export class MiembroDto {
  @IsEmail() email!: string;
  @IsIn(['admin', 'editor', 'lector']) rol!: 'admin' | 'editor' | 'lector';
}

export class CrearProyectoDto {
  @IsString() @Length(3, 120) nombre!: string;

  @IsISO8601() inicio!: string;

  @IsOptional() @IsISO8601()
  @Validate(EsPosteriorA, ['inicio'])          // validador de clase personalizado
  fin?: string;

  @IsArray() @ArrayMaxSize(10) @IsString({each: true}) @Length(1, 24, {each: true})
  @Transform(({value}) => Array.isArray(value)
    ? [...new Set(value.map((v: unknown) => String(v).trim().toLowerCase()))]
    : value)
  etiquetas: string[] = [];

  @ValidateNested() @Type(() => AjustesDto)     // @Type es OBLIGATORIO o llega un objeto plano
  ajustes!: AjustesDto;

  @IsArray() @ArrayMinSize(1) @ValidateNested({each: true}) @Type(() => MiembroDto)
  miembros!: MiembroDto[];
}

app.useGlobalPipes(new ValidationPipe({
  whitelist: true,              // elimina propiedades sin decorador
  forbidNonWhitelisted: true,   // …y además responde 400 si llegan: detecta clientes desalineados
  transform: true,              // convierte el JSON plano en instancias de la clase DTO
  transformOptions: {enableImplicitConversion: false},   // conversiones explícitas: menos sorpresas
  stopAtFirstError: false,      // devuelve todos los errores de una vez: mejor experiencia de usuario
}));

@Type(() => AjustesDto) es el olvido número uno: sin él, class-transformer deja un objeto plano y @ValidateNested() no valida absolutamente nada, dando una falsa sensación de seguridad. Y sin forbidNonWhitelisted, un cliente que envía rol: 'admin' en el DTO de registro solo verá su campo silenciosamente descartado; con él, recibe un 400 claro.

export interface Orden { campo: string; dir: 'ASC' | 'DESC' }

@Injectable()
export class ParseOrdenPipe implements PipeTransform<string | undefined, Orden[]> {
  constructor(private readonly permitidos: readonly string[]) {}

  transform(valor: string | undefined): Orden[] {
    if (!valor) return [];
    const partes = valor.split(',').map((p) => p.trim()).filter(Boolean);
    if (partes.length > 3) throw new BadRequestException('Máximo 3 criterios de orden');

    return partes.map((parte) => {
      const dir = parte.startsWith('-') ? 'DESC' : 'ASC';
      const campo = parte.replace(/^[-+]/, '');
      // Lista blanca: el nombre de columna acabará en el SQL, así que NUNCA se acepta libre.
      if (!this.permitidos.includes(campo)) {
        throw new BadRequestException(
          `Campo de orden no permitido: '${campo}'. Permitidos: ${this.permitidos.join(', ')}`);
      }
      return {campo, dir};
    });
  }
}

// Uso: se instancia con sus parámetros en el propio decorador.
@Get()
listar(@Query('orden', new ParseOrdenPipe(['titulo', 'vence', 'prioridad'])) orden: Orden[]) { … }

export type Rol = 'admin' | 'gestor' | 'miembro';
export const ROLES_CLAVE = 'roles';
export const PUBLICO_CLAVE = 'esPublico';

export const Roles = (...roles: Rol[]) => SetMetadata(ROLES_CLAVE, roles);
export const Publico = () => SetMetadata(PUBLICO_CLAVE, true);

@Injectable()
export class RolesGuard implements CanActivate {
  constructor(private readonly reflector: Reflector) {}

  canActivate(contexto: ExecutionContext): boolean {
    // getAllAndOverride: el metadato del método tiene prioridad sobre el de la clase.
    const esPublico = this.reflector.getAllAndOverride<boolean>(PUBLICO_CLAVE,
      [contexto.getHandler(), contexto.getClass()]);
    if (esPublico) return true;

    const requeridos = this.reflector.getAllAndOverride<Rol[]>(ROLES_CLAVE,
      [contexto.getHandler(), contexto.getClass()]);
    if (!requeridos || requeridos.length === 0) return true;   // sin @Roles, basta estar autenticado

    const peticion = contexto.switchToHttp().getRequest<{usuario?: {roles: Rol[]}}>();
    const usuario = peticion.usuario;
    if (!usuario) throw new UnauthorizedException('Sin sesión');

    if (!requeridos.some((r) => usuario.roles.includes(r))) {
      throw new ForbiddenException(`Se requiere uno de estos roles: ${requeridos.join(', ')}`);
    }
    return true;
  }
}

La diferencia entre getAllAndOverride (el primero que encuentre gana; el método pisa a la clase) y getAllAndMerge (une los dos arrays) es una pregunta habitual de entrevista. Para roles casi siempre quieres Override: un método concreto puede ser más restrictivo o más laxo que su controlador.

export interface Sobre<T> { datos: T; meta: {correlacionId: string; ms: number} }

@Injectable()
export class EnvolturaInterceptor<T> implements NestInterceptor<T, Sobre<T>> {
  intercept(contexto: ExecutionContext, siguiente: CallHandler<T>): Observable<Sobre<T>> {
    const inicio = Date.now();
    const peticion = contexto.switchToHttp().getRequest<{correlacionId?: string}>();
    // Solo se transforma el camino feliz: los errores van al filtro de excepciones.
    return siguiente.handle().pipe(
      map((datos) => ({
        datos,
        meta: {correlacionId: peticion.correlacionId ?? '-', ms: Date.now() - inicio},
      })),
    );
  }
}

@Injectable()
export class TimeoutInterceptor implements NestInterceptor {
  constructor(private readonly ms = 5_000) {}
  intercept(_c: ExecutionContext, siguiente: CallHandler): Observable<unknown> {
    return siguiente.handle().pipe(
      timeout({each: this.ms}),
      catchError((error: unknown) =>
        throwError(() => (error instanceof TimeoutError
          ? new RequestTimeoutException('La operación superó el tiempo máximo')
          : error))),
    );
  }
}

// main.ts — el orden importa: el primero es el más externo.
app.useGlobalInterceptors(new TimeoutInterceptor(5_000), new EnvolturaInterceptor());

El timeout va fuera para que cuente también el tiempo del resto de la cadena; la envoltura, dentro, para que solo vea respuestas ya producidas. Advertencia importante: timeout cancela la suscripción, pero no cancela la consulta SQL que ya está corriendo en el servidor de base de datos. Para eso necesitas statement_timeout en PostgreSQL; el interceptor solo libera al cliente.

interface ProblemDetails {
  type: string; title: string; status: number; detail?: string; instance?: string;
  correlationId?: string; errors?: Record<string, string[]>;
}

@Catch()
export class ProblemDetailsFilter implements ExceptionFilter {
  private readonly logger = new Logger(ProblemDetailsFilter.name);
  private readonly titulos: Record<number, string> = {
    400: 'Petición incorrecta', 401: 'No autenticado', 403: 'Prohibido',
    404: 'Recurso no encontrado', 409: 'Conflicto', 422: 'Entidad no procesable',
    429: 'Demasiadas peticiones', 500: 'Error interno del servidor',
  };

  catch(excepcion: unknown, host: ArgumentsHost): void {
    const ctx = host.switchToHttp();
    const respuesta = ctx.getResponse<Response>();
    const peticion = ctx.getRequest<Request & {correlacionId?: string}>();

    let estado = HttpStatus.INTERNAL_SERVER_ERROR;
    let detalle: string | undefined;
    let errores: Record<string, string[]> | undefined;

    if (excepcion instanceof HttpException) {
      estado = excepcion.getStatus();
      const cuerpo = excepcion.getResponse();
      if (typeof cuerpo === 'string') {
        detalle = cuerpo;
      } else if (typeof cuerpo === 'object' && cuerpo !== null) {
        const c = cuerpo as {message?: string | string[]};
        // El ValidationPipe devuelve message como array de cadenas.
        if (Array.isArray(c.message)) errores = {cuerpo: c.message};
        else detalle = c.message;
      }
    } else if (excepcion instanceof UniqueConstraintViolationException) {
      estado = HttpStatus.CONFLICT;                    // 409, no 500
      detalle = 'Ya existe un recurso con esos datos';
    } else if (excepcion instanceof NotFoundError) {   // NotFoundError de MikroORM
      estado = HttpStatus.NOT_FOUND;
    }

    const problema: ProblemDetails = {
      type: `https://api.taskflow.dev/errores/${estado}`,
      title: this.titulos[estado] ?? 'Error',
      status: estado,
      // Regla de oro: en 5xx NUNCA se devuelve el mensaje interno al cliente.
      detail: estado >= 500 ? 'Se ha producido un error inesperado' : detalle,
      instance: peticion.url,
      correlationId: peticion.correlacionId,
      ...(errores ? {errors: errores} : {}),
    };

    if (estado >= 500) {
      this.logger.error(
        {correlationId: problema.correlationId, ruta: peticion.url},
        excepcion instanceof Error ? excepcion.stack : String(excepcion));
    }

    respuesta.status(estado).type('application/problem+json').json(problema);
  }
}

Tres decisiones defendibles en una revisión: @Catch() sin argumentos captura todo, incluidos los errores no controlados, y garantiza que ninguna respuesta se escape del formato; los 4xx no se registran como error porque son culpa del cliente y llenarían el registro de ruido; y el correlationId es lo que permite que el usuario te dé un identificador por teléfono y tú encuentres la traza exacta.

export interface OpcionesAlmacenamiento { raiz: string; maxMb: number; publico: boolean }
export const OPCIONES_ALMACENAMIENTO = Symbol('OPCIONES_ALMACENAMIENTO');

export interface OpcionesAsincronas {
  imports?: ModuleMetadata['imports'];
  inject?: InjectionToken[];
  useFactory: (...args: never[]) => Promise<OpcionesAlmacenamiento> | OpcionesAlmacenamiento;
}

@Module({})
export class AlmacenamientoModule {
  static forRoot(opciones: OpcionesAlmacenamiento): DynamicModule {
    return {
      module: AlmacenamientoModule,
      global: true,                       // disponible sin reimportar en cada módulo
      providers: [
        {provide: OPCIONES_ALMACENAMIENTO, useValue: this.validar(opciones)},
        AlmacenamientoService,
      ],
      exports: [AlmacenamientoService],
    };
  }

  static forRootAsync(op: OpcionesAsincronas): DynamicModule {
    return {
      module: AlmacenamientoModule,
      global: true,
      imports: op.imports ?? [],
      providers: [
        {
          provide: OPCIONES_ALMACENAMIENTO,
          inject: op.inject ?? [],
          useFactory: async (...args: never[]) => this.validar(await op.useFactory(...args)),
        },
        AlmacenamientoService,
      ],
      exports: [AlmacenamientoService],
    };
  }

  // Fallar al arrancar es infinitamente mejor que fallar en la primera subida de un usuario.
  private static validar(o: OpcionesAlmacenamiento): OpcionesAlmacenamiento {
    if (!o.raiz) throw new Error('AlmacenamientoModule: falta "raiz"');
    if (o.maxMb <= 0 || o.maxMb > 500) throw new Error('AlmacenamientoModule: maxMb fuera de rango');
    return o;
  }
}

// Uso asíncrono, leyendo de ConfigService
AlmacenamientoModule.forRootAsync({
  inject: [ConfigService],
  useFactory: (c: ConfigService) => ({
    raiz: c.getOrThrow('ALMACEN_RAIZ'), maxMb: Number(c.get('ALMACEN_MAX_MB') ?? 20), publico: false,
  }),
});

@Entity()
export class RefreshToken {
  @PrimaryKey() id: string = v4();
  @Property({unique: true}) hash!: string;      // SOLO el hash: si roban la BD, no sirven
  @Property() familia!: string;                 // todos los descendientes de un login
  @ManyToOne(() => Usuario) usuario!: Usuario;
  @Property() expiraEn!: Date;
  @Property({nullable: true}) usadoEn?: Date;   // marca de consumo
  @Property({default: false}) revocado!: boolean;
}

@Injectable()
export class AuthService {
  private readonly hash = (t: string) => createHash('sha256').update(t).digest('hex');

  async rotar(refreshPlano: string): Promise<{acceso: string; refresco: string}> {
    const registro = await this.em.findOne(RefreshToken, {hash: this.hash(refreshPlano)},
      {populate: ['usuario']});

    if (!registro || registro.revocado || registro.expiraEn < new Date()) {
      throw new UnauthorizedException('Refresh token inválido');
    }

    // DETECCIÓN DE REUTILIZACIÓN: alguien está usando un token ya consumido.
    // O bien es un atacante con un token robado, o bien el usuario legítimo tras un robo.
    // En cualquier caso, la única respuesta segura es revocar TODA la familia.
    if (registro.usadoEn) {
      await this.em.nativeUpdate(RefreshToken, {familia: registro.familia}, {revocado: true});
      this.logger.warn({familia: registro.familia}, 'Reutilización de refresh token: familia revocada');
      throw new UnauthorizedException('Sesión comprometida, vuelve a iniciar sesión');
    }

    registro.usadoEn = new Date();               // consumido, no borrado: hace falta para detectar

    const nuevoPlano = randomBytes(48).toString('base64url');
    this.em.create(RefreshToken, {
      hash: this.hash(nuevoPlano),
      familia: registro.familia,                 // misma familia: encadena la sesión
      usuario: registro.usuario,
      expiraEn: new Date(Date.now() + 7 * 24 * 3600_000),
      revocado: false,
    });
    await this.em.flush();                       // una sola transacción para consumo y creación

    return {
      acceso: await this.jwt.signAsync(
        {sub: registro.usuario.id, roles: registro.usuario.roles}, {expiresIn: '15m'}),
      refresco: nuevoPlano,
    };
  }
}

Por qué este diseño y no un simple JWT de larga duración: un JWT no se puede revocar sin lista negra, así que un token robado vale hasta que caduque. Con rotación, el robo se detecta en cuanto los dos —atacante y usuario— intentan usar la misma cadena, y la familia entera se corta. Detalles imprescindibles: el refresh viaja en una cookie httpOnly, secure y sameSite=strict, no en localStorage; y el consumo más la creación deben ocurrir en la misma transacción, o una caída entre ambas operaciones deja al usuario sin sesión.

// La clave combina IP y email: ninguna de las dos por separado es suficiente.
@Injectable()
export class LoginThrottleGuard extends ThrottlerGuard {
  protected async getTracker(peticion: Record<string, unknown>): Promise<string> {
    const cuerpo = (peticion['body'] ?? {}) as {email?: string};
    const ip = (peticion['ip'] as string) ?? 'desconocida';
    return `${ip}:${(cuerpo.email ?? '').toLowerCase()}`;
  }
}

@Controller('auth')
export class AuthController {
  @Publico()
  @UseGuards(LoginThrottleGuard)
  @Throttle({default: {limit: 5, ttl: 60_000}})
  @HttpCode(200)
  @Post('login')
  async login(@Body() dto: LoginDto) {
    return this.auth.login(dto);   // el ThrottlerGuard añade Retry-After al responder 429
  }
}

Por qué la clave combinada. Solo por IP: una red corporativa o un CGNAT comparten IP y bloquearías a cientos de usuarios legítimos; además, un atacante con una botnet la rota trivialmente. Solo por email: cualquiera puede bloquear la cuenta de otro enviando cinco intentos fallidos, que es un ataque de denegación de servicio dirigido. La combinación limita la fuerza bruta contra una cuenta desde un origen sin castigar a terceros. En producción se añade un límite global por IP más laxo (por ejemplo 100/min) y almacenamiento en Redis, porque el contador en memoria no sirve con varias instancias.

@Injectable()
export class ProyectosService {
  constructor(@Inject(CACHE_MANAGER) private readonly cache: Cache, private readonly em: EntityManager) {}

  private clave(id: string) { return `proyecto:${id}`; }

  async obtener(id: string): Promise<ProyectoDto> {
    const enCache = await this.cache.get<ProyectoDto>(this.clave(id));
    if (enCache) return enCache;

    const proyecto = await this.em.findOneOrFail(Proyecto, {id}, {populate: ['miembros']});
    const dto = aDto(proyecto);
    await this.cache.set(this.clave(id), dto, 60_000);
    return dto;
  }

  async actualizar(id: string, dto: ActualizarProyectoDto): Promise<ProyectoDto> {
    const proyecto = await this.em.findOneOrFail(Proyecto, {id});
    this.em.assign(proyecto, dto);
    await this.em.flush();
    await this.invalidar(id);          // invalidar DESPUÉS del commit, nunca antes
    return aDto(proyecto);
  }

  /** Lo llaman también TareasService y MiembrosService: cualquier escritura que afecte al proyecto. */
  async invalidar(id: string): Promise<void> {
    await this.cache.del(this.clave(id));
  }
}

Con varias instancias, el almacén debe ser Redis (CacheModule.registerAsync con cache-manager-redis-yet): una caché en memoria haría que la instancia B siguiera sirviendo datos viejos tras un cambio hecho por la A. El orden importa: si invalidas antes del flush, una lectura concurrente puede volver a cachear el valor antiguo entre la invalidación y el commit. Y el CacheInterceptor automático solo sirve para GET sin datos por usuario; si la respuesta depende de quién pregunta, o incluyes el usuario en la clave o filtras información entre cuentas (caso DEBUG-06).

// 1) Encolado idempotente: el jobId determinista impide duplicar el mismo trabajo lógico.
await this.cola.add(
  'resumen-diario',
  {usuarioId, fecha: '2026-07-31'},
  {
    jobId: `resumen:${usuarioId}:2026-07-31`,   // BullMQ ignora un add con jobId ya existente
    attempts: 5,
    backoff: {type: 'exponential', delay: 2_000},
    removeOnComplete: {age: 3600, count: 1000},
    removeOnFail: {age: 24 * 3600},
  },
);

// 2) Idempotencia REAL en el procesado: el jobId no basta si el worker muere a mitad.
@Processor('correos')
export class ResumenProcessor extends WorkerHost {
  constructor(private readonly em: EntityManager, private readonly correo: Notificador) { super(); }

  async process(trabajo: Job<{usuarioId: string; fecha: string}>): Promise<void> {
    const clave = `resumen:${trabajo.data.usuarioId}:${trabajo.data.fecha}`;

    // Inserción con clave única: si ya existe, este envío ya se hizo. Es una barrera
    // atómica en la base de datos, que es la única fuente de verdad fiable.
    try {
      await this.em.insert(EnvioRealizado, {clave, creadoEn: new Date()});
    } catch (e) {
      if (e instanceof UniqueConstraintViolationException) return;   // ya enviado: éxito silencioso
      throw e;
    }

    try {
      await this.correo.enviar(/* … */);
    } catch (e) {
      // Si el envío falla, se retira la marca para que el reintento pueda volver a intentarlo.
      await this.em.nativeDelete(EnvioRealizado, {clave});
      throw e;                                   // relanzar activa el backoff de BullMQ
    }
  }
}

La lección de fondo: «al menos una vez» es lo que garantiza cualquier cola; «exactamente una vez» lo tienes que construir tú, y se construye con una clave de idempotencia persistida en una tabla con restricción única. Confiar solo en jobId falla en el escenario clásico: el worker envía el correo, muere antes de marcar el trabajo como completado y BullMQ lo reencola.

@WebSocketGateway({namespace: '/eventos', cors: {origin: process.env['ORIGEN_WEB']}})
export class EventosGateway implements OnGatewayConnection {
  @WebSocketServer() servidor!: Server;

  constructor(private readonly jwt: JwtService, private readonly acceso: AccesoService) {}

  async handleConnection(cliente: Socket): Promise<void> {
    try {
      // El token NO se pone en la URL: queda en logs y en el historial del navegador.
      const token = cliente.handshake.auth?.['token'] as string | undefined;
      if (!token) throw new Error('sin token');
      const carga = await this.jwt.verifyAsync<{sub: string}>(token);
      cliente.data['usuarioId'] = carga.sub;
    } catch {
      cliente.disconnect(true);        // desconexión inmediata: nunca se une a ninguna sala
    }
  }

  @SubscribeMessage('unirse-proyecto')
  async unirse(@ConnectedSocket() cliente: Socket, @MessageBody() proyectoId: string): Promise<void> {
    const usuarioId = cliente.data['usuarioId'] as string;
    // Autorización por mensaje: estar conectado no da derecho a escuchar cualquier proyecto.
    if (!(await this.acceso.puedeVerProyecto(usuarioId, proyectoId))) {
      throw new WsException('Sin acceso a ese proyecto');
    }
    await cliente.join(`proyecto:${proyectoId}`);
  }

  emitirCambioTarea(proyectoId: string, tarea: TareaDto): void {
    this.servidor.to(`proyecto:${proyectoId}`).emit('tarea-actualizada', tarea);
  }
}

@Controller('salud')
export class SaludController {
  constructor(
    private readonly salud: HealthCheckService,
    private readonly orm: MikroOrmHealthIndicator,
    private readonly memoria: MemoryHealthIndicator,
    private readonly redis: RedisHealthIndicator,       // indicador propio
  ) {}

  /** LIVENESS: ¿el proceso está vivo? No comprueba dependencias externas. */
  @Publico() @Get('vivo')
  vivo() { return {estado: 'ok', tiempoActivo: process.uptime()}; }

  /** READINESS: ¿puede atender tráfico? Aquí sí se comprueban las dependencias. */
  @Publico() @Get('listo')
  @HealthCheck()
  listo() {
    return this.salud.check([
      () => this.orm.pingCheck('base-datos', {timeout: 1_500}),
      () => this.redis.estaDisponible('redis'),
      () => this.memoria.checkHeap('memoria', 400 * 1024 * 1024),
    ]);
  }
}

La distinción es operativamente crítica. Si liveness falla, Kubernetes reinicia el contenedor; si readiness falla, solo lo saca del balanceador hasta que se recupere. El error clásico es comprobar la base de datos en liveness: cuando la base de datos parpadea, Kubernetes reinicia en cascada todos los pods sanos y convierte una incidencia menor en una caída total.

describe('Tareas (e2e)', () => {
  let app: INestApplication;
  let orm: MikroORM;
  let tokenMiembro: string;
  let tokenLector: string;

  beforeAll(async () => {
    const modulo = await Test.createTestingModule({imports: [AppModule]})
      .overrideProvider(NOTIFICADOR).useClass(NotificadorEnMemoria)
      .compile();

    app = modulo.createNestApplication();
    app.useGlobalPipes(new ValidationPipe({whitelist: true, forbidNonWhitelisted: true, transform: true}));
    app.useGlobalFilters(new ProblemDetailsFilter());
    await app.init();

    orm = app.get(MikroORM);
    await orm.getSchemaGenerator().refreshDatabase();   // esquema limpio, base de datos real
    ({tokenMiembro, tokenLector} = await sembrarUsuarios(orm));
  });

  // Aislamiento: cada test parte del mismo estado conocido.
  beforeEach(async () => { await orm.getSchemaGenerator().clearDatabase(); await sembrarProyecto(orm); });
  afterAll(async () => { await app.close(); });

  it('POST /tareas crea y devuelve 201 con Location', async () => {
    const res = await request(app.getHttpServer())
      .post('/tareas')
      .set('Authorization', `Bearer ${tokenMiembro}`)
      .send({titulo: 'Escribir el test e2e', proyectoId: PROYECTO_ID, prioridad: 'alta'})
      .expect(201);

    expect(res.body.datos).toMatchObject({titulo: 'Escribir el test e2e', estado: 'pendiente'});
    expect(res.headers['location']).toMatch(/^\/tareas\//);
  });

  it('POST /tareas rechaza campos desconocidos con 400 y formato problem+json', async () => {
    const res = await request(app.getHttpServer())
      .post('/tareas')
      .set('Authorization', `Bearer ${tokenMiembro}`)
      .send({titulo: 'x', proyectoId: PROYECTO_ID, esAdmin: true})
      .expect(400)
      .expect('Content-Type', /application\/problem\+json/);
    expect(res.body.errors.cuerpo.join(' ')).toContain('esAdmin');
  });

  it('GET /tareas filtra y pagina', async () => {
    const res = await request(app.getHttpServer())
      .get('/tareas?estado=pendiente&pagina=1&tamano=2&orden=-vence')
      .set('Authorization', `Bearer ${tokenMiembro}`)
      .expect(200);
    expect(res.body.datos.length).toBeLessThanOrEqual(2);
  });

  it('DELETE /tareas/:id devuelve 403 para el rol lector', async () => {
    await request(app.getHttpServer())
      .delete(`/tareas/${TAREA_ID}`)
      .set('Authorization', `Bearer ${tokenLector}`)
      .expect(403);
  });

  it('GET /tareas/:id inexistente devuelve 404', async () => {
    await request(app.getHttpServer())
      .get('/tareas/00000000-0000-0000-0000-000000000000')
      .set('Authorization', `Bearer ${tokenMiembro}`)
      .expect(404);
  });
});

Dos decisiones importantes. Primera: base de datos real (PostgreSQL en Docker o Testcontainers), no SQLite en memoria; si el destino es PostgreSQL, un test contra SQLite no prueba los tipos, los índices parciales ni el comportamiento transaccional que vas a usar. Segunda: el aislamiento entre tests debe ser explícito. Limpiar y sembrar en beforeEach es lento pero infalible; envolver cada test en una transacción con rollback es mucho más rápido, pero solo funciona si el código bajo prueba no abre transacciones propias.

// ORM-01 · Las cuatro cardinalidades
@Entity()
export class Usuario {
  @PrimaryKey() id: string = v4();
  @Property({unique: true}) email!: string;
  // 1:1 propietario: la FK perfil_id vive en la tabla usuario.
  @OneToOne(() => Perfil, (p) => p.usuario, {owner: true, orphanRemoval: true}) perfil!: Perfil;
}

@Entity()
export class Proyecto {
  @PrimaryKey() id: string = v4();
  @Property() nombre!: string;
  // 1:N lado inverso: NO hay columna en proyecto; la FK está en tarea.proyecto_id.
  @OneToMany(() => Tarea, (t) => t.proyecto) tareas = new Collection<Tarea>(this);
}

@Entity()
@Index({properties: ['proyecto', 'estado']})   // el índice sigue al patrón de consulta real
export class Tarea {
  @PrimaryKey() id: string = v4();
  @Property({length: 160}) titulo!: string;
  @Enum(() => Estado) estado: Estado = Estado.Pendiente;

  // N:1 propietario: aquí está la FK. Es SIEMPRE el lado propietario en un 1:N.
  @ManyToOne(() => Proyecto, {deleteRule: 'cascade'}) proyecto!: Proyecto;

  // N:M propietario: MikroORM crea la tabla pivote tarea_etiquetas.
  @ManyToMany(() => Etiqueta, (e) => e.tareas, {owner: true}) etiquetas = new Collection<Etiqueta>(this);

  // Auto-referencia N:1: una tarea bloquea a otra.
  @ManyToOne(() => Tarea, {nullable: true}) dependeDe?: Tarea;
  @OneToMany(() => Tarea, (t) => t.dependeDe) bloquea = new Collection<Tarea>(this);
}

Regla que no falla: la clave foránea vive siempre en el lado @ManyToOne, y ese es el lado propietario. En un @OneToMany puro no hay ninguna columna nueva; si añades un elemento a la colección sin asignar el lado @ManyToOne, MikroORM lo resuelve, pero conviene asignar los dos lados para que el objeto en memoria sea coherente antes del flush.

// ORM-02 · Pivote con atributos: un @ManyToMany puro no puede almacenar rol ni fecha.
@Entity()
export class MiembroProyecto {
  @ManyToOne(() => Usuario, {primary: true}) usuario!: Usuario;
  @ManyToOne(() => Proyecto, {primary: true}) proyecto!: Proyecto;
  // La PK compuesta impide por diseño que alguien sea miembro dos veces del mismo proyecto.
  [PrimaryKeyProp]?: ['usuario', 'proyecto'];

  @Enum(() => RolProyecto) rol: RolProyecto = RolProyecto.Lector;
  @Property() altaEn: Date = new Date();
  @Property({nullable: true}) bajaEn?: Date;
}

La clave primaria compuesta es preferible a un id sintético más un índice único: expresa el invariante en el propio esquema y ahorra una columna y un índice. El coste es que las relaciones hacia esta entidad necesitan dos columnas.

// ORM-03 · Semántica de borrado, decidida por el dominio
@Entity()
export class Tarea {
  // Los comentarios NO tienen vida propia: si desaparece la tarea, desaparecen.
  @OneToMany(() => Comentario, (c) => c.tarea, {orphanRemoval: true})
  comentarios = new Collection<Comentario>(this);

  // Los adjuntos se conservan en un archivo documental aunque se borre la tarea.
  @OneToMany(() => Adjunto, (a) => a.tarea) adjuntos = new Collection<Adjunto>(this);
}

// El test que demuestra la diferencia
it('orphanRemoval borra al sacar de la colección; cascade REMOVE solo al borrar el padre', async () => {
  const tarea = await em.findOneOrFail(Tarea, {id}, {populate: ['comentarios']});
  const comentario = tarea.comentarios[0]!;

  tarea.comentarios.remove(comentario);   // solo se desvincula…
  await em.flush();
  // …pero con orphanRemoval: true la fila se BORRA, no queda con FK nula.
  expect(await em.count(Comentario, {id: comentario.id})).toBe(0);
});

Los tres conceptos que se confunden. cascade: [Cascade.REMOVE] propaga el borrado del padre a los hijos, y lo hace en memoria, cargando las entidades. orphanRemoval: true hace eso y además borra al hijo cuando se le saca de la colección. deleteRule: 'cascade' es una cláusula ON DELETE CASCADE en la base de datos: es la más rápida (una sola sentencia) pero invisible para el ORM, así que los hooks y suscriptores de las entidades hijas no se ejecutan. Elige el nivel de base de datos para volúmenes grandes y el nivel de ORM cuando necesites lógica de dominio.

// ORM-04 · Son 51 consultas: 1 del listado + 1 por proyecto al tocar la colección.
// MAL: la colección se carga perezosamente dentro del bucle.
const proyectos = await em.find(Proyecto, {}, {limit: 50});
for (const p of proyectos) console.log(p.nombre, (await p.tareas.loadItems()).length);

// BIEN (opción A): populate declarativo. MikroORM emite UNA segunda consulta con IN (…).
const proyectos = await em.find(Proyecto, {}, {populate: ['tareas'], limit: 50});

// BIEN (opción B): si solo necesitas el recuento, no traigas las filas.
const filas = await em.createQueryBuilder(Proyecto, 'p')
  .select(['p.id', 'p.nombre', 'count(t.id) as total'])
  .leftJoin('p.tareas', 't')
  .groupBy('p.id')
  .limit(50)
  .execute<Array<{id: string; nombre: string; total: string}>>();

Cómo se detecta antes de que llegue a producción: activa debug: ['query'] en desarrollo y pon un umbral en los tests («esta ruta no debe emitir más de 3 consultas») usando un contador sobre el logger. Un N+1 no se ve en local con 10 filas de prueba; se ve en producción con 5.000.

// ORM-05 · Filtros dinámicos: se construye un objeto FilterQuery, nunca una cadena SQL.
async function listar(f: FiltroTareas, pagina: number, tamano: number) {
  const where: FilterQuery<Tarea> = {};
  if (f.estado)        where.estado = f.estado;
  if (f.prioridad?.length) where.prioridad = {$in: f.prioridad};
  if (f.venceAntesDe)  where.vence = {$lte: f.venceAntesDe};
  if (f.asignadoA)     where.asignado = f.asignadoA;
  if (f.texto)         where.titulo = {$ilike: `%${f.texto}%`};   // parametrizado por el ORM
  // Etiquetas en Y: una condición por etiqueta, no un $in (que sería una O).
  if (f.etiquetas?.length) where.$and = f.etiquetas.map((e) => ({etiquetas: {nombre: e}}));

  const [datos, total] = await em.findAndCount(Tarea, where, {
    populate: ['asignado', 'etiquetas'],
    orderBy: {vence: 'ASC', id: 'ASC'},     // desempate estable: sin él la paginación baila
    limit: tamano,
    offset: (pagina - 1) * tamano,
  });
  return {datos, total, pagina, tamano};
}

// ORM-06 · Agregados con HAVING
const filas = await em.createQueryBuilder(Proyecto, 'p')
  .select(['p.id', 'p.nombre'])
  .addSelect('count(t.id) as total')
  .addSelect(`count(t.id) filter (where t.estado = 'pendiente') as pendientes`)
  .addSelect(`avg(case when t.vence < now() and t.estado <> 'hecha'
                       then extract(day from now() - t.vence) end) as dias_retraso`)
  .leftJoin('p.tareas', 't')
  .groupBy(['p.id', 'p.nombre'])
  .having(`count(t.id) filter (where t.estado = 'pendiente') > ?`, [10])
  .orderBy({dias_retraso: 'DESC NULLS LAST'})
  .execute<FilaResumen[]>();

WHERE filtra filas antes de agrupar; HAVING filtra grupos después. Poner estado = 'pendiente' en el WHERE daría un resultado distinto: perderías los proyectos sin ninguna pendiente y el total dejaría de ser el total.

// ORM-07 · Paginación por cursor sobre (vence, id)
interface Cursor { vence: string; id: string }
const codificar = (c: Cursor) => Buffer.from(JSON.stringify(c)).toString('base64url');
const decodificar = (s: string) => JSON.parse(Buffer.from(s, 'base64url').toString()) as Cursor;

async function pagina(cursor: string | undefined, tamano = 20) {
  const where: FilterQuery<Tarea> = {};
  if (cursor) {
    const c = decodificar(cursor);
    // Comparación lexicográfica de la tupla: «lo que vaya después de (vence, id)».
    where.$or = [{vence: {$gt: c.vence}}, {vence: c.vence, id: {$gt: c.id}}];
  }
  const filas = await em.find(Tarea, where, {orderBy: {vence: 'ASC', id: 'ASC'}, limit: tamano + 1});
  const hayMas = filas.length > tamano;
  const datos = hayMas ? filas.slice(0, tamano) : filas;
  const ultimo = datos.at(-1);
  return {
    datos,
    siguiente: hayMas && ultimo ? codificar({vence: ultimo.vence.toISOString(), id: ultimo.id}) : null,
  };
}

Qué resuelve. Dos cosas. Rendimiento: OFFSET 100000 obliga a PostgreSQL a leer y descartar cien mil filas, y el tiempo crece linealmente con la página; el cursor usa el índice (vence, id) y cuesta lo mismo en la página 1 que en la 5.000. Corrección: con OFFSET, si alguien inserta una fila mientras paginas, verás un elemento repetido o te saltarás otro. Qué pierdes: no puedes saltar a la página 37 ni mostrar «página 3 de 200», y el orden debe ser único y estable (de ahí el desempate por id). Regla práctica: cursor para scroll infinito y APIs; offset para tablas de administración con pocas páginas.

// ORM-08 · Bloqueo pesimista: se serializa el acceso a las filas implicadas.
await em.transactional(async (em) => {
  // SELECT … FOR UPDATE: cualquier otra transacción que pida estas filas espera aquí.
  const destino = await em.find(Tarea,
    {columna: columnaDestinoId},
    {lockMode: LockMode.PESSIMISTIC_WRITE, orderBy: {posicion: 'ASC'}});
    // orderBy en TODAS las transacciones que bloqueen: bloquear en distinto orden = interbloqueo.

  const tarea = await em.findOneOrFail(Tarea, {id: tareaId}, {lockMode: LockMode.PESSIMISTIC_WRITE});

  tarea.columna = em.getReference(Columna, columnaDestinoId);
  destino.filter((t) => t.id !== tarea.id && t.posicion >= nuevaPosicion)
         .forEach((t) => { t.posicion += 1; });
  tarea.posicion = nuevaPosicion;
});   // el commit libera los bloqueos

Coste real del bloqueo pesimista: las transacciones se serializan, así que la transacción debe ser corta y no contener llamadas HTTP ni envíos de correo. Mantén siempre el mismo orden de bloqueo (por eso el orderBy) o dos transacciones que bloqueen A→B y B→A se quedarán en interbloqueo hasta que PostgreSQL mate a una.

// ORM-09 · Bloqueo optimista: sin bloqueos, se detecta el conflicto al escribir.
@Entity()
export class Tarea {
  @Property({version: true}) version!: number;   // UPDATE … WHERE id = ? AND version = ?
}

// En el servicio: la versión llega del cliente (cabecera If-Match o campo del DTO).
async actualizar(id: string, dto: ActualizarTareaDto, versionCliente: number) {
  const tarea = await this.em.findOneOrFail(Tarea, {id});
  try {
    this.em.assign(tarea, dto);
    await this.em.lock(tarea, LockMode.OPTIMISTIC, {lockVersion: versionCliente});
    await this.em.flush();
    return tarea;
  } catch (e) {
    if (e instanceof OptimisticLockError) {
      // 409 con el estado actual: el cliente puede mostrar un diff y dejar decidir al usuario.
      throw new ConflictException({
        title: 'La tarea fue modificada por otra persona',
        actual: aDto(await this.em.refresh(tarea) ?? tarea),
      });
    }
    throw e;
  }
}

Optimista frente a pesimista: usa el optimista cuando el conflicto es raro (edición de un formulario por dos personas) porque no cuesta nada mientras no ocurra; usa el pesimista cuando el conflicto es frecuente y caro (inventario, asientos, saldos). Nunca uses «leer, comprobar en JavaScript y escribir» sin ninguno de los dos: entre la lectura y la escritura cabe otra transacción entera.

// ORM-10 · Soft delete con filtro global
@Entity()
@Filter({name: 'noBorradas', cond: {borradaEn: null}, default: true})
export class Tarea {
  @Property({nullable: true, index: true}) borradaEn?: Date;
}

// Consultas normales: el filtro se aplica solo. Para verlas todas:
const todas = await em.find(Tarea, {}, {filters: {noBorradas: false}});

-- El índice único parcial: la unicidad solo se exige entre las filas vivas.
create unique index tarea_titulo_unico_vivas
  on tarea (proyecto_id, lower(titulo))
  where borrada_en is null;

Sin la cláusula where, borrar una tarea llamada «Desplegar» impediría para siempre crear otra con ese nombre, lo que produce el ticket de soporte más desconcertante posible. Ten en cuenta también que un filtro global es fácil de saltarse: las consultas nativas, el QueryBuilder con disableFilters y las claves foráneas de la base de datos no lo conocen.

-- ORM-11 · Expand / migrate / contract: tres despliegues, cero tiempo de inactividad.

-- (1) EXPAND. Se despliega ANTES que el código nuevo. Compatible con el código viejo.
alter table tarea add column descripcion text;
update tarea set descripcion = "desc" where descripcion is null;
-- Disparador que mantiene ambas columnas sincronizadas mientras convivan las dos versiones:
create function sync_desc() returns trigger as $$
begin
  new.descripcion := coalesce(new.descripcion, new."desc");
  new."desc" := coalesce(new."desc", new.descripcion);
  return new;
end $$ language plpgsql;
create trigger tarea_sync_desc before insert or update on tarea
  for each row execute function sync_desc();

-- (2) Se despliega el CÓDIGO NUEVO, que solo usa `descripcion`. Se espera a que
--     todas las instancias viejas hayan desaparecido (y a poder revertir con seguridad).

-- (3) CONTRACT. Despliegue posterior, cuando ya nadie usa la columna vieja.
drop trigger tarea_sync_desc on tarea;
drop function sync_desc();
alter table tarea drop column "desc";

Un ALTER TABLE … RENAME COLUMN directo rompe el servicio durante los segundos o minutos en que conviven las dos versiones del código: las instancias viejas consultan una columna que ya no existe. La regla general de las migraciones sin parada: cada migración debe ser compatible con la versión anterior y con la siguiente del código. Lo mismo aplica a añadir una columna NOT NULL (añádela nullable, rellena y luego impón la restricción) y a borrar cualquier cosa.

// ORM-12 · Seeder con factorías reproducibles
export class TareaFactory extends Factory<Tarea> {
  model = Tarea;
  protected definition(faker: Faker): EntityData<Tarea> {
    return {
      titulo: faker.hacker.phrase().slice(0, 120),
      prioridad: faker.helpers.arrayElement(['baja', 'media', 'alta']),
      estado: faker.helpers.weightedArrayElement([
        {weight: 6, value: 'pendiente'}, {weight: 3, value: 'en_curso'}, {weight: 1, value: 'hecha'},
      ]),
      vence: faker.date.between({from: '2026-01-01', to: '2026-12-31'}),
    };
  }
}

export class DatabaseSeeder extends Seeder {
  async run(em: EntityManager): Promise<void> {
    faker.seed(20260731);          // semilla fija: los datos son IDÉNTICOS en cada ejecución
    const usuarios = new UsuarioFactory(em).make(20);
    for (const proyecto of new ProyectoFactory(em).make(5)) {
      new TareaFactory(em).each((t) => {
        t.proyecto = proyecto;
        t.asignado = faker.helpers.arrayElement(usuarios);
      }).make(100);
    }
    await em.flush();              // un único flush: una transacción, no 500
  }
}

// ORM-13 · Suscriptor de auditoría
@Injectable()
export class AuditoriaSubscriber implements EventSubscriber<Tarea> {
  constructor(em: EntityManager, private readonly ctx: ContextoPeticionService) {
    em.getEventManager().registerSubscriber(this);
  }
  getSubscribedEntities() { return [Tarea]; }

  // onFlush es el ÚNICO momento en que el changeset original sigue disponible.
  async onFlush(args: FlushEventArgs): Promise<void> {
    const uow = args.uow;
    for (const cambio of uow.getChangeSets()) {
      if (!(cambio.entity instanceof Tarea)) continue;

      const registro = args.em.create(Auditoria, {
        entidad: 'Tarea',
        entidadId: cambio.entity.id,
        operacion: cambio.type,                       // create | update | delete
        cambios: cambio.payload,                      // solo los campos modificados
        anterior: cambio.originalEntity ?? null,
        usuarioId: this.ctx.usuarioActual()?.id ?? null,
        creadoEn: new Date(),
      });
      // Hay que registrar el nuevo objeto en la MISMA unidad de trabajo, o no se persistirá.
      uow.computeChangeSet(registro);
    }
  }
}

Los suscriptores son la respuesta correcta a «necesito que esto pase siempre, sin que nadie tenga que acordarse»: auditoría, invalidación de caché, publicación de eventos de dominio. La trampa es el momento: en afterFlush el changeset ya no tiene los valores anteriores, y en onFlush hay que llamar a computeChangeSet para que las entidades creadas dentro del suscriptor entren en la misma transacción.

// ORM-14 · 100.000 filas con memoria acotada
import {createReadStream} from 'node:fs';
import {parse} from 'csv-parse';

const TAMANO_LOTE = 1_000;

export async function importar(ruta: string, orm: MikroORM): Promise<number> {
  const em = orm.em.fork();                    // NUNCA el em global en un proceso largo
  const flujo = createReadStream(ruta).pipe(parse({columns: true, trim: true}));

  let lote: EntityData<Tarea>[] = [];
  let total = 0;

  const volcar = async () => {
    if (lote.length === 0) return;
    // insertMany omite el Unit of Work: no crea entidades gestionadas ni dispara hooks.
    await em.insertMany(Tarea, lote);
    total += lote.length;
    lote = [];
    em.clear();          // vacía el Identity Map: SIN ESTO la memoria crece sin límite
  };

  for await (const fila of flujo) {            // el stream aplica contrapresión: no lee todo el CSV
    lote.push({id: v4(), titulo: fila.titulo, proyecto: fila.proyecto_id, estado: 'pendiente'});
    if (lote.length >= TAMANO_LOTE) await volcar();
  }
  await volcar();
  return total;
}

Los tres errores que hacen explotar la memoria: leer el archivo entero con readFileSync en lugar de un flujo; hacer em.persist() de las 100.000 entidades y un solo flush al final (el Identity Map las retiene todas); y olvidar em.clear() entre lotes, que es exactamente el mismo problema en cámara lenta. Con esta versión la memoria se mantiene plana porque en ningún momento hay más de 1.000 objetos vivos.

-- SQL-01 · LEFT JOIN en el asignado (puede no existir), INNER en el proyecto (siempre existe).
select t.titulo, p.nombre as proyecto, u.email as asignado
from tarea t
join proyecto p on p.id = t.proyecto_id
left join usuario u on u.id = t.asignado_id
where p.nombre = 'Rediseño' and t.estado = 'pendiente' and t.borrada_en is null
order by t.vence nulls last;

-- SQL-02 · FILTER es la forma limpia del agregado condicional en PostgreSQL.
select p.nombre,
       count(t.id)                                        as total,
       count(t.id) filter (where t.estado = 'pendiente')   as pendientes,
       round(100.0 * count(t.id) filter (where t.estado = 'hecha')
             / nullif(count(t.id), 0), 1)                  as pct_completado
from proyecto p
left join tarea t on t.proyecto_id = p.id and t.borrada_en is null
group by p.id, p.nombre
having count(t.id) filter (where t.estado = 'pendiente') > 10
order by pendientes desc;

-- SQL-03 · Subconsulta correlacionada: se evalúa una vez por fila externa.
select u.email,
       (select t.titulo from tarea t
        where t.asignado_id = u.id and t.estado = 'pendiente' and t.borrada_en is null
        order by t.vence asc nulls last, t.id
        limit 1) as tarea_mas_urgente
from usuario u
order by u.email;
-- Alternativa casi siempre más rápida en PostgreSQL: LATERAL.
select u.email, x.titulo
from usuario u
left join lateral (
  select t.titulo from tarea t
  where t.asignado_id = u.id and t.estado = 'pendiente'
  order by t.vence asc nulls last, t.id limit 1
) x on true;

-- SQL-04 · CTE recursiva sobre comentarios anidados.
with recursive hilo as (
  select c.id, c.padre_id, c.texto, c.creado_en, 0 as nivel,
         -- camino jerárquico: fecha + id como texto, para ordenar hijos bajo su padre
         array[to_char(c.creado_en, 'YYYYMMDDHH24MISS') || ':' || c.id::text] as camino
  from comentario c
  where c.tarea_id = $1 and c.padre_id is null
  union all
  select h2.id, h2.padre_id, h2.texto, h2.creado_en, hilo.nivel + 1,
         hilo.camino || (to_char(h2.creado_en, 'YYYYMMDDHH24MISS') || ':' || h2.id::text)
  from comentario h2
  join hilo on h2.padre_id = hilo.id
  where hilo.nivel < 20                     -- cortafuegos contra ciclos y árboles patológicos
)
select repeat('  ', nivel) || texto as comentario, nivel
from hilo
order by camino;

-- SQL-05 · Ranking por partición.
with completadas as (
  select t.proyecto_id, t.asignado_id, count(*) as n
  from tarea t
  where t.estado = 'hecha' and t.asignado_id is not null
  group by t.proyecto_id, t.asignado_id
), ordenadas as (
  select c.*, dense_rank() over (partition by c.proyecto_id order by c.n desc) as puesto
  from completadas c
)
select p.nombre as proyecto, u.email, o.n as completadas, o.puesto
from ordenadas o
join proyecto p on p.id = o.proyecto_id
join usuario  u on u.id = o.asignado_id
where o.puesto <= 3
order by p.nombre, o.puesto;

Los dos errores clásicos. En SQL-01, poner la condición del asignado en el WHERE en lugar de en el ON convierte un LEFT JOIN en un INNER JOIN encubierto y hace desaparecer las tareas sin asignar. En SQL-05, row_number() daría exactamente 3 filas rompiendo empates de forma arbitraria; rank() deja huecos tras un empate; dense_rank() no los deja. Elige según lo que signifique «los 3 primeros» en tu dominio.

-- SQL-06 · Acumulado con marco de ventana explícito.
select date_trunc('week', creado_en)::date as semana,
       count(*) as creadas,
       sum(count(*)) over (order by date_trunc('week', creado_en)
                           rows between unbounded preceding and current row) as acumulado
from tarea
where creado_en >= date '2026-01-01' and creado_en < date '2027-01-01'
group by 1
order by 1;
-- sum(count(*)) no es un error: el agregado se calcula primero y la ventana se aplica al resultado.

-- SQL-07 · NOT EXISTS es más legible y suele ser más rápido que un LEFT JOIN … IS NULL.
select t.id, t.titulo, t.creado_en, t.actualizado_en
from tarea t
where t.estado = 'pendiente'
  and t.borrada_en is null
  and t.creado_en < now() - interval '30 days'
  and t.actualizado_en < now() - interval '14 days'
  and not exists (
    select 1 from comentario c
    where c.tarea_id = t.id and c.creado_en >= now() - interval '14 days'
  )
order by t.creado_en;

-- SQL-08 · Diagnóstico: Seq Scan sobre 2.000.000 de filas, 1.970.898 descartadas por el filtro,
-- 31.892 bloques leídos de disco y una ordenación posterior. No hay índice utilizable.
create index concurrently tarea_proyecto_estado_vence
  on tarea (proyecto_id, estado, vence)
  where borrada_en is null;
-- El orden de las columnas importa: primero las de igualdad (proyecto_id, estado) y después
-- la del ORDER BY (vence). Así el índice sirve para filtrar Y para ordenar, y el LIMIT 20
-- puede parar tras leer 20 entradas: el plan pasa a Index Scan y de ~810 ms a <1 ms.
-- CONCURRENTLY evita bloquear la tabla en producción (no puede ir dentro de una transacción).

-- SQL-09 · Upsert idempotente. Requiere el índice único correspondiente.
create unique index if not exists etiqueta_nombre_unico on etiqueta (lower(nombre));

insert into etiqueta (id, nombre)
values (gen_random_uuid(), $1)
on conflict (lower(nombre))
do update set nombre = excluded.nombre   -- «no-op» necesario para que RETURNING devuelva fila
returning id, nombre, (xmax = 0) as fue_insertada;
-- Con DO NOTHING, RETURNING no devuelve nada cuando la fila ya existía: es el fallo típico.

-- SQL-10 · Consulta de auditoría sobre jsonb.
select a.creado_en, u.email as autor,
       a.cambios -> 'estado' ->> 'anterior' as estado_anterior,
       a.cambios -> 'estado' ->> 'nuevo'    as estado_nuevo,
       t.titulo
from auditoria a
join tarea t    on t.id = a.entidad_id and a.entidad = 'Tarea'
join proyecto p on p.id = t.proyecto_id
left join usuario u on u.id = a.usuario_id
where p.nombre = 'Rediseño'
  and a.creado_en >= now() - interval '7 days'
  and a.cambios ? 'estado'          -- el operador ? comprueba la existencia de la clave
order by a.creado_en desc;
-- Para que esto escale hace falta un índice GIN: create index on auditoria using gin (cambios);

Cómo leer un EXPLAIN en treinta segundos: busca primero Seq Scan sobre tablas grandes, después Rows Removed by Filter muy alto (leíste mucho para tirarlo casi todo), y por último la diferencia entre las filas estimadas y las reales (si difieren en un orden de magnitud, las estadísticas están desfasadas y necesitas ANALYZE). BUFFERS distingue lo que vino de memoria (hit) de lo que vino de disco (read), que es donde se va el tiempo.

Causa raíz. Con OnPush, Angular solo revisa el componente si cambia la referencia de una entrada. push muta el array en su sitio: la referencia es la misma, así que el componente nunca se marca como sucio. Al redimensionar la ventana se dispara un evento que provoca una detección global y «arregla» la pantalla, lo que da la pista definitiva.

Cómo se detecta. Si al quitar OnPush funciona, es un problema de referencias, no de datos. Confírmalo comparando tareas antes y después con ===.

Corrección. Reemplazar la referencia o, mejor, usar señales, que notifican por sí mismas:

readonly tareas = input.required<readonly Tarea[]>();
readonly anadida = output<Tarea>();
// El padre actualiza inmutablemente: this.lista.update((ts) => [...ts, nueva]);

Prevención. Tipa las entradas como readonly T[]: el compilador rechazará push. Usa OnPush en todos los componentes desde el primer día (si lo activas al final, aparecen veinte fallos como este a la vez) y estado en señales.

Causa raíz. El EntityManager inyectado es el global. En las peticiones HTTP, el middleware de @mikro-orm/nestjs crea un contexto por petición (con AsyncLocalStorage) y cada una recibe su propio fork con su Identity Map y su Unit of Work. Un trabajo programado o un procesador de cola se ejecutan fuera de ese contexto, así que reutilizan el manager global: la primera ejecución lo deja lleno de entidades gestionadas y la segunda encuentra un estado sucio.

Cómo se detecta. El propio mensaje lo dice. La pista adicional es que solo falla fuera del ciclo HTTP: cron, colas, WebSockets y onApplicationBootstrap.

@Cron('0 6 * * *')
async generarResumen(): Promise<void> {
  // fork() da un EntityManager limpio y aislado: propio Identity Map, propia transacción.
  const em = this.em.fork();
  const tareas = await em.find(Tarea, {vence: {$lte: new Date()}});
  for (const t of tareas) t.notificada = true;
  await em.flush();
}
// Alternativa equivalente: envolver todo en RequestContext.create(this.orm.em, async () => { … })

Prevención. Regla de equipo: todo punto de entrada que no sea HTTP empieza con un fork(). Y añade un test que ejecute el trabajo dos veces seguidas en el mismo proceso; es justo el escenario que nadie prueba.

Causa raíz (test 1). No hay ORDER BY. SQL no garantiza ningún orden sin él; en local, con la tabla recién creada, PostgreSQL devuelve las filas en orden físico de inserción y parece que funciona. En CI, con otro plan o tras un VACUUM, el orden cambia. Es un test que nunca fue correcto: simplemente tenía suerte.

Causa raíz (test 2). agruparPorDia usa la zona horaria local del proceso. En tu máquina (Europe/Madrid, UTC+1) las 23:30 UTC son las 00:30 del día 16; en CI (UTC) siguen siendo el día 15. El test codifica la zona horaria del desarrollador.

Cómo se detecta. Ejecuta en local con el entorno de CI: TZ=UTC npm test. Para el orden, ejecuta la suite con semilla aleatoria (vitest --sequence.shuffle): los tests que dependen del orden caen enseguida.

// 1) Orden explícito y desempate estable.
const tareas = await em.find(Tarea, {proyecto: p.id}, {orderBy: {creadoEn: 'DESC', id: 'DESC'}, limit: 3});

// 2) La zona horaria es un parámetro del dominio, no del entorno.
export function agruparPorDia(fechas: Date[], zona = 'Europe/Madrid'): Record<string, Date[]> { … }

Prevención. Fija TZ=UTC en local y en CI y trata la zona como dato explícito; nunca uses new Date() directamente en la lógica de negocio (inyecta un reloj); y ordena siempre de forma determinista. Un test intermitente que se «arregla» reintentando es deuda técnica con intereses.

Causa raíz: dos fugas superpuestas. La primera y más grave es el Scope.REQUEST combinado con bus.on(...): se crea una instancia del servicio por petición y cada una registra un listener que nunca se elimina. El emisor mantiene una referencia al closure, el closure al servicio y el servicio a su caché, así que nada se puede recolectar. Con 10 peticiones por segundo son 216.000 listeners en seis horas. La segunda fuga es la caché sin límite ni caducidad: si la clave tiene alta cardinalidad, crece indefinidamente.

Cómo se detecta. Registra process.memoryUsage().heapUsed cada minuto: una fuga da una recta ascendente que los GC no bajan, frente al diente de sierra normal. Después, node --inspect, dos instantáneas del montón separadas por diez minutos y la vista «Comparison» de Chrome DevTools: el tipo con más objetos retenidos aparece arriba. En este caso process.listenerCount('tarifas.actualizadas') o el aviso MaxListenersExceededWarning lo delatan de inmediato.

@Injectable()                                     // singleton: UNA instancia, UN listener
export class TarifasService implements OnModuleInit, OnModuleDestroy {
  private readonly cache = new LRUCache<string, Tarifa>({max: 5_000, ttl: 5 * 60_000});
  private readonly limpiar = () => this.cache.clear();

  onModuleInit(): void { this.bus.on('tarifas.actualizadas', this.limpiar); }
  onModuleDestroy(): void { this.bus.off('tarifas.actualizadas', this.limpiar); }   // simétrico
}

Prevención. Todo on necesita su off en el hook de destrucción simétrico, y para poder quitarlo hace falta guardar la referencia de la función (una flecha en línea es imposible de desregistrar). Toda caché en memoria necesita max y ttl. Y usa Scope.REQUEST solo cuando de verdad lo necesites: además de este riesgo, obliga a instanciar toda la cadena de dependencias en cada petición.

Causa raíz: tres problemas encadenados. (1) N+1 por partida triple: con 200 proyectos son 1 + 200 + 200 + 200 = 601 consultas, y encima tareas.loadItems() se llama dos veces. (2) Se transfiere todo: si cada proyecto tiene 500 tareas, son 100.000 filas serializadas a JSON para pintar una lista. (3) No hay paginación ni límite: el coste crece sin techo con los datos.

Cómo se detecta. Activa debug: ['query'] y cuenta líneas; o mira las métricas de la base de datos: muchas consultas rápidas en lugar de una lenta es la firma inconfundible del N+1. El tamaño de la respuesta en el panel de red confirma el punto 2.

@Get()
async listar(@Query() q: ListarProyectosDto): Promise<Pagina<ProyectoResumenDto>> {
  // Una sola consulta con agregados: no se cargan las tareas, se cuentan en la base de datos.
  const qb = this.em.createQueryBuilder(Proyecto, 'p')
    .select(['p.id', 'p.nombre', 'p.creadoEn'])
    .addSelect(`count(t.id) filter (where t.estado = 'pendiente') as pendientes`)
    .leftJoin('p.tareas', 't')
    .groupBy(['p.id'])
    .orderBy({'p.creadoEn': 'DESC'})
    .limit(q.tamano).offset((q.pagina - 1) * q.tamano);

  const [datos, total] = await Promise.all([qb.execute<ProyectoResumenDto[]>(), this.em.count(Proyecto)]);
  return {datos, total, pagina: q.pagina, tamano: q.tamano};
}

Prevención. Ningún endpoint de listado sin paginación obligatoria con un tamaño máximo. Un DTO de resumen distinto del DTO de detalle: la lista no necesita las tareas. Y un test de rendimiento que falle si una ruta supera un número de consultas: es la única forma de que el N+1 no vuelva en el siguiente sprint.

Causa raíz. Dos fallos que se refuerzan. (1) Un proveedor de NestJS es singleton por defecto: hay una sola instancia para todo el proceso. Guardar el usuario en un campo significa que la petición de B sobrescribe el campo justo entre el establecer() y el await de la petición de A. Es una condición de carrera clásica y solo se manifiesta con concurrencia, de ahí que en local no aparezca. (2) La clave de caché 'panel' es global: el primer panel calculado se sirve a todo el mundo durante 60 segundos.

Cómo se detecta. Prueba de carga con dos usuarios distintos en paralelo (autocannon, k6) comprobando que cada respuesta corresponde a su token. Y una auditoría del código: cualquier campo mutable en un proveedor singleton es sospechoso.

@Injectable()
export class PerfilService {
  // El usuario se pasa explícitamente: sin estado compartido no hay carrera posible.
  async panel(usuarioId: string): Promise<PanelDto> {
    const clave = `panel:${usuarioId}`;                // la clave SIEMPRE incluye la identidad
    const enCache = await this.cache.get<PanelDto>(clave);
    if (enCache) return enCache;
    const dto = await this.construir(usuarioId);
    await this.cache.set(clave, dto, 60_000);
    return dto;
  }
}
// En el controlador: this.perfil.panel(peticion.usuario.id)
// Alternativa cuando la firma se ensucia demasiado: AsyncLocalStorage (ver TS-10) o nestjs-cls.

Prevención. Prohíbe por convención el estado mutable en singletons y revísalo en cada pull request. Toda clave de caché lleva el identificador de usuario o de tenant. Y en la base de datos, filtros de acceso obligatorios (un filtro global de MikroORM por tenant o row level security de PostgreSQL) para que el fallo sea imposible incluso si alguien olvida el WHERE. Este tipo de fallo es notificable como brecha de datos bajo el RGPD: no es un bug menor.

Causa raíz. El interceptor se aplica a todas las peticiones, incluida /auth/refresh. Si el refresco devuelve 401 (porque el refresh token también ha caducado), el catchError vuelve a llamar al refresco, que vuelve a dar 401: recursión infinita. Además se reintenta con conToken, que lleva el token viejo ya clonado, así que el reintento vuelve a dar 401 aunque el refresco funcione. Y como no hay deduplicación, diez peticiones simultáneas lanzan diez refrescos que, con rotación de tokens, se invalidan entre sí.

Cómo se detecta. El panel de red lo enseña de inmediato: la misma URL repetida sin fin. Un contador de reintentos por petición o un tope de profundidad convierte el bucle en un error visible.

Corrección. Las tres piezas de la solución de NG-10: excluir las rutas de autenticación mediante lista, clonar la petición después de obtener el token nuevo, y compartir un único refresco en curso con shareReplay. Si el refresco falla, cerrar la sesión y redirigir al login en lugar de reintentar.

Prevención. Un test que simule dos 401 seguidos y afirme que solo se emite un POST /auth/refresh, con HttpTestingController. Y un límite duro de un reintento por petición, para que un fallo futuro degrade en un error y no en una tormenta de peticiones que puede tumbar tu propio servidor de autenticación.

Causa raíz: tres errores en cuatro líneas. (1) {...tarea, ...dto} produce un objeto plano, no una entidad gestionada: MikroORM sigue el patrón Data Mapper y solo escribe los cambios de las entidades que su Unit of Work vigila; ese objeto nuevo es invisible para él. (2) persist() únicamente marca para persistir; quien escribe en la base de datos es flush(). (3) La respuesta se construye con el objeto en memoria, por lo que parece correcta y oculta el fallo. El as Tarea es la señal de alarma: una aserción que silencia al compilador cuando este tenía razón.

Cómo se detecta. Activa el registro de SQL: no aparece ningún UPDATE. Y añade siempre al test de actualización un em.clear() seguido de una relectura, que es lo que reproduce el «recargar la página».

async actualizar(id: string, dto: ActualizarTareaDto): Promise<Tarea> {
  const tarea = await this.em.findOneOrFail(Tarea, {id});
  this.em.assign(tarea, dto);       // muta la entidad GESTIONADA: el UoW detecta el cambio
  await this.em.flush();            // aquí, y solo aquí, se emite el UPDATE
  return tarea;
}

// El test que lo habría detectado:
it('persiste el cambio', async () => {
  await servicio.actualizar(id, {titulo: 'Nuevo'});
  em.clear();                                        // vacía el Identity Map: obliga a releer
  const releida = await em.findOneOrFail(Tarea, {id});
  expect(releida.titulo).toBe('Nuevo');
});

Prevención. Interioriza el modelo: cargar → mutar la entidad → flush. Nunca copies entidades con spread; usa em.assign o wrap(entidad).assign(). Y que todo test de escritura incluya un em.clear() antes de comprobar, o estarás verificando la memoria en lugar de la base de datos.

Decisión central: cómo garantizar la no superposición. Tres alternativas y sus consecuencias:

create extension if not exists btree_gist;
alter table reserva add column periodo tstzrange
  generated always as (tstzrange(inicio, fin, '[)')) stored;
alter table reserva add constraint reserva_sin_solape
  exclude using gist (sala_id with =, periodo with &&) where (estado = 'confirmada');

Razonamiento. Elijo la tercera. La corrección de un invariante de negocio tan duro no debe depender de que todos los caminos del código recuerden bloquear: se declara una vez en el esquema y ya no se puede violar, ni desde una migración, ni desde un script de importación, ni desde otro servicio. El where (estado = 'confirmada') permite que convivan solicitudes pendientes y canceladas sobre el mismo hueco. El coste es acoplarse a PostgreSQL, algo que asumo sin dudar: la portabilidad entre motores es un requisito imaginario en el 95 % de los proyectos.

Recurrencia: guardar la regla (RRULE de iCalendar) y materializar las ocurrencias como filas hasta un horizonte (por ejemplo 12 meses), regenerándolas con un trabajo programado. Solo la regla impide usar la restricción de exclusión y obliga a expandir en cada consulta; solo las filas impide editar «la serie entera». Con las dos cosas, cada ocurrencia puede además desviarse (mover una sesión concreta) mediante una fila de excepción.

Zonas horarias: almacenar siempre timestamptz (UTC) y guardar aparte la zona IANA de la sede ('Europe/Madrid', nunca un desfase fijo, que se rompe con el horario de verano). La recurrencia se expande en la zona de la sede: «todos los martes a las 10:00» debe seguir siendo a las 10:00 locales después del cambio de hora, aunque el instante UTC cambie.

Lista de espera: tabla propia con orden de llegada y ventana de aceptación; al cancelarse una reserva, un evento de dominio notifica al primero y le reserva el hueco durante N minutos.

Recomendación: monolito modular. Un único despliegue, una única base de datos, pero con módulos de NestJS de fronteras explícitas, cada uno con su esquema de base de datos propio y comunicación entre módulos solo a través de interfaces publicadas y eventos, nunca por consultas SQL cruzadas.

Razonamiento cuantitativo. Con 7 desarrolladores no hay problema de coordinación que resolver: la ley de Conway funciona en los dos sentidos y 8 servicios para 7 personas significa que todos tocan todo, con el coste de los microservicios y ninguna de sus ventajas. Los costes son concretos y se pagan desde el primer día: transacciones distribuidas (adiós al ACID, hola a las sagas), depuración a través de la red, ocho pipelines, ocho conjuntos de secretos, versionado de contratos, latencia añadida y observabilidad distribuida obligatoria. Los beneficios (escalado independiente, aislamiento de fallos, despliegue independiente, heterogeneidad tecnológica) solo se cobran con equipos y volúmenes que aquí no existen.

Qué mediría para cambiar de opinión. Extraería un servicio cuando se cumpla alguna de estas condiciones, no antes: (1) un módulo tiene un perfil de escalado radicalmente distinto (el conversor de PDF consume CPU en ráfagas y obliga a sobredimensionar todo el monolito); (2) un módulo necesita otra tecnología (OCR en Python); (3) un módulo tiene requisitos de cumplimiento o aislamiento distintos; (4) el equipo supera las 25-30 personas y los despliegues se bloquean entre sí; (5) un fallo en un módulo tumba el sistema entero y el aislamiento tiene valor de negocio medible.

Cómo dejarlo preparado sin pagarlo ahora. Fronteras de módulo estrictas y verificadas con reglas de dependencia automatizadas; nada de join entre esquemas de módulos distintos; eventos de dominio internos desde el principio (si mañana pasan por una cola, el código que los emite no cambia); y contratos con DTO explícitos en lugar de exponer entidades. Extraer un módulo bien delimitado cuesta semanas; deshacer ocho microservicios prematuros cuesta años. La arquitectura debe ser la más simple que resuelva el problema de hoy sin impedir el de mañana.

Principio rector: cachear por volatilidad y por coste de estar equivocado, no «cachearlo todo». Un precio desactualizado 30 segundos es un problema legal y de confianza; una descripción desactualizada una hora no le importa a nadie.

Decisiones que hay que saber defender. El stock exacto no se cachea porque el coste de equivocarse es vender lo que no tienes; sí se cachea el booleano «disponible» para el listado, donde un error transitorio solo lleva a la ficha, que consulta en directo. La caché de HTML completo en CDN se descarta porque la página lleva precio y personalización; la alternativa es cachear el armazón y cargar la parte volátil aparte.

Los tres problemas que hay que resolver explícitamente. Estampida: cuando caduca una clave muy popular, mil peticiones van a la vez a la base de datos; se resuelve con un bloqueo de recálculo (solo uno recalcula, los demás sirven el valor viejo) o con recálculo anticipado probabilístico. Avalancha: si todas las claves se cargaron a la vez, caducan a la vez; se resuelve añadiendo jitter al TTL. Incoherencia entre capas: la CDN puede servir durante horas algo que ya purgaste en Redis, así que la CDN necesita su propia purga por etiquetas y TTL cortos en lo volátil.

Cómo se mide el éxito: tasa de aciertos por tipo de clave (por debajo del 80 % la caché no está pagando su complejidad), latencia p95 y p99, y carga de la base de datos antes y después. Sin métricas, una caché es una fuente de bugs imposibles de reproducir.

Tensión de fondo. Los JWT no se pueden revocar: esa es toda su gracia (el servidor no consulta nada) y todo su problema. Cualquier diseño con revocación introduce estado en el servidor; la pregunta es cuánto.

Diseño elegido. Access token JWT de 15 minutos, firmado y no consultado; refresh token opaco de 30 días, almacenado hasheado en la base de datos, uno por dispositivo, con rotación en cada uso (ver NEST-08). Cada fila guarda dispositivo, agente de usuario, IP aproximada, último uso y familia. La pantalla de «sesiones activas» es literalmente un SELECT sobre esa tabla, y cerrar una sesión es marcar su familia como revocada. Al cambiar la contraseña se revocan todas las familias del usuario y se incrementa un contador tokenVersion incluido en el JWT, de modo que los access tokens ya emitidos dejan de validar de inmediato: es el único punto donde se paga una comprobación adicional, y solo compara un entero que ya viaja en el token.

Detección de robo. La rotación con detección de reutilización: si aparece un refresh ya consumido, alguien tiene una copia. Se revoca la familia completa, se registra el incidente y se avisa al usuario. Complementos razonables: alerta por cambio brusco de país o de dispositivo, y reautenticación obligatoria para operaciones sensibles.

Almacenamiento en el cliente: el refresh en cookie httpOnly, secure, sameSite=strict, con ruta limitada al endpoint de refresco; el access token en memoria, nunca en localStorage, que es legible por cualquier XSS. En la extensión y en el móvil, almacenamiento seguro del sistema.

Primer cambio de marco: esto no es una petición, es un trabajo. Ninguna petición HTTP síncrona debe durar minutos. El flujo correcto es asíncrono: el cliente solicita la exportación y recibe un 202 con un identificador; un worker la genera; cuando termina, el cliente se la descarga.

POST /exportaciones        -> 202 { id, estado: 'en_cola' }
GET  /exportaciones/:id    -> 200 { estado: 'procesando', progreso: 42 }
GET  /exportaciones/:id    -> 200 { estado: 'lista', url: 'https://…?firma', expiraEn }

Cómo se genera sin agotar la memoria. Tres reglas: (1) leer con cursor del servidor (em.getConnection().execute con un cursor, o paginación por clave), nunca find() completo; (2) transformar por filas con un flujo (Readable → transformador a CSV → Writable), de modo que la memoria dependa del tamaño del búfer y no del número de filas; (3) escribir directamente al almacenamiento de objetos (S3) con multipart upload, sin tocar el disco local ni acumular en RAM.

const cursor = em.getConnection().stream('select … from tarea where … order by id');
await pipeline(cursor, transformarACsv(), subidaMultiparteS3(clave));

Entrega. URL prefirmada con caducidad corta (15 min) que apunta al almacenamiento de objetos: el archivo nunca pasa por tu API, así que no consume ni memoria ni conexiones. Notificación por WebSocket o por correo cuando esté lista.

Alternativas consideradas. Streaming síncrono con Transfer-Encoding: chunked: funciona técnicamente y evita el problema de memoria, pero mantiene una conexión abierta varios minutos, depende de que el cliente no pierda la red y no permite reintentar; aceptable solo hasta unos cientos de miles de filas. Generación previa nocturna: válida si el informe es estándar y no depende de filtros del usuario. Criterio de decisión: por debajo de unos 30 segundos y 50 MB, streaming síncrono por su simplicidad; por encima, trabajo asíncrono.

Detalles que se olvidan: límite de exportaciones concurrentes por cliente (o un usuario tumba el sistema con diez peticiones); caducidad y borrado automático de los archivos (son datos personales); registro de auditoría de quién exportó qué; y BOM UTF-8 al inicio del CSV si tus usuarios lo abren con Excel, o verán los acentos rotos.

Primero, clasificar el cambio. No todo necesita versión nueva: añadir un campo opcional a la respuesta, añadir un endpoint o añadir un valor a un enumerado que el cliente ya debe ignorar son cambios compatibles. Solo rompen: renombrar o eliminar un campo, cambiar un tipo, endurecer una validación, cambiar un código de estado o convertir un campo opcional en obligatorio.

Recomendación: versión mayor en la URI (/v1, /v2) por su simplicidad operativa, combinada con la regla de solo versiones mayores y muy pocas. Internamente, una sola implementación con la lógica actual y una capa de traducción por versión: los controladores de /v1 son adaptadores finos que transforman la entrada y la salida hacia el modelo interno. Duplicar la lógica de negocio por versión es lo que hace insostenible el versionado.

Los cuatro cambios del enunciado. Renombrar un campo: en /v2 el nombre nuevo, y el adaptador de /v1 lo reexpone con el viejo. Cambiar un tipo: igual, con conversión en el adaptador; si no es convertible sin pérdida, campo nuevo junto al viejo y el antiguo se marca como obsoleto. Eliminar un endpoint: no se elimina en /v1; se marca como obsoleto y desaparece en /v2. Campo obligatorio nuevo en la petición: en /v1 se aplica un valor por defecto documentado; obligatorio solo en /v2.

Política de ciclo de vida (esto es lo que más se olvida y lo que más valoran en una entrevista): anuncio con 12 meses de antelación; cabecera Deprecation y Sunset en las respuestas de la versión antigua; métricas de uso por versión y por cliente para saber a quién llamar; avisos por correo a los clientes que siguen usándola a los 6, 3 y 1 mes; y «días de brownout» antes del apagado, en los que la versión antigua devuelve 410 durante unas horas para que nadie se lleve una sorpresa el día final. Máximo dos versiones vivas a la vez: cada versión adicional multiplica la matriz de pruebas.