הטיפוס never ב-TypeScript: בדיקות exhaustive ו-never מול void

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

function fail(message: string): never {
  throw new Error(message);
}

function parsePort(text: string): number {
  const n = Number(text);
  if (Number.isInteger(n) && n > 0 && n < 65536) return n;
  return fail(`invalid port: ${text}`); // never is assignable to number
}

console.log(parsePort("8080")); // 8080

try {
  parsePort("http");
} catch (e) {
  console.log((e as Error).message); // invalid port: http
}

return fail(...) מתקמפל בפונקציה שמחזירה number כי never ניתן להשמה לכל טיפוס: ערך מטיפוס never לעולם לא באמת יגיע.

פונקציות שאף פעם לא חוזרות

שני סוגים של פונקציות לא מגיעים לסוף שלהם: אחת שתמיד זורקת שגיאה, ואחת עם לולאה אינסופית. הקומפיילר בודק את הטענה. פונקציה עם הגדרת never שאפשר להגיע לסוף שלה היא שגיאה TS2534, A function returning 'never' cannot have a reachable end point.

function fail(message: string): never {
  throw new Error(message);
}

function runForever(): never {
  while (true) {
    // poll, serve requests...
  }
}

ההסקה תלויה בתחביר. עבור function declaration שרק זורקת שגיאה מוסק טיפוס החזרה void, ואילו עבור arrow function או function expression שרק זורקת שגיאה מוסק never:

function f1() { throw new Error("x"); }       // () => void
const f2 = () => { throw new Error("x"); };   // () => never

narrowing מתייחס לקריאה כמבוי סתום רק כשלשם שנקרא יש טיפוס מפורש שמחזיר never: function declaration עם הגדרה : never, כמו fail למעלה, או משתנה עם הגדרת טיפוס, const fail: (m: string) => never = (m) => { throw new Error(m); }. never מוסק לא נחשב, וגם לא const fail = (m: string): never => ..., שבו רק לחץ יש הגדרת טיפוס ולמשתנה אין.

never מול void

ההבדל המעשי מתגלה ב-narrowing. אחרי if (!user) fail("no user"), הקומפיילר יודע ש-user מוגדר בשורה הבאה רק אם fail מחזירה never. עם החזרת void הוא מניח שהריצה יכולה להמשיך.

בדיקות exhaustive עם never

כל case של switch על union מצמצם את הערך. כשכל איבר טופל, מה שנשאר ב-default הוא never. השמה שלו למשתנה never הופכת את "טיפלתי בכל מקרה" למשהו שהקומפיילר מאמת:

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; side: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.side ** 2;
    default: {
      const unhandled: never = shape; // shape is never here
      throw new Error(`unknown shape: ${JSON.stringify(unhandled)}`);
    }
  }
}

console.log(area({ kind: "square", side: 3 })); // 9
console.log(area({ kind: "circle", radius: 1 }).toFixed(4)); // 3.1416

עכשיו הוסיפו איבר שלישי ל-union בלי להוסיף case:

// This does not compile: "triangle" is not handled
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; side: number }
  | { kind: "triangle"; base: number; height: number };

function assertNever(value: never): never {
  throw new Error(`Unhandled value: ${JSON.stringify(value)}`);
}

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "square":
      return shape.side ** 2;
    default:
      return assertNever(shape);
  }
}

console.log(area({ kind: "square", side: 3 }));

index.ts(18,26): error TS2345: Argument of type '{ kind: "triangle"; base: number; height: number; }' is not assignable to parameter of type 'never'.

השגיאה מציינת את האיבר ששכחתם. הוסיפו case "triangle": return (shape.base * shape.height) / 2; והקוד יתקמפל שוב. פונקציית העזר assertNever היא הצורה הרב פעמית של אותה בדיקה, וה-throw שלה עדיין חשוב בזמן ריצה: נתונים מ-JSON או מלקוח ישן יותר יכולים להכיל kind שהטיפוסים אומרים שהוא בלתי אפשרי. הדפוס הזה הוא עמוד השדרה של discriminated unions.

Narrowing עד never

אותו דבר קורה בכל narrowing, לא רק ב-switch. ברגע שכל אפשרות נפסלה, למשתנה יש טיפוס never:

function describe(x: string | number | boolean): string {
  if (typeof x === "string") return `string "${x}"`;
  if (typeof x === "number") return `number ${x}`;
  if (typeof x === "boolean") return `boolean ${x}`;
  const nothing: never = x; // every option handled
  return nothing;
}

console.log(describe("a")); // string "a"
console.log(describe(2));   // number 2
console.log(describe(true)); // boolean true

אם בהמשך תרחיבו את הפרמטר ל-string | number | boolean | bigint, השורה const nothing: never = x תהפוך לשגיאה, ותצביע על הפונקציה שצריך לעדכן.

never נעלם ב-unions

never הוא הקבוצה הריקה של ערכים, ולכן הוספה שלו ל-union לא משנה כלום: string | never הוא פשוט string. כך conditional types מסננים unions. ענף שמחזיר never מסיר את האיבר הזה:

type OnlyStrings<T> = T extends string ? T : never;

type Mixed = "a" | "b" | 1 | 2 | true;
type Letters = OnlyStrings<Mixed>; // "a" | "b"

const ok: Letters = "a";
// @ts-expect-error: Type '1' is not assignable to type 'Letters'.
const bad: Letters = 1;

console.log(ok);

ה-Exclude<T, U> וה-Extract<T, U> המובנים עובדים בדיוק כך. ב-intersection זה ההפך: string & never הוא never.

טיפוסים בלתי אפשריים הופכים ל-never

intersection ששום ערך לא יכול לקיים מצטמצם ל-never:

type A = string & number;                   // never
type B = { kind: "a" } & { kind: "b" };     // never

קריאת מאפיין של ערך B מדווחת את הסיבה: Property 'kind' does not exist on type 'never'. The intersection 'B' was reduced to 'never' because property 'kind' has conflicting types in some constituents. כשטיפוס שבניתם מתברר כ-never, חפשו שני חלקים שסותרים זה את זה.

never, unknown ו-any

unknown נמצא בראש היררכיית הטיפוסים ו-never בתחתית. any בכלל לא חלק מההיררכיה: הוא מכבה את הבדיקות.