6. Router, lazy loading, HTTP y comunicación con el backend

import {inject} from '@angular/core';
import {
  Router, NavigationStart, NavigationEnd, NavigationCancel,
  NavigationError, NavigationSkipped, NavigationCancellationCode,
} from '@angular/router';
import {filter} from 'rxjs';
export function registrarTelemetriaNavegacion(): void {
  const router = inject(Router);
  const inicio = new Map<number, number>();
  router.events.subscribe((evento) => {
    if (evento instanceof NavigationStart) {
      inicio.set(evento.id, performance.now());
    } else if (evento instanceof NavigationEnd) {
      const ms = performance.now() - (inicio.get(evento.id) ?? 0);
      // Métrica útil de verdad: cuánto tarda una navegación de principio a fin,
      // incluyendo guards, resolvers y descarga de chunks.
      console.info(`[nav] ${evento.urlAfterRedirects} en ${ms.toFixed(0)} ms`);
      inicio.delete(evento.id);
    } else if (evento instanceof NavigationCancel) {
      // code distingue un guard que devolvió false de una redirección con UrlTree
      const motivo = evento.code === NavigationCancellationCode.GuardRejected
        ? 'un guard la rechazó'
        : 'redirección o navegación superpuesta';
      console.warn(`[nav] cancelada ${evento.url}: ${motivo}`);
    } else if (evento instanceof NavigationError) {
      console.error(`[nav] error en ${evento.url}`, evento.error);
    } else if (evento instanceof NavigationSkipped) {
      // Misma URL con onSameUrlNavigation: 'ignore'. No es un fallo.
      console.debug(`[nav] omitida ${evento.url}`);
    }
  });
}

import {ApplicationConfig, provideZonelessChangeDetection} from '@angular/core';
import {
  provideRouter, withComponentInputBinding, withViewTransitions,
  withInMemoryScrolling, withRouterConfig, withPreloading, PreloadAllModules,
  withNavigationErrorHandler, Router,
} from '@angular/router';
import {provideHttpClient, withFetch, withInterceptors} from '@angular/common/http';
import {routes} from './app.routes';
import {authInterceptor, cargaInterceptor, idiomaInterceptor} from './core/http';
export const appConfig: ApplicationConfig = {
  providers: [
    provideZonelessChangeDetection(),
    provideRouter(
      routes,
      // Los parámetros de ruta llegan a los @Input() del componente:
      // menos boilerplate y sin suscripciones manuales.
      withComponentInputBinding(),
      // Transiciones nativas del navegador entre vistas. Mejora progresiva:
      // donde no hay soporte, la navegación es la de siempre.
      withViewTransitions({skipInitialTransition: true}),
      // Restaura la posición del scroll con el botón atrás y salta a #anclas.
      withInMemoryScrolling({scrollPositionRestoration: 'enabled', anchorScrolling: 'enabled'}),
      withRouterConfig({
        onSameUrlNavigation: 'reload',        // permite "recargar" la ruta actual
        paramsInheritanceStrategy: 'always',  // las hijas heredan params y data
        urlUpdateStrategy: 'deferred',        // la URL cambia al confirmar la navegación
      }),
      // Descarga en segundo plano todos los chunks diferidos tras el arranque.
      withPreloading(PreloadAllModules),
      // Último recurso: un resolver que explota no debe dejar la app en blanco.
      withNavigationErrorHandler((error) => {
        console.error('Navegación fallida', error);
        return inject(Router).parseUrl('/error');
      }),
    ),
    provideHttpClient(
      withFetch(),
      withInterceptors([authInterceptor, idiomaInterceptor, cargaInterceptor]),
    ),
  ],
};

import {Routes} from '@angular/router';
import {ShellComponent} from './layout/shell.component';
import {authGuard, rolGuard} from './core/guards';
import {tareaResolver} from './tareas/tarea.resolver';
export const routes: Routes = [
  {
    path: '',
    component: ShellComponent,          // layout persistente con la barra y el menú
    canActivate: [authGuard],           // protege todo el bloque de una vez
    children: [
      // Ruta vacía: '' con pathMatch 'full' es la portada de este bloque.
      {path: '', pathMatch: 'full', redirectTo: 'tareas'},
      {
        path: 'tareas',
        title: 'Tareas',                            // lo aplica TitleStrategy
        data: {icono: 'check', preload: true},      // metadatos estáticos arbitrarios
        loadChildren: () => import('./tareas/tareas.routes').then((m) => m.TAREAS_ROUTES),
      },
      {
        path: 'informes',
        // Solo se descarga el chunk si el usuario tiene el rol. Con canActivate
        // el código llegaría al navegador y solo después se rechazaría.
        canMatch: [rolGuard('analista')],
        loadChildren: () => import('./informes/informes.routes'),   // export default
      },
      {
        // Ruta SIN componente: agrupa providers y guards sin añadir un nivel de DOM.
        path: 'admin',
        canActivate: [rolGuard('admin')],
        providers: [AdminApiService, {provide: LIMITE_PAGINA, useValue: 50}],
        loadChildren: () => import('./admin/admin.routes').then((m) => m.ADMIN_ROUTES),
      },
      {
        path: 'perfil/:id',
        resolve: {perfil: perfilResolver},
        loadComponent: () => import('./perfil/perfil.component').then((m) => m.PerfilComponent),
      },
      // Panel de ayuda en un outlet auxiliar: convive con la ruta principal.
      {
        path: 'ayuda',
        outlet: 'lateral',
        loadComponent: () => import('./ayuda/ayuda.component'),
      },
    ],
  },
  {path: 'login', loadComponent: () => import('./auth/login.component')},
  // Redirección permanente de una URL antigua, conservando el parámetro.
  {path: 'tasks/:id', redirectTo: 'tareas/:id'},
  // Comodín: SIEMPRE el último.
  {path: '**', loadComponent: () => import('./errores/no-encontrado.component')},
];

import {Injectable, inject} from '@angular/core';
import {Title} from '@angular/platform-browser';
import {RouterStateSnapshot, TitleStrategy} from '@angular/router';
@Injectable({providedIn: 'root'})
export class TituloAplicacionStrategy extends TitleStrategy {
  private readonly title = inject(Title);
  override updateTitle(estado: RouterStateSnapshot): void {
    // buildTitle recorre el árbol y devuelve el title de la ruta activa
    // más profunda que lo defina (resolviendo funciones si es el caso).
    const titulo = this.buildTitle(estado);
    this.title.setTitle(titulo ? `${titulo} · Gestor de tareas` : 'Gestor de tareas');
  }
}
// En los providers de la aplicación:
// {provide: TitleStrategy, useClass: TituloAplicacionStrategy}

// title admite una ResolveFn<string>, así que puede inyectar servicios y leer
// lo que ya han dejado los resolvers de la misma ruta en data.
const tituloTarea: ResolveFn<string> = (ruta) =>
  (ruta.data['tarea'] as Tarea | undefined)?.titulo ?? 'Detalle de tarea';

export const TAREAS_ROUTES: Routes = [
  {path: '', title: 'Tareas', loadComponent: () => import('./lista.component')},
  {path: ':id', resolve: {tarea: tareaResolver}, title: tituloTarea,
   loadComponent: () => import('./detalle.component')},
];

import {Component, inject} from '@angular/core';
import {ActivatedRoute} from '@angular/router';
import {takeUntilDestroyed} from '@angular/core/rxjs-interop';
import {switchMap, map} from 'rxjs';
export class DetalleTareaComponent {
  private readonly route = inject(ActivatedRoute);
  private readonly api = inject(TareasApi);
  // paramMap emite en CADA cambio de parámetro, incluso si el componente se reutiliza.
  readonly tarea$ = this.route.paramMap.pipe(
    map((p) => p.get('id')!),                  // ParamMap: get, getAll, has, keys
    switchMap((id) => this.api.obtener(id)),   // switchMap cancela la petición anterior
  );
  // Query params: independientes del path, viven en el árbol completo.
  readonly pagina$ = this.route.queryParamMap.pipe(map((q) => Number(q.get('pagina') ?? 1)));
  // Parámetros de matriz del último segmento consumido por ESTA ruta:
  // /tareas/42;modo=edicion  ─►  params incluye { id: '42', modo: 'edicion' }
  readonly modo$ = this.route.params.pipe(map((p) => p['modo'] ?? 'lectura'));
}

import {Component, input, computed} from '@angular/core';
import {rxResource} from '@angular/core/rxjs-interop';
@Component({
  selector: 'app-detalle-tarea',
  template: `
    @if (tarea.isLoading()) { <app-esqueleto /> }
    @else if (tarea.value(); as t) { <h2>{{ t.titulo }}</h2> }
  `,
})
export class DetalleTareaComponent {
  // Del path /tareas/:id. Es una señal: cambia sola en cada navegación.
  readonly id = input.required<string>();
  // De ?modo=edicion. Como es opcional, conviene un valor por defecto.
  readonly modo = input<'lectura' | 'edicion'>('lectura');
  // De resolve: {tarea: ...} o de data: {...} de la ruta.
  readonly soloLectura = computed(() => this.modo() === 'lectura');
  private readonly api = inject(TareasApi);
  readonly tarea = rxResource({params: () => this.id(), stream: ({params}) => this.api.obtener(params)});
}

<!-- Absoluto: empieza por '/'. Ignora dónde estemos. -->
<a routerLink="/tareas">Todas las tareas</a>
<!-- Con parámetros: array de "comandos". Angular escapa los valores por ti. -->
<a [routerLink]="['/tareas', tarea.id]">{{ tarea.titulo }}</a>
<!-- Relativo a la ruta activa: si estamos en /tareas, va a /tareas/42 -->
<a [routerLink]="[tarea.id]">Ver</a>
<!-- Relativo hacia arriba: desde /tareas/42/editar hasta /tareas/42 -->
<a routerLink="..">Volver al detalle</a>
<!-- Parámetros de matriz: /tareas;vista=compacta -->
<a [routerLink]="['/tareas', {vista: 'compacta'}]">Vista compacta</a>
<!-- Query params y fragmento. 'merge' conserva los que ya hubiera. -->
<a [routerLink]="['/tareas']"
   [queryParams]="{estado: 'abierta', pagina: 1}"
   queryParamsHandling="merge"
   fragment="resultados">Abiertas</a>
<!-- Base relativa explícita: útil dentro de un componente reutilizable
     que no sabe en qué nivel del árbol de rutas se está pintando. -->
<a [routerLink]="['detalle']" [relativeTo]="rutaBase">Detalle</a>
<!-- Estado activo. ariaCurrentWhenActive lo anuncia a los lectores de pantalla. -->
<a routerLink="/tareas"
   routerLinkActive="activo"
   [routerLinkActiveOptions]="{exact: true}"
   ariaCurrentWhenActive="page">Inicio</a>
<!-- Coincidencia fina: el path debe ser exacto, pero los query params se ignoran. -->
<a routerLink="/informes"
   routerLinkActive="activo"
   [routerLinkActiveOptions]="{paths: 'exact', queryParams: 'ignored',
                               matrixParams: 'ignored', fragment: 'ignored'}">Informes</a>

private readonly router = inject(Router);
private readonly route = inject(ActivatedRoute);
async guardar(): Promise<void> {
  const tarea = await this.api.crear(this.formulario.getRawValue());
  // 1) navigate: acepta el mismo array de comandos que routerLink.
  //    Devuelve Promise<boolean>: false si un guard la canceló.
  const ok = await this.router.navigate(['/tareas', tarea.id], {
    // Reemplaza la entrada actual del historial en lugar de añadir una:
    // así el botón atrás no devuelve al formulario ya enviado.
    replaceUrl: true,
    // Datos que viajan con la navegación sin aparecer en la URL.
    state: {mensaje: 'Tarea creada correctamente'},
  });
  if (!ok) console.warn('La navegación fue cancelada por un guard');
}
verHermana(id: string): void {
  // 2) Relativa: sube un nivel y baja al hermano. Sin relativeTo, 'navigate'
  //    interpreta los comandos como absolutos.
  this.router.navigate(['..', id], {relativeTo: this.route});
}
filtrar(estado: string): void {
  // 3) Mantener la URL y cambiar solo un query param.
  this.router.navigate([], {
    relativeTo: this.route,
    queryParams: {estado, pagina: 1},
    queryParamsHandling: 'merge',   // 'preserve' mantendría los antiguos y descartaría los nuevos
  });
}
irACrudo(url: string): void {
  // 4) navigateByUrl: recibe una URL YA construida. No admite relativeTo
  //    ni queryParams: lo que le pases es literalmente la URL final.
  this.router.navigateByUrl(url, {skipLocationChange: true});
}
enlaceCompartible(id: string): string {
  // 5) createUrlTree + serializeUrl: construir la URL sin navegar.
  //    Imprescindible para "copiar enlace", canonical, o comparaciones.
  const arbol = this.router.createUrlTree(['/tareas', id], {queryParams: {origen: 'email'}});
  return location.origin + this.router.serializeUrl(arbol);
}

import {Location} from '@angular/common';
export class DetalleTareaComponent {
  private readonly router = inject(Router);
  private readonly location = inject(Location);
  constructor() {
    // A) DURANTE la navegación (el constructor se ejecuta en la fase de activación):
    const enCurso = this.router.getCurrentNavigation();
    const mensaje = enCurso?.extras.state?.['mensaje'] as string | undefined;
    // B) DESPUÉS de la navegación, o al recargar la página: history.state.
    //    Location.getState() ya filtra las claves internas del router (navigationId).
    const estadoPersistido = this.location.getState() as {mensaje?: string} | null;
    if (mensaje ?? estadoPersistido?.mensaje) {
      this.avisos.mostrar(mensaje ?? estadoPersistido!.mensaje!);
    }
  }
}

type MaybeAsync<T>  = T | Observable<T> | Promise<T>;
type GuardResult    = boolean | UrlTree | RedirectCommand;   // RedirectCommand: v18+
type CanActivateFn      = (ruta: ActivatedRouteSnapshot, estado: RouterStateSnapshot)
                            => MaybeAsync<GuardResult>;
type CanActivateChildFn = (hija: ActivatedRouteSnapshot, estado: RouterStateSnapshot)
                            => MaybeAsync<GuardResult>;
type CanDeactivateFn<T> = (componente: T, rutaActual: ActivatedRouteSnapshot,
                           estadoActual: RouterStateSnapshot, estadoSiguiente: RouterStateSnapshot)
                            => MaybeAsync<GuardResult>;
type CanMatchFn         = (ruta: Route, segmentos: UrlSegment[]) => MaybeAsync<GuardResult>;
type ResolveFn<T>       = (ruta: ActivatedRouteSnapshot, estado: RouterStateSnapshot) => MaybeAsync<T>;

export class LoginComponent {
  // Con withComponentInputBinding, el query param llega como input.
  readonly returnUrl = input<string>('/');
  private readonly router = inject(Router);
  async entrar(credenciales: Credenciales): Promise<void> {
    await this.auth.iniciarSesion(credenciales);
    // SEGURIDAD: nunca navegues a ciegas a una URL que viene de la query string.
    // Un atacante podría enviar ?returnUrl=https://malicioso.example y convertir
    // tu login en un redirector abierto (open redirect).
    const destino = this.esInterna(this.returnUrl()) ? this.returnUrl() : '/';
    // replaceUrl: el botón atrás no debe volver al formulario de login.
    await this.router.navigateByUrl(destino, {replaceUrl: true});
  }
  private esInterna(url: string): boolean {
    // Debe empezar por una sola barra: descarta '//otro.dominio' y 'http://...'
    return url.startsWith('/') && !url.startsWith('//');
  }
}

// Fábrica: devuelve un guard configurado. Sirve para canActivate y para canMatch,
// porque ninguno de los dos usa realmente los argumentos en este caso.
export function rolGuard(...rolesRequeridos: Rol[]): CanActivateFn & CanMatchFn {
  return () => {
    const usuario = inject(SesionStore).usuario();
    if (!usuario) return inject(Router).createUrlTree(['/login']);
    const autorizado = rolesRequeridos.some((r) => usuario.roles.includes(r));
    // Para canActivate, un UrlTree a /sin-permiso informa al usuario.
    // Para canMatch, devolver false hace que el router pruebe la ruta siguiente.
    return autorizado ? true : inject(Router).createUrlTree(['/sin-permiso']);
  };
}

// canMatch permite algo que canActivate no puede: rutas alternativas.
// El router prueba en orden; la primera cuyo canMatch devuelva true, gana.
export const routes: Routes = [
  {
    path: 'panel',
    canMatch: [() => inject(SesionStore).esAdmin()],
    loadComponent: () => import('./panel/panel-admin.component'),
  },
  {
    path: 'panel',                     // misma URL, otro componente y otro chunk
    loadComponent: () => import('./panel/panel-basico.component'),
  },
];

// Contrato mínimo que debe cumplir el componente protegido.
export interface PuedeTenerCambios {
  readonly tieneCambiosSinGuardar: () => boolean;   // señal o método
}
export const cambiosSinGuardarGuard: CanDeactivateFn<PuedeTenerCambios> = (
  componente, _rutaActual, _estadoActual, estadoSiguiente,
) => {
  if (!componente.tieneCambiosSinGuardar()) return true;
  // Si el destino es la propia pantalla de login (sesión caducada), no tiene
  // sentido preguntar: el usuario no puede guardar nada de todas formas.
  if (estadoSiguiente.url.startsWith('/login')) return true;
  // confirm() bloquea el hilo y no se puede estilizar; en producción se usa
  // un diálogo propio que devuelve una promesa u observable.
  return inject(DialogoService)
    .confirmar('Tienes cambios sin guardar. ¿Salir y descartarlos?')
    .pipe(take(1));   // el router toma el primer valor: cerramos el flujo explícitamente
};

export const tareaResolver: ResolveFn<Tarea> = (ruta) => {
  const api = inject(TareasApi);
  const router = inject(Router);
  return api.obtener(ruta.paramMap.get('id')!).pipe(
    catchError((error: unknown) => {
      // Si no gestionas el error, la navegación termina en NavigationError
      // y el usuario se queda en la pantalla anterior sin ninguna explicación.
      if (error instanceof HttpErrorResponse && error.status === 404) {
        // Redirigir: cancela esta navegación y lanza otra.
        router.navigate(['/tareas'], {state: {aviso: 'Esa tarea ya no existe'}});
      } else {
        inject(NotificadorErrores).registrar(error);
      }
      // EMPTY completa sin emitir: el router aborta la navegación en silencio.
      return EMPTY;
    }),
  );
};

@Component({
  template: `
    @if (tarea.isLoading()) { <app-esqueleto-detalle /> }   <!-- ya se ha navegado -->
    @else if (tarea.error()) { <app-error (reintentar)="tarea.reload()" /> }
    @else if (tarea.hasValue()) { <app-ficha-tarea [tarea]="tarea.value()" /> }
  `,
})
export class DetalleTareaComponent {
  readonly id = input.required<string>();
  private readonly api = inject(TareasApi);
  // La navegación es instantánea; el dato llega después y el usuario ve progreso.
  readonly tarea = rxResource({
    params: () => this.id(),
    stream: ({params}) => this.api.obtener(params),
  });
}

import {Routes} from '@angular/router';
// Un fichero de rutas por funcionalidad, exportado como constante o por defecto.
export const TAREAS_ROUTES: Routes = [
  {
    path: '',
    // Layout propio de la funcionalidad, con su router-outlet.
    loadComponent: () => import('./tareas-layout.component').then((m) => m.TareasLayoutComponent),
    // Estado y servicios que solo viven mientras el usuario esté en /tareas.
    providers: [TareasStore],
    children: [
      {path: '', loadComponent: () => import('./lista.component')},           // export default
      {path: 'nueva', loadComponent: () => import('./crear.component')},
      {path: ':id', loadComponent: () => import('./detalle.component')},
      {path: ':id/editar', loadComponent: () => import('./editar.component'),
       canDeactivate: [cambiosSinGuardarGuard]},
    ],
  },
];
// Y en el fichero del componente:
//   export default class ListaTareasComponent { ... }
// Angular admite export default en loadComponent y loadChildren, lo que
// ahorra el .then(m => m.X) y evita erratas en el nombre de la clase.

import {Injectable} from '@angular/core';
import {PreloadingStrategy, Route} from '@angular/router';
import {EMPTY, Observable, timer, switchMap} from 'rxjs';
@Injectable({providedIn: 'root'})
export class PrecargaSelectivaStrategy implements PreloadingStrategy {
  // 'load' es la función que descarga el chunk. Si no la llamas, no se descarga.
  preload(ruta: Route, load: () => Observable<unknown>): Observable<unknown> {
    // 1) Decisión declarativa desde la propia configuración de rutas.
    if (ruta.data?.['preload'] !== true) return EMPTY;
    // 2) Respeto por la conexión del usuario. La Network Information API NO está
    //    disponible en todos los navegadores (falta en Safari y Firefox), así que
    //    se comprueba con optional chaining y se asume "buena" si no hay dato.
    const conexion = (navigator as Navigator & {connection?: NetworkInformationLike}).connection;
    if (conexion?.saveData) return EMPTY;                              // modo ahorro de datos
    if (/(^|-)(2g|slow-2g)$/.test(conexion?.effectiveType ?? '')) return EMPTY;
    // 3) Esperar un poco para no competir con las peticiones críticas del arranque.
    return timer(2000).pipe(switchMap(() => load()));
  }
}
interface NetworkInformationLike { saveData?: boolean; effectiveType?: string; }
// provideRouter(routes, withPreloading(PrecargaSelectivaStrategy))
// y en la ruta:  {path: 'informes', data: {preload: true}, loadChildren: ...}

# 1) La tabla de salida del build ya dice qué hay en el bundle inicial
#    y qué son chunks diferidos ("Lazy chunk files").
ng build --configuration production
# 2) Análisis detallado: quién ocupa qué dentro de cada chunk.
ng build --configuration production --stats-json
npx esbuild-visualizer --metadata dist/<app>/stats.json --open
# 3) Verificación empírica, la única que no miente: abre la pestaña Red de las
#    DevTools, filtra por JS, navega a la sección y comprueba que aparece un
#    fichero nuevo. Si aparece en la carga inicial, tu lazy loading no funciona.

{
  "budgets": [
    { "type": "initial", "maximumWarning": "500kB", "maximumError": "800kB" },
    { "type": "anyComponentStyle", "maximumWarning": "4kB", "maximumError": "8kB" }
  ]
}

<div class="admin">
  <nav>
    <a routerLink="usuarios" routerLinkActive="activo">Usuarios</a>
    <a routerLink="ajustes"  routerLinkActive="activo">Ajustes</a>
  </nav>
  <!-- Outlet principal: aquí se pintan las rutas hijas sin 'outlet' -->
  <main><router-outlet (activate)="alActivar($event)" (deactivate)="alDesactivar($event)" /></main>
  <!-- Outlet auxiliar: panel lateral independiente de la ruta principal.
       Se rellena solo si la URL contiene el grupo (lateral:...) -->
  <aside><router-outlet name="lateral" /></aside>
</div>

export const ADMIN_ROUTES: Routes = [
  {
    path: '',
    component: AdminLayoutComponent,
    children: [
      {path: '', pathMatch: 'full', redirectTo: 'usuarios'},
      {path: 'usuarios', loadComponent: () => import('./usuarios.component')},
      {path: 'ajustes',  loadComponent: () => import('./ajustes.component')},
      // Rutas del outlet auxiliar: mismo nivel, otra zona de la pantalla.
      {path: 'detalle/:id', outlet: 'lateral',
       loadComponent: () => import('./usuario-panel.component')},
      {path: 'ayuda', outlet: 'lateral',
       loadComponent: () => import('./ayuda-panel.component')},
    ],
  },
];

private readonly router = inject(Router);
private readonly route = inject(ActivatedRoute);
abrirPanel(id: string): void {
  // La sintaxis {outlets: {...}} modifica SOLO el outlet indicado.
  // URL resultante: /admin/usuarios(lateral:detalle/42)
  this.router.navigate([{outlets: {lateral: ['detalle', id]}}], {relativeTo: this.route.parent});
}
cerrarPanel(): void {
  // null vacía el outlet y limpia el grupo de la URL.
  this.router.navigate([{outlets: {lateral: null}}], {relativeTo: this.route.parent});
}

{
  // Sin 'component' ni 'loadComponent': no crea nada en el DOM.
  // Sirve para aplicar de una vez guards, providers y data a un grupo de rutas.
  path: 'facturacion',
  canActivate: [authGuard, rolGuard('finanzas')],
  resolve: {empresa: empresaResolver},
  providers: [FacturacionApi, {provide: MONEDA, useValue: 'EUR'}],
  data: {seccion: 'facturacion'},
  children: [
    {path: 'facturas', loadComponent: () => import('./facturas.component')},
    {path: 'recibos',  loadComponent: () => import('./recibos.component')},
  ],
}

@Injectable({providedIn: 'root'})
export class TareasApi {
  private readonly http = inject(HttpClient);
  private readonly base = '/api/tareas';
  // Por defecto observe: 'body' → el observable emite el cuerpo ya deserializado.
  listar(): Observable<TareaDto[]> { return this.http.get<TareaDto[]>(this.base); }
  // observe: 'response' → HttpResponse<T>: acceso a status, headers y body.
  // Imprescindible para paginación por cabeceras (X-Total-Count) o para leer ETag.
  listarPaginado(pagina: number): Observable<{items: TareaDto[]; total: number}> {
    return this.http.get<TareaDto[]>(this.base, {params: {pagina}, observe: 'response'}).pipe(
      map((resp) => ({
        items: resp.body ?? [],
        total: Number(resp.headers.get('X-Total-Count') ?? 0),
      })),
    );
  }
  crear(dto: CrearTareaDto): Observable<TareaDto> {
    return this.http.post<TareaDto>(this.base, dto, {
      headers: new HttpHeaders({'Idempotency-Key': crypto.randomUUID()}),
    });
  }
  // PATCH parcial. DELETE suele responder 204 sin cuerpo: el tipo correcto es void.
  actualizar(id: string, cambios: Partial<CrearTareaDto>): Observable<TareaDto> {
    return this.http.patch<TareaDto>(`${this.base}/${id}`, cambios);
  }
  eliminar(id: string): Observable<void> { return this.http.delete<void>(`${this.base}/${id}`); }
  // responseType cambia cómo se interpreta la respuesta: 'json' (defecto),
  // 'text', 'blob' o 'arraybuffer'. Un CSV o un PDF necesitan 'blob'.
  exportarCsv(): Observable<Blob> {
    return this.http.get(`${this.base}/export`, {responseType: 'blob'});
  }
}

import {HttpEvent, HttpEventType} from '@angular/common/http';
export type EstadoSubida =
  | {tipo: 'progreso'; porcentaje: number}
  | {tipo: 'completada'; fichero: FicheroDto};
subir(fichero: File): Observable<EstadoSubida> {
  const cuerpo = new FormData();
  cuerpo.append('fichero', fichero, fichero.name);
  // NO pongas Content-Type a mano: el navegador debe añadir el boundary del
  // multipart. Si lo fijas tú, el backend no sabrá dónde separa cada parte.
  return this.http.post<FicheroDto>('/api/ficheros', cuerpo, {
    reportProgress: true,   // pide los eventos de progreso
    observe: 'events',      // el observable emite TODO el ciclo, no solo el cuerpo
  }).pipe(
    map((evento: HttpEvent<FicheroDto>): EstadoSubida | null => {
      switch (evento.type) {
        // total puede ser undefined si el servidor no informa del tamaño.
        case HttpEventType.UploadProgress:
          return {tipo: 'progreso',
            porcentaje: evento.total ? Math.round((100 * evento.loaded) / evento.total) : 0};
        case HttpEventType.Response: return {tipo: 'completada', fichero: evento.body!};
        default: return null;   // Sent, ResponseHeader, DownloadProgress, User…
      }
    }),
    filter((e): e is EstadoSubida => e !== null),
  );
}

export type ErrorDominio =
  | {clase: 'sin-conexion'}                                  // no hubo respuesta
  | {clase: 'autenticacion'} | {clase: 'permisos'}           // 401 · 403
  | {clase: 'no-encontrado'}                                 // 404
  | {clase: 'validacion'; campos: Record<string, string[]>}  // 422 / 400
  | {clase: 'conflicto'; mensaje: string}                    // 409
  | {clase: 'servidor'; mensaje: string};                    // 5xx y el resto
export function aErrorDominio(error: unknown): ErrorDominio {
  if (!(error instanceof HttpErrorResponse)) return {clase: 'servidor', mensaje: 'Error inesperado'};
  // status 0 = la petición NUNCA obtuvo respuesta: red caída, DNS, CORS
  // bloqueado, petición abortada o certificado rechazado. El navegador oculta
  // el motivo real por seguridad, así que no intentes distinguirlo desde el JS.
  if (error.status === 0) return {clase: 'sin-conexion'};
  // A partir de aquí SÍ hubo respuesta del servidor y error.error es su cuerpo
  // (ya deserializado si era JSON; una cadena si era texto).
  switch (error.status) {
    case 401: return {clase: 'autenticacion'};
    case 403: return {clase: 'permisos'};
    case 404: return {clase: 'no-encontrado'};
    case 409: return {clase: 'conflicto', mensaje: leerMensaje(error)};
    case 400:
    case 422: return {clase: 'validacion', campos: error.error?.errors ?? {}};
    default:  return {clase: 'servidor', mensaje: leerMensaje(error)};
  }
}
function leerMensaje(error: HttpErrorResponse): string {
  // Formato problem+details (RFC 9457) o el estándar de NestJS: {message}.
  return error.error?.detail ?? error.error?.message ?? error.statusText ?? 'Error del servidor';
}

import {httpResource} from '@angular/common/http';
// Plantilla: @if (tareas.isLoading()) { esqueleto } @else if (tareas.error())
// { error + botón que llama a tareas.reload() } @else { @for sobre value() }
export class ListaTareasComponent {
  readonly texto = signal('');
  readonly pagina = signal(1);
  // La función reactiva se reevalúa cuando cambia CUALQUIER señal que lee.
  // Cada cambio lanza un GET nuevo y ABORTA el anterior automáticamente.
  readonly tareas = httpResource<Tarea[]>(
    () => ({url: '/api/tareas', params: {q: this.texto(), pagina: this.pagina()}}),
    {
      defaultValue: [],
      // parse es el punto natural para validar Y para mapear DTO → dominio.
      parse: (crudo) => TareaSchema.array().parse(crudo).map(desdeDto),
    },
  );
  // Expone además: status(), headers(), statusCode(), progress(), hasValue(), reload()
  // Variantes para respuestas no JSON: httpResource.text(), .blob(), .arrayBuffer()
}

import {HttpContextToken} from '@angular/common/http';
// Un HttpContextToken viaja con la petición sin ensuciar cabeceras ni URL.
// Es el mecanismo idiomático para las excepciones, mucho mejor que comprobar
// la URL con expresiones regulares dentro del interceptor.
export const SIN_AUTH   = new HttpContextToken<boolean>(() => false);
export const SIN_CARGA  = new HttpContextToken<boolean>(() => false);
export const CACHEABLE  = new HttpContextToken<boolean>(() => false);
export const REINTENTADA = new HttpContextToken<boolean>(() => false);
// Uso desde un servicio:
// this.http.get('/api/publico', {context: new HttpContext().set(SIN_AUTH, true)});

import {HttpInterceptorFn, HttpResponse} from '@angular/common/http';
import {inject, LOCALE_ID} from '@angular/core';
import {finalize, tap} from 'rxjs';
// 1) TOKEN DE AUTENTICACIÓN
export const authInterceptor: HttpInterceptorFn = (req, next) => {
  // inject() debe llamarse de forma SÍNCRONA aquí: dentro de un callback
  // posterior ya no hay contexto de inyección (error NG0203).
  const token = inject(SesionStore).accessToken();
  // SEGURIDAD: no envíes nunca el token a un dominio que no sea el tuyo.
  const esPropia = req.url.startsWith('/') || req.url.startsWith(API_BASE);
  if (!token || !esPropia || req.context.get(SIN_AUTH)) return next(req);
  // clone es obligatorio: la petición es inmutable.
  return next(req.clone({setHeaders: {Authorization: `Bearer ${token}`}}));
};
// 2) CABECERA DE IDIOMA
export const idiomaInterceptor: HttpInterceptorFn = (req, next) => {
  const idioma = inject(LOCALE_ID);          // 'es-ES' con la configuración del CLI
  return next(req.clone({setHeaders: {'Accept-Language': idioma}}));
};
// 3) LOGGING DE TIEMPOS
export const tiemposInterceptor: HttpInterceptorFn = (req, next) => {
  const t0 = performance.now();
  let estado = 0;
  return next(req).pipe(
    tap({next: (e) => { if (e instanceof HttpResponse) estado = e.status; }}),
    // finalize se ejecuta también si hay error o si se cancela la suscripción,
    // así que la medición nunca se pierde.
    finalize(() => {
      const ms = performance.now() - t0;
      if (ms > 1000) console.warn(`[http] LENTA ${req.method} ${req.urlWithParams} ${ms.toFixed(0)} ms`);
      else console.debug(`[http] ${req.method} ${req.urlWithParams} ${estado} ${ms.toFixed(0)} ms`);
    }),
  );
};
// 4) INDICADOR GLOBAL DE CARGA
export const cargaInterceptor: HttpInterceptorFn = (req, next) => {
  if (req.context.get(SIN_CARGA)) return next(req);   // sondeos, telemetría, autocompletar
  const indicador = inject(IndicadorCargaService);
  indicador.comenzar();
  return next(req).pipe(finalize(() => indicador.terminar()));
};

@Injectable({providedIn: 'root'})
export class IndicadorCargaService {
  // Un CONTADOR, no un booleano: con dos peticiones simultáneas, la primera
  // que termina apagaría el indicador mientras la otra sigue en curso.
  private readonly enCurso = signal(0);
  readonly cargando = computed(() => this.enCurso() > 0);
  comenzar(): void { this.enCurso.update((n) => n + 1); }
  terminar(): void { this.enCurso.update((n) => Math.max(0, n - 1)); }
}

// 5) REINTENTO CON RETROCESO EXPONENCIAL
const IDEMPOTENTES = new Set(['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE']);
export const reintentoInterceptor: HttpInterceptorFn = (req, next) => {
  // Reintentar un POST puede duplicar un pedido. Solo métodos idempotentes
  // (o POST con cabecera Idempotency-Key acordada con el backend).
  if (!IDEMPOTENTES.has(req.method)) return next(req);
  return next(req).pipe(
    retry({
      count: 3,
      delay: (error, intento) => {
        const reintentable = error instanceof HttpErrorResponse &&
          (error.status === 0 || error.status === 429 || error.status >= 500);
        if (!reintentable) return throwError(() => error);   // 4xx: no insistas
        // Retroceso exponencial + jitter, para no sincronizar a mil clientes
        // contra un servidor que intenta levantarse (efecto manada atronadora).
        const espera = Math.min(500 * 2 ** (intento - 1), 8000) + Math.random() * 250;
        return timer(espera);
      },
    }),
  );
};
// 6) CACHÉ DE GET
export const cacheInterceptor: HttpInterceptorFn = (req, next) => {
  if (req.method !== 'GET' || !req.context.get(CACHEABLE)) return next(req);
  const cache = inject(CacheHttpService);
  const guardada = cache.obtener(req.urlWithParams);
  // clone() evita entregar la MISMA instancia a dos consumidores que
  // podrían mutar el cuerpo y contaminarse entre sí.
  if (guardada) return of(guardada.clone());
  return next(req).pipe(
    tap((evento) => {
      if (evento instanceof HttpResponse) cache.guardar(req.urlWithParams, evento);
    }),
  );
};
// 7) FECHAS ISO → Date
const ISO_8601 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
function revivirFechas(valor: unknown): unknown {
  if (typeof valor === 'string') return ISO_8601.test(valor) ? new Date(valor) : valor;
  if (Array.isArray(valor)) return valor.map(revivirFechas);
  if (valor !== null && typeof valor === 'object') {
    return Object.fromEntries(
      Object.entries(valor).map(([k, v]) => [k, revivirFechas(v)]),
    );
  }
  return valor;
}
export const fechasInterceptor: HttpInterceptorFn = (req, next) =>
  next(req).pipe(
    map((evento) => evento instanceof HttpResponse
      ? evento.clone({body: revivirFechas(evento.body)})
      : evento),
  );

@Injectable({providedIn: 'root'})
export class AuthService {
  private readonly http = inject(HttpClient);
  readonly accessToken = signal<string | null>(null);
  // El estado compartido vive en el SERVICIO, no en una variable de módulo.
  // Motivo crítico: en SSR el módulo se comparte entre TODAS las peticiones
  // del servidor, así que una variable de módulo filtraría el refresco (y el
  // token) de un usuario a otro. El injector, en cambio, es por petición.
  private refresco$: Observable<string> | null = null;
  refrescar(): Observable<string> {
    this.refresco$ ??= this.http
      .post<{accessToken: string}>('/api/auth/refresh', {}, {
        withCredentials: true,                                 // el refresh token va en cookie httpOnly
        context: new HttpContext().set(SIN_AUTH, true),        // no interceptar esta llamada
      })
      .pipe(
        map((r) => r.accessToken),
        tap((t) => this.accessToken.set(t)),
        // finalize ANTES de shareReplay: se ejecuta cuando el flujo compartido
        // termina, y libera el hueco para un refresco futuro.
        finalize(() => { this.refresco$ = null; }),
        // refCount: false mantiene el refresco vivo aunque el primer
        // suscriptor se desuscriba (por ejemplo, si el usuario navega).
        shareReplay({bufferSize: 1, refCount: false}),
      );
    return this.refresco$;
  }
  cerrarSesion(): void {
    this.accessToken.set(null);
    this.refresco$ = null;
    inject(Router).navigateByUrl('/login', {replaceUrl: true});
  }
}

// DTO: la forma EXACTA que habla el backend. Fechas como cadenas, campos
// planos, nombres del servidor, enteros donde el dominio quiere enumerados.
export interface TareaDto {
  id: string; title: string; done: boolean;
  due_date: string | null; priority: 0 | 1 | 2; assignee_id: string | null;
}
// Modelo de dominio: la forma que quiere la interfaz. Tipos ricos y nombres
// del negocio, en el idioma del proyecto.
export interface Tarea {
  id: string; titulo: string; completada: boolean;
  vencimiento: Date | null; prioridad: 'baja' | 'media' | 'alta'; responsableId: string | null;
}
const PRIORIDADES = ['baja', 'media', 'alta'] as const;
// Los dos mapeadores son el único punto del frontend que conoce los nombres
// y los formatos del servidor. Son funciones puras: triviales de testear.
export function desdeDto(dto: TareaDto): Tarea {
  return {id: dto.id, titulo: dto.title, completada: dto.done,
    vencimiento: dto.due_date ? new Date(dto.due_date) : null,
    prioridad: PRIORIDADES[dto.priority], responsableId: dto.assignee_id};
}
export function aDto(t: Omit<Tarea, 'id'>): Omit<TareaDto, 'id'> {
  return {title: t.titulo, done: t.completada,
    due_date: t.vencimiento?.toISOString() ?? null,
    priority: PRIORIDADES.indexOf(t.prioridad) as 0 | 1 | 2, assignee_id: t.responsableId};
}

@Injectable({providedIn: 'root'})
export class TareasApi {
  private readonly http = inject(HttpClient);
  // Peticiones en vuelo: dos componentes que piden lo mismo a la vez comparten
  // UNA petición. Es deduplicación, no caché: la entrada se borra al terminar.
  private readonly enVuelo = new Map<string, Observable<Tarea>>();
  // Caché de lectura con invalidación explícita.
  private readonly cache = new Map<string, Observable<Tarea[]>>();
  obtener(id: string): Observable<Tarea> {
    const existente = this.enVuelo.get(id);
    if (existente) return existente;
    const peticion = this.http.get<TareaDto>(`/api/tareas/${id}`).pipe(
      map(desdeDto),
      catchError((e: unknown) => throwError(() => aErrorDominio(e))),
      finalize(() => this.enVuelo.delete(id)),
      shareReplay({bufferSize: 1, refCount: true}),
    );
    this.enVuelo.set(id, peticion);
    return peticion;
  }
  listar(filtro = ''): Observable<Tarea[]> {
    if (!this.cache.has(filtro)) {
      this.cache.set(filtro, this.http.get<TareaDto[]>('/api/tareas', {params: {q: filtro}}).pipe(
        map((dtos) => dtos.map(desdeDto)),
        // refCount: false mantiene el valor aunque nadie escuche: es una caché.
        // Sin invalidarla nunca, el usuario vería datos rancios para siempre.
        shareReplay({bufferSize: 1, refCount: false}),
      ));
    }
    return this.cache.get(filtro)!;
  }
  crear(tarea: Omit<Tarea, 'id'>): Observable<Tarea> {
    return this.http.post<TareaDto>('/api/tareas', aDto(tarea)).pipe(
      map(desdeDto),
      // Toda escritura invalida las lecturas afectadas. Es la parte que se
      // olvida siempre y la razón de los "no se actualiza hasta que recargo".
      tap(() => this.invalidar()),
    );
  }
  invalidar(): void { this.cache.clear(); }
}

import {webSocket, WebSocketSubject} from 'rxjs/webSocket';
import {Observable, retry, timer, share} from 'rxjs';
// ── WebSocket: bidireccional. webSocket() de RxJS abre la conexión al primer
//    suscriptor y la cierra cuando no queda ninguno.
@Injectable({providedIn: 'root'})
export class NotificacionesSocket {
  readonly conectado = signal(false);
  private readonly socket: WebSocketSubject<MensajeServidor> = webSocket({
    // El token no puede ir en cabeceras (el handshake no las admite desde JS):
    // se usa un ticket de un solo uso pedido antes por HTTP, o una cookie.
    url: `wss://api.example/ws?ticket=${obtenerTicket()}`,
    openObserver:  {next: () => this.conectado.set(true)},
    closeObserver: {next: () => this.conectado.set(false)}});
  // Reconexión con retroceso; share() para que N componentes usen UNA conexión.
  readonly mensajes$ = this.socket.pipe(
    retry({delay: (_e, n) => timer(Math.min(1000 * 2 ** (n - 1), 30_000))}),
    share({resetOnRefCountZero: false}),
  );
  enviar(m: MensajeCliente): void { this.socket.next(m as never); }
}
// ── SSE: unidireccional servidor → cliente, sobre HTTP normal. Reconexión
//    automática del navegador y reanudación con Last-Event-ID.
export function eventosServidor<T>(url: string): Observable<T> {
  return new Observable<T>((observador) => {
    // Limitación importante: EventSource NO admite cabeceras propias, así que
    // no puedes enviar Authorization. Autentica con cookie o con un token en
    // la query string (y asume que quedará en los logs del servidor).
    const fuente = new EventSource(url, {withCredentials: true});
    fuente.onmessage = (e) => observador.next(JSON.parse(e.data) as T);
    // readyState CLOSED significa fallo definitivo; en otro caso el navegador
    // ya está reintentando por su cuenta: no lo trates como error fatal.
    fuente.onerror = () => { if (fuente.readyState === EventSource.CLOSED)
      observador.error(new Error('SSE cerrado')); };
    return () => fuente.close();     // limpieza al cancelar la suscripción
  });
}

provideHttpClient(
  withFetch(),
  // Angular lee la cookie indicada y copia su valor en la cabecera indicada,
  // pero SOLO en peticiones mutantes (no GET ni HEAD) y SOLO a URLs relativas
  // o del mismo origen. Nunca envía el token a otro dominio.
  withXsrfConfiguration({cookieName: 'XSRF-TOKEN', headerName: 'X-XSRF-TOKEN'}),
)
// Requisitos para que funcione:
//  1. La cookie NO puede ser httpOnly: Angular necesita leerla desde JS.
//  2. El backend debe emitirla y validar que cabecera y cookie coinciden.
//  3. Si tu API está en OTRO dominio, el mecanismo integrado no se aplica:
//     tendrás que enviar la cabecera a mano en un interceptor.