TypeScript Namespace: was er ist und wann man ihn nutzt

Ein Namespace ist ein benannter Block, der Funktionen, Konstanten und Typen unter einem Namen zusammenfasst. Mit export markierte Member sind als Name.member erreichbar; der Rest bleibt privat im Block. Zur Laufzeit ist ein Namespace ein einfaches Objekt.

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

Wozu ein Namespace kompiliert wird

Namespaces gehören zu den wenigen TypeScript-Features, die Code erzeugen. Der Block oben wird zu einer Funktion, die ein Objekt befüllt:

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

Mit diesem Muster hat JavaScript-Code, bevor es Module gab, vermieden, jeden Namen in den globalen Scope zu legen. TAU ist eine lokale Variable der Funktion, deshalb kann anderer Code sie nicht sehen. Der Versuch, sie zu lesen, ist ein Fehler beim Kompilieren:

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

Der Compiler meldet index.ts(10,17): error TS2339: Property 'rate' does not exist on type 'typeof Tax'. Setze export vor const rate, und beide Zeilen laufen.

Verschachtelung, Merging und Aliasse

Namespaces lassen sich verschachteln, und zwei Blöcke mit demselben Namen verschmelzen zu einem. Das Geometry || (Geometry = {}) in der Ausgabe macht das möglich: Der zweite Block ergänzt das vorhandene Objekt. import X = A.B erzeugt einen kurzen 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 { } ist die Kurzform für drei verschachtelte Blöcke. Die alte Schreibweise module Shop { } bedeutet dasselbe, wird heute aber mit dem Fehler TS1540 abgelehnt, A 'namespace' declaration should not be declared using the 'module' keyword. Please use the 'namespace' keyword instead.

Merging mit Funktionen und Klassen

Ein Namespace kann seinen Namen mit einer Funktion, Klasse oder einem Enum teilen und ihm Member hinzufügen. Das ist immer noch der sauberste Weg, eine Funktion zu beschreiben, die auch Eigenschaften trägt, oder eine Klasse mit angehängten Hilfsfunktionen.

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 }

Bei einer Klasse erledigt eine static-Methode dieselbe Aufgabe und ist reines JavaScript. Bei einer Funktion kannst du den Namespace auch weglassen und direkt nach der Deklaration format.prefix = "$" zuweisen; TypeScript erfasst Eigenschaften, die so zugewiesen werden.

Namespaces vs Module

Vor den ES-Modulen bestand ein großes TypeScript-Programm aus vielen Skriptdateien mit gemeinsamen globalen Namespaces, die mit /// <reference path="..." /> verbunden und mit outFile zu einer Datei kompiliert wurden. Module haben das abgelöst: Jede Datei ist ein eigener Scope, Abhängigkeiten sind explizite Imports, und Bundler können ungenutzte Exports entfernen. TypeScript 7 hat outFile entfernt (Fehler TS5102), das Setup mit Namespaces über mehrere Dateien ist also keine Build-Option mehr.

Innerhalb eines Moduls fügt es ohne Nutzen eine zweite Namensebene hinzu, alles in einen Namespace zu packen: Importierende müssten Utils.Utils.format schreiben. Exportiere die Funktionen direkt und lass den Importierenden import * as Utils from "./utils.js" wählen, wenn er ein Präfix möchte.

Wo dir Namespaces noch begegnen

Deklarationsdateien nutzen sie, um Bibliotheken zu beschreiben, die ein einziges globales Objekt bereitstellen, und um Typen zu gruppieren:

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

Typpakete nutzen sie, um Typen bereitzustellen, die du erweitern kannst. @types/node deklariert namespace NodeJS, und um sein Interface ProcessEnv aus einem beliebigen Modul heraus zu ergänzen, brauchst du 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
        }
    }
}

Auch Interfaces in verschmolzenen Namespaces verschmelzen, und genau das lässt diese Augmentation funktionieren.

Namespaces und Type Stripping

Node 24 führt .ts-Dateien aus, indem es die Typsyntax löscht. Ein Namespace mit Werten lässt sich nicht löschen, er muss zu dem oben gezeigten Objekt kompiliert werden, also bricht node app.ts ab mit:

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

Zwei Arten von Namespaces sind unproblematisch, weil sie vollständig verschwinden: ein declare namespace und ein Namespace, dessen Member alle Typen oder Interfaces sind. Die Compileroption erasableSyntaxOnly: true meldet die übrigen beim Kompilieren als Fehler TS1294, This syntax is not allowed when 'erasableSyntaxOnly' is enabled., und so halten Projekte, die auf Type Stripping laufen, sie fern. node --experimental-transform-types kompiliert Namespaces, mit einer Warnung, dass das Feature experimentell ist.