‏TypeScript Transformer 3 برای PHP اومد!

TypeScript Transformer 3 بعد از حدود سه سال کار، بالاخره منتشر شد. Ruben Van Assche، سازنده این پکیج، تصمیم گرفت کل کدبیس قبلی رو پاک کنه و از صفر شروع به نوشتن بکنه. دلیل اصلی این تصمیم، گسترش‌پذیری ضعیف نسخه‌های قبلی بود؛ به‌خصوص وقتی که کسی می‌خواست این پکیج رو با Laravel Data ترکیب کنه، با محدودیت‌های جدی روبرو می‌شد.

در نسخه‌های قبلی یه سیستم Collector وجود داشت که کلاس‌های واجد شرایط رو پیدا می‌کرد و بعد Transformer اون‌ها رو به TypeScript تبدیل می‌کرد. در v3 این مفهوم کلاً حذف شده؛ حالا هر کلاس از میان تمام Transformer ها رد می‌شه و اولین Transformer ای که یه شیء Transformed معتبر برگردونه، برنده‌ست. این تغییر باعث می‌شه توسعه‌دهنده‌ها راحت‌تر Transformer های سفارشی برای نیازهای خودشون بسازن.

یکی دیگه از تغییرات مهم، معرفی مفهوم TransformedProvider هست. قبلاً فقط کلاس‌ها رو می‌شد به TypeScript تبدیل کرد، ولی حالا می‌شه هر نوع قطعه TypeScript ای تولید کرد: یه تایپ، یه آبجکت، یه تابع یا هر کد اجراپذیری. مثلاً می‌شه یه تابع route helper لاراول رو در TypeScript تولید کرد، یا تایپ‌هایی مثل paginated collections رو به پروژه فرانت‌اند اضافه کرد.

یکی از بزرگ‌ترین ارتقاء‌های فنی، جایگزین کردن کتابخانه PHPDocumentor با PHPStan PHPDoc parser هست. این تغییر امکان پشتیبانی از انواع پیچیده‌تری از annotation ها رو فراهم می‌کنه. برای مثال، array shape هایی مثل زیر حالا درست پردازش می‌شن:

class CreateUserData {
    /** @var array{name: string, email: string, age?: int} */
    public array $payload;
}

که به این TypeScript تبدیل می‌شه:

{ name: string; email: string; age?: number }

یا حتی می‌شه value-of و key-of enum ها رو هم type کرد:

class Filter {
    /** @var value-of<Status> */
    public string $status;
    /** @var key-of<Status> */
    public string $statusKey;
}

در نسخه‌های قبلی، Transformer ها یه رشته خام TypeScript برمی‌گردوندن. ولی در v3 هر شیء Transformed حاوی یه نود AST هست. پکیج بیش از ۴۰ نود آماده داره که زیرمجموعه‌ای از زبان TypeScript رو نمایش می‌دن. مهم‌ترینشون TypeScriptReference هست که ارجاع به یه Transformed object دیگه رو نگه می‌داره و موقع نوشتن خروجی resolve می‌شه. قبلاً این کار با جایگزینی رشته‌های %ReferenceName% انجام می‌شد که خیلی شکننده بود.

Writer ها هم کلاً بازطراحی شدن. دو نوع Writer وجود داره: namespace writer که همه چیز رو در یه فایل TypeScript می‌نویسه، و module writer که namespace ها رو به فایل‌های جداگانه تقسیم می‌کنه. حالا یه Transformer می‌تونه خروجیش رو در چند writer مختلف ذخیره کنه، و حتی می‌شه بین symbol های نوشته‌شده در writer های مختلف ارجاع متقاطع داشت.

یکی از جذاب‌ترین ویژگی‌های جدید، حالت watch هست. در لاراول می‌شه با دستور php artisan typescript:transform --watch این حالت رو فعال کرد. این سیستم از معماری supervisor/worker استفاده می‌کنه و به‌محض تغییر فایل‌ها، TypeScript مربوطه رو به‌روز می‌کنه. چون PHP's Reflection API تغییرات فایل رو در لحظه نشون نمی‌ده، از پکیج Roave Reflection برای خواندن مستقیم فایل و parse کردن اون استفاده می‌شه.

نکات کلیدی:

• بازنویسی کامل از صفر برای بهبود گسترش‌پذیری
• حذف مفهوم Collector و سادهٔ‌سازی فرآیند تبدیل کلاس‌ها
• معرفی TransformedProvider برای تولید هر نوع کد TypeScript، نه فقط تایپ‌ها
• جایگزینی PHPDocumentor با PHPStan PHPDoc parser برای پشتیبانی از annotation های پیچیده‌تر
• سیستم AST با بیش از ۴۰ نود آماده به‌جای خروجی رشته خام
• بازطراحی Writer ها با امکان ارجاع متقاطع بین فایل‌های مختلف
• اضافه شدن حالت watch برای رصد لحظه‌ای تغییرات فایل‌ها