TypeScriptのnamespace（名前空間）とは？使いどころを解説

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'. と報告します。const rate の前に export を付ければ、両方の行が実行できます。

入れ子、マージ、エイリアス

namespace は入れ子にでき、同じ名前の2つのブロックはひとつにマージされます。出力の Geometry || (Geometry = {}) がそれを可能にしています。2つ目のブロックは既存のオブジェクトにメンバーを追加するのです。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 { } は、3つの入れ子のブロックの省略形です。古い書き方の 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のプログラムはグローバルな namespace を共有する多数のスクリプトファイルで、/// <reference path="..." /> でつなぎ合わせ、outFile でひとつのファイルにコンパイルしていました。モジュールがそれを置き換えました。各ファイルが独自のスコープを持ち、依存関係は明示的な import になり、バンドラーは使われていないエクスポートを取り除けます。TypeScript 7 では outFile が削除された（エラー TS5102）ので、複数ファイルにまたがる namespace の構成はもうビルドの選択肢にありません。

モジュールの中ですべてを namespace で包むと、何の利点もなく名前の階層がもう一段増えます。import する側は Utils.Utils.format と書くことになります。関数を直接エクスポートし、接頭辞がほしければ import する側が 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 の中のインターフェースもマージされます。この拡張が働くのはそのためです。

namespace と型除去

Node 24 は型の構文を削除することで .ts ファイルを実行します。値を持つ namespace は削除できず、上で見たオブジェクトにコンパイルする必要があるので、node app.ts は次のエラーで止まります:

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

完全に消えるので問題ない namespace が2種類あります。declare namespace と、メンバーがすべて型かインターフェースの namespace です。コンパイラーオプション erasableSyntaxOnly: true はそれ以外をコンパイル時にエラー TS1294 This syntax is not allowed when 'erasableSyntaxOnly' is enabled. として報告します。型除去で動かすプロジェクトはこれで namespace を締め出しています。node --experimental-transform-types は、実験的機能の警告付きで namespace をコンパイルします。