Branded Types ב-TypeScript: טיפוסים נומינליים עם דוגמאות

TypeScript משווה טיפוסים לפי מבנה, ולכן שני aliases של string ניתנים להחלפה. branded type מוסיף תגית שקיימת רק במערכת הטיפוסים, string & { readonly __brand: "UserId" }, וזה הופך UserId ללא תואם למחרוזת רגילה ולכל brand אחר:

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". ה-brand הוא תווית של זמן קומפילציה, והתפקיד היחיד שלו הוא למנוע ערבוב של מזהים, יחידות מידה ומחרוזות שעברו ולידציה.

הבעיה: aliases הם רק שמות

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. באובייקטים המבנים בדרך כלל שונים; במזהים, כתובות אימייל, מטבעות ויחידות מידה, הם אף פעם לא שונים. brands מתקנים את המקרה הזה.

איך ה-brand עובד

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() או לשים אותו ב-template. ה-brand חוסם רק את הדרך פנימה.

פונקציות בנייה שמבצעות ולידציה

ה-assertion as UserId הוא הדרך היחידה פנימה, ו-assertion לא בודק כלום. שימו אותו בפונקציה אחת שמבצעת ולידציה לקלט, ואז ידוע שכל ערך עם brand בתוכנית עבר את הבדיקה הזו:

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": בודקים בגבול, ואז נושאים את ההוכחה בטיפוס. גם type guard עובד כפונקציית בנייה כשמעדיפים ערך בוליאני על פני חריגה: function isEmail(s: string): s is Email.

עוזר Brand גנרי

כתיבת ה-intersection ביד לכל טיפוס נהיית חזרתית. גנרי קטן עושה את זה פעם אחת:

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

הוספת brand למספר עובדת בדיוק כמו למחרוזת. שימו לב ש-amount / 100 הוא number רגיל: פעולות חשבון על מספר עם brand נותנות תוצאה בלי brand, כפי שמוסבר בהמשך.

brands עם 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 מצהיר על symbol שקיים רק בשביל בודק הטיפוסים; מילת המפתח declare אומרת שלא נוצר עבורו JavaScript. מכיוון שה-symbol לא מיוצא מהמודול שלו, קוד בקבצים אחרים לא יכול אפילו לציין את מאפיין ה-brand, ולכן מחוץ למודול הזה הדרכים היחידות לקבל Meters הן הפונקציות שאתם מייצאים או assertion של as Meters.

ל-brands אין עלות בזמן ריצה

בפלט המקומפל אין שום זכר ל-brand. אלה השורות שנוצרות עבור הדוגמה של Meters, מתחת לכותרת המודול שהקומפיילר מוסיף: ה-declare, שני ה-type aliases וכל ה-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);

ערך עם brand הוא הפרימיטיבי הרגיל: typeof נותן "string" או "number", JSON.stringify כותב אותו כרגיל, והשוואות עובדות כמו קודם. הצד השני הוא ששום דבר לא נבדק בזמן ריצה, אלא אם פונקציית הבנייה שלכם בודקת. מידע שפוענח מ-JSON, ממסד נתונים או מ-URL מגיע כ-string, והוא הופך ל-UserId רק כשמעבירים אותו דרך הפונקציה הזו.

פעולות חשבון ומתודות מאבדות את ה-brand

פעולות על ערך עם brand מחזירות את טיפוס הבסיס, כי ה-brand לא חלק ממה ש-+ או .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

השתמשו ב-brands במקומות שבהם ערבוב של שני ערכים מאותו טיפוס פרימיטיבי הוא סיכון אמיתי והקומפיילר לא יכול לעזור בדרך אחרת:

ותרו עליהם לערכים שאף פעם לא מתבלבלים ביניהם, ולטיפוסי אובייקט שכבר שונים במבנה. ספריות ולידציה יכולות לייצר branded types מסכמה: ב-Zod, z.string().brand<"UserId">() נותן סכמה שה-parse שלה מחזיר UserId עם brand, וזה חוסך את הכתיבה הידנית של פונקציות הבנייה.