AzLearn

TypeScript مع Node

TypeScript with Node

مفهوم ~16 دقيقة

TypeScript مع Node — TypeScript with Node

Node يشغل JavaScript، لا TypeScript الخام في الوضع التقليدي. لذلك تكتب .ts، تفحص وتبني، ثم يعمل الناتج .js. بعض الأدوات تشغّل TypeScript مباشرة أثناء التطوير، لكن الفكرة الأساسية تبقى: runtime مختلف عن type checker.

في مشاريع Node، TypeScript مفيدة جداً لأنها تصف config، أوامر CLI، استجابات API، وملفات JSON. لكنها لا تجعل process.env مضموناً. متغيرات البيئة نصوص أو undefined، ويجب التحقق منها.

مثال إعداد

index.ts

هذا يمثل config بعد التحقق. لا تفترض أن القيم القادمة من البيئة صحيحة قبل تحويلها.

ESM أم CommonJS؟

Node يدعم نظامَي وحدات: CommonJS (القديم، require("fs")) وESM (الحديث، import { readFileSync } from "node:fs"). TypeScript يدعم كليهما، لكن ESM هو الاتجاه الحالي ويجب اختياره في المشاريع الجديدة.

لتفعيل ESM في مشروع TypeScript:

// package.json
{ "type": "module" }

// tsconfig.json
{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

مع ESM تكتب import { readFileSync } from "node:fs" بدلاً من require. ملاحظة: node: prefix (مثل "node:fs") يوضح صراحةً أن الاستيراد من Node وليس من npm، وهو الأسلوب الموصى به في Node ≥ 18.

تمارين هذا الفصل تستخدم ESM. إذا واجهت كودًا قديماً بـrequire، فهو CommonJS — مزيج الأسلوبين في نفس المشروع يسبب أخطاء.

قراءة config من process.env

في Node الحقيقي، config يأتي من process.env. متغيرات البيئة string | undefined دائماً — حتى الأرقام. يجب التحقق والتحويل عند الحد:

function loadConfig(): AppConfig {
  const portStr = process.env.PORT;
  const port = portStr ? Number(portStr) : 3000;

  if (!Number.isInteger(port) || port <= 0) {
    throw new Error(`Invalid PORT: ${portStr}`);
  }

  const env = process.env.NODE_ENV;
  if (env !== "development" && env !== "production") {
    throw new Error(`Invalid NODE_ENV: ${String(env)}`);
  }

  return { port, env };
}

تحقق مرة واحدة عند البدء، ثم مرر config typed لبقية التطبيق. لا تقرأ process.env.PORT في كل مكان.

runtime boundaries

كل ما يأتي من خارج الكود typed يحتاج فحصاً: env، files، network، CLI args.

تحدي — Challenge