TypeScript Namespace Nedir, Ne Zaman Kullanılır

Namespace, fonksiyonları, sabitleri ve tipleri tek bir ad altında toplayan adlandırılmış bir bloktur. export ile işaretlenen üyelere Name.member biçiminde erişilir; geri kalanı bloğa özel kalır. Çalışma zamanında bir namespace düz bir nesnedir.

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

Bir Namespace Neye Derlenir

Namespace'ler, kod üreten az sayıdaki TypeScript özelliğinden biridir. Yukarıdaki blok, bir nesneyi dolduran bir fonksiyona dönüşür:

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

Bu, modüller var olmadan önce JavaScript kodunun her adı global kapsama koymamak için kullandığı kalıptır. TAU fonksiyonun yerel bir değişkenidir, diğer kodun onu görememesinin nedeni budur. Onu okumaya çalışmak bir derleme zamanı hatasıdır:

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

Derleyici şunu bildirir: index.ts(10,17): error TS2339: Property 'rate' does not exist on type 'typeof Tax'. const rate önüne export ekleyin, iki satır da çalışır.

İç İçe Yapı, Birleşme ve Takma Adlar

Namespace'ler iç içe olabilir ve aynı adlı iki blok tek bir blokta birleşir. Çıktıdaki Geometry || (Geometry = {}) bunu mümkün kılar: ikinci blok var olan nesneye ekleme yapar. import X = A.B kısa bir takma ad oluşturur.

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 { }, iç içe üç blok için bir kısaltmadır. Eski module Shop { } yazımı aynı anlama gelir ama artık TS1540 hatasıyla reddedilir: A 'namespace' declaration should not be declared using the 'module' keyword. Please use the 'namespace' keyword instead.

Fonksiyon ve Class'larla Birleşme

Bir namespace adını bir fonksiyon, class ya da enum ile paylaşabilir ve ona üye ekleyebilir. Bu, aynı zamanda özellik taşıyan bir fonksiyonu ya da yardımcıları eklenmiş bir class'ı tanımlamanın hâlâ en temiz yoludur.

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 }

Bir class için static bir metot aynı işi görür ve düz JavaScript'tir. Bir fonksiyon için namespace'i atlayıp tanımın hemen ardından format.prefix = "$" ataması da yapabilirsiniz; TypeScript bu şekilde atanan özellikleri izler.

Namespace ve Modül

ES modüllerinden önce büyük bir TypeScript programı, global namespace'leri paylaşan, /// <reference path="..." /> ile birbirine bağlanan ve outFile ile tek bir dosyaya derlenen birçok script dosyasından oluşurdu. Modüller bunun yerini aldı: her dosya kendi kapsamıdır, bağımlılıklar açık import'lardır ve bundler'lar kullanılmayan export'ları atabilir. TypeScript 7 outFile seçeneğini kaldırdı (TS5102 hatası), bu yüzden çok dosyalı namespace kurulumu artık bir build seçeneği değil.

Bir modülün içinde her şeyi bir namespace'e sarmak hiçbir kazanç olmadan ikinci bir adlandırma seviyesi ekler: import edenler Utils.Utils.format yazmak zorunda kalır. Fonksiyonları doğrudan export edin ve bir önek isteyen import eden import * as Utils from "./utils.js" seçsin.

Namespace'lerle Hâlâ Nerede Karşılaşırsınız

Declaration dosyaları, tek bir global nesne sunan kütüphaneleri tanımlamak ve tipleri gruplamak için onları kullanır:

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

Tip paketleri, genişletebileceğiniz tipleri sunmak için onları kullanır. @types/node, namespace NodeJS tanımlar ve herhangi bir modülden onun ProcessEnv interface'ine ekleme yapmak declare global gerektirir:

// env.d.ts
export {};

declare global {
    namespace NodeJS {
        interface ProcessEnv {
            API_URL: string; // process.env.API_URL is now string, not string | undefined
        }
    }
}

Birleşen namespace'lerin içindeki interface'ler de birleşir; bu augmentation'ı çalıştıran şey budur.

Namespace'ler ve Type Stripping

Node 24, .ts dosyalarını tip söz dizimini silerek çalıştırır. Değer içeren bir namespace silinemez, yukarıda gösterilen nesneye derlenmesi gerekir; bu yüzden node app.ts şu hatayla durur:

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

İki tür namespace sorun çıkarmaz, çünkü tamamen kaybolurlar: bir declare namespace ve bütün üyeleri tip ya da interface olan bir namespace. erasableSyntaxOnly: true derleyici seçeneği diğerlerini derleme zamanında TS1294 hatası olarak bildirir (This syntax is not allowed when 'erasableSyntaxOnly' is enabled.); type stripping ile çalışan projeler onları böyle dışarıda tutar. node --experimental-transform-types ise namespace'leri deneysel bir uyarıyla derler.