TypeScript: пространства имён

Темный монитор с кодом TypeScript в редакторе VSCode.

Пространства имён (namespaces) в TypeScript группируют связанные переменные, функции и классы под общим идентификатором, снижая риск конфликтов имён. Для новых проектов обычно рекомендуют использовать ES-модули, но пространства имён всё ещё полезны для логической группировки кода в однозвучных сборках или при миграции старого кода.

Что такое коллизия имён и зачем нужны пространства имён

Коллизия имён возникает, когда два или более компонента кода используют одно и то же имя переменной, функции или класса. В больших проектах, где над кодовой базой работают многие разработчики, такие конфликты — частое явление. Они усложняют поиск источника ошибок и могут приводить к неожиданному поведению во время выполнения.

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

Создание пространства имён

В TypeScript пространство имён создаётся с помощью ключевого слова namespace, за которым следует идентификатор и блок в фигурных скобках. По синтаксису это похоже на создание класса.

Пример простого пространства имён:

namespace Example {
  // публичная функция
  export function Foo(): void {
    console.log("This is a function inside the Example namespace");
  }

  // публичный класс
  export class Bar {
    property: string;

    constructor(property: string) {
      this.property = property;
    }
  }

  // публичная константа
  export const baz = "This is a namespace variable";
}

В примере выше Foo, Bar и baz — члены пространства имён Example. По умолчанию члены пространства имён видны только внутри него; чтобы сделать их доступными снаружи, используйте ключевое слово export.

Доступ к публичным членам осуществляется через точечную нотацию:

Example.Foo(); // This is a function inside the Example namespace

const bar = new Example.Bar("string");
console.log(bar.property); // string

console.log(Example.baz); // This is a namespace variable

Вложенные пространства имён

TypeScript позволяет вкладывать пространства имён одно в другое, создавая иерархию. Это помогает ещё сильнее разграничить области имён, но чрезмерная вложенность может ухудшить читаемость.

Пример вложенной структуры:

namespace Example {
  export const property_1 = "Foo";

  export namespace Bar {
    export const printFoo = function () {
      console.log(property_1);
    };
  }

  export namespace Baz {
    export class Foo {
      property: string;

      constructor(property: string) {
        this.property = property;
      }
    }
  }
}

Доступ к вложенным элементам через точечную нотацию:

console.log(Example.property_1); // Foo
Example.Bar.printFoo(); // Foo
const foo = new Example.Baz.Foo("example");

Если попытаться обратиться к члену вложенного пространства имён напрямую через родителя, а не через полное имя, TypeScript выдаст ошибку:

Example.printFoo();
// error TS2339: Property 'printFoo' does not exist on type 'typeof Example'

Важно: не создавайте слишком глубокие иерархии. Длинные цепочки Example.A.B.C.D усложняют навигацию и рефакторинг.

Алиасы пространств имён

Алиас — это сокращённое имя пространства имён, которое упрощает обращение к его членам.

Создать алиас можно с помощью ключевого слова import в стиле TypeScript для внутренних ссылок на пространство имён:

namespace Car {
  export namespace Tesla {
    export class ModelX {
      create(): string {
        return `Model X Created`;
      }
    }
  }

  export namespace Toyota {
    export class Camry {}
  }

  export namespace Ford {
    export class Mustang {}
  }
}

// Создание алиаса
import tesla = Car.Tesla;

const modelX = new tesla.ModelX();
modelX.create(); // Model X Created

Алиасы полезны, когда имена пространств имён длинные или часто используются.

Использование пространств имён в нескольких файлах

Чтобы использовать пространство имён, объявленное в другом файле, его нужно корректно подключить. Для устаревших подходов и проектов без модульной системы TypeScript предоставляет трёхслешевую директиву — одиночную строковую XML-подобную аннотацию, которая сообщает компилятору о зависимостях.

Пример использования трёхслешевой директивы в main.ts:

// main.ts

/// 
Example.Foo();

Директива должна стоять в начале файла. Она указывает на файл index.ts, где определено пространство имён Example. Чтобы собрать несколько файлов в один итоговый JavaScript, можно использовать опцию компилятора outFile:

tsc --outFile index.js main.ts

Эта команда соберёт main.ts и все файлы, на которые указывают трёхслешевые директивы, в единый index.js.

Альтернативно, можно перечислить все входные файлы явно:

tsc --outFile index.js main.ts index.ts utils.ts

Примечание: трёхслешевые директивы работают только в файлах TypeScript и действуют только при объявлении в самом начале файла. Если директива указана не вверху, компилятор проигнорирует её как обычный комментарий.

Когда пространства имён удобны, а когда нет

Когда подходят пространства имён:

Внутренние библиотеки или утилиты, которые собираются в один файл (bundle) и не используют систему модулей.
При постепенной миграции старого кода на TypeScript, когда модули ещё не применены везде.
Когда требуется простая логическая группировка, но не нужна модель зависимостей на уровне файлов.

Когда лучше использовать модули:

Для новых проектов предпочтительнее ES-модули (import/export). Они обеспечивают явные зависимости и лучшую поддержку сборщиков и современных инструментов.
В проектах с системой пакетов (npm, yarn) и модульной загрузкой (ESM, CommonJS).

Быстрый чеклист для разработчика

Решите, нужна ли модульная система проекта (ESM/CJS) или код будет собираться в один файл.
Если используете пространства имён — публикуйте только нужные члены через export.
Избегайте глубоко вложенных пространств имён (не более 2–3 уровней).
Для доступа к пространствам имён в нескольких файлах используйте трёхслешевые директивы и опцию outFile при необходимости.
Рассмотрите перевод логики в ES-модули при рефакторинге.

Справочная шпаргалка (cheat sheet)

// объявление
namespace MyLib {
  export function fn() {}
  export class C {}
}

// доступ
MyLib.fn();
const c = new MyLib.C();

// алиас
import ML = MyLib;
ML.fn();

// вложение
namespace MyLib.Utils {
  export function helper() {}
}
MyLib.Utils.helper();

Сравнение: пространства имён vs модули

Критерий	Пространства имён	ES-модули
Уровень организации	Логическая группировка в коде	Файловая система + явные зависимости
Использование в сборке	Часто собираются в один файл	Поддерживаются сборщиками, tree-shaking
Явные зависимости	Нет	Да (import/export)
Совместимость с пакетами	Ограниченная	Широкая
Рекомендация для новых проектов	Только в особых случаях	Предпочтительнее

Ментальные модели и эвристики

Представляйте пространство имён как контейнер для связанной функциональности, подобно пакету в других языках.
Если вам нужно выразить зависимость между частями кода — используйте модули. Если требуется просто сгруппировать, подойдёт пространство имён.
Переходите на модули при росте проекта и при интеграции с экосистемой npm.

Когда пространства имён дают сбой (контрпримеры)

Проект использует динамическую подгрузку модулей (lazy loading) — пространства имён не выражают зависимости и плохо подходят.
Сложный граф зависимостей между файлами — отложите использование пространств имён, лучше перейти на модули.
Большая команда и модульные релизы — модули обеспечивают более предсказуемые границы и управления версиями.

Краткий словарь (1 строка)

Пространство имён: логический контейнер именованных сущностей в TypeScript.
Алиас: сокращённое имя для пространства имён (import =).
Трёхслешевые директивы: однострочные ссылки /// для указания зависимостей в TS-файлах.
outFile: опция tsc для объединения нескольких входных файлов в один выходной JS.

Критерии приёмки

Код не использует глобальных имен без экспорта в пространстве имён.
Публичные члены помечены export, приватные — опущены.
Трёхслешевые директивы находятся в начале файлов и корректно указывают на зависимости.
При сборке с outFile итоговый JS содержит все объявленные файлы и порядок их подключения корректный.

Безопасность и приватность

Пространства имён сами по себе не предоставляют механизмы контроля доступа на уровне рантайма — это только конструкция типов/структуры кода. Чувствительные данные следует держать вне глобальных пространств имён и использовать модули или замыкания для ограничения видимости.

Короткое объявление для команды (100–200 слов)

Мы стандартизировали применение пространств имён в устаревших частях проекта: пространства имён можно использовать для локальной группировки вспомогательных функций и классов, которые собираются в единый бандл с помощью tsc –outFile. Для новых модулей и библиотек переходите на ES-модули (import/export) — они дают явные зависимости, лучше интегрируются с системой сборки и поддерживают tree-shaking. При использовании пространств имён помните про экспорт только публичных членов, избегайте глубокой вложенности и размещайте трёхслешевые директивы в начале файлов.

Итоговый вывод

Пространства имён в TypeScript — это удобный инструмент для группировки и предотвращения конфликтов имён в некоторых сценариях, особенно при сборке в один файл или при поэтапной миграции старого кода. Однако для современных приложений и при необходимости явных зависимостей предпочтительнее использовать ES-модули.

Если нужно, могу подготовить руководство по миграции с пространств имён на ES-модули с реальными примерами вашего кода и планом работ.