Namespace в TypeScript: что это и когда использовать

Namespace это именованный блок, который объединяет функции, константы и типы под одним именем. Члены с пометкой export доступны как Name.member; остальные остаются приватными для блока. Во время выполнения namespace это обычный объект.

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' ]

Во что компилируется namespace

Namespace одна из немногих возможностей TypeScript, которые генерируют код. Блок выше превращается в функцию, которая заполняет объект:

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 = {}));

Этим приёмом код на JavaScript пользовался до появления модулей, чтобы не складывать все имена в глобальную область видимости. TAU это локальная переменная функции, поэтому другой код её не видит. Попытка её прочитать даёт ошибку компиляции:

// 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);

Компилятор сообщает index.ts(10,17): error TS2339: Property 'rate' does not exist on type 'typeof Tax'. Добавьте export перед const rate, и обе строки выполнятся.

Вложенность, слияние и псевдонимы

Namespace могут быть вложенными, а два блока с одинаковым именем сливаются в один. Именно Geometry || (Geometry = {}) в сгенерированном коде это обеспечивает: второй блок дополняет уже существующий объект. import X = A.B создаёт короткий псевдоним.

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 { } это сокращение для трёх вложенных блоков. Старая запись module Shop { } означает то же самое, но теперь отвергается с ошибкой TS1540, A 'namespace' declaration should not be declared using the 'module' keyword. Please use the 'namespace' keyword instead.

Слияние с функциями и классами

Namespace может иметь то же имя, что функция, класс или enum, и добавлять к ним члены. Это по-прежнему самый чистый способ описать функцию, у которой есть свойства, или класс с прикреплёнными вспомогательными функциями.

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 }

Для класса ту же задачу решает static-метод, и это обычный JavaScript. Для функции можно обойтись без namespace и присвоить format.prefix = "$" сразу после объявления; TypeScript отслеживает свойства, присвоенные таким образом.

Namespace и модули

До ES-модулей большая программа на TypeScript состояла из множества скриптов с общими глобальными пространствами имён, связанных через /// <reference path="..." /> и скомпилированных в один файл с помощью outFile. Модули это заменили: каждый файл это своя область видимости, зависимости это явные импорты, а бандлеры могут выбрасывать неиспользуемые экспорты. В TypeScript 7 outFile удалён (ошибка TS5102), так что многофайловая схема на namespace больше не вариант сборки.

Внутри модуля оборачивать всё в namespace значит добавлять второй уровень имён без всякой пользы: импортирующему коду пришлось бы писать Utils.Utils.format. Экспортируйте функции напрямую, и пусть импортирующий код сам выберет import * as Utils from "./utils.js", если ему нужен префикс.

Где namespace встречаются до сих пор

Файлы объявлений используют их, чтобы описывать библиотеки, которые открывают один глобальный объект, и чтобы группировать типы:

// 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>;
}

Пакеты типов используют их, чтобы открыть типы, которые можно расширять. @types/node объявляет namespace NodeJS, и чтобы дополнить его интерфейс ProcessEnv из любого модуля, нужен 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
        }
    }
}

Интерфейсы внутри слитых пространств имён тоже сливаются, и именно поэтому такое расширение работает.

Namespace и удаление типов

Node 24 запускает файлы .ts, удаляя синтаксис типов. Namespace со значениями удалить нельзя, его нужно скомпилировать в объект, показанный выше, поэтому node app.ts останавливается с ошибкой:

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

Два вида namespace работают без проблем, потому что исчезают полностью: declare namespace и namespace, все члены которого это типы или интерфейсы. Опция компилятора erasableSyntaxOnly: true сообщает об остальных при компиляции ошибкой TS1294, This syntax is not allowed when 'erasableSyntaxOnly' is enabled., и так проекты, работающие на удалении типов, не пускают их в код. node --experimental-transform-types компилирует namespace, но с предупреждением об экспериментальной функции.