Offline-first: Service Worker și cache

ng add @angular/pwa
# adaugă @angular/service-worker, ngsw-config.json, un manifest, iconițe și provideServiceWorker()
ng build   # worker-ul rulează doar în build-urile de producție, pe HTTPS (sau pe localhost)

{
  "$schema": "./node_modules/@angular/service-worker/config/schema.json",
  "index": "/index.html",
  "assetGroups": [
    {
      "name": "app-shell",
      "installMode": "prefetch",
      "resources": { "files": ["/favicon.ico", "/index.html", "/*.css", "/*.js"] }
    },
    {
      "name": "assets",
      "installMode": "lazy",
      "updateMode": "prefetch",
      "resources": { "files": ["/assets/**", "/*.(svg|png|webp|woff2)"] }
    }
  ],
  "dataGroups": [
    {
      "name": "prices",
      "urls": ["/api/prices/**"],
      "cacheConfig": { "strategy": "freshness", "timeout": "3s", "maxSize": 50, "maxAge": "1h" }
    },
    {
      "name": "catalogue",
      "urls": ["/api/products/**"],
      "cacheConfig": {
        "strategy": "performance",
        "maxSize": 200,
        "maxAge": "7d",
        "refreshAhead": "1d"
      }
    }
  ]
}

import { ApplicationRef, Component, DestroyRef, inject, signal } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { SwUpdate, type VersionReadyEvent } from '@angular/service-worker';
import { filter, interval } from 'rxjs';

@Component({
  selector: 'app-update-banner',
  template: `
    @if (ready()) {
      <div role="status">
        E gata o versiune nouă.
        <button type="button" (click)="reload()">Reîncarcă</button>
      </div>
    }
  `,
})
export class UpdateBanner {
  private readonly updates = inject(SwUpdate);
  protected readonly ready = signal(false);

  constructor() {
    if (!this.updates.isEnabled) return; // mod dev sau un browser fără Service Worker
    const destroyRef = inject(DestroyRef);

    this.updates.versionUpdates
      .pipe(
        filter((e): e is VersionReadyEvent => e.type === 'VERSION_READY'),
        takeUntilDestroyed(destroyRef),
      )
      .subscribe(() => this.ready.set(true)); // întrebăm; nu reîncărcăm în mijlocul unui formular

    // fișierele versiunii care rulează au dispărut de pe server: singura ieșire e un reload
    this.updates.unrecoverable
      .pipe(takeUntilDestroyed(destroyRef))
      .subscribe(() => document.location.reload());

    // un tab care stă deschis zile întregi trebuie și el să verifice din când în când
    const appRef = inject(ApplicationRef);
    void appRef.whenStable().then(() =>
      interval(6 * 60 * 60 * 1000)
        .pipe(takeUntilDestroyed(destroyRef))
        .subscribe(() => void this.updates.checkForUpdate()),
    );
  }

  protected reload(): void {
    document.location.reload(); // versiunea nouă pornește la următoarea încărcare a paginii
  }
}

import { HttpClient, HttpContext } from '@angular/common/http';
import { DOCUMENT, Service, computed, effect, inject, signal, untracked } from '@angular/core';
import { firstValueFrom } from 'rxjs';
import { IDEMPOTENCY_KEY } from './idempotency'; // vezi pagina despre actualizări optimiste
import { injectOnline } from './online';

interface Pending {
  key: string; // Idempotency-Key, generată O SINGURĂ DATĂ, când utilizatorul salvează
  url: string;
  body: unknown;
}

const STORAGE = 'outbox';

@Service()
export class Outbox {
  private readonly http = inject(HttpClient);
  private readonly storage = inject(DOCUMENT).defaultView?.localStorage; // undefined în timpul SSR
  readonly online = injectOnline();
  readonly items = signal<readonly Pending[]>(JSON.parse(this.storage?.getItem(STORAGE) ?? '[]'));
  readonly waiting = computed(() => this.items().length);
  private flushing = false;

  constructor() {
    // rezistă la reload (IndexedDB dacă datele sunt mari sau trebuie citite dintr-un worker)
    effect(() => this.storage?.setItem(STORAGE, JSON.stringify(this.items())));
    effect(() => {
      if (this.online()) untracked(() => void this.flush());
    });
  }

  save(url: string, body: unknown): void {
    this.items.update((list) => [...list, { key: crypto.randomUUID(), url, body }]);
    if (this.online()) void this.flush();
  }

  /** Câte una, în ordine. Un eșec oprește coada; următorul "online" o reia. */
  private async flush(): Promise<void> {
    if (this.flushing) return;
    this.flushing = true;
    try {
      while (this.online() && this.items().length) {
        const [next] = this.items();
        await firstValueFrom(
          this.http.post(next.url, next.body, {
            context: new HttpContext().set(IDEMPOTENCY_KEY, next.key),
          }),
        );
        this.items.update((list) => list.slice(1));
      }
    } catch {
      // tot offline sau serverul e căzut: elementul rămâne primul la rând
    } finally {
      this.flushing = false;
    }
  }
}

ng add @angular/pwa              worker + manifest + ngsw-config.json (doar build-uri de producție)
registrationStrategy             'registerWhenStable:30000': după primul render
assetGroups prefetch             shell-ul aplicației: index.html, JS, CSS, disponibile offline
assetGroups lazy                 imagini, fonturi: puse în cache la prima folosire
dataGroups freshness + timeout   întâi rețeaua; mai lent decât timeout → răspuns din cache
dataGroups performance           întâi cache-ul; refreshAhead reîmprospătează în fundal înainte de maxAge
maxAge                           limită fermă: intrările mai vechi se aruncă, chiar și offline
SwUpdate.versionUpdates          VERSION_READY → întrebi utilizatorul, reîncarci la click
SwUpdate.unrecoverable           fișierele versiunii vechi au dispărut → reload
checkForUpdate()                 periodic, pentru taburi care stau deschise zile întregi
CDN / cache HTTP                 ngsw.json și ngsw-worker.js: no-cache, niciodată immutable
navigator.onLine                 false e sigur, true înseamnă doar „există o rețea”
scrieri offline                  outbox: ordonat, persistat, fiecare cu un Idempotency-Key