Branded Types في TypeScript: الأنواع الاسمية بالأمثلة

تقارن TypeScript الأنواع حسب شكلها، لذا فإن اسمين بديلين لـ string قابلان للتبادل. يضيف النوع الموسوم وسمًا موجودًا في نظام الأنواع فقط، string & { readonly __brand: "UserId" }، فيصبح UserId غير متوافق مع النص العادي ومع كل وسم آخر:

type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

function loadUser(id: UserId) {
  console.log("loading user", id);
}

const userId = "u_42" as UserId;
const orderId = "ord_7" as OrderId;

loadUser(userId); // loading user u_42

// @ts-expect-error: an OrderId is not a UserId
loadUser(orderId); // loading user ord_7 (the error is suppressed, and types do not exist at runtime)

وقت التشغيل، userId هو النص "u_42" فقط. الوسم تسمية وقت الترجمة، ووظيفته الوحيدة منع الخلط بين المعرّفات والوحدات والنصوص التي جرى التحقق منها.

المشكلة: الأسماء البديلة مجرد أسماء

الـ type alias لا ينشئ نوعًا جديدًا. إنه يعطي نوعًا موجودًا اسمًا ثانيًا، ويعامل المترجم الاسمين كشيء واحد:

type UserId = string;
type OrderId = string;

function cancelOrder(id: OrderId) {
  console.log("cancelling", id);
}

const user: UserId = "u_42";
cancelOrder(user); // compiles: both are just string
// cancelling u_42  (the bug ships)

هذا هو التنميط البنيوي (structural typing): تتحقق TypeScript من أن الشكل مناسب، وstring يناسب string. في الكائنات تختلف الأشكال عادةً؛ أما في المعرّفات وعناوين البريد والعملات والوحدات فلا تختلف أبدًا. والوسوم تعالج هذه الحالة تحديدًا.

كيف يعمل الوسم

string & { readonly __brand: "UserId" } هو intersection: يجب أن تكون القيمة نصًا وأن تملك أيضًا خاصية __brand من النوع "UserId". لا يوجد نص حقيقي يملك هذه الخاصية، لذا لا يمكن إسناد أي نص عادي إليه:

// This does not compile: a plain string, and a different brand, are both rejected
type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

function loadUser(id: UserId) {
  console.log("loading user", id);
}

const orderId = "ord_7" as OrderId;
loadUser("u_42");
loadUser(orderId);

index.ts(10,10): error TS2345: Argument of type 'string' is not assignable to parameter of type 'UserId'.
  Type 'string' is not assignable to type '{ readonly __brand: "UserId"; }'.
index.ts(11,10): error TS2345: Argument of type 'OrderId' is not assignable to parameter of type 'UserId'.
  Type 'OrderId' is not assignable to type '{ readonly __brand: "UserId"; }'.
    Types of property '__brand' are incompatible.
      Type '"OrderId"' is not assignable to type '"UserId"'.

الاتجاه المهم ما زال يعمل: UserId نص، فيمكنك تمريره إلى أي شيء يأخذ نصًا، واستدعاء .startsWith() عليه، ووضعه داخل قالب نص. الوسم يمنع الدخول فقط.

دوال إنشاء تتحقق من المدخلات

تأكيد النوع as UserId هو الطريق الوحيد للدخول، وتأكيد النوع لا يفحص شيئًا. ضعه في دالة واحدة تتحقق من المُدخل، وعندها تعرف أن كل قيمة موسومة في البرنامج قد اجتازت هذا الفحص:

type Email = string & { readonly __brand: "Email" };

function toEmail(input: string): Email {
  const trimmed = input.trim().toLowerCase();
  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(trimmed)) {
    throw new Error(`not an email: ${input}`);
  }
  return trimmed as Email; // the only "as Email" in the codebase
}

function sendWelcome(to: Email) {
  console.log("sending to", to);
}

sendWelcome(toEmail("  Ada@Example.com ")); // sending to ada@example.com

try {
  sendWelcome(toEmail("ada at example"));
} catch (e) {
  console.log((e as Error).message); // not an email: ada at example
}

لا تفحص sendWelcome مدخلها مرة أخرى أبدًا، لأن نوع معاملها يقول إن الفحص قد جرى. هذه فكرة «حلّل ولا تكتفِ بالتحقق» (parse, don't validate): افحص عند الحدود، ثم احمل الإثبات في النوع. ويعمل حارس النوع كدالة إنشاء أيضًا إذا فضّلت قيمة منطقية على الاستثناء: function isEmail(s: string): s is Email.

مساعد Brand عام

كتابة الـ intersection يدويًا لكل نوع تصبح تكرارًا. نوع generic صغير يفعل ذلك مرة واحدة:

type Brand<T, Name extends string> = T & { readonly __brand: Name };

type ProductId = Brand<string, "ProductId">;
type Cents = Brand<number, "Cents">;

const cents = (n: number): Cents => {
  if (!Number.isInteger(n)) throw new Error("cents must be whole");
  return n as Cents;
};

function price(id: ProductId, amount: Cents): string {
  return `${id}: $${(amount / 100).toFixed(2)}`;
}

console.log(price("p_1" as ProductId, cents(1999))); // p_1: $19.99

وسم الرقم يعمل بالطريقة نفسها كوسم النص. لاحظ أن amount / 100 هو number عادي: العمليات الحسابية على رقم موسوم تعطي نتيجة غير موسومة، كما يأتي لاحقًا.

وسوم unique symbol

اسم خاصية نصي مثل __brand يبدو كخاصية حقيقية: userId.__brand يجتاز فحص الأنواع على أنه "UserId" لكنه undefined وقت التشغيل، وقد تختار مكتبتان الاسم نفسه. مفتاح من نوع unique symbol يتجنب المشكلتين:

declare const brand: unique symbol;

type Brand<T, Name extends string> = T & { readonly [brand]: Name };

type Meters = Brand<number, "Meters">;
type Feet = Brand<number, "Feet">;

function toMeters(feet: Feet): Meters {
  return (feet * 0.3048) as Meters;
}

const height = 10 as Feet;
const inMeters = toMeters(height);
console.log(inMeters.toFixed(3)); // 3.048

// @ts-expect-error: Meters is not Feet
toMeters(inMeters);

يعلن declare const brand: unique symbol رمزًا موجودًا لفاحص الأنواع فقط؛ والكلمة المفتاحية declare تعني أنه لا يُولَّد له أي JavaScript. ولأن الرمز غير مُصدَّر من وحدته، لا يستطيع الكود في الملفات الأخرى حتى أن يسمّي خاصية الوسم، فخارج تلك الوحدة لا سبيل للحصول على Meters إلا عبر الدوال التي تصدّرها أو تأكيد نوع as Meters.

الوسوم لا تكلف شيئًا وقت التشغيل

المخرجات المترجمة لا تحتوي على أي أثر للوسم. هذه هي الأسطر المولَّدة لمثال Meters، بعد ترويسة الوحدة التي يضيفها المترجم: اختفى declare والاسمان البديلان للنوعين وكل as، وما زال الاستدعاء المكتوم في السطر الأخير يعمل.

function toMeters(feet) {
    return (feet * 0.3048);
}
const height = 10;
const inMeters = toMeters(height);
console.log(inMeters.toFixed(3)); // 3.048
// @ts-expect-error: Meters is not Feet
toMeters(inMeters);

القيمة الموسومة هي القيمة البدائية العادية: يعطي typeof النتيجة "string" أو "number"، ويكتبها JSON.stringify كالمعتاد، والمقارنات تعمل كما كانت. والوجه الآخر أنه لا شيء يُفحص وقت التشغيل ما لم تفحصه دالة الإنشاء. البيانات المحلَّلة من JSON أو قاعدة بيانات أو URL تصل كـ string، ولا تصبح UserId إلا عندما تمررها عبر تلك الدالة.

العمليات الحسابية والدوال تُسقط الوسم

العمليات على قيمة موسومة تعيد النوع الأساسي، لأن الوسم ليس جزءًا مما ينتجه + أو .slice():

type Cents = number & { readonly __brand: "Cents" };

const a = 500 as Cents;
const b = 250 as Cents;

const sum = a + b;           // number, not Cents
const total: Cents = a + b;  // error TS2322: Type 'number' is not assignable to type 'Cents'
const fixed = (a + b) as Cents; // re-brand when the result is still valid

وهذا عادةً ما تريده: جمع مبلغين بالسنتات يعطي سنتات، لكن ضرب السنتات بالسنتات لا يعطي ذلك، وأنت وحدك تعرف أي العمليات تحافظ على المعنى. اكتب دوالًا مساعدة صغيرة مثل addCents(a: Cents, b: Cents): Cents للعمليات التي يحتاجها كودك.

متى تستخدم branded types

استخدم الوسوم حيث يكون الخلط بين قيمتين من النوع البدائي نفسه خطرًا حقيقيًا ولا يستطيع المترجم المساعدة بطريقة أخرى:

تجاوزها في القيم التي لا يُخلط بينها أبدًا، وفي أنواع الكائنات التي تختلف أشكالها أصلًا. تستطيع مكتبات التحقق إنتاج أنواع موسومة من مخطط: في Zod يعطي z.string().brand<"UserId">() مخططًا تعيد دالة parse فيه UserId موسومًا، وهذا يوفّر عليك كتابة دوال الإنشاء يدويًا.