31. Actualizar y migrar proyectos heredados

31.1 Qué vas a poder hacer al terminar

31.2 El problema: deuda técnica, miedo a actualizar, «si funciona no lo toques»

La frase «si funciona, no lo toques» es el mayor generador de coste oculto en equipos de producto. Un TaskFlow que lleva tres años sin actualizar no es un sistema estable: es un sistema congelado. Cada mes que pasa, la distancia con el ecosistema crece, los parches de seguridad dejan de llegar, las bibliotecas de terceros abandonan tu rama mayor y el próximo intento de actualizar cuesta el doble.

La deuda técnica no es solo código feo. En migraciones de stack full-stack aparece en cuatro capas:

• Dependencias. Paquetes anclados a majors antiguas, resoluciones forzadas en package.json, overrides/resolutions que esconden incompatibilidades.
• Plataforma. Node 14 o 16 fuera de LTS, PostgreSQL sin actualizaciones de seguridad, imágenes Docker basadas en Alpine con OpenSSL incompatible.
• Arquitectura de aplicación. NgModules monolíticos, servicios con estado global, entidades MikroORM con relaciones cargadas siempre en eager, tests E2E que solo pasan en la máquina de un compañero.
• Proceso. Ausencia de changelog interno, releases manuales, sin canary, sin feature flags, sin métricas de error post-despliegue (ver capítulo 21).

31.2.1 Por qué los equipos tienen miedo (y cuándo ese miedo es racional)

El miedo no es irracional. Actualizar Angular de 12 a 19 de un golpe, sin tests de contrato ni entorno de preproducción fiel, sí es una receta para un incidente. Lo irracional es convertir ese miedo en política permanente. Un miedo racional se traduce en: inventario, estrategia, flags, canary y rollback. Un miedo irracional se traduce en: «esperamos a reescribirlo todo el año que viene».

En TaskFlow Legacy, el equipo identificó tres síntomas clásicos:

1. El npm audit muestra vulnerabilidades críticas en dependencias transitivas que ya no reciben parches en la major actual.
2. Un desarrollador nuevo tarda dos días en arrancar el entorno porque Node 16 ya no se instala limpio en macOS reciente y el Dockerfile usa una imagen retirada.
3. Una librería de UI esencial abandona Angular 12; el equipo empieza a forkearla «temporalmente».

31.2.2 El coste compuesto de no actualizar

Cada major saltada no suma linealmente: multiplica. Angular publica guías de actualización por saltos de una o pocas majors; saltar siete de golpe obliga a encadenar breaking changes, codemods y cambios de mentalidad (RxJS operators pipeables ya asumidos, Ivy obligatorio, standalone por defecto, control flow nuevo). NestJS y MikroORM muestran el mismo patrón. Por eso la estrategia correcta a medio plazo es actualizar de forma continua (al menos dentro de la ventana LTS), no acumular y luego «hacer el proyecto de migración del Q3».

  Coste de actualizar (cualitativo)

  ^
  │                                    ╭──── big bang acumulado
  │                               ╭────╯
  │                          ╭────╯
  │                     ╭────╯
  │                ╭────╯
  │           ╭────╯
  │      ╭────╯  ← actualizaciones frecuentes (pequeñas)
  │ ─────╯
  └──────────────────────────────────────────► tiempo / majors saltadas

31.3 Inventario: dependencias, Node LTS, versiones y TypeScript strict

Ninguna migración seria empieza con ng update. Empieza con un inventario que responda a cinco preguntas: ¿dónde estamos?, ¿qué nos obliga el negocio?, ¿qué nos bloquea?, ¿qué tests nos protegen?, ¿cómo medimos el éxito? Sin ese mapa, cada PR de actualización es un acto de fe.

31.3.1 Inventario de dependencias y runtime

Para TaskFlow Legacy, el inventario mínimo cabe en una tabla viva (Confluence, Notion o un MIGRATION.md en el repo). Lo importante es que sea verificable con comandos, no con recuerdos.

#!/usr/bin/env bash
set -euo pipefail

echo "=== Node / npm ==="
node -v
npm -v

echo "=== Angular ==="
npx ng version || true

echo "=== Nest / MikroORM (desde package.json) ==="
node -e "const p=require('./package.json'); \
  console.log('nest', p.dependencies['@nestjs/core']); \
  console.log('mikro', p.dependencies['@mikro-orm/core']); \
  console.log('typescript', p.devDependencies.typescript);"

echo "=== Auditoría ==="
npm audit --json > audit-report.json || true

echo "=== Outdated ==="
npm outdated || true

31.3.2 TypeScript strict como red de seguridad

Migrar con strict: false es volar sin instrumentos. Antes de tocar majors de frameworks, activa (aunque sea de forma gradual con strictNullChecks primero) el modo estricto y corrige los errores que ya existían. Cada any que «arregla» un fallo de compilación tras un update es una bomba de relojería en producción.

{
  "compilerOptions": {
    "strict": false,
    "noImplicitAny": false,
    "skipLibCheck": true,
    "suppressImplicitAnyIndexErrors": true
  }
}

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": false,
    "skipLibCheck": true
  }
}

skipLibCheck: true sigue siendo pragmático en monorepos grandes (evita pelearte con declaraciones de terceros inconsistentes entre sí). Lo que no es pragmático es desactivar strict «para que compile el update».

31.3.3 Inventario de tests y contratos

Sin una red de tests mínima, la migración es teatro. El capítulo 8 (Angular testing) y el 13 (Nest testing) son prerrequisitos porque aquí los usamos como criterio de salida de cada fase:

• Tests unitarios de servicios de dominio TaskFlow (tareas, proyectos, permisos).
• Tests de contrato HTTP (Pact o al menos snapshots de OpenAPI) entre SPA y API.
• Una suite E2E smoke (login, crear tarea, asignar, completar) automatizada en CI.
• Migraciones MikroORM aplicadas en CI contra PostgreSQL efímero (Testcontainers o servicio Compose).

# Extracto del inventario TaskFlow (markdown en repo)

## Runtime
- Node: 16.20.2 (CI + prod)
- npm: 8.19

## Apps
- apps/web: Angular 12.2.13, RxJS 6.6, Zone.js 0.11
- apps/api: NestJS 8.4, Express 4.18, MikroORM 5.6, PG 13

## Cobertura crítica
- Unit web: 42% (flaky en TaskListComponent)
- Unit api: 61%
- E2E smoke: 6 escenarios Playwright (solo staging)
- Contract: OpenAPI generado, sin validación en CI

## Bloqueadores conocidos
- librería UI X solo soporta Angular <=13
- decoradores Reflect metadata con emitDecoratorMetadata=true obligatorio
- script de deploy asume dist/browser layout Angular 12

31.4 Estrategia de migración: big bang vs incremental, strangler fig, feature flags

La estrategia responde a una pregunta de gestión de riesgo: ¿cuánto cambio quieres que cruce el límite de producción en un solo despliegue? No hay una respuesta universal; hay una respuesta honestamente alineada con tu cobertura de tests, tu capacidad de rollback y la tolerancia al fallo del negocio.

31.4.1 Big bang

Un único tren: actualizas Node, Angular, Nest, MikroORM, esquema y front en una rama larga y despliegas todo junto. Tiene sentido solo cuando el producto es pequeño, el equipo cabe en una pizza, hay ventana de mantenimiento aceptada y la suite de tests es excelente. En TaskFlow con clientes B2B y SLA, el big bang puro suele ser imprudente.

31.4.2 Incremental por capas

Orden recomendado para TaskFlow (de menor a mayor acoplamiento visible al usuario):

1. Node LTS + herramientas de build (CLI, webpack/esbuild/vite según versión).
2. TypeScript strict y limpieza de any críticos.
3. NestJS + MikroORM en la API (contratos HTTP estables).
4. Angular major a major (o siguiendo el generador oficial de saltos).
5. Refactors estructurales: standalone, control flow, signals, zoneless.
6. Esquema DB con expand/contract desacoplado del deploy de código cuando haga falta.

  Estrategia incremental TaskFlow
  ================================

  semana 1-2   [Node 20 + CI + Docker]
       │
       ▼
  semana 3-4   [Nest 9→10 + peers]──── API canary 10%
       │
       ▼
  semana 5-6   [MikroORM 5→6 + migraciones expand]
       │
       ▼
  semana 7-10  [Angular 12→15→17→actual]  (PRs pequeños)
       │
       ▼
  semana 11+   [standalone / signals / zoneless]
               detrás de feature flags por ruta

31.4.3 Strangler fig

El patrón strangler fig (Martin Fowler) consiste en rodear el sistema legado con uno nuevo que va «estrangulando» rutas o capacidades hasta que el legado puede apagarse. En front, puede significar cargar microfrontends o rutas lazy nuevas en Angular moderno mientras el shell antiguo sigue vivo. En back, puede significar un BFF Nest nuevo que proxya al monolito Nest 8 hasta reimplementar módulos.

Para TaskFlow, un strangler pragmático es: nuevas features solo en módulos ya migrados a standalone + Nest actual; el módulo de informes legacy se toca lo mínimo hasta su turno. No hace falta Kubernetes ni service mesh para aplicar la idea: basta enrutado y disciplina de equipo.

import { Routes } from '@angular/router';
import { legacyGuard } from './migration/legacy.guard';

export const APP_ROUTES: Routes = [
  {
    path: 'tasks',
    // Ya migrado: standalone + signals
    loadChildren: () => import('./tasks/tasks.routes').then((m) => m.TASK_ROUTES),
  },
  {
    path: 'reports',
    // Legado: aún NgModule; se estrangula después
    canMatch: [legacyGuard],
    loadChildren: () =>
      import('./reports/reports.module').then((m) => m.ReportsModule),
  },
];

31.4.4 Feature flags

Las feature flags desacoplan desplegar de activar. El código nuevo puede estar en producción apagado; se enciende por porcentaje de usuarios, por tenant o por lista interna. En migraciones de UI (nuevo control flow, nueva pantalla de tareas) son casi obligatorias. En cambios de esquema DB no sustituyen expand/contract, pero ayudan a conmutar lecturas entre columnas viejas y nuevas.

export type FlagName =
  | 'tasks_standalone_ui'
  | 'tasks_zoneless'
  | 'orm_read_new_assignee_column';

export interface FlagContext {
  userId: string;
  tenantId: string;
  percentage: number; // 0..100 asignado de forma estable por hash
}

export function isEnabled(flag: FlagName, ctx: FlagContext): boolean {
  const rules: Record<FlagName, (c: FlagContext) => boolean> = {
    tasks_standalone_ui: (c) => c.percentage < 25 || c.tenantId === 'internal',
    tasks_zoneless: (c) => c.tenantId === 'internal',
    orm_read_new_assignee_column: (c) => c.percentage < 50,
  };
  return rules[flag](ctx);
}

31.4.5 Criterios de decisión para el comité técnico

Cuando producto, operaciones y desarrollo discrepan («hay que reescribir», «no toquéis nada», «hagamos canary ya»), conviene anclar la conversación a criterios observables. Una plantilla que funciona en equipos universitarios y en empresas es puntuar del 1 al 5 cada eje y elegir la estrategia con menor riesgo residual, no la más elegante en un diagrama.

En TaskFlow Legacy la puntuación típica fue: cobertura media, staging pobre, SLA estricto, acoplamiento alto, equipo de cuatro personas. La conclusión no fue «no migrar»: fue «Node+CI primero, Nest después, Angular a ritmo de una major por sprint, informes legacy estrangulados al final». Esa frase cabe en una diapositiva; el resto del capítulo es cómo ejecutarla sin romanticismo.

31.5 Actualizar Angular (update.angular.dev, ng update, breaking changes)

Angular es el componente del stack con la mejor experiencia de actualización documentada. Úsala. El sitio update.angular.dev genera una checklist personalizada según versión origen/destino y opciones (Angular Material, UI Router, etc.). El CLI aplica muchos cambios mecánicos con ng update.

31.5.1 Flujo recomendado con ng update

# 1) Asegura working tree limpio y CI verde en main
git checkout -b chore/angular-13

# 2) Actualiza el propio CLI en la versión intermedia
npx @angular/cli@13 update @angular/core@13 @angular/cli@13

# 3) Ejecuta tests y smoke E2E
npm test -- --watch=false
npm run e2e:smoke

# 4) Repite major a major (14, 15, 16, 17...)
# No saltes "por ahorrar tiempo" si el generador recomienda pasos

Actualizar major a major parece lento; en la práctica es más rápido que depurar un salto de siete versiones donde se mezclan deprecaciones ya eliminadas, cambios de tsconfig y renombres de paquetes. Cada salto debe dejar main desplegable.

31.5.2 Breaking changes típicos que verás en TaskFlow

31.5.3 Control flow y signals: no los mezcles con el salto de major a ciegas

Una mala práctica habitual es, en el mismo PR que sube de Angular 15 a 17, reescribir todas las plantillas a @if/@for y convertir todos los componentes a signals. Estás mezclando tres ejes de cambio. Primero deja la app compilando y testeada en la nueva major; después aplica codemods de control flow por carpeta; después introduce signals en features nuevas o en islas acotadas.

<!-- PR gigante: update + rewrite total -->
@for (task of tasksSignal(); track task.id) {
  @if (task.assignee(); as user) {
    <tf-task-row [task]="task" />
  }
}

<!-- Tras update estable: codemod por feature -->
@for (task of tasks; track task.id) {
  @if (task.assignee) {
    <tf-task-row [task]="task" />
  }
}

En el ejemplo «correcto» aún no hemos introducido signals: solo el nuevo control flow sobre el modelo imperativo/RxJS existente. El siguiente PR puede convertir tasks en tasks = signal<Task[]>([]) con calma.

import { Component, OnInit, inject, signal } from '@angular/core';
import { TaskApi } from './task-api.service';
import { Task } from './task.model';

@Component({
  selector: 'tf-task-list',
  standalone: true,
  templateUrl: './task-list.component.html',
})
export class TaskListComponent implements OnInit {
  private readonly api = inject(TaskApi);
  readonly tasks = signal<Task[]>([]);
  readonly error = signal<string | null>(null);

  ngOnInit(): void {
    this.api.list().subscribe({
      next: (items) => this.tasks.set(items),
      error: () => this.error.set('No se pudieron cargar las tareas'),
    });
  }
}

31.5.4 Material, CDK y el layout de assets

Si TaskFlow usa Angular Material, actualízalo en el mismo salto de major que el core cuando el schematic lo indique. Los temas, tipografías y tokens han cambiado entre eras (temas legacy frente a nuevos sistemas de theming). Además, el layout de salida de build (dist/...) ha variado entre majors: scripts de Nginx o CloudFront que asumen dist/browser o un index.html en una ruta concreta deben inventariarse en el apartado 31.3 y probarse en el pipeline, no el día del release.

# Verifica tras cada major que la ruta real del index coincide
# Ejemplo orientativo; adáptalo al outputPath de angular.json
root /usr/share/nginx/html/browser;
try_files $uri $uri/ /index.html;

Otro detalle que tumba canaries «verdes» en infra pero rojos en negocio: los service workers y cachés agresivas de PWA (capítulo 27). Tras un update, fuerza un ciclo de actualización del worker en staging y documenta cómo invalidar caché si un usuario se queda con el bundle antiguo hablando con una API nueva.

31.6 Actualizar NestJS (Express/Fastify, breaking changes, peer deps)

NestJS evoluciona con más prudencia semántica que el front, pero los saltos de major siguen rompiendo tipos, adapters y peer dependencies. El error más caro en TaskFlow Legacy fue actualizar @nestjs/core sin alinear @nestjs/common, @nestjs/platform-express y los paquetes de microservicios/websockets que compartían versión.

31.6.1 Peer dependencies: actualiza el conjunto, no el paquete suelto

# Inventario de paquetes @nestjs/*
npm ls --depth=0 | grep @nestjs || true

# Actualización alineada (ejemplo a una major concreta; consulta el changelog)
npm install @nestjs/common@^10 @nestjs/core@^10 @nestjs/platform-express@^10 \
  @nestjs/config@^3 @nestjs/testing@^10 reflect-metadata rxjs

# Verifica peers
npm ls @nestjs/core

31.6.2 Express frente a Fastify en una migración

Cambiar de Express a Fastify no debe colarse en el mismo tren que el salto de major de Nest. Son ejes ortogonales. Express sigue siendo el default razonable para TaskFlow si tienes middleware Express puro (certain auth, multipart, legacy). Fastify aporta rendimiento y esquema JSON; exige adaptar middleware y, a veces, plugins de Nest.

// En el mismo PR: Nest 10 + Fastify + quitar middleware
const app = await NestFactory.create<NestFastifyApplication>(
  AppModule,
  new FastifyAdapter(),
);
// Se rompe el middleware de correlacion-id basado en Express
app.use(correlationMiddleware);

// Primero: Nest 10 + Express estable
const app = await NestFactory.create(AppModule);
app.use(correlationMiddleware);

// Otro PR, más adelante: evaluar Fastify con spike y adapters

31.6.3 Breaking changes y deprecaciones que afectan a TaskFlow

• Versiones de TypeScript mínimas por major: el compilador del API debe subir con Nest.
• Cambios en tipado de ExecutionContext, guards y pipes personalizados.
• Módulos de terceros (@nestjs/passport, Swagger, Schedule) con majors propias: léelos en el mismo checklist.
• Configuración de validación (ValidationPipe) y transformaciones class-transformer cuando actualizas esas libs en paralelo.

import { Controller, Get, Param, ParseUUIDPipe } from '@nestjs/common';
import { TasksService } from './tasks.service';
import { TaskDto } from './task.dto';

@Controller('tasks')
export class TasksController {
  constructor(private readonly tasks: TasksService) {}

  @Get(':id')
  findOne(@Param('id', ParseUUIDPipe) id: string): Promise<TaskDto> {
    return this.tasks.findOne(id);
  }
}

Tras actualizar Nest, ejecuta la suite del capítulo 13 (testing) completa: unitarios de servicios con mocked EntityManager, e2e con supertest y un PostgreSQL de CI. Si solo corres tsc --noEmit, te perderás roturas de runtime en filters y middleware.

31.7 Actualizar MikroORM 5→6 y migraciones de esquema

MikroORM 6 introduce cambios de API y de empaquetado que conviene tratar como un proyecto propio, acoplado al despliegue de Nest pero con checklist separada. La documentación oficial de upgrading es la fuente de verdad; aquí condensamos el impacto en TaskFlow.

31.7.1 Cambios de API que rompen compilaciones

Patrones frecuentes al pasar de 5 a 6 (verifica siempre la guía oficial de tu minor exacta):

• Ajustes en imports de drivers y paquetes reflejo (@mikro-orm/postgresql, etc.).
• Cambios en la configuración (defineConfig, opciones renombradas).
• Diferencias en el manejo de WrappedEntity, populate y serialización.
• CLI de migraciones: asegúrate de que el mismo config usa la app y la CLI.

import { defineConfig } from '@mikro-orm/postgresql';
import { Migrator } from '@mikro-orm/migrations';
import { Task } from './tasks/task.entity';
import { User } from './users/user.entity';

export default defineConfig({
  entities: [Task, User],
  clientUrl: process.env.DATABASE_URL,
  migrations: {
    path: 'dist/migrations',
    pathTs: 'src/migrations',
  },
  extensions: [Migrator],
  // Nunca uses forceEntityConstructor / allowGlobalContext a la ligera en prod
});

// Asumir que el EntityManager "global" sigue igual tras el update
await this.em.flush();
const task = await this.em.findOneOrFail(Task, id, ['assignee']);

const task = await this.em.findOneOrFail(
  Task,
  id,
  { populate: ['assignee'] },
);
await this.em.flush();

31.7.2 Migraciones de esquema: generar, revisar, aplicar

Nunca ejecutes en producción una migración generada sin revisión humana. El generador de esquemas es una ayuda, no un oráculo. En TaskFlow, una migración automática propuso DROP COLUMN porque alguien renombró un campo en la entidad sin mapear el nombre de columna antiguo.

# Desarrollo: genera a partir del diff de metadatos
npx mikro-orm migration:create --name rename_task_title

# Revisa el SQL generado en src/migrations/*.ts
# Aplica en local / CI
npx mikro-orm migration:up

# Estado
npx mikro-orm migration:pending
npx mikro-orm migration:list

import { Migration } from '@mikro-orm/migrations';

export class Migration20260731120000 extends Migration {
  override async up(): Promise<void> {
    // Expand: columna nueva nullable primero (ver 31.12)
    this.addSql(
      `alter table "task" add column "title_v2" varchar(200) null;`,
    );
  }

  override async down(): Promise<void> {
    this.addSql(`alter table "task" drop column "title_v2";`);
  }
}

31.7.3 Repositorio y tests tras el salto 5→6

Los tests que mockean EntityManager suelen ser el primer fuego tras actualizar MikroORM. Si tipabas métodos con firmas antiguas de find/findOne, TypeScript empezará a quejarse; si los mockeabas con as any, el runtime de integración fallará más tarde. Aprovecha el update para sustituir mocks frágiles por tests contra PostgreSQL efímero en los repositorios críticos (tareas, permisos, asignaciones).

import { MikroORM } from '@mikro-orm/core';
import config from '../mikro-orm.config';
import { Task } from './task.entity';

describe('TasksRepository (integración)', () => {
  let orm: MikroORM;

  beforeAll(async () => {
    orm = await MikroORM.init({
      ...config,
      clientUrl: process.env.TEST_DATABASE_URL,
      allowGlobalContext: true,
    });
    await orm.getSchemaGenerator().refreshDatabase();
  });

  afterAll(async () => {
    await orm.close(true);
  });

  it('persiste y recupera una tarea con populate', async () => {
    const em = orm.em.fork();
    const task = em.create(Task, {
      id: crypto.randomUUID(),
      title: 'Probar MikroORM 6',
    });
    await em.persistAndFlush(task);

    const found = await em.findOneOrFail(Task, task.id);
    expect(found.title).toBe('Probar MikroORM 6');
  });
});

Este estilo de test es más lento que un mock, pero es exactamente la red que necesitas cuando cambian detalles de persistencia. Reserva mocks para lógica de dominio pura; no para verificar que el ORM sigue mapeando columnas tras un upgrade.

31.8 Migrar de NgModules a standalone de forma segura

Standalone no es un interruptor binario. Angular permite convivir módulos y componentes standalone durante mucho tiempo. Esa convivencia es tu aliada: migra feature por feature, empieza por hojas del árbol (componentes presentacionales) y termina por el AppModule / bootstrap.

31.8.1 Secuencia segura en TaskFlow

1. Marca componentes presentacionales como standalone: true e importa sus dependencias de plantilla en el propio decorador.
2. Decláralos en los imports de los NgModules que aún los usan (sí, los módulos pueden importar standalone).
3. Convierte rutas a loadComponent / loadChildren con arrays de rutas.
4. Sustituye HttpClientModule por provideHttpClient() en bootstrap.
5. Elimina AppModule cuando ya no aporte nada y usa bootstrapApplication.

  NgModule monolítico
        │
        │  1. hojas standalone
        ▼
  NgModule + imports standalone
        │
        │  2. rutas loadComponent
        ▼
  Shell module fino + features standalone
        │
        │  3. bootstrapApplication
        ▼
  App 100% standalone

import { Component, Input } from '@angular/core';
import { DatePipe } from '@angular/common';
import { Task } from './task.model';

@Component({
  selector: 'tf-task-row',
  standalone: true,
  imports: [DatePipe],
  template: `
    <article class="task-row">
      <h3>{{ task.title }}</h3>
      <time>{{ task.dueAt | date: 'shortDate' }}</time>
    </article>
  `,
})
export class TaskRowComponent {
  @Input({ required: true }) task!: Task;
}

import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { TaskRowComponent } from './task-row.component';
import { TaskListComponent } from './task-list.component';

@NgModule({
  // TaskList aún no standalone: se declara
  declarations: [TaskListComponent],
  // TaskRow ya standalone: se importa
  imports: [CommonModule, TaskRowComponent],
  exports: [TaskListComponent],
})
export class TasksModule {}

31.8.2 TestBed durante la convivencia

import { ComponentFixture, TestBed } from '@angular/core/testing';
import { TaskRowComponent } from './task-row.component';

describe('TaskRowComponent', () => {
  let fixture: ComponentFixture<TaskRowComponent>;

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      imports: [TaskRowComponent],
    }).compileComponents();

    fixture = TestBed.createComponent(TaskRowComponent);
    fixture.componentInstance.task = {
      id: '1',
      title: 'Migrar standalone',
      dueAt: new Date('2026-08-01'),
    };
    fixture.detectChanges();
  });

  it('muestra el título', () => {
    const el: HTMLElement = fixture.nativeElement;
    expect(el.textContent).toContain('Migrar standalone');
  });
});

31.9 Migrar Zone.js → zoneless / signals gradualmente

Zone.js parchea APIs asíncronas para disparar change detection automáticamente. Funciona, pero oculta costes y complica SSR, microfrontends y debugging. El rumbo de Angular es zoneless con signals y notificaciones explícitas. La migración no es «quitar zone.js el viernes».

31.9.1 Enfoque gradual

1. Introduce signals en estado local de UI (contadores, filtros, formularios simples).
2. Sustituye patrones markForCheck / OnPush mal entendidos por datos reactivos claros.
3. Activa zoneless en un entorno de desarrollo o detrás de flag interno.
4. Corrige los componentes que dependían del «magic refresh» tras setTimeout o callbacks de librerías no parcheadas.
5. Solo entonces elimines Zone del bootstrap de producción.

import { bootstrapApplication } from '@angular/platform-browser';
import { provideExperimentalZonelessChangeDetection } from '@angular/core';
import { AppComponent } from './app/app.component';
import { appConfig } from './app/app.config';

// Flag interno: solo staff TaskFlow
const zoneless = localStorage.getItem('tf_zoneless') === '1';

bootstrapApplication(AppComponent, {
  providers: [
    ...appConfig.providers,
    ...(zoneless ? [provideExperimentalZonelessChangeDetection()] : []),
  ],
}).catch(console.error);

// Depende de Zone para repintar tras el callback
export class FiltersComponent {
  query = '';
  onExternalSearch(cb: (q: string) => void): void {
    legacySearchWidget.onChange((q) => {
      this.query = q; // en zoneless puede no refrescar
      cb(q);
    });
  }
}

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

export class FiltersComponent {
  readonly query = signal('');

  onExternalSearch(): void {
    legacySearchWidget.onChange((q: string) => {
      this.query.set(q); // notificación explícita
    });
  }
}

31.10 Sustituir HttpModule viejo, interceptores funcionales y TestBed

En Angular moderno, HttpClientModule se sustituye por provideHttpClient() y los interceptores de clase pueden (y suelen) migrarse a interceptores funcionales. En TaskFlow Legacy convivían un AuthInterceptor de clase, un RetryInterceptor a medias y tests que importaban el módulo completo.

31.10.1 Bootstrap con provideHttpClient

import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import {
  provideHttpClient,
  withInterceptors,
} from '@angular/common/http';
import { APP_ROUTES } from './app.routes';
import { authInterceptor } from './http/auth.interceptor';
import { errorInterceptor } from './http/error.interceptor';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(APP_ROUTES),
    provideHttpClient(withInterceptors([authInterceptor, errorInterceptor])),
  ],
};

import { HttpInterceptorFn } from '@angular/common/http';
import { inject } from '@angular/core';
import { AuthStore } from '../auth/auth.store';

export const authInterceptor: HttpInterceptorFn = (req, next) => {
  const token = inject(AuthStore).accessToken();
  if (!token) {
    return next(req);
  }
  return next(
    req.clone({
      setHeaders: { Authorization: `Bearer ${token}` },
    }),
  );
};

await TestBed.configureTestingModule({
  imports: [HttpClientModule], // legado + trae interceptores reales
  providers: [TaskApi],
}).compileComponents();

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

await TestBed.configureTestingModule({
  providers: [
    TaskApi,
    provideHttpClient(),
    provideHttpClientTesting(),
  ],
}).compileComponents();

const http = TestBed.inject(HttpTestingController);

Si aún necesitas un interceptor de clase durante la transición, Angular permite withInterceptorsFromDi(). Úsalo como puente, no como destino. Documenta en el inventario qué interceptores faltan por convertir y apártanos un PR por interceptor (auth, error, correlacion-id).

import { HttpInterceptorFn, HttpErrorResponse } from '@angular/common/http';
import { inject } from '@angular/core';
import { catchError, throwError } from 'rxjs';
import { ToastService } from '../ui/toast.service';

export const errorInterceptor: HttpInterceptorFn = (req, next) => {
  const toast = inject(ToastService);
  return next(req).pipe(
    catchError((err: unknown) => {
      if (err instanceof HttpErrorResponse && err.status >= 500) {
        toast.error('Error del servidor. Inténtalo de nuevo.');
      }
      return throwError(() => err);
    }),
  );
};

31.11 Codemods, reglas ESLint y ts-migrate

La migración mecánica no debe hacerse a mano archivo a archivo cuando existen transformaciones automatizadas. Un codemod es un script que reescribe el AST; una regla ESLint impide que el código nuevo reintroduzca el patrón viejo; herramientas como enfoques tipo ts-migrate ayudan a tipar bases JavaScript, aunque en TaskFlow (ya TypeScript) el valor está más en codemods de Angular/RxJS y en strictness gradual.

31.11.1 Codemods del ecosistema Angular

• Schematics de ng update: renombres, imports, tsconfig.
• Migraciones a standalone y a nuevo control flow publicadas con el CLI (según versión).
• Codemods comunitarios para RxJS (sustituir toPromise por firstValueFrom/lastValueFrom).

# Ejemplo: schematic de control flow (el nombre exacto depende de la CLI)
npx ng generate @angular/core:control-flow

# Revisa siempre el diff
git diff --stat
git diff apps/web/src/app/tasks | less

# Ejecuta tests de la feature tocada, no solo tsc
npm test -- --include='**/tasks/**/*.spec.ts'

31.11.2 ESLint como barandilla post-migración

Tras migrar una carpeta a standalone o a interceptores funcionales, añade reglas que fallen en CI si alguien vuelve a importar el patrón prohibido.

// Pseudoconfig: adapta a flat config o .eslintrc según el repo
export default [
  {
    files: ['apps/web/src/app/**/*.ts'],
    rules: {
      'no-restricted-imports': [
        'error',
        {
          paths: [
            {
              name: '@angular/common/http',
              importNames: ['HttpClientModule'],
              message:
                'Usa provideHttpClient() en el bootstrap (ver cap. 31).',
            },
            {
              name: 'rxjs',
              importNames: ['toPromise'],
              message: 'Usa firstValueFrom / lastValueFrom.',
            },
          ],
        },
      ],
    },
  },
];

import { Injectable, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { firstValueFrom } from 'rxjs';
import { Task } from './task.model';

@Injectable({ providedIn: 'root' })
export class TaskApi {
  private readonly http = inject(HttpClient);

  list(): Promise<Task[]> {
    return firstValueFrom(this.http.get<Task[]>('/api/tasks'));
  }
}

31.11.3 ts-migrate y strictness gradual

Si alguna parte de TaskFlow sigue en JavaScript (scripts de tooling, un panel admin antiguo), herramientas al estilo ts-migrate insertan anotaciones $TSFixMe / any para conseguir compilación tipada y luego ir cerrando agujeros. En código ya TypeScript, el análogo es activar flags uno a uno:

1. noImplicitAny
2. strictNullChecks
3. strictFunctionTypes
4. noUncheckedIndexedAccess (más agresivo; al final)

#!/usr/bin/env bash
# Cuenta errores de tsc como métrica de migración tipada
npx tsc -p apps/api/tsconfig.json --noEmit --pretty false 2>&1 \
  | tee /tmp/tsc-api.txt \
  | wc -l

31.12 Bases de datos: migraciones zero-downtime y expand/contract

El código puede desplegarse en minutos; el esquema compartido entre instancias viejas y nuevas durante un rolling deploy es el verdadero cuello de botella. El patrón expand/contract (también llamado parallel change) evita downtime y rollbacks imposibles.

  Expand / Contract sobre columna assignee

  1. EXPAND
     task.assignee_id (vieja)     task.assignee_uuid (nueva, nullable)
            │                              │
            └──── app escribe en AMBAS ────┘
                  (o trigger/backfill)

  2. MIGRATE READS
     lecturas pasan a assignee_uuid detrás de flag
     backfill batch de filas históricas

  3. CONTRACT
     se deja de escribir en assignee_id
     se elimina columna vieja en migración posterior

31.12.1 Fase expand

import { Migration } from '@mikro-orm/migrations';

export class Migration20260801100000 extends Migration {
  override async up(): Promise<void> {
    this.addSql(
      `alter table "task" add column "assignee_uuid" uuid null;`,
    );
    this.addSql(
      `create index "task_assignee_uuid_idx" on "task" ("assignee_uuid");`,
    );
  }

  override async down(): Promise<void> {
    this.addSql(`drop index "task_assignee_uuid_idx";`);
    this.addSql(`alter table "task" drop column "assignee_uuid";`);
  }
}

import { Entity, PrimaryKey, Property, ManyToOne } from '@mikro-orm/core';
import { User } from '../users/user.entity';

@Entity({ tableName: 'task' })
export class Task {
  @PrimaryKey({ type: 'uuid' })
  id!: string;

  @Property()
  title!: string;

  /** Columna legada; no leer en código nuevo */
  @ManyToOne(() => User, { nullable: true, fieldName: 'assignee_id' })
  assigneeLegacy?: User;

  @Property({ nullable: true, fieldName: 'assignee_uuid' })
  assigneeUuid?: string;
}

31.12.2 Backfill y doble escritura

async assign(taskId: string, userId: string): Promise<void> {
  const task = await this.em.findOneOrFail(Task, taskId);
  const user = await this.em.findOneOrFail(User, userId);

  // Doble escritura durante expand
  task.assigneeLegacy = user;
  task.assigneeUuid = user.id;

  await this.em.flush();
}

async backfillAssignees(batchSize = 500): Promise<number> {
  const pending = await this.em.find(
    Task,
    { assigneeUuid: null, assigneeLegacy: { $ne: null } },
    { limit: batchSize, populate: ['assigneeLegacy'] },
  );
  for (const task of pending) {
    task.assigneeUuid = task.assigneeLegacy!.id;
  }
  await this.em.flush();
  return pending.length;
}

31.12.3 Fase contract

Solo cuando el 100 % del tráfico lee y escribe la columna nueva, y el backfill ha terminado, eliminas la columna vieja. Ese deploy de código que deja de referenciar assigneeLegacy debe ocurrir antes del DROP COLUMN.

31.13 Plan de rollback y canary

Si no tienes rollback escrito antes del deploy, no tienes un plan de migración: tienes una esperanza. El canary reduce el radio de explosión; el rollback limita la duración del incidente.

31.13.1 Canary de TaskFlow

  Tráfico usuarios TaskFlow
           │
           ▼
     ┌─────────────┐
     │  balanceador│
     └──────┬──────┘
            │
     ┌──────┴──────┐
     │ 10% canary  │──── pods api:nest10-mikro6 + web:angular-nueva
     │ 90% estable │──── pods versión anterior
     └─────────────┘
            │
            ▼
     métricas: 5xx, latencia p95, error JS (Sentry),
     login success rate, "crear tarea" success

• Promociona canary solo si las métricas de negocio (crear tarea, asignar) se mantienen.
• No mires solo CPU: un 500 en POST /tasks con CPU baja es un canary fallido.
• El front y el back pueden canarearse por separado si el contrato HTTP es compatible (preferible).

31.13.2 Rollback: qué es reversible y qué no

# Runbook resumido TaskFlow — canary API nest10

1. Observabilidad: dashboard "release-canary" (5xx, p95, Sentry).
2. Si 5xx > 1% durante 5 min O error JS x3 baseline:
   a. Apagar flag tasks_standalone_ui (si aplica).
   b. kubectl rollout undo deploy/taskflow-api-canary
   c. Verificar health /readyz en pods estables.
3. Si la migración SQL expand se aplicó:
   - NO ejecutar contract.
   - Decidir si DROP columna nueva o dejarla inerte.
4. Abrir incidente, postmortem en 48h (blameless).

31.14 Checklist de release post-migración

Usa esta lista como puerta de calidad antes de declarar la major «terminada». No es cosmética: cada ítem evita una clase de incidente que ya hemos visto en proyectos reales.

name: migration-gate
on:
  pull_request:
    paths:
      - 'apps/**'
      - 'package.json'
      - 'package-lock.json'
jobs:
  gate:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: taskflow
        ports: ['5432:5432']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm run test:api
      - run: npm run test:web
      - run: npm run mikro:migrate:up
      - run: npm run e2e:smoke

31.15 Errores comunes y cómo solucionarlos

{
  "dependencies": {
    "@nestjs/common": "10.3.0",
    "@nestjs/core": "8.4.7",
    "@nestjs/platform-express": "9.4.0"
  }
}

{
  "dependencies": {
    "@nestjs/common": "10.3.0",
    "@nestjs/core": "10.3.0",
    "@nestjs/platform-express": "10.3.0"
  }
}

31.16 Buenas y malas prácticas

31.17 Preguntas frecuentes

31.18 Ejercicios

git checkout -b chore/angular-16
git status  # working tree limpio
npx @angular/cli@16 update @angular/core@16 @angular/cli@16
# Si usas Material u otras libs oficiales:
# npx ng update @angular/material@16
npm test -- --watch=false
npm run e2e:smoke
git add -A && git commit -m "chore(web): Angular 15 a 16"

31.19 Resumen del capítulo

Guarda plantillas reutilizables: checklist de inventario, plantilla de ADR para elegir strangler frente a big bang, plantilla de runbook de rollback, y un tablero con el estado de cada app/lib respecto a la versión objetivo. El coste de mantener esas plantillas es ridículo frente al de un fin de semana entero apagando fuegos tras un ng update a ciegas.

En la entrevista, distingue actualización de framework (tooling + breaking changes) de migración de arquitectura (standalone, zoneless, módulos Nest). Son ejes distintos: puedes estar en Angular reciente con NgModules, o a medias en standalone con una versión vieja. El plan debe decir qué eje se mueve en cada tren y qué métrica indica éxito (tests, bundle, error rate, tiempo de build).

Cierra el círculo con el capítulo 13 (tests como red de seguridad), el 21 (despliegue y probes) y el 30 (monorepo affected): sin esas tres piezas, cada actualización es un salto de fe. Con ellas, es mantenimiento rutinario — aburrido, predecible y barato a largo plazo, que es exactamente lo que quieres en producción.

31.20 Recursos adicionales

• Angular Update Guide (update.angular.dev) — checklist oficial origen/destino.
• Angular.dev · Keeping up-to-date — prácticas de actualización continua.
• Angular.dev · Components (standalone) — modelo standalone actual.
• Angular.dev · Signals — reactividad moderna.
• Angular.dev · Zoneless — change detection sin Zone.js (consulta tu versión).
• NestJS Migration Guide — breaking changes entre majors.
• NestJS Documentation — referencia de Application Context, providers y platforms.
• MikroORM · Upgrading from v5 to v6 — guía oficial 5→6.
• MikroORM · Migrations — CLI y flujo de migraciones.
• Node.js Release Schedule — ventanas LTS.
• Martin Fowler · Strangler Fig Application — patrón de estrangulamiento.
• Martin Fowler · Parallel Change — base conceptual de expand/contract.