TypeScript
Funcionamiento de namespaces en TypeScript, declaración y combinación de espacios de nombres, diferencias con módulos ES y casos de compatibilidad heredada.
Un agrupa nombres bajo un objeto y puede combinar declaraciones distribuidas en varios bloques.
namespace Validation {
export function isText(value: unknown): value is string {
return typeof value === "string";
}
}namespace Validation {
const minimumLength = 3;
export function isValidName(value: string): boolean {
return value.length >= minimumLength;
}
}minimumLength solo es visible dentro de ese bloque. isValidName queda disponible como:
Validation.isValidName("Nicolás");Para un script, TypeScript puede producir una estructura semejante a:
var Validation;
(function (Validation) {
function isValidName(value) {
return value.length >= 3;
}
Validation.isValidName = isValidName;
})(Validation || (Validation = {}));El resultado exacto depende del target y configuración, pero el punto importante es que el namespace puede crear un valor runtime.
namespace Application {
export namespace Products {
export type Identifier = string;
export function findById(id: Identifier) {
// ...
}
}
}Application.Products.findById("p1");Anidar demasiado produce nombres largos y dependencias difíciles de descubrir.
namespace Validation {
export function isText(value: unknown): value is string {
return typeof value === "string";
}
}
namespace Validation {
export function isNumber(value: unknown): value is number {
return typeof value === "number";
}
}Las declaraciones se fusionan y comparten los miembros exportados.
namespace Validation {
const secret = "internal";
}
namespace Validation {
console.log(secret);
}No funciona. Un miembro no exportado solo pertenece al bloque donde fue declarado, aunque el namespace tenga el mismo nombre.
namespace Products {
export type Identifier = string;
export interface Repository {
findById(id: Identifier): Product | undefined;
}
}Los tipos exportados se usan como:
let repository: Products.Repository;No existen como propiedades runtime, aunque el namespace sí pueda existir como valor por otros miembros.
function createProduct() {
// ...
}
namespace createProduct {
export type Input = {
name: string;
price: number;
};
}const input: createProduct.Input = {
name: "Keyboard",
price: 100,
};Este patrón asocia tipos a una función, pero los exports de módulo suelen ser más simples en APIs nuevas.
class Product {}
namespace Product {
export type Status = "active" | "inactive";
}La namespace añade miembros estáticos o tipos asociados al nombre de la clase.
enum Status {
Active,
Inactive,
}
namespace Status {
export function isFinal(value: Status): boolean {
return value === Status.Inactive;
}
}Históricamente podían dividirse mediante referencias y concatenación:
/// <reference path="validation-text.ts" />
/// <reference path="validation-number.ts" />Con outFile, varios scripts podían emitirse juntos.
Este modelo exige controlar orden, globals y build. Los módulos modernos resuelven dependencias mediante imports explícitos.
export namespace Validation {
export function isText(value: unknown): value is string {
return typeof value === "string";
}
}Es válido, pero suele añadir una capa innecesaria:
export function isText(value: unknown): value is string {
return typeof value === "string";
}El módulo ya proporciona scope y agrupación.
import isText = Validation.isText;Es una sintaxis propia de TypeScript para aliases de entidades cualificadas. No debe confundirse con los imports de módulos ES.
declare namespace LegacySDK {
function initialize(apiKey: string): void;
interface Options {
debug?: boolean;
}
}Describe un objeto global proporcionado por un script externo. No crea LegacySDK.
Una librería puede consumirse como módulo y, en scripts, exponer un global:
export as namespace LegacySDK;
export function initialize(apiKey: string): void;Este patrón pertenece principalmente a declarations para librerías UMD heredadas.
outFile.Para aplicaciones modernas de Node.js o navegador, prefiere módulos ES salvo una necesidad concreta.
declare namespace PaymentWidget {
type Options = {
amountInCents: number;
currency: string;
};
function open(options: Options): void;
}El script externo debe crear realmente PaymentWidget.
import = con import ES.¿Por qué un namespace dentro de un módulo suele ser redundante?
Porque el módulo ya crea un scope propio y permite agrupar una API mediante exports; el namespace añade otra capa de acceso y posible emisión sin resolver un problema nuevo.
Enums y const enum explica tipos que también producen valores runtime y sus alternativas mediante objetos literales.