پشتیبانی از TypeScript در Node.js

1. فعال‌سازی پشتیبانی TypeScript

• پشتیبانی کامل: با نصب بسته‌های شخص ثالث مانند tsx می‌توان تمام ویژگی‌های TypeScript را اجرا کرد.
• حذف نوع‌ها (type stripping): Node.js به‌طور داخلی نوع‌ها را حذف می‌کند و کد را بدون بررسی اجرا می‌کند.

// نصب tsx
npm install --save-dev tsx

// اجرای فایل TypeScript
npx tsx your-file.ts

2. Type Stripping

در این حالت، Node.js تنها نوع‌های قابل حذف را پاک می‌کند و هیچ تبدیل پیچیده‌ای انجام نمی‌دهد. برای ویژگی‌هایی مانند enum یا parameter properties باید فلگ --experimental-transform-types فعال شود.

// تنظیمات پیشنهادی tsconfig.json
{
  "compilerOptions": {
    "noEmit": true,
    "target": "esnext",
    "module": "nodenext",
    "rewriteRelativeImportExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true
  }
}

3. تعیین سیستم ماژول

• .ts: مانند فایل‌های .js بسته به فیلد type در package.json.
• .mts: همیشه ES Module.
• .cts: همیشه CommonJS.
• .tsx: پشتیبانی نمی‌شود.

پسوند فایل‌ها در import و require الزامی است.

4. ویژگی‌های TypeScript

• ویژگی‌هایی مانند enum، namespace با کد اجرایی و parameter properties نیاز به تبدیل دارند.
• ویژگی‌هایی مانند namespace فقط برای type پشتیبانی می‌شوند.
• Decorators پشتیبانی نمی‌شوند و خطا ایجاد می‌کنند.

5. Importing Types

برای جلوگیری از خطا باید از کلیدواژه type استفاده شود:

// صحیح
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';

6. ورودی‌های غیر فایل

Type stripping برای --eval و STDIN فعال می‌شود. اما در REPL یا inspect پشتیبانی نمی‌شود.

7. Source Maps

در حالت حذف نوع‌ها، نیازی به source map نیست. اما اگر --experimental-transform-types فعال شود، source map به‌طور پیش‌فرض فعال می‌شود.

8. محدودیت‌ها

• Node.js فایل‌های TypeScript داخل node_modules را اجرا نمی‌کند.
• تنظیمات tsconfig مانند paths پشتیبانی نمی‌شوند.
• بهترین جایگزین برای paths استفاده از subpath imports با پیشوند # است.

نتیجه‌گیری

پشتیبانی از TypeScript در Node.js به دو شکل ارائه می‌شود: استفاده از ابزارهای شخص ثالث برای پشتیبانی کامل، یا استفاده از قابلیت داخلی حذف نوع‌ها برای اجرای سریع و سبک. انتخاب بین این دو بستگی به نیاز پروژه دارد؛ برای توسعه و تست می‌توان از type stripping استفاده کرد، اما برای پروژه‌های بزرگ و پیچیده بهتر است از ابزارهای کامل مانند tsx بهره برد.