Namespace w TypeScript: czym jest i kiedy go używać

Namespace to nazwany blok, który grupuje funkcje, stałe i typy pod jedną nazwą. Elementy oznaczone export są dostępne jako Name.member; reszta pozostaje prywatna w bloku. W czasie działania namespace jest zwykłym obiektem.

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

Do czego kompiluje się namespace

Namespace'y to jedna z niewielu funkcji TypeScript, które generują kod. Powyższy blok staje się funkcją, która wypełnia obiekt:

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

To wzorzec, którego kod JavaScript używał, zanim pojawiły się moduły, żeby nie umieszczać każdej nazwy w zakresie globalnym. TAU jest zmienną lokalną funkcji, dlatego inny kod jej nie widzi. Próba odczytania jej to błąd kompilacji:

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

Kompilator zgłasza index.ts(10,17): error TS2339: Property 'rate' does not exist on type 'typeof Tax'. Dodaj export przed const rate, a obie linie się wykonają.

Zagnieżdżanie, łączenie i aliasy

Namespace'y można zagnieżdżać, a dwa bloki o tej samej nazwie łączą się w jeden. Umożliwia to Geometry || (Geometry = {}) w wyjściu: drugi blok dopisuje do istniejącego obiektu. import X = A.B tworzy krótki alias.

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 { } to skrót od trzech zagnieżdżonych bloków. Dawny zapis module Shop { } znaczy to samo, ale jest teraz odrzucany z błędem TS1540, A 'namespace' declaration should not be declared using the 'module' keyword. Please use the 'namespace' keyword instead.

Łączenie z funkcjami i klasami

Namespace może mieć tę samą nazwę co funkcja, klasa lub enum i dodawać do nich elementy. To wciąż najczystszy sposób na opisanie funkcji, która ma też właściwości, albo klasy z dołączonymi funkcjami pomocniczymi.

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 }

W przypadku klasy to samo zadanie spełnia metoda static, która jest zwykłym JavaScriptem. W przypadku funkcji możesz też pominąć namespace i przypisać format.prefix = "$" zaraz po deklaracji; TypeScript śledzi właściwości przypisane w ten sposób.

Namespace'y a moduły

Przed ES modules duży program w TypeScript składał się z wielu plików skryptów dzielących globalne namespace'y, połączonych przez /// <reference path="..." /> i kompilowanych do jednego pliku przez outFile. Zastąpiły to moduły: każdy plik ma własny zakres, zależności to jawne importy, a bundlery mogą usuwać nieużywane eksporty. TypeScript 7 usunął outFile (błąd TS5102), więc konfiguracja z namespace'ami w wielu plikach nie jest już opcją budowania.

Wewnątrz modułu opakowanie wszystkiego w namespace dodaje drugi poziom nazw bez żadnego zysku: importujący pisałby Utils.Utils.format. Eksportuj funkcje bezpośrednio i pozwól importującemu wybrać import * as Utils from "./utils.js", jeśli chce przedrostka.

Gdzie wciąż spotkasz namespace'y

Pliki deklaracji używają ich do opisu bibliotek, które udostępniają jeden globalny obiekt, i do grupowania typów:

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

Pakiety typów używają ich do udostępniania typów, które można rozszerzać. @types/node deklaruje namespace NodeJS, a dopisanie czegoś do jego interfejsu ProcessEnv z dowolnego modułu wymaga 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
        }
    }
}

Interfejsy wewnątrz połączonych namespace'ów też się łączą i dzięki temu to rozszerzenie działa.

Namespace'y a type stripping

Node 24 uruchamia pliki .ts, usuwając składnię typów. Namespace z wartościami nie może zostać po prostu usunięty, musi zostać skompilowany do obiektu pokazanego wyżej, więc node app.ts kończy się komunikatem:

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

Dwa rodzaje namespace'ów działają, bo znikają całkowicie: declare namespace oraz namespace, którego wszystkie elementy to typy lub interfejsy. Opcja kompilatora erasableSyntaxOnly: true zgłasza pozostałe już podczas kompilacji jako błąd TS1294, This syntax is not allowed when 'erasableSyntaxOnly' is enabled., i tak projekty działające na type stripping trzymają je z daleka. node --experimental-transform-types kompiluje namespace'y, z ostrzeżeniem o funkcji eksperymentalnej.