حدود الوحدات

Module Boundaries

مفهوم ~20 دقيقة

حدود الوحدات — Module Boundaries

في production، TypeScript ليست فقط types. هي وسيلة لرسم حدود. module جيد يصدّر types ودوالاً قليلة وواضحة، ويخفي التفاصيل. إذا صدّرت كل شيء، فلن يبقى لديك حد معماري؛ سيعتمد كل ملف على تفاصيل داخلية.

ابدأ بتحديد public API لكل module. ما الذي يحتاجه الخارج؟ وما الذي يجب أن يبقى داخلياً؟ الأنواع العامة يجب أن تكون مستقرة قدر الإمكان، لأن تغييرها يكسر المستهلكين.

مثال حد صغير

index.ts

export type Money = {
  halalas: number;
};

export function formatMoney(money: Money): string {
  return `${(money.halalas / 100).toFixed(2)} SAR`;
}

const HALALAS_PER_RIYAL = 100; // ثابت داخلي — لا يُصدَّر
console.log(formatMoney({ halalas: HALALAS_PER_RIYAL * 25 }));

Output:

في ملف حقيقي، internalRate لا يصدّر لأنه تفصيل داخلي.

الأنواع الاسمية — Branded Types

export type Money = { halalas: number } يمنع بعض الأخطاء لكن يسمح بتمرير رقم رياليات كـ هللات لأن TypeScript يعمل بالتوافق الهيكلي. الحل هو branded types:

index.ts

type Halalas = number & { readonly __brand: unique symbol };
type Riyals = number & { readonly __brand: unique symbol };

function toHalalas(n: number): Halalas {
  return n as Halalas;
}

function spend(amount: Halalas): void {
  console.log(`إنفاق ${amount} هللة`);
}

const price = toHalalas(2500);
spend(price); // صواب

// const r: Riyals = 50 as Riyals;
// spend(r); // خطأ في النوع — Type error

Output:

unique symbol يضمن أن Halalas وRiyals لا يتبادلان حتى لو كلاهما number. المشروع الإنتاجي يصنع دالة بناء واحدة (toHalalas) ولا يُصدر as Halalas مباشرة من خارج الحد.

لا تصدّر types مؤقتة

إذا كان النوع يخدم تنفيذ دالة واحدة، اتركه داخلياً. public types هي عقود.

تحدي — Challenge

type Money = { halalas: number };

function formatMoney(money: Money): string {
  return `${(money.halalas / 100).toFixed(2)} SAR`;
}

// اطبع تنسيق 2500 هللة — Print 2500 halalas formatted