الترحيل الذي قُدته نقل نظام دفع وإدارة طلبات مكتوبًا بـ 400,000 سطر من JavaScript إلى TypeScript صارمة خلال نحو ثمانية عشر شهرًا، دون تجميد للميزات ودون branch طويل العمر. ونشرنا التحديثات كل يوم طوال تلك المدة. تقنيات مستوى الأنواع في هذه الدورة مهمة، لكن في قاعدة كود حقيقية العملية هي ما يقرّر إن كان الترحيل سيكتمل. هذا الدرس هو تلك العملية، إضافة إلى كيفية الحفاظ على سرعة فحص الأنواع بعد أن تنتهي.
\nابدأ بالسماح لـ TypeScript وJavaScript بالعيش معًا:
\n{\n \"compilerOptions\": {\n \"allowJs\": true,\n \"checkJs\": false,\n \"noEmit\": true,\n \"strict\": true,\n \"module\": \"esnext\",\n \"moduleResolution\": \"bundler\",\n \"target\": \"es2022\",\n \"skipLibCheck\": true\n },\n \"include\": [\"src\"]\n}allowJs تُدخل ملفات .js إلى البرنامج، فتستطيع ملفات .ts استيرادها والعكس. وnoEmit تترك البناء للـ bundler الموجود؛ وtsc --noEmit يعمل في CI كفاحص فقط. وstrict مفعَّل منذ اليوم الأول، لكنه لا ينطبق إلا على ملفات .ts، فيُحاسَب الكود الجديد بالمعيار الكامل ويُترك القديم وشأنه. ادمج هذا على main في pull request صغير واحد. لا شيء في التطبيق يتغيّر.
يمكنك الحصول على فحص حقيقي في ملف .js دون إعادة تسميته. أضف // @ts-check في أعلاه، فيفحص TypeScript الملف، قارئًا الأنواع من تعليقات JSDoc:
// @ts-check\n\n/** @typedef {'USD' | 'EUR' | 'EGP'} Currency */\n/** @typedef {{ cents: number; currency: Currency }} Money */\n\n/**\n * @param {Money} a\n * @param {Money} b\n * @returns {Money}\n */\nexport function add(a, b) {\n if (a.currency !== b.currency) throw new Error('Currency mismatch');\n return { cents: a.cents + b.cents, currency: a.currency };\n}إنه الفاحص نفسه، بالقواعد نفسها، على ملف JavaScript عادي. استخدمه على أكثر الملفات حساسية وخطورة أولًا. ويستطيع JSDoc حتى استيراد أنواع من ملفات .ts بـ @import أو import('./types').Order، فيستخدم ملف JavaScript أنواع المجال التي كتبتها أصلًا.
حين تعيد تسمية الملفات فعلًا، يكون الترتيب مهمًا. ارسم (أو ولّد) مخطّط الـ imports وابدأ من الأوراق: الوحدات التي لا تستورد شيئًا آخر من قاعدة كودك، مثل دوال المال المساعدة، والتنسيق، والثوابت، وأنواع المجال. ثم حوّل الوحدات التي لا تعتمد إلا على وحدات محوَّلة، واستمر في العمل نحو الداخل باتجاه نقاط الدخول.
\nتحويل نقطة دخول أولًا يعطيك ملف .ts كل ما يستورده بلا أنواع، أي كثيرًا من any وقليلًا جدًا من الفحص. أما تحويل ورقة أولًا فيعطي كل ملف لاحق أنواعًا حقيقية يبني عليها.
وإلى جانب الأوراق، أعطِ الأولوية لـ الحدود: عميل الـ API، والمحلّلات، ونماذج المجال. Order محدَّد النوع واستجابة API محلَّلة يحميان كل ملف يلمسهما، محوَّلًا كان أم لا. ولهذا تهمّ الأقسام 1 و2 و4 من هذه الدورة في الترحيل أكثر من القسم 3.
حين يختفي آخر ملف .js، أزِل allowJs. ثم شدّ الخيارات الإضافية من صرامة tsconfig التي تؤتي ثمارها تدريجيًا، بدءًا بـ noUncheckedIndexedAccess، واحدًا تلو الآخر، مُخفيًا الأخطاء الموجودة بـ // @ts-expect-error مع تذكرة، كي يبلغ الكود الجديد المستوى المطلوب فورًا.
في قاعدة كود كبيرة، تصبح سرعة فحص الأنواع مشكلة في تجربة المطوّرين. قِس قبل أن تخمّن: tsc --noEmit --extendedDiagnostics يطبع زمن الفحص والذاكرة وعدد تجسيدات الأنواع. القفزة المفاجئة في التجسيدات تأتي دائمًا تقريبًا من أداة ثقيلة على مستوى الأنواع، مثل Paths التعاودي من الأنواع التعاودية ومتى تتوقّف، مطبَّقة على نوع كبير. و--generateTrace <dir> يسجّل أين يذهب الوقت، ملفًا بعد ملف.
الإصلاحات البنيوية راسخة. فعّل incremental كي لا يُعاد فحص الملفات التي لم تتغيّر. وقسّم المستودع الكبير إلى مراجع مشاريع (project references) (composite: true في كل حزمة، وtsc -b في الجذر)، فيُفحص كل جزء مرة واحدة وتُعاد استخدام تصريحاته. وفضّل الـ interfaces التي يمتدّ (extend) بعضها من بعض على السلاسل الطويلة من تقاطعات & لأنواع الكائنات الكبيرة، لأن الـ compiler يخزّن علاقات الـ interfaces مؤقتًا بفعالية أكبر. وعلّق أنواع إرجاع الدوال المُصدَّرة، فهذا يوفّر على الفاحص إعادة استنتاجها ويُبقي مخرجات التصريحات مستقرة.
استخدمت الأنواع لتصميم الحالات، ووجّهت الـ inference، وكتبت كودًا على مستوى الأنواع باعتدال، وبنيت الأنماط التي تعتمد عليها قواعد الكود الحقيقية، وضبطت الـ compiler ليسندها. والعادة التي يجب أن تحتفظ بها هي تلك التي من الدرس الأول: قبل أن تكتب type، سمِّ الخطأ الذي يمنعه. ثم اختر أبسط type يمنعه. التمرين أدناه يرتّب دليل الترحيل؛ والتقييم النهائي يغطّي الدورة كلها.
\n","toc":[{"id":"sec-1","text":"التعايش أولًا","level":2},{"id":"sec-2","text":"افحص JavaScript قبل تحويلها","level":2},{"id":"sec-3","text":"حوّل من الأوراق نحو الداخل","level":2},{"id":"sec-4","text":"الحفاظ على السرعة","level":2},{"id":"sec-5","text":"إلى أين من هنا","level":2}],"takeaways":["رحّل تدريجيًا باستخدامallowJs، كي تعيش ملفات JavaScript وTypeScript جنبًا إلى جنب ويُنشر التطبيق كل يوم.","// @ts-check مع أنواع JSDoc يعطي ملف JavaScript فحصًا حقيقيًا قبل أن تعيد تسميته.","حوّل وحدات الأوراق أولًا واعمل نحو نقاط الدخول، كي يستورد كل ملف محوَّل حديثًا كودًا محدَّد الأنواع.","حدّد أنواع الحدود (استجابات الـ API ونماذج المجال) مبكرًا؛ فهي تعطي أكبر حماية مقابل كل ساعة عمل.","قِس فحص الأنواع بـ --extendedDiagnostics، واستخدم البناء التدريجي ومراجع المشاريع، وأبقِ كود مستوى الأنواع الثقيل خارج المسارات الساخنة."],"further":[{"title":"Migrating from JavaScript","url":"https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html"},{"title":"JSDoc Reference","url":"https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html"},{"title":"Project References","url":"https://www.typescriptlang.org/docs/handbook/project-references.html"},{"title":"Type Checking JavaScript Files","url":"https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html"}],"quiz":[{"q":"تبدأ ترحيل تطبيق JavaScript من 1,500 ملف. أيّ خطوة أولى تُبقي التطبيق قابلًا للنشر؟
","options":[{"text":"أنشئ branch طويل العمر باسمtypescript وأعِد تسمية كل ملف إلى .ts هناك.","why":"الـ branch الضخم دفعة واحدة يبتعد عن main يوميًا ويُدمج في جدار من التعارضات والأخطاء. والفرق التي تجرّبه كثيرًا ما تتخلّى عنه."},{"text":"أعِد تسمية كل ملف إلى .ts على main وأضف // @ts-nocheck إلى كلٍّ منها.","why":"هذا ينشئ آلاف الملفات التي تبدو محدَّدة الأنواع ولا تفحص شيئًا، وإزالة التوجيه لاحقًا هي مشكلة “الدفعة الواحدة” نفسها."},{"text":"انتظر حتى يجد الفريق وقتًا لتحويل كل شيء في sprint واحد.","why":"ذلك الـ sprint لا يأتي أبدًا لقاعدة كود بهذا الحجم؛ العمل التدريجي هو النهج الوحيد الذي يكتمل."},{"text":"أضف tsconfig فيه allowJs، وشغّل tsc --noEmit في CI، وحوّل الملفات واحدًا تلو الآخر على main.","why":"صحيح. تتعايش JavaScript وTypeScript، ويُنشر كل pull request، ولا تتحرّك النسبة المحوَّلة إلا صعودًا."}],"answer":3},{"q":"بأيّ ترتيب يجب أن تحوّل الوحدات؟
","options":[{"text":"نقاط الدخول أولًا، كي يكون الكود الأكثر ظهورًا محدَّد الأنواع.","why":"نقاط الدخول تستورد كل شيء آخر؛ وإن حُوّلت مبكرًا فستستورد وحدات بلا أنواع وتحصل في الغالب علىany."},{"text":"وحدات الأوراق (التي لا تستورد شيئًا داخليًا) أولًا، ثم الوحدات التي تعتمد عليها.","why":"صحيح. حينها يستورد كل ملف محوَّل كودًا محدَّد الأنواع أصلًا، فتكون أنواعه حقيقية منذ اليوم الأول."},{"text":"أبجديًا، كي يسهل تتبّع التقدّم.","why":"أسماء الملفات لا تقول شيئًا عن الاعتماديات؛ ستحوّل كثيرًا ملفًا قبل الكود الذي يعتمد عليه."}],"answer":1},{"q":"يُظهر tsc --extendedDiagnostics تسعة ملايين تجسيد للأنواع، معظمها من ملف واحد. ما السبب المرجّح؟
any غير كافية.","why":"إضافة any تُخفي المشكلة بإزالة الفحص، وهذا ليس إصلاحًا."}],"answer":0},{"q":"كيف يساعد // @ts-check أعلى ملف .js في الترحيل؟
tsc يولّد ملف .d.ts لتلك الوحدة.","why":"مخرجات التصريحات تعتمد على إعدادات declaration، لا على @ts-check."},{"text":"يفحص أنواع ملف JavaScript ذلك، مستخدمًا تعليقات JSDoc للأنواع، فتستطيع إيجاد الأخطاء قبل إعادة تسميته.","why":"صحيح. تعليقات JSDoc مثل @param {Order} order أنواع حقيقية بالنسبة للفاحص، دون تغييرات في البناء."}],"answer":2}],"exercise":{"kind":"order","items":["add-tsconfig","check-boundaries","convert-leaves","convert-inward","drop-allowjs","ratchet-flags"],"title":"رتّب دليل الترحيل","prompt":"تطبيق إدارة الطلبات في Cartwheel مكوَّن من 1,500 ملف JavaScript ويجب أن يستمر في نشر التحديثات كل يوم. رتّب خطوات الترحيل هذه بالترتيب الذي يوصي به الدرس، من أول pull request إلى آخره.
\n","hints":["الخطوة الأولى تمامًا لا تغيّر شيئًا في طريقة بناء التطبيق أو تشغيله.","يمكنك الحصول على فحص الأنواع في ملفات JavaScript قبل إعادة تسمية أيٍّ منها.","يجب أن تستورد الملفات المحوَّلة كودًا محدَّد الأنواع أصلًا، وتأتي خيارات الصرامة الإضافية حين يصير كل شيء TypeScript."],"explanation":"أولًا، tsconfig فيه allowJs وnoEmit، يُفحص في CI، يتيح للغتين التعايش دون المساس بالبناء. بعد ذلك، // @ts-check وJSDoc على الحدود (عميل الـ API ونماذج المجال) يعطيان أكبر حماية قبل أي إعادة تسمية. ثم حوّل وحدات الأوراق، واعمل نحو الداخل، كي يستورد كل ملف محوَّل كودًا محدَّد الأنواع. وحين لا يبقى أي مصدر .js، أسقط allowJs. وأخيرًا، شدّ الخيارات الإضافية مثل noUncheckedIndexedAccess واحدًا تلو الآخر، مُخفيًا الأخطاء الموجودة بـ @ts-expect-error مع تذكرة كي يبلغ الكود الجديد المستوى الأعلى فورًا.
allowJs وnoEmit وstrict، وشغّل tsc --noEmit في CI بجوار البناء الموجود","check-boundaries":"أضف // @ts-check وأنواع JSDoc إلى ملفات عميل الـ API ونماذج المجال","convert-leaves":"أعِد تسمية وحدات الأوراق (الدوال المساعدة التي لا تستورد شيئًا داخليًا) من .js إلى .ts","convert-inward":"حوّل الوحدات التي تعتمد على وحدات محوَّلة أصلًا، عاملًا نحو نقاط الدخول","drop-allowjs":"أزِل allowJs حين لا يبقى أي ملف مصدر .js","ratchet-flags":"فعّل noUncheckedIndexedAccess والخيارات الإضافية الأخرى واحدًا تلو الآخر، معلّمًا الأخطاء القديمة بـ @ts-expect-error"}},"words":737,"readMinutes":4}