ts-morph لـ TypeScript: دليل شامل مع أمثلة عملية

مقدمة عن ts-morph: ما هي ولماذا تحتاجها

ts-morph هي مكتبة قوية للعمل البرمجي مع شجرة التركيب المجرد (AST) الخاصة بـ TypeScript. توفر واجهة برمجة تطبيقات (API) سهلة وبديهية لتحليل وتعديل وإنشاء كود TypeScript. على عكس استخدام مترجم TypeScript مباشرة (TypeScript Compiler API)، تقدم ts-morph واجهة عالية المستوى تبسط العديد من المهام الروتينية بشكل كبير.

لماذا تحتاج هذه المكتبة؟ تخيل أنك بحاجة إلى:

• إعادة هيكلة الكود: إعادة تسمية جميع استخدامات دالة تلقائياً، تغيير توقيع دالة، أو نقل كلاس إلى ملف آخر.
• التحليل الثابت: العثور على جميع المتغيرات غير المستخدمة، التحقق من الالتزام بقواعد الترميز المؤسسية، أو جمع بيانات وصفية عن هيكل المشروع.
• توليد الكود: إنشاء أنواع بناءً على مخطط JSON، توليد عمليات CRUD لقاعدة بيانات، أو إضافة توثيق تلقائياً.
• إنشاء أدوات المطورين: كتابة إضافة لـ linter، مولد توثيق مخصص، أو أداة لترحيل الكود.

تعمل ts-morph على تجريد تعقيد TypeScript Compiler API، وتوفر نهجاً كائني التوجه. أنت تتعامل مع المشاريع والملفات والكلاسات والدوال والعناصر الأخرى ككائنات عادية، وليس كعقد منخفضة المستوى في AST.

تثبيت ts-morph

يتم تثبيت المكتبة عبر npm أو yarn. وهي متاحة كحزمة لـ Node.js.

npm install ts-morph

أو، إذا كنت تستخدم yarn:

yarn add ts-morph

بعد التثبيت، يمكنك استيراد المكتبة في مشروعك:

import { Project } from 'ts-morph';

لكي تعمل ts-morph، تحتاج إلى TypeScript (وهو مدرج كـ peer dependency). تأكد من تثبيت TypeScript في مشروعك:

npm install typescript

بداية سريعة مع مثال كود

لنكتب سكريبت بسيط يقوم بإنشاء ملف TypeScript جديد، وإضافة دالة إليه، ثم طباعة الكود المُنشأ.

import { Project, SyntaxKind } from 'ts-morph';

// إنشاء مشروع جديد
const project = new Project({
    useInMemoryFileSystem: true, // العمل في الذاكرة دون حفظ على القرص
});

// إنشاء ملف جديد
const sourceFile = project.createSourceFile('example.ts', '');

// إضافة دالة
const functionDeclaration = sourceFile.addFunction({
    name: 'greet',
    parameters: [{ name: 'name', type: 'string' }],
    returnType: 'string',
    statements: [
        `return \`Hello, \${name}!\`;`,
    ],
});

// إضافة تعليق JSDoc
functionDeclaration.addJsDoc({
    description: 'ترحيب بالمستخدم',
    tags: [{ tagName: 'param', text: 'name - اسم المستخدم' }],
});

// طباعة الكود المُنشأ
console.log(sourceFile.getText());

نتيجة تشغيل السكريبت:

/**
 * ترحيب بالمستخدم
 * @param name - اسم المستخدم
 */
function greet(name: string): string {
    return `Hello, ${name}!`;
}

كما ترى، قمنا برمجياً بإنشاء دالة كاملة مع توثيق JSDoc. هذا مجرد جزء صغير من إمكانيات ts-morph.

أهم الدوال والوظائف في ts-morph

دعنا نستعرض 10 دوال رئيسية في المكتبة مع شرح وأمثلة مفصلة.

1. Project.createSourceFile()

الوظيفة: إنشاء ملف مصدر TypeScript جديد في المشروع. يمكن أن يكون الملف فارغاً أو يحتوي على كود ابتدائي.

المعاملات:

• filePath: string — مسار الملف (نسبة إلى جذر المشروع).
• sourceText?: string — المحتوى الابتدائي للملف (اختياري).
• overwrite?: boolean — هل يتم استبدال الملف الموجود (القيمة الافتراضية false).