الوحدات: TypeScript

[السجل]

الإصدار	التغييرات
v22.7.0	تمت إضافة علم --experimental-transform-types.

[مستقر: 1 - تجريبي]

مستقر: 1 استقرار: 1.1 - تطوير نشط

التفعيل

هناك طريقتان لتمكين دعم وقت التشغيل لـ TypeScript في Node.js:

دعم TypeScript الكامل

لاستخدام TypeScript مع دعم كامل لجميع ميزات TypeScript، بما في ذلك tsconfig.json، يمكنك استخدام حزمة تابعة لجهات خارجية. تستخدم هذه التعليمات tsx كمثال، ولكن هناك العديد من المكتبات المماثلة الأخرى المتاحة.

إزالة الأنواع

تمت الإضافة في: v22.6.0

[مستقر: 1 - تجريبي]

مستقر: 1 استقرار: 1.1 - تطوير نشط

يُمَكّن العلم --experimental-strip-types Node.js من تشغيل ملفات TypeScript. بشكل افتراضي، سيُنفذ Node.js فقط الملفات التي لا تحتوي على ميزات TypeScript التي تتطلب تحويلًا، مثل التعدادات أو مسافات الأسماء. سيستبدل Node.js تعليقات الأنواع المضمنة بمسافات بيضاء، ولن يتم إجراء أي فحص للأنواع. لتمكين تحويل هذه الميزات، استخدم العلم --experimental-transform-types. ميزات TypeScript التي تعتمد على الإعدادات داخل tsconfig.json، مثل المسارات أو تحويل بناء جملة JavaScript الأحدث إلى معايير أقدم، غير مدعومة عمدًا. للحصول على دعم TypeScript الكامل، راجع دعم TypeScript الكامل.

تم تصميم ميزة إزالة الأنواع لتكون خفيفة الوزن. من خلال عدم دعم بناء الجملة الذي يتطلب إنشاء كود JavaScript عمدًا، ومن خلال استبدال الأنواع المضمنة بمسافات بيضاء، يمكن لـ Node.js تشغيل كود TypeScript دون الحاجة إلى خرائط المصدر.

تعمل إزالة الأنواع مع معظم إصدارات TypeScript، لكننا نوصي بالإصدار 5.7 أو أحدث مع إعدادات tsconfig.json التالية:

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "allowImportingTsExtensions": true,
    "rewriteRelativeImportExtensions": true,
    "verbatimModuleSyntax": true
  }
}

تحديد نظام الوحدات

يدعم Node.js كلًا من بناء جملة CommonJS و ES Modules في ملفات TypeScript. لن يقوم Node.js بالتحويل من نظام وحدة إلى آخر؛ إذا كنت تريد تشغيل كودك كوحدة ES، فيجب عليك استخدام بناء جملة import و export، وإذا كنت تريد تشغيل كودك كـ CommonJS، فيجب عليك استخدام require و module.exports.

• سيتم تحديد نظام الوحدة الخاص بملفات .ts بنفس الطريقة التي يتم بها تحديد نظام الوحدة لملفات .js. لاستخدام بناء جملة import و export، أضف "type": "module" إلى أقرب ملف package.json رئيسي.
• سيتم دائمًا تشغيل ملفات .mts كـ وحدات ES، مشابهة لملفات .mjs.
• سيتم دائمًا تشغيل ملفات .cts كـ وحدات CommonJS، مشابهة لملفات .cjs.
• ملفات .tsx غير مدعومة.

كما هو الحال في ملفات JavaScript، يُعدّ امتدادات الملفات إلزامية في عبارات import و تعابير import() : import './file.ts', وليس import './file'. نظرًا للتوافق مع الإصدارات السابقة، فإن امتدادات الملفات إلزامية أيضًا في مكالمات require() : require('./file.ts'), وليس require('./file'), مشابهة لكيفية كون امتداد .cjs إلزاميًا في مكالمات require في ملفات CommonJS.

سيسمح خيار tsconfig.json allowImportingTsExtensions لـ مُجمِّع TypeScript tsc بالتحقق من نوع الملفات التي تحتوي على مُحدِّدات import التي تتضمن امتداد .ts.

ميزات TypeScript

بما أن Node.js يقوم فقط بإزالة الأنواع المضمنة، فإن أي ميزات TypeScript تتضمن استبدال بناء جملة TypeScript ببناء جملة JavaScript جديد ستؤدي إلى حدوث خطأ، ما لم يتم تمرير العلم --experimental-transform-types.

أبرز الميزات التي تتطلب التحويل هي:

• Enum
• namespaces
• legacy module
• خصائص المعلمة

بما أن الديكورات هي حاليًا اقتراح TC39 المرحلة 3 وسيتم دعمها قريبًا بواسطة محرك JavaScript، فلن يتم تحويلها وستؤدي إلى حدوث خطأ في المُحلِّل. هذا قيد مؤقت وسيتم حله في المستقبل.

بالإضافة إلى ذلك، لا يقوم Node.js بقراءة ملفات tsconfig.json ولا يدعم الميزات التي تعتمد على الإعدادات داخل tsconfig.json، مثل المسارات أو تحويل بناء جملة JavaScript الأحدث إلى معايير أقدم.

استيراد الأنواع بدون كلمة المفتاح type

بسبب طبيعة إزالة الأنواع، فإن كلمة المفتاح type ضرورية لإزالة استيراد الأنواع بشكل صحيح. بدون كلمة المفتاح type، سيعامل Node.js الاستيراد على أنه استيراد قيمة، مما سيؤدي إلى خطأ وقت التشغيل. يمكن استخدام خيار tsconfig verbatimModuleSyntax لمطابقة هذا السلوك.

سيعمل هذا المثال بشكل صحيح:

import type { Type1, Type2 } from './module.ts'
import { fn, type FnParams } from './fn.ts'

سيؤدي هذا إلى خطأ وقت التشغيل:

import { Type1, Type2 } from './module.ts'
import { fn, FnParams } from './fn.ts'

الأشكال غير المتعلقة بالملفات للإدخال

يمكن تمكين إزالة الأنواع لـ --eval. سيتم تحديد نظام الوحدات بواسطة --input-type، كما هو الحال بالنسبة لـ JavaScript.

جملة TypeScript غير مدعومة في REPL، إدخال STDIN، --print، --check، و inspect.

خرائط المصدر

بما أن الأنواع المضمنة يتم استبدالها بمسافات بيضاء، فإن خرائط المصدر غير ضرورية لأرقام الأسطر الصحيحة في تتبعات المكدس؛ ولا يقوم Node.js بإنشائها. عند تمكين --experimental-transform-types، يتم تمكين خرائط المصدر بشكل افتراضي.

إزالة الأنواع في التبعيات

لتثبيط مُلفي حزم البرامج من نشر حزم مكتوبة بلغة TypeScript، سيرفض Node.js بشكل افتراضي التعامل مع ملفات TypeScript داخل المجلدات الموجودة ضمن مسار node_modules.

أسماء المسارات البديلة

لن يتم تحويل tsconfig "paths" وبالتالي سيتسبب في حدوث خطأ. الميزة الأقرب المتاحة هي استيراد المسارات الفرعية مع القيد الذي يجب أن تبدأ بـ #.