علامة التعجب في TypeScript: تأكيد عدم الفراغ (!)

علامة التعجب بعد تعبير، 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 في كائن وتنفجر في ملف آخر. هذه المسافة هي سبب خطورة !.

الإسناد المؤكد: 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 }; تأكيد إسناد مؤكد: «سيُسند هذا قبل أي قراءة». يصلح الخطأ، مع المشكلة نفسها التي في x!: إذا تُخطي init() يومًا، تحصل القراءة على undefined. وإعادة الهيكلة أفضل عادة، مثل const config = init(); مع دالة init تعيد الكائن.

خصائص الأصناف: prop!: T

مع strictPropertyInitialization (جزء من strict)، يجب تهيئة كل خاصية في الصنف عند تصريحها أو في المُنشئ. وإلا تحصل على TS2564: Property 'socket' has no initializer and is not definitely assigned in the constructor. وعندما تُضبط الخاصية لاحقًا بدالة أو بإطار عمل، يخبر 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?: ... وافحصها، أو أنشئ الكائن في المُنشئ. الموضع الرئيسي الذي يكون فيه prop! ممارسة معيارية هو إطار عمل يملأ خاصية بعد الإنشاء: @ViewChild(...) child!: ChildDirective في Angular (يُضبط قبل تشغيل ngAfterViewInit)، أو أصناف كيانات 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 دالة تأكيد (asserts value is ...): بعد الاستدعاء يعامل المترجم host على أنه string. مزيد من الأنماط في type guards.

علامات التعجب الأخرى

تعني ! أشياء مختلفة بحسب موضعها:

الأوليان فقط تُمحيان وقت الترجمة. أما !value و!!value فتعملان وقت التشغيل وتعيدان boolean.