Respuesta.

Historia de la pregunta

La fusión de declaraciones es una característica única de TypeScript que permite combinar múltiples declaraciones con los mismos nombres en una sola entidad. Esto está relacionado con la historia de TypeScript como una tipificación sobre JavaScript: muchas bibliotecas externas declaraban interfaces, funciones, espacios de nombres, y TypeScript debía permitir su ampliación sin modificar el código fuente de la biblioteca.

Problema

En APIs complejas y al tipar bibliotecas JS externas, puede ser necesario dividir la responsabilidad: por ejemplo, ampliar los tipos de un módulo, añadir campos a una interfaz, combinar nombres. Sin embargo, la mayoría de los lenguajes no soportan tal fusión de declaraciones.

Solución

TypeScript permite combinar (merge) las declaraciones de interfaces, espacios de nombres (namespace), funciones, clases con los mismos nombres, lo que hace que la API sea flexible para la expansión. Se utiliza para extender tipos externos, añadir métodos personalizados a las bibliotecas, así como para organizar el código modular.

Ejemplo de código:

// fusión de interfaces
interface User {
  id: number;
}
interface User {
  name: string;
}
const u: User = { id: 1, name: "Jack" };

// fusión de namespace + función
function greet() {
  return "¡Hola!";
}
namespace greet {
  export function loud() { return "¡HOLA!"; }
}
greet(); // "¡Hola!"
greet.loud(); // "¡HOLA!"

Características clave:

Permite combinar interfaces, funciones con namespace, enums con namespace, pero no tipos.
Se utiliza para describir APIs extensibles y ampliaciones globales de declaraciones.
Permite modificar/ampliar tipos de bibliotecas externas de forma segura sin cambiarlas.

Preguntas capciosas.

¿Se pueden combinar type alias de manera similar a las interfaces?

No, los type alias no se pueden combinar. Si intentas declarar varios types con el mismo nombre, habrá un error de compilación.

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

¿Insertará TypeScript los campos de la interfaz/namespace en orden aleatorio?

La estructura fusionada siempre se construye en el orden de las declaraciones: si hay nombres de propiedades idénticos, la última declaración "gana".

¿Se combinan los métodos de una interfaz en una sola función?

No, los métodos con los mismos nombres en diferentes interfaces no se combinan en una sola función: si las firmas coinciden, TypeScript aún no permitirá implementar ambas variantes.

Errores comunes y anti-patrones

Intentar combinar type alias o enums sin namespace resultará en un error.
Campos repetidos con diferentes tipos dentro de interfaces causaran un conflicto, no se fusionan;
Usar fusión sin una necesidad consciente conduce a un código ilegible.

Ejemplo de la vida real

Caso negativo

Una empresa define la interfaz global Window dos veces con diferentes campos y diferentes tipos para el campo con el mismo nombre. Durante la compilación, el compilador no detecta el problema, pero al ejecutarse surge un conflicto de tipos inesperado.

Ventajas:

Rápida posibilidad de "ampliar" la interfaz sin cambiar la fuente.

Desventajas:

Nombres en conflicto conducen a errores, son difíciles de rastrear.
A menudo dificulta la comprensión de la estructura completa del tipo.

Caso positivo

Se escribe un archivo d.ts para una biblioteca externa, donde la interfaz de la API se amplía mediante módulos separados sin modificar la biblioteca misma, todas las extensiones están documentadas y la política de nomenclatura está descrita en la Wiki.