סימן קריאה ב-TypeScript: ה-Non-Null Assertion (!)

סימן קריאה אחרי ביטוי, value!, הוא האופרטור non-null assertion. הוא מסיר את null ו-undefined מהטיפוס, כך שאפשר להשתמש ב-number | undefined כ-number. זו הבטחה לקומפיילר, לא בדיקה: בזמן ריצה לא קורה כלום.

const prices = new Map<string, number>([
  ["tea", 2.5],
  ["coffee", 3.2],
]);

const tea = prices.get("tea");         // number | undefined
const coffee = prices.get("coffee")!;  // number

console.log(coffee.toFixed(2)); // 3.20
console.log(tea!.toFixed(2));   // 2.50: ! works on any expression

בלי ה-!, tea.toFixed(2) היא שגיאה TS18048, 'tea' is possibly 'undefined'. איתו, הקוד מתקמפל כי אמרתם לקומפיילר שהמפתח קיים.

מה x! עושה בזמן ריצה: כלום

ה-! נמחק מהפלט. ה-JavaScript המקומפל של prices.get("coffee")! הוא פשוט prices.get("coffee"). אם הטענה שגויה, השגיאה מופיעה מאוחר יותר, במקום הראשון שבו משתמשים בערך החסר:

const prices = new Map<string, number>([["tea", 2.5]]);

try {
  const juice = prices.get("juice")!; // compiles: the ! silences the check
  console.log(juice.toFixed(2));      // TypeError at runtime
} catch (e) {
  console.log((e as Error).message);
}

התוכנית מדפיסה Cannot read properties of undefined (reading 'toFixed'). הקריסה קורית בשורה שאחרי ה-!, ובקוד אמיתי היא יכולה להיות רחוקה בהרבה: ה-undefined עשוי להישמר באובייקט ולהתפוצץ בקובץ אחר. המרחק הזה הוא הסיבה ש-! מסוכן.

Definite assignment: let x!: T

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

// This does not compile: TypeScript cannot see the assignment inside init()
let config: { port: number };

function init() {
  config = { port: 8080 };
}

init();
console.log(config.port);

index.ts(9,13): error TS2454: Variable 'config' is used before being assigned.

let config!: { port: number }; הוא definite assignment assertion: "זה יקבל ערך לפני כל קריאה". זה מתקן את השגיאה, עם אותו מלכוד כמו x!: אם init() ידולג אי פעם, הקריאה תקבל undefined. בדרך כלל עדיף לשנות את מבנה הקוד, למשל const config = init(); כש-init מחזירה את האובייקט.

מאפייני מחלקה: prop!: T

עם strictPropertyInitialization (חלק מ-strict), כל מאפיין מחלקה חייב לקבל ערך בהצהרה שלו או ב-constructor. אחרת מקבלים TS2564: Property 'socket' has no initializer and is not definitely assigned in the constructor. כשמאפיין מוגדר מאוחר יותר על ידי מתודה או framework, prop!: T אומר לקומפיילר לקבל אותו:

class Connection {
  url: string;
  socket!: { send(msg: string): string }; // set in open(), not in the constructor

  constructor(url: string) {
    this.url = url;
  }

  open() {
    this.socket = { send: (msg) => `sent "${msg}" to ${this.url}` };
  }
}

const c = new Connection("ws://example.com");
console.log(c.socket);            // undefined: declared but not set yet
c.open();
console.log(c.socket.send("hi")); // sent "hi" to ws://example.com

ה-console.log הראשון מראה את הפער: הטיפוס אומר ש-socket תמיד קיים, אבל לפני open() הוא undefined. קריאה ל-c.socket.send בשלב הזה מתקמפלת וזורקת שגיאה. אם המאפיין באמת יכול להיות חסר, הצהירו עליו כ-socket?: ... ובדקו אותו, או צרו את האובייקט ב-constructor. המקום העיקרי שבו prop! הוא נוהג מקובל הוא framework שממלא מאפיין אחרי היצירה: @ViewChild(...) child!: ChildDirective של Angular (מוגדר לפני ש-ngAfterViewInit רץ), או מחלקות entity של ORM שהספרייה ממלאת את העמודות שלהן כשהיא טוענת שורה (בתיעוד של MikroORM כתוב @Property() title!: string).

חלופות בטוחות יותר

את רוב ה-! אפשר להחליף במשהו שהקומפיילר בודק, או בבדיקה שנכשלת בקול רם במקום הנכון:

function must<T>(value: T | null | undefined, what: string): T {
  if (value == null) throw new Error(`missing ${what}`);
  return value;
}

function assertDefined<T>(value: T, what: string): asserts value is NonNullable<T> {
  if (value == null) throw new Error(`missing ${what}`);
}

const env = new Map([["PORT", "8080"]]);

const port = must(env.get("PORT"), "PORT"); // string
console.log(Number(port) + 1);              // 8081

const host = env.get("HOST");
try {
  assertDefined(host, "HOST");
  console.log(host.toUpperCase()); // host is string after the assertion
} catch (e) {
  console.log((e as Error).message); // missing HOST
}

שתי פונקציות העזר מצמצמות את הטיפוס כמו ש-! עושה, אבל הנחה שגויה מייצרת missing HOST במקום, במקום TypeError במקום אחר. assertDefined היא assertion function (asserts value is ...): אחרי הקריאה, הקומפיילר מתייחס ל-host כ-string. דפוסים נוספים ב-type guards.

סימני הקריאה האחרים

ל-! יש משמעויות שונות לפי המיקום שלו:

רק השניים הראשונים נמחקים בזמן קומפילציה. !value ו-!!value רצים בזמן ריצה ומחזירים ערך בוליאני.