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

namespaces הם אחת מהתכונות הבודדות של 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 השתמש בו לפני שהיו מודולים, כדי לא לשים כל שם ב-scope הגלובלי. 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'. הוסיפו export לפני const rate ושתי השורות ירוצו.

קינון, מיזוג וכינויים

אפשר לקנן namespaces, ושני בלוקים עם אותו שם מתמזגים לאחד. ה-Geometry || (Geometry = {}) בפלט הוא מה שגורם לזה לעבוד: הבלוק השני מוסיף לאובייקט הקיים. 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 { } הוא קיצור לשלושה בלוקים מקוננים. הכתיב הישן 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 עוקב אחרי מאפיינים שמושמים כך.

Namespaces מול מודולים

לפני ES modules, תוכנית TypeScript גדולה הייתה הרבה קבצי סקריפט שחולקים namespaces גלובליים, מחוברים יחד עם /// <reference path="..." /> ומקומפלים לקובץ אחד עם outFile. מודולים החליפו את זה: כל קובץ הוא scope משלו, תלויות הן imports מפורשים, ו-bundlers יכולים להשמיט exports שלא בשימוש. TypeScript 7 הסיר את outFile (שגיאה TS5102), כך שתצורת namespaces מרובת קבצים כבר אינה אפשרות build.

בתוך מודול, עטיפת הכול ב-namespace מוסיפה רמת שמות שנייה בלי שום תועלת: המייבאים יכתבו Utils.Utils.format. ייצאו את הפונקציות ישירות ותנו למייבא לבחור import * as Utils from "./utils.js" אם הוא רוצה קידומת.

איפה עדיין פוגשים namespaces

קבצי הצהרות משתמשים בהם כדי לתאר ספריות שחושפות אובייקט גלובלי אחד, וכדי לקבץ טיפוסים:

// 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, והוספה ל-interface בשם 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
        }
    }
}

גם interfaces בתוך namespaces שמתמזגים מתמזגים, וזה מה שגורם להרחבה הזו לעבוד.

Namespaces ו-type stripping

Node 24 מריץ קבצי .ts על ידי מחיקת תחביר הטיפוסים. namespace עם ערכים אי אפשר למחוק, צריך לקמפל אותו לאובייקט שמוצג למעלה, ולכן node app.ts נעצר עם:

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

שני סוגים של namespace תקינים כי הם נעלמים לגמרי: declare namespace, ו-namespace שכל האיברים שלו הם טיפוסים או interfaces. אפשרות הקומפיילר erasableSyntaxOnly: true מדווחת על האחרים בזמן קומפילציה כשגיאה TS1294, This syntax is not allowed when 'erasableSyntaxOnly' is enabled., וכך פרויקטים שרצים עם type stripping מרחיקים אותם. node --experimental-transform-types כן מקמפל namespaces, עם אזהרה על תכונה ניסיונית.