Risposta.

Storia della questione

Il Declaration Merging è una caratteristica unica di TypeScript che consente di unire più dichiarazioni con lo stesso nome in un'unica entità. Questo è legato alla storia di TypeScript come tipizzazione su JavaScript: molte librerie di terze parti dichiaravano interfacce, funzioni, spazi dei nomi, e TypeScript doveva consentire la loro estensione senza modificare il codice sorgente della libreria.

Problema

In API complesse e nella tipizzazione di librerie JS di terze parti può essere necessario dividere le responsabilità — ad esempio, estendere i tipi di un modulo, aggiungere campi a un'interfaccia, unire nomi. Tuttavia, la maggior parte dei linguaggi non supporta questo tipo di unione di dichiarazioni.

Soluzione

TypeScript consente di unire (merge) le dichiarazioni di interfacce, spazi dei nomi (namespace), funzioni, classi con nomi identici, rendendo l'API flessibile per l'estensione. È utilizzato per estendere tipi di terze parti, aggiungere metodi personalizzati alle librerie, e organizzare codice modulare.

Esempio di codice:

// merging di interfacce
interface User {
  id: number;
}
interface User {
  name: string;
}
const u: User = { id: 1, name: "Jack" };

// merging di namespace + funzione
function greet() {
  return "Hi!";
}
namespace greet {
  export function loud() { return "HI!"; }
}
greet(); // "Hi!"
greet.loud(); // "HI!"

Caratteristiche chiave:

Consente di unire interfacce, funzioni con namespace, enum con namespace, ma non tipi.
Utilizzato per descrivere API estensibili e globali dichiarazioni di estensione.
Consente di modificare/estendere in modo sicuro i tipi delle librerie di terze parti senza modificarle.

Domande insidiose.

È possibile unire type alias analogamente alle interfacce?

No, type alias non possono essere uniti. Tentare di dichiarare più type con lo stesso nome genererà un errore di compilazione.

type T = { a: string };
type T = { b: number }; // Errore

TypeScript inserirà i campi dell'interfaccia/spazio dei nomi in ordine casuale?

La struttura unita è sempre costruita nell'ordine delle dichiarazioni — se ci sono nomi di proprietà identici, l'ultima dichiarazione "vince".

I metodi di un'interfaccia si uniscono in un'unica funzione?

No, i metodi con nomi identici in interfacce diverse non si uniscono in un'unica funzione — se le firme coincidono, TypeScript non permetterà comunque di implementare "entrambi" i varianti.

Errori comuni e anti-pattern

Tentativi di unire type alias o enum senza namespace — generano errore.
Campi ripetuti con tipi diversi all'interno delle interfacce — conflitto, non si uniscono;
Usare il merging senza una necessità consapevole — porta a codice illeggibile.

Esempio dalla vita reale

Caso negativo

Un'azienda definisce l'interfaccia globale Window due volte con campi diversi e tipi diversi per il campo con lo stesso nome. Durante la costruzione il compilatore non rileva il problema, ma all'esecuzione si presenta un conflitto di tipo inaspettato.

Pro:

Veloce possibilità di "espandere" l'interfaccia senza modifica dell'origine.

Contro:

Nomi conflittuali portano a bug, difficile da rintracciare.
Spesso complica la comprensione della struttura completa del tipo.

Caso positivo

Si scrive un file d.ts per una libreria di terze parti, dove l'interfaccia API viene ampliata da moduli separati senza modifiche alla libreria stessa, tutte le estensioni sono documentate, la naming policy è descritta in Wiki.