Namespace en TypeScript: qué es y cuándo usarlo

Un namespace es un bloque con nombre que agrupa funciones, constantes y tipos bajo un mismo nombre. Los miembros marcados con export son accesibles como Name.member; el resto queda privado dentro del bloque. En tiempo de ejecución un namespace es un objeto normal.

namespace Geometry {
  const TAU = Math.PI * 2; // not exported: private to the namespace

  export function circumference(radius: number): number {
    return TAU * radius;
  }

  export function area(radius: number): number {
    return Math.PI * radius ** 2;
  }
}

console.log(Geometry.circumference(1).toFixed(2)); // 6.28
console.log(Geometry.area(2).toFixed(2));          // 12.57
console.log(Object.keys(Geometry));                // [ 'circumference', 'area' ]

A qué compila un namespace

Los namespaces son una de las pocas características de TypeScript que generan código. El bloque de arriba se convierte en una función que rellena un objeto:

var Geometry;
(function (Geometry) {
    const TAU = Math.PI * 2;
    function circumference(radius) {
        return TAU * radius;
    }
    Geometry.circumference = circumference;
    function area(radius) {
        return Math.PI * radius ** 2;
    }
    Geometry.area = area;
})(Geometry || (Geometry = {}));

Es el patrón que usaba el código JavaScript antes de que existieran los módulos para no poner todos los nombres en el ámbito global. TAU es una variable local de la función, y por eso el resto del código no puede verla. Intentar leerla es un error en tiempo de compilación:

// This does not compile: rate is not exported from the namespace.
namespace Tax {
  const rate = 0.2;
  export function withTax(price: number): number {
    return price * (1 + rate);
  }
}

console.log(Tax.withTax(100));
console.log(Tax.rate);

El compilador informa index.ts(10,17): error TS2339: Property 'rate' does not exist on type 'typeof Tax'. Añade export delante de const rate y las dos líneas se ejecutan.

Anidamiento, fusión y alias

Los namespaces se pueden anidar, y dos bloques con el mismo nombre se fusionan en uno. El Geometry || (Geometry = {}) de la salida es lo que lo hace posible: el segundo bloque añade cosas al objeto existente. import X = A.B crea un alias corto.

namespace Shop {
  export namespace Pricing {
    export type Currency = "USD" | "EUR";
    export function format(amount: number, currency: Currency): string {
      return `${amount.toFixed(2)} ${currency}`;
    }
  }
}

// A second block with the same name adds members to Shop.
namespace Shop {
  export const name = "Corner Shop";
}

import Pricing = Shop.Pricing; // alias for the nested namespace

const c: Pricing.Currency = "EUR";
console.log(Shop.name, Pricing.format(4.5, c)); // Corner Shop 4.50 EUR

namespace A.B.C { } es una forma abreviada de tres bloques anidados. La forma antigua module Shop { } significa lo mismo pero ahora se rechaza con el error TS1540, A 'namespace' declaration should not be declared using the 'module' keyword. Please use the 'namespace' keyword instead.

Fusión con funciones y clases

Un namespace puede compartir nombre con una función, una clase o un enum y añadirle miembros. Sigue siendo la forma más limpia de describir una función que además lleva propiedades, o una clase con funciones auxiliares añadidas.

function format(n: number): string {
  return format.prefix + n.toFixed(format.digits);
}
namespace format {
  export let prefix = "$";
  export let digits = 2;
}

console.log(format(3.5)); // $3.50
format.prefix = "EUR ";
console.log(format(3.5)); // EUR 3.50

class Temperature {
  constructor(public celsius: number) {}
}
namespace Temperature {
  export function fromFahrenheit(f: number): Temperature {
    return new Temperature(((f - 32) * 5) / 9);
  }
}

console.log(Temperature.fromFahrenheit(212)); // Temperature { celsius: 100 }

En una clase, un método static hace el mismo trabajo y es JavaScript normal. En una función, también puedes prescindir del namespace y asignar format.prefix = "$" justo después de la declaración; TypeScript registra las propiedades asignadas así.

Namespaces frente a módulos

Antes de los ES modules, un programa grande de TypeScript eran muchos archivos de script que compartían namespaces globales, unidos con /// <reference path="..." /> y compilados en un solo archivo con outFile. Los módulos sustituyeron eso: cada archivo es su propio ámbito, las dependencias son imports explícitos y los bundlers pueden descartar los exports que no se usan. TypeScript 7 eliminó outFile (error TS5102), así que la configuración de namespaces repartidos en varios archivos ya no es una opción de compilación.

Dentro de un módulo, envolverlo todo en un namespace añade un segundo nivel de nombres sin ganar nada: quien importe escribiría Utils.Utils.format. Exporta las funciones directamente y deja que quien importe elija import * as Utils from "./utils.js" si quiere un prefijo.

Dónde siguen apareciendo los namespaces

Los archivos de declaraciones los usan para describir librerías que exponen un único objeto global, y para agrupar tipos:

// jquery-like.d.ts: a global function that also has properties
declare function $(selector: string): unknown;
declare namespace $ {
    const version: string;
    function ajax(url: string): Promise<unknown>;
}

Los paquetes de tipos los usan para exponer tipos que puedes ampliar. @types/node declara namespace NodeJS, y ampliar su interfaz ProcessEnv desde cualquier módulo requiere declare global:

// env.d.ts
export {};

declare global {
    namespace NodeJS {
        interface ProcessEnv {
            API_URL: string; // process.env.API_URL is now string, not string | undefined
        }
    }
}

Las interfaces dentro de namespaces fusionados también se fusionan, y eso es lo que hace funcionar esta ampliación.

Namespaces y type stripping

Node 24 ejecuta archivos .ts borrando la sintaxis de tipos. Un namespace con valores no se puede borrar, hay que compilarlo al objeto que se ha mostrado arriba, así que node app.ts se detiene con:

SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript namespace declaration is not supported in strip-only mode

Hay dos tipos de namespace que funcionan porque desaparecen por completo: un declare namespace, y un namespace cuyos miembros son todos tipos o interfaces. La opción del compilador erasableSyntaxOnly: true marca los demás en tiempo de compilación con el error TS1294, This syntax is not allowed when 'erasableSyntaxOnly' is enabled., y así es como los proyectos que se ejecutan con type stripping los mantienen fuera. node --experimental-transform-types sí compila namespaces, con un aviso de que es experimental.