Namespace في TypeScript: ما هو ومتى تستخدمه

الـ 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 قبل وجود الوحدات لتجنب وضع كل اسم في النطاق العام. 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 كان برنامج TypeScript الكبير عبارة عن ملفات script كثيرة تتشارك namespaces عامة، تُربط معًا بـ /// <reference path="..." /> وتُترجم إلى ملف واحد بـ outFile. حلّت الوحدات محل ذلك: كل ملف له نطاقه الخاص، والتبعيات استيرادات صريحة، وأدوات التجميع تستطيع حذف التصديرات غير المستخدمة. أزال TypeScript 7 الخيار outFile (الخطأ TS5102)، فلم يعد إعداد الـ namespaces متعددة الملفات خيارًا للبناء.

داخل وحدة، تغليف كل شيء في 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، والإضافة إلى الواجهة 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
        }
    }
}

الواجهات داخل الـ namespaces المندمجة تندمج أيضًا، وهذا ما يجعل هذا التوسيع يعمل.

الـ Namespaces وحذف الأنواع

تشغّل Node 24 ملفات .ts بحذف صياغة الأنواع. الـ namespace الذي فيه قيم لا يمكن حذفه، بل يجب ترجمته إلى الكائن الموضح سابقًا، لذلك يتوقف node app.ts مع:

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

نوعان من الـ namespaces لا مشكلة فيهما لأنهما يختفيان تمامًا: declare namespace، والـ namespace الذي كل أعضائه أنواع أو واجهات. يبلّغ خيار المترجم erasableSyntaxOnly: true عن الأنواع الأخرى وقت الترجمة بالخطأ TS1294، This syntax is not allowed when 'erasableSyntaxOnly' is enabled.، وهكذا تُبعدها المشاريع التي تعمل بحذف الأنواع. أما node --experimental-transform-types فيترجم الـ namespaces، مع تحذير بأن الميزة تجريبية.