استخدام TypeScript للدوال في السحابة الإلكترونية

بالنسبة إلى مطوّري البرامج الذين يفضّلون كتابة الدوالّ في TypeScript، توفّر دوال Cloud Functions نوعَين من الدعم وهما:

  • يمكنك إنشاء مشاريع TypeScript وإعدادها للترجمة التلقائية عند الإعداد (firebase init functions).
  • نقل مصدر TypeScript الحالي إلى JavaScript في وقت النشر من خلال عنصر الجذب السابق.

باتّباع التعليمات الواردة في هذا الدليل، يمكنك نقل مشروع JavaScript حالي إلى TypeScript ومواصلة نشر الدوال باستخدام عنصر جذب قبل النشر لتحويل رمز المصدر. توفر TypeScript العديد من الفوائد على JavaScript من vanilla عند كتابة الدوال:

  • يتوافق TypeScript مع أحدث ميزات JavaScript، مثل عدم المزامنة أو الانتظار، ما يسهِّل عملية إدارة الوعود.
  • يسلّط موقع Cloud Functions linter الضوء على المشاكل الشائعة أثناء الترميز.
  • تساعدك ميزة "سلامة نوع النشاط" في تجنُّب أخطاء وقت التشغيل في الدوال المفعَّلة.

إذا كنت مبتدئًا في استخدام TypeScript، يمكنك الاطّلاع على TypeScript خلال 5 دقائق.

إعداد مشروع جديد لدوال السحابة باستخدام TypeScript

تشغيل firebase init functions في دليل جديد تمنحك الأداة خيارات لإنشاء المشروع باستخدام JavaScript أو TypeScript. اختر TypeScript لإخراج البنية التالية للمشروع:

myproject
 +- functions/     # Directory containing all your functions code
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- tsconfig.json
      |
      +- .eslintrc.js # Optional file if you enabled ESLint
      +- tsconfig.dev.json # Optional file that references .eslintrc.js
      |
      +- src/     # Directory containing TypeScript source
      |   |
      |   +- index.ts  # main source file for your Cloud Functions code
      |
      +- lib/
          |
          +- index.js  # Built/transpiled JavaScript code
          |
          +- index.js.map # Source map for debugging

بعد اكتمال عملية الإعداد، يُرجى إلغاء تعليق النموذج في index.ts وتشغيل npm run serve للاطّلاع على الدالة "Hello World" (أهلاً بالعالم).

استخدام مشروع TypeScript حالي

إذا كان لديك مشروع TypeScript حاليًا، يمكنك إضافة عنصر جذب قبل النشر للتأكد من تحويل مشروعك إلى نص في كل مرة تنشر فيها الرمز في Cloud Functions for Firebase. ستحتاج إلى ملف tsconfig.json بتنسيق صحيح ومشروع في Firebase، وعليك إجراء التعديلات التالية على إعدادات Firebase:

  1. عدِّل package.json لإضافة نص برمجي bash لإنشاء مشروع TypeScript. على سبيل المثال:

     {
       "name": "functions",
       "scripts": {
         "build": "npm run lint && tsc"
       }
     ...
    
  2. يمكنك تعديل firebase.json لإضافة عنصر جذب قبل النشر لتشغيل النص البرمجي للإصدار. على سبيل المثال:

     {
       "functions": {
         "predeploy": "npm --prefix functions run build",
       }
     }
    

باستخدام هذه الإعدادات، ينشئ الأمر firebase deploy --only functions رمز TypeScript وينشره كدوال.

نقل مشروع JavaScript حالي إلى TypeScript

إذا كان لديك مشروع حالي على Cloud Functions تم إعداده وتطويره باستخدام JavaScript، يمكنك نقله إلى TypeScript. نشجعك على ضرورة إنشاء نقطة تفتيش git أو أي نقطة احتياطية أخرى قبل البدء.

لنقل مشروع حالي في JavaScript Cloud Functions:

  1. يمكنك إنشاء نقطة فحص git وحفظ نُسخ من ملفات مصدر JavaScript الحالية.
  2. في دليل المشروع، شغِّل firebase init functions واختَر TypeScript عندما يُطلب منك إدخال لغة لكتابة الدوال.
  3. عندما يُطلب منك ما إذا كنت تريد استبدال ملف package.json الحالي أم لا، اختَر لا ما لم تكن متأكدًا من أنّك لا تريد الاحتفاظ بالملف الحالي.
  4. يمكنك حذف index.ts في الدليل functions/src، مع استبداله برمز المصدر الحالي.
  5. في ملف tsconfig.json الذي تم إنشاؤه عند الإعداد، عليك ضبط خيارات برنامج التحويل البرمجي للسماح بتشغيل JavaScript: "allowJs": true.
  6. انسخ ملف package.json المحفوظ إلى دليل functions، وعدِّله لضبط "main" على "lib/index.js".
  7. في package.json أيضًا، يمكنك إضافة نص برمجي لإنشاء النوع TypeScript كما يلي:

     {
       "name": "functions",
       "scripts": {
         "build": "npm run lint && tsc"
       }
     ...
    
  8. أضِف "typescript" كتبعية للمطوّر من خلال تشغيل npm install --save-dev typescript @typescript-eslint/eslint-plugin @typescript-eslint/parser.

  9. بالنسبة إلى جميع التبعيات، شغِّل npm install --save @types/<dependency>.

  10. أعِد كتابة رمز المصدر من .js إلى .ts على النحو المطلوب.

محاكاة دوال TypeScript

لاختبار دوال TypeScript محليًا، يمكنك استخدام أدوات المحاكاة الموضحة في تشغيل الدوال محليًا. من المهم تجميع التعليمة البرمجية قبل استخدام هذه الأدوات، لذا تأكد من تشغيل npm run build داخل دليل الدوال قبل تشغيل firebase emulators:start أو firebase functions:shell. بدلاً من ذلك، يمكنك تشغيل npm run serve أو npm run shell كاختصار، إذ تعمل هذه الأوامر على تشغيل إصدار الواجهة وserve/بدء استخدام الدوال.

سجلات الدوال لمشاريع TypeScript

خلال firebase deploy، يتم تحويل index.ts لمشروعك إلى index.js، ما يعني أنّ سجلّ وظائف السحابة الإلكترونية سيخرج أرقام الأسطر من ملف index.js وليس الرمز الذي كتبته. لتسهيل العثور على المسارات وأرقام الأسطر المتجاوبة في index.ts، يتم إنشاء functions/lib/index.js.map من خلال firebase deploy. يمكنك استخدام خريطة المصدر هذه في بيئة التطوير المتكاملة (IDE) لديك أو عبر وحدة العقدة.