TypeScript union types: האופרטור | עם דוגמאות

Union type מפרט אפשרויות עם |: ערך מטיפוס string | number הוא מחרוזת או מספר. בעזרת unions TypeScript מתאר ערכים שיכולים באופן לגיטימי להופיע ביותר מצורה אחת, והקומפיילר מחייב לבדוק איזו צורה יש לכם לפני שמשתמשים במשהו שייחודי לה.

function formatId(id: string | number): string {
  if (typeof id === "number") {
    return id.toString().padStart(6, "0"); // id is number here
  }
  return id.toUpperCase();                 // id is string here
}

console.log(formatId(42));     // 000042
console.log(formatId("ab-7")); // AB-7

בתוך כל ענף של בדיקת ה-typeof, ל-id יש טיפוס יחיד. לשלב הזה קוראים narrowing, והוא מה שהופך unions לשימושיים.

מותר רק מה שמשותף לכל האיברים

לפני הצמצום, אפשר להשתמש רק במה שכל איבר של ה-union תומך בו. toString() קיים גם על מחרוזות וגם על מספרים, ולכן זה תקין; toUpperCase() קיים רק על מחרוזות:

// This does not compile: numbers have no toUpperCase()
function shout(value: string | number) {
  return value.toUpperCase();
}

console.log(shout("hi"));

index.ts(3,16): error TS2339: Property 'toUpperCase' does not exist on type 'string | number'.
  Property 'toUpperCase' does not exist on type 'number'.

השורה השנייה מציינת את האיבר שחסר לו המאפיין. אותו כלל חל גם בכיוון ההפוך: אי אפשר להעביר ערך מטיפוס string | number לפרמטר מטיפוס string (TS2345), כי הוא עשוי להיות מספר. Union מקבל יותר ערכים, ובתמורה מאפשר לעשות איתם פחות עד שבודקים.

צמצום של union

צמצום משתמש בבדיקות JavaScript רגילות. TypeScript עוקב אחרי זרימת הבקרה ומסיר איברים ככל שהם נפסלים, כך שאחרי הבדיקה האחרונה נשאר רק איבר אחד:

type Input = string | number | string[] | Date | null;

function normalize(input: Input): string {
  if (input === null) return "(empty)";
  if (typeof input === "string") return input.trim();
  if (typeof input === "number") return input.toFixed(1);
  if (Array.isArray(input)) return input.join(", ");
  return input.toISOString().slice(0, 10); // only Date is left
}

const samples: Input[] = ["  hi  ", 3, ["a", "b"], new Date("2024-03-15T10:30:00Z"), null];
for (const s of samples) console.log(normalize(s));
// hi
// 3.0
// a, b
// 2024-03-15
// (empty)

הרשימה המלאה של צורות הצמצום נמצאת בעמוד type narrowing.

Unions של טיפוסים ליטרליים

Union של ערכים ליטרליים הוא קבוצה סגורה של ערכים מותרים. זה ה-union הנפוץ ביותר בקוד אמיתי:

type Status = "idle" | "loading" | "success" | "error";
type Dice = 1 | 2 | 3 | 4 | 5 | 6;
type Toggle = "on" | "off" | boolean; // boolean is itself true | false

let current: Status = "idle";
current = "loading";   // fine
current = "finished";  // error TS2322: Type '"finished"' is not assignable to type 'Status'.

השוואה לליטרל מצמצמת: אחרי if (current === "error"), ענף ה-else יודע ש-current הוא אחד משלושת האחרים. Unions של ליטרלים מחליפים enums בהרבה בסיסי קוד; ראו literal types על as const ועל איך גוזרים union כזה ממערך.

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

כשהאיברים הם טיפוסי אובייקטים, מאפיינים שמשותפים לכולם זמינים ישירות. לשאר, בדקו שהמאפיין קיים עם in:

type Cat = { name: string; meow(): string };
type Fish = { name: string; swim(): string };

function act(pet: Cat | Fish): string {
  const intro = `${pet.name}: `; // name exists on both, so it is allowed
  if ("meow" in pet) {
    return intro + pet.meow();   // pet is Cat here
  }
  return intro + pet.swim();     // pet is Fish here
}

const tom: Cat = { name: "Tom", meow: () => "meow" };
const nemo: Fish = { name: "Nemo", swim: () => "swims away" };

console.log(act(tom));  // Tom: meow
console.log(act(nemo)); // Nemo: swims away

עבור unions של כמה מבני אובייקטים, הדפוס הנקי יותר הוא מאפיין ליטרלי משותף כמו kind: "cat" / kind: "fish". בדיקה של המאפיין הזה בלבד מצמצמת את האובייקט כולו, ואפשר לבדוק ש-switch עליו מכסה את כל המקרים. הדפוס הזה נקרא discriminated union.

מערכים ו-unions

המיקום של הסוגריים משנה את המשמעות לגמרי:

const mixed: (string | number)[] = [1, "two", 3]; // each element may be either
const eitherOr: string[] | number[] = ["a", "b"]; // all strings OR all numbers

// @ts-expect-error: Type '(string | number)[]' is not assignable to type 'string[] | number[]'.
const bad: string[] | number[] = ["a", 1];

const precedence: string | number[] = "not an array"; // | binds looser than []

console.log(mixed, eitherOr, precedence);
// [ 1, 'two', 3 ] [ 'a', 'b' ] not an array

const total = mixed.reduce<number>((sum, x) => sum + (typeof x === "number" ? x : 0), 0);
console.log(total); // 4

במעבר על (string | number)[], כל איבר הוא ה-union וצריך צמצום, כמו ב-callback של reduce שלמעלה. מתודות כמו map ו-filter עובדות גם על string[] | number[], וה-callback מקבל string | number.

Unions עם null ו-undefined

ה-union הנפוץ מכולם הוא "ערך או כלום": string | null, User | undefined. זה מה ש-Array.prototype.find ו-Map.prototype.get מחזירים, ומאפיין אופציונלי name?: string נקרא כ-string | undefined. לטיפול בהם עם ?., ?? ובדיקות null יש עמוד משלו: null ו-undefined.

כדי להסיר איברים מ-union קיים ברמת הטיפוסים, השתמשו בטיפוסי העזר המובנים: Exclude<"a" | "b" | "c", "a"> הוא "b" | "c", ו-NonNullable<string | null> הוא string.