كل نوع في هذه الدورة جدير بالثقة بقدر إعدادات الـ compiler التي خلفه فقط. نوع Order نفسه الذي يلتقط رقم تتبّع ناقصًا تحت tsconfig ما، يترك انهيارًا يمرّ تحت آخر. حين انضممت إلى عملية الترحيل التي قُدتها لاحقًا، كان في tsconfig القيمة strict: false، وكان الفريق فخورًا بتغطية TypeScript بنسبة 100%. معظم تلك التغطية كانت تفحص القليل جدًا.
هذا الدرس عن اختيار الخيارات عن قصد، وعن تفعيلها في قاعدة كود حقيقية دون تجميد للعمل ستة أسابيع.
\nstrict ليس فحصًا واحدًا بل عائلة. أهمّها في العمل اليومي:
| الخيار | \nما يلتقطه | \n
|---|---|
strictNullChecks | \nاستخدام قيمة قد تكون null أو undefined | \n
noImplicitAny | \nمعاملات ومتغيّرات نوعها any بصمت | \n
strictFunctionTypes | \nأنواع معاملات callback غير آمنة (الدرس 1-2) | \n
useUnknownInCatchVariables | \nمعاملة القيمة الملتقَطة على أنها Error دون فحص | \n
strictPropertyInitialization | \nحقول أصناف لا يُسند إليها شيء أبدًا | \n
منذ TypeScript 6.0، صار strict مفعَّلًا افتراضيًا، فيحصل عليه المشروع الجديد دون أن يطلبه. وفي المشاريع الأقدم يبقى أثمن سطر في الملف. وكل ما تبقّى في هذا الدرس يفترض وجوده.
noUncheckedIndexedAccess يجعل الوصول بالفهرس صادقًا. معه يكون lines[0] من نوع Line | undefined، وSTOCK[sku] من نوع number | undefined:
const first = cart.lines[0];\nfirst.sku;\n// Error: 'first' is possibly 'undefined'.\n\nconst available: number = STOCK[sku];\n// Error: Type 'number | undefined' is not assignable to type 'number'.“Cannot read properties of undefined” هو أكثر أخطاء وقت التشغيل شيوعًا في JavaScript، والمصفوفات الفارغة والمفاتيح الناقصة مصادره المفضّلة. وهذا الخيار يلتقطها. والثمن بعض الفحوص الإضافية حيث تعرف أن الفهرس صالح (داخل for (let i = 0; i < xs.length; i++))؛ أما حلقات for…of ودوال المصفوفات مثل map فلا تتأثّر.
exactOptionalPropertyTypes يفصل “الغائبة” عن “الموجودة لكن undefined”. الـ endpoint الخاص بـ PATCH في Cartwheel يعامل { couponCode: undefined } على أنها “أزِل الكوبون” و{} على أنها “اتركه كما هو”. دون الخيار، للاثنين النوع نفسه. ومعه:
type OrderPatch = { couponCode?: string };\nconst patch: OrderPatch = { couponCode: undefined };\n// Error: Type '{ couponCode: undefined; }' is not assignable to type 'OrderPatch'\n// with 'exactOptionalPropertyTypes: true'. …إن كنت تقصد فعلًا “قد تكون undefined صراحةً”، فقلها: couponCode?: string | undefined. هذا الخيار أكثر إزعاجًا عند تبنّيه، لأن أنواع مكتبات كثيرة كُتبت دونه، ففعّله بعد الآخرين.
صار tsc --init في TypeScript 5.9 يفعّل الخيارين افتراضيًا في الـ tsconfig الذي يولّده، وهذا تلميح قوي إلى الاتجاه الذي يسير فيه النظام البيئي.
verbatimModuleSyntax (TypeScript 5.0) يجعل الـ imports الناتجة مطابقة لما كتبته. أي import دون المعدِّل type يُحفظ؛ والـ imports المعلَّمة بـ type تُمحى. هذا مهم لأن أدوات مثل Vite وesbuild وتجريد الأنواع المدمج في Node تترجم ملفًا واحدًا في كل مرة، ولا تستطيع البحث عمّا إذا كان Order نوعًا:
import { Order } from './orders';\n// Error: 'Order' is a type and must be imported using a type-only import\n// when 'verbatimModuleSyntax' is enabled.\n\nimport { type Order, placeOrder } from './orders'; // finemoduleResolution يخبر TypeScript كيف يجد الـ imports الخاصة بك. طابِقه مع الأداة التي تحلّها فعلًا. لتطبيق يبنيه Vite أو bundler آخر، استخدم "bundler" (مع "module": "esnext" أو "preserve"): يفهم exports في الحزم ولا يتطلّب امتدادات الملفات. وللكود الذي يشغّله Node مباشرة، مثل خادم أو أداة سطر أوامر، استخدم "module": "nodenext"، الذي يتبع قواعد Node الحقيقية، بما فيها امتدادات .js في الـ imports النسبية. الإعداد القديم "node" (المسمّى أيضًا node10) أقدم من exports في الحزم؛ وهو مهمل في TypeScript 6.0 ومُزال في 7.0، مع baseUrl وtarget: "es5".
erasableSyntaxOnly (TypeScript 5.8) يرفض الميزات القليلة في TypeScript التي تولّد كودًا وقت التشغيل: enum، والـ namespaces التي فيها قيم، وخصائص معاملات المُنشئ (parameter properties)، وصيغتَي CommonJS import x = require(…) وexport =. فعّله إن كان كودك يمرّ عبر تجريد الأنواع في Node، أو إن كنت تريد أن يبقى TypeScript “JavaScript مع أنواع”.
بجمعها معًا، يبدو tsconfig لتطبيق مُجمَّع بـ bundler في 2026 هكذا:
\n{\n \"compilerOptions\": {\n \"target\": \"es2022\",\n \"module\": \"esnext\",\n \"moduleResolution\": \"bundler\",\n \"verbatimModuleSyntax\": true,\n \"erasableSyntaxOnly\": true,\n \"noEmit\": true,\n \"strict\": true,\n \"noUncheckedIndexedAccess\": true,\n \"exactOptionalPropertyTypes\": true,\n \"noImplicitOverride\": true,\n \"skipLibCheck\": true,\n \"jsx\": \"react-jsx\"\n },\n \"include\": [\"src\"]\n}noEmit لأن الـ bundler هو من ينتج JavaScript وtsc يفحص فقط. وskipLibCheck لأن فحص كل ملف .d.ts في node_modules يكلّف وقتًا ويجد مشكلات لا تستطيع إصلاحها.
فعّل خيارًا في قاعدة كود كبيرة وقد تحصل على 2,000 خطأ. لا تُصلحها كلها في pull request واحد. قِس أولًا (tsc --noEmit | grep -c "error TS")، ثم اختر أحد نهجين. إمّا أن تُصلح مجلدًا بعد مجلد باستخدام tsconfig منفصل يمتدّ من الرئيسي ولا يضمّ إلا المجلدات النظيفة، أو أن تفعّل الخيار في كل مكان وتعلّم الأخطاء الموجودة بـ // @ts-expect-error مع مرجع لتذكرة، فيُحاسَب الكود الجديد بالمعيار الجديد فورًا ولا يتحرّك العدد القديم إلا نزولًا.
التمرين سيناريو: ثلاثة أخطاء حقيقية، وتختار أنت الخيارات التي كانت ستلتقطها. بيئة التجربة نفسها تعمل بـ strict ومكتبة ES2022، ولهذا تحتاج بعض الميزات اللاحقة إلى تصريح صغير لتعمل فيها، كما سترى في الدرس القادم.
strict عائلة من الفحوص (فحوص null، والـ any الضمني، وفحوص معاملات الدوال وغيرها)، وهو الافتراضي منذ TypeScript 6.0.","noUncheckedIndexedAccess يضيف undefined إلى عمليات البحث في المصفوفات والـ records، فيلتقط أكثر انهيار شيوعًا يفوته strict.","exactOptionalPropertyTypes يفصل الخاصية الغائبة عن الخاصية المضبوطة صراحةً على undefined، وهذا مهم لأجسام طلبات PATCH والـ spreads.","verbatimModuleSyntax يجعل الـ imports الناتجة مطابقة لما كتبته، فيجب أن تقول الـ imports الخاصة بالأنواع فقط import type.","استخدم moduleResolution: "bundler" للتطبيقات التي يبنيها Vite أو bundler آخر، وnodenext للكود الذي يشغّله Node مباشرة."],"further":[{"title":"TSConfig Reference","url":"https://www.typescriptlang.org/tsconfig/"},{"title":"noUncheckedIndexedAccess","url":"https://www.typescriptlang.org/tsconfig/noUncheckedIndexedAccess.html"},{"title":"Modules - Choosing Compiler Options","url":"https://www.typescriptlang.org/docs/handbook/modules/guides/choosing-compiler-options.html"},{"title":"TypeScript 6.0 release notes","url":"https://www.typescriptlang.org/docs/handbook/release-notes/typescript-6-0.html"}],"quiz":[{"q":"مع تفعيل strict وإيقاف noUncheckedIndexedAccess، ماذا يحدث هنا حين تكون السلة فارغة؟
const first = cart.lines[0];\nconsole.log(first.sku);lines[0] هو Line لا Line | undefined، فتكون الحالة الفارغة غير مرئية."},{"text":"يفشل في الترجمة، لأن strictNullChecks يعرف أن المصفوفات قد تكون فارغة.","why":"strictNullChecks لا يتتبّع null وundefined إلا في الأنواع المعلَنة. الوصول بالفهرس متفائل ما لم يُفعَّل noUncheckedIndexedAccess."},{"text":"يمرّ في الترجمة ويطبع undefined.","why":"قراءة .sku من undefined ترمي خطأً؛ لا تُعيد undefined."},{"text":"يفشل في الترجمة، لأن strict يمنع الوصول بالفهرس.","why":"الوصول بالفهرس مسموح دائمًا؛ الخيار يغيّر فقط النوع الناتج."}],"answer":0},{"q":"type Patch = { couponCode?: string }. مع تفعيل exactOptionalPropertyTypes، أيّ قيمة تُرفض؟
{}","why":"حذف خاصية اختيارية مسموح دائمًا."},{"text":"{ couponCode: 'LOYAL5' }","why":"النص هو بالضبط ما تسمح به الخاصية."},{"text":"{ couponCode: undefined }","why":"صحيح. يعامل الخيار “موجودة بقيمة undefined” على أنها مختلفة عن “غائبة”؛ أعلن couponCode?: string | undefined إن كنت تقصد السماح بها."}],"answer":2},{"q":"في ملفك import { Order, placeOrder } from './orders' حيث Order نوع. مع تفعيل verbatimModuleSyntax، ماذا تكتب؟
Order من الناتج تلقائيًا.","why":"هذا الحذف التلقائي هو بالضبط ما يُطفئه الخيار، كي تطابق الـ imports الناتجة المصدر."},{"text":"import { type Order, placeOrder } from './orders'","why":"صحيح. المعدِّل type يعلّم Order على أنه للأنواع فقط، فيُمحى بينما تبقى placeOrder."},{"text":"import * as orders from './orders' واستخدم orders.Order","why":"الـ import على هيئة namespace يعمل مع القيم، لكنه لا يحلّ تعليم “للأنواع فقط” الذي يطلبه الخيار."},{"text":"فعّل esModuleInterop.","why":"esModuleInterop يتعلّق بالـ imports الافتراضية من CommonJS ولا علاقة له بالـ imports الخاصة بالأنواع فقط."}],"answer":1},{"q":"في tsconfig تطبيقك المبني بـ Vite القيمة "moduleResolution": "node". إلى ماذا يجب أن تغيّرها، ولماذا؟
"classic"، لأنها الأكثر تساهلًا.","why":"classic أقدم من أعراف npm، ومثل node هي مهملة في TypeScript 6.0 ومُزالة في 7.0."},{"text":""nodenext"، لأن Vite يعمل على Node.","why":"Vite يعمل على Node، لكن كود تطبيقك يحلّه الـ bundler، وnodenext سيطلب امتدادات ملفات لا يحتاجها الـ bundler."},{"text":""bundler"، لأنها تحاكي طريقة Vite في حلّ الـ imports، بما فيها exports في الحزم، وnode مهملة.","why":"صحيح. bundler تطابق الأداة التي تحلّ الـ imports فعلًا، وnode (node10) مُزالة في TypeScript 7.0."}],"answer":2}],"exercise":{"kind":"choice","multiple":true,"options":["unchecked-index","exact-optional","implicit-override","skip-lib-check","verbatim-modules","allow-js"],"correct":["unchecked-index","exact-optional","implicit-override"],"title":"أيّ الخيارات كانت ستلتقط هذه الأخطاء؟","prompt":"نظام الدفع في Cartwheel يُترجم أصلًا مع strict: true. ومع ذلك وصلت هذه الأخطاء الثلاثة إلى الإنتاج في الربع الماضي:
cart.lines[0].sku لعرض صورة مصغّرة. ومع سلة فارغة، انهارت الصفحة برسالة Cannot read properties of undefined.{ couponCode: formValue.coupon } إلى الـ endpoint الخاص بـ PATCH. ونوع formValue.coupon هو string | undefined (فالحقل اختياري)؛ وحين كان الحقل فارغًا، كانت قيمته undefined، والـ API يعامل couponCode الموجودة بقيمة undefined على أنها “أزِل الكوبون”، فخسر العملاء كوبونات كانوا قد طبّقوها سابقًا.PriceCalculator.applyTax() إلى addTax() في الصنف الأساسي. وما زال الصنف الفرعي GulfPriceCalculator يعرّف applyTax()، التي لم تعد تتجاوز شيئًا، فطُبّقت على طلبات الخليج النسبة الافتراضية للضريبة.اختر كل خيار في الـ compiler كان سيحوّل، إذا أُضيف إلى strict، واحدًا على الأقل من هذه الأخطاء إلى خطأ ترجمة.
cart.lines[0] اليوم، وأيّ خيار يغيّره.","خيار واحد يميّز بين {} و{ couponCode: undefined } لخاصية اختيارية.","خيار واحد يتطلّب الكلمة المفتاحية override على كل method تتجاوز method في الصنف الأساسي، فيتوقّف التجاوز المتقادم عن المرور في الترجمة."],"explanation":"noUncheckedIndexedAccess يجعل نوع cart.lines[0] هو Line | undefined، فيفرض فحصًا قبل .sku (الخطأ 1). وexactOptionalPropertyTypes يرفض إسناد undefined إلى couponCode?: string، فكان على النموذج أن يحذف المفتاح أو يعلن string | undefined صراحة (الخطأ 2). وnoImplicitOverride يتطلّب override applyTax() في الصنف الفرعي؛ وما إن تُعاد تسمية الـ method الأساسية حتى يصبح override على method لا تتجاوز شيئًا خطأً (الخطأ 3). أما skipLibCheck فيقلّل الفحص، وverbatimModuleSyntax يتعلّق بطريقة توليد الـ imports، وallowJs يُدخل ملفات JavaScript إلى البرنامج؛ ولا يلتقط أيٌّ منها هذه الأخطاء.
noUncheckedIndexedAccess","why":"صحيح. يجعل cart.lines[0] قد تكون undefined، فتصبح قراءة .sku دون فحص خطأً (الخطأ 1)."},"exact-optional":{"text":"exactOptionalPropertyTypes","why":"صحيح. يمنع كتابة undefined في couponCode?: string، وهي بالضبط القيمة التي أزالت الكوبونات (الخطأ 2)."},"implicit-override":{"text":"noImplicitOverride","why":"صحيح. معه يجب أن يعلّم الصنف الفرعي override applyTax()، وتفشل تلك العلامة ما إن تُعاد تسمية الـ method الأساسية (الخطأ 3)."},"skip-lib-check":{"text":"skipLibCheck","why":"يتخطّى فحص أنواع ملفات التصريحات، ومعظمها في node_modules. يجعل الفحص أسرع وأكثر تساهلًا، ولا يجعله أكثر صرامة أبدًا."},"verbatim-modules":{"text":"verbatimModuleSyntax","why":"يتحكّم في الـ imports التي تُحفظ في JavaScript الناتجة. إنه قيّم للـ bundlers، لكنه لا يفحص الوصول إلى الخصائص ولا التجاوزات."},"allow-js":{"text":"allowJs","why":"يتيح لملفات .js الانضمام إلى البرنامج. إنه أداة ترحيل ولا يضيف أي فحوص إلى كود TypeScript الموجود."}}},"words":731,"readMinutes":4}