TypeScript Intersection Types: שילוב טיפוסים עם &

טיפוס intersection, שנכתב A & B, מתאר ערך שהוא A וגם B באותו זמן. בטיפוסי אובייקט זה אומר שלערך יש כל מאפיין של שניהם. כך משלבים טיפוסים קיימים בלי לכתוב שוב את המאפיינים.

type Person = { name: string; email: string };
type Employee = { employeeId: number; team: string };

type Staff = Person & Employee; // has all four properties

const ada: Staff = { name: "Ada", email: "ada@example.com", employeeId: 7, team: "compilers" };

function badge(s: Staff): string {
  return `${s.name} (#${s.employeeId}, ${s.team})`;
}

console.log(badge(ada)); // Ada (#7, compilers)

// @ts-expect-error: Type '{ name: string; email: string; employeeId: number; }' is not assignable to type 'Staff'.
const partial: Staff = { name: "Alan", email: "alan@example.com", employeeId: 8 };

באובייקט השני חסר team, ולכן הוא שגיאת הקומפילציה TS2322, והשורה הבאה בהודעה אומרת Property 'team' is missing ... but required in type 'Employee'. אפשר להעביר ערך Staff בכל מקום שבו מצופה Person או Employee.

שילוב טיפוסי אובייקט

& עובד עם כל שילוב של type aliases, interfaces וטיפוסי אובייקט שנכתבו במקום, וגם עם פרמטרי טיפוס גנריים. במקרה האחרון קשה להחליף אותו: פונקציה שמוסיפה מאפיינים לכל אובייקט שהיא מקבלת יכולה לומר את זה בדיוק.

function withMeta<T extends object>(obj: T, author: string): T & { author: string; savedAt: string } {
  return { ...obj, author, savedAt: "2024-03-15T10:30:00.000Z" };
}

const note = withMeta({ title: "Draft", words: 120 }, "ada");
// type: { title: string; words: number } & { author: string; savedAt: string }

console.log(note.title, note.words, note.author); // Draft 120 ada
console.log(note.savedAt);                         // 2024-03-15T10:30:00.000Z

מי שקורא לפונקציה שומר על הטיפוס המדויק של מה שהעביר (title, words), ובנוסף שני המאפיינים שנוספו. interface ... extends לא יכול לבטא "מה שלא יהיה T, ועוד אלה", כי interface לא יכול להרחיב פרמטר טיפוס.

מאפיינים מתנגשים הופכים ל-never

כששני הצדדים מצהירים על אותו מאפיין, הטיפוס של המאפיין הוא ה-intersection של השניים. אם לטיפוסים האלה אין אף ערך משותף, המאפיין הופך ל-never, והקומפיילר לא אומר כלום עד שמנסים ליצור ערך:

// This does not compile: id cannot be a string and a number at once
type WithStringId = { id: string; name: string };
type WithNumberId = { id: number };

type Account = WithStringId & WithNumberId; // no error on this line

const r: Account = { id: "u1", name: "Ada" };
console.log(r);

index.ts(7,22): error TS2322: Type 'string' is not assignable to type 'never'.

השגיאה מצביעה על האובייקט, לא על הטיפוס שגרם לה, ובגלל זה קשה לאתר באגים כאלה. מעבר עם העכבר מעל r.id בעורך מראה את הטיפוס שלו: never. כשהמאפיין המתנגש הוא תג ליטרל, כמו ב-type Shape = { kind: "circle" } & { kind: "square" }, TypeScript הולך רחוק יותר ומצמצם את כל ה-intersection ל-never. קריאה של מאפיין בערך כזה מסבירה אז למה: Property 'kind' does not exist on type 'never'. The intersection 'Shape' was reduced to 'never' because property 'kind' has conflicting types in some constituents.

interface ... extends תופס את אותה התנגשות כבר בהצהרה, עם השגיאה TS2430. זה ההבדל המעשי העיקרי בין השניים; העמוד interface מול type משווה ביניהם זה לצד זה.

חפיפות תואמות מצמצמות את המאפיין

אם שני טיפוסי המאפיין כן חופפים, התוצאה היא החפיפה. זה שימושי, לא שגיאה:

type Editable = { id: string | number; tags: string[] };
type Stored = { id: string; createdAt: string };

type Doc = Editable & Stored; // id: (string | number) & string, which is string

const doc: Doc = { id: "d1", tags: ["draft"], createdAt: "2024-03-15" };
console.log(doc.id.toUpperCase()); // D1: id is a string, so string methods are allowed

type Letters = "a" | "b" | "c";
type Later = "b" | "c" | "d";
type Both = Letters & Later; // "b" | "c": what the two unions have in common

const shared: Both[] = ["b", "c"];
console.log(shared); // [ 'b', 'c' ]

החצי השני מראה מה & עושה ל-unions: הוא שומר את האיברים ששני הצדדים חולקים. חשיבה על טיפוסים כעל קבוצות של ערכים הופכת את זה לצפוי. A | B הוא האיחוד של שתי הקבוצות, A & B הוא החפיפה שלהן, וחפיפה ריקה היא never.

Intersection מול union

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

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

Intersection מול extends

לשילוב של כמה type aliases של אובייקטים, & הוא הדרך המקובלת והוא בסדר גמור. לטיפוס שנבנה מהרבה חלקים, או לטיפוס של API ציבורי, extends נותן שגיאות מוקדמות יותר ובדיקות טיפוסים זולות יותר.

Intersections עם טיפוסים פרימיטיביים: branding

intersection של טיפוס פרימיטיבי עם טיפוס אובייקט לא מייצר never: string & { readonly __brand: "UserId" } היא מחרוזת שנושאת סימון נוסף שקיים רק בזמן הקומפילציה. לאף מחרוזת אמיתית אין את המאפיין הזה, וזו בדיוק הנקודה: רק קוד שמצהיר על ה-brand בכוונה יכול ליצור כזו, ולכן כבר אי אפשר להעביר string רגיל או OrderId במקום שבו מצופה UserId. לטכניקה הזו יש עמוד משלה, branded types.