Что такое namespace в TypeScript и когда его использовать?

Namespace в TypeScript

Namespace (пространство имён) — механизм TypeScript для логической группировки кода: интерфейсов, классов, функций и переменных. Все члены namespace живут внутри одного именованного объекта, что исключает конфликты имён в глобальной области.

До появления ES-модулей namespace был основным способом структурировать большие TypeScript-проекты. Сейчас его роль значительно сузилась.

Базовый синтаксис

namespace Validation {
  // Экспортируем только то, что нужно снаружи
  export interface StringValidator {
    isAcceptable(s: string): boolean;
  }

  // Вспомогательное регулярное выражение — скрыто внутри namespace
  const lettersRegexp = /^[A-Za-z]+$/;

  export class LettersOnlyValidator implements StringValidator {
    isAcceptable(s: string): boolean {
      return lettersRegexp.test(s);
    }
  }
}

const validator = new Validation.LettersOnlyValidator();
console.log(validator.isAcceptable('Hello')); // true

Вложенные namespace

namespace App {
  export namespace Models {
    export interface User {
      id: number;
      name: string;
    }
  }

  export namespace Services {
    export function getUser(id: number): Models.User {
      return { id, name: 'Test' };
    }
  }
}

const user: App.Models.User = App.Services.getUser(1);

Разделение по файлам

Namespace можно распределить по нескольким файлам с директивой /// <reference path="..." />:

// validators/letters.ts
/// <reference path="validators.ts" />
namespace Validation {
  export class LettersValidator implements StringValidator {
    isAcceptable(s: string) {
      return /^[A-Za-z]+$/.test(s);
    }
  }
}

Алиасы для длинных путей

import StringValidator = Validation.StringValidator;
// Теперь можно писать StringValidator вместо Validation.StringValidator

Когда использовать namespace

Используйте namespace:

• В файлах деклараций .d.ts для описания типов глобальных библиотек (jQuery, Google Maps)
• В скриптах без модульной системы (браузерные <script>-теги, outFile-компиляция)
• В legacy-проектах, где переход на ES-модули нецелесообразен
• Для аугментации глобальных типов (declare namespace NodeJS { interface ProcessEnv { ... } })

Не используйте namespace:

• Когда проект уже использует ES-модули (import/export) — они несовместимы с namespace-подходом
• В любом современном Node.js, React или Vue проекте
• Как замену папок и файлов — файловая структура ES-модулей справляется лучше

Namespace vs ES-модули

Итог

Namespace — исторический инструмент TypeScript. В современном коде их почти всегда заменяют ES-модули. Ключевое исключение — типизация глобальных библиотек и .d.ts-файлы, где namespace остаётся стандартной практикой.