‏TypeScript 7 و پایان پلاگین‌های tsserver برای gql.tada

GraphQLSP یه پلاگین tsserver هست که داخل graphql()ها تکمیل خودکار، hover و گزارش خطا می‌ده. مشکل اینه که TypeScript 7، یعنی نسخه‌ای که با Go بازنویسی شده و خیلی‌ها هنوز بهش tsgo می‌گن، اصلاً پلاگین‌های tsserver رو لود نمی‌کنه. نویسنده می‌گه تایپ‌های gql.tada کار می‌کنن چون خودشون TypeScript‌ان، ولی همه‌ی خطاهای GraphQL مثل غلط تایپی اسم فیلد یا فیلد deprecated بی‌صدا از ادیتور غیب می‌شن.

TypeScript 7.1 دو تا ابزار جدید داده: content mapper و یه API برنامه‌نویسی که با کامپایلرِ در حال اجرا حرف می‌زنه. content mapper یه پروسه‌ی جداست که TypeScript اجراش می‌کنه و از طریق JSON-RPC باهاش حرف می‌زنه. توی tsconfig.json برای یک یا چند پسوند ثبتش می‌کنی:

{
  "contentMappers": [
    {
      "package": "typed-css-modules-mapper",
      "extensions": [".module.css"]
    }
  ]
}

TypeScript محتوای فایل رو با یه درخواست transform برای mapper می‌فرسته و mapper متن TypeScript، یه نقشه از بازه‌ها به فایل اصلی و خطاهای احتمالی رو برمی‌گردونه. دو تا قانون مهم هست: mapper نمی‌تونه پسوندهای خود TypeScript مثل .ts، .tsx یا .json رو بگیره، و چون کد خارجی‌ه فقط با tsc --runExternalCode یا اعتماد به workspace توی ادیتور اجرا می‌شه. یعنی mapper هیچ‌وقت graphql() داخل یه فایل .ts رو نمی‌بینه.

نویسنده اول روی CSS module امتحانش کرده. typed-css-modules-mapper کلاس‌ها رو مستقیم از فایل CSS می‌خونه، پس دیگه نه declare module کلی لازمه، نه فایل .d.ts که با تغییر CSS قدیمی بشه. اگه کلاسی وجود نداشته باشه tsc خطا می‌ده و توی VS Code رفتن به تعریف، hover و تکمیل خودکار کلاس‌ها کار می‌کنه. به گفته‌ی نویسنده، بیشتر زحمت کار هماهنگ کردن رفتار با bundlerها بوده.

برای GraphQL، mapper روی فایل‌های .graphql کار می‌کنه. هر فایل به همون graphql()ی تبدیل می‌شه که قبلاً دستی می‌نوشتی، پس تایپ‌ها، FragmentOf و readFragment مثل قبل کار می‌کنن. کامنت # import هم به یه import واقعی تبدیل می‌شه و fragmentها از مسیر module resolution عادی ترکیب می‌شن. mapper اسکیما رو هم لود می‌کنه و فیلدهای ناشناخته، متغیرهای اشتباه و خطاهای سینتکسی رو هم توی tsc و هم توی ادیتور نشون می‌ده.

نویسنده نتیجه می‌گیره که content mapperها جای خیلی از کارهای GraphQLSP رو خوب پر می‌کنن. ولی documentهایی که inline داخل فایل‌های .ts نوشته شدن هنوز یه checker جدا لازم دارن که به گفته‌ی خودش API نسخه‌ی 7.1 برای ساختنش کافیه. این کار توی چند PR روی gql.tada و GraphQLSP در جریانه و mapper مربوط به CSS هم روی npm منتشر شده.

نکات کلیدی:

• TypeScript 7 (نسخه‌ی Go) پلاگین‌های tsserver رو لود نمی‌کنه
• TypeScript 7.1 قابلیت content mapper رو با پروتکل JSON-RPC اضافه کرده
• mapper نمی‌تونه پسوندهای .ts، .tsx و .json رو بگیره
• اجرای mapperها نیاز به tsc --runExternalCode یا workspace trust داره
• gql.tada حالا فایل‌های .graphql رو با اعتبارسنجی اسکیما پشتیبانی می‌کنه
• documentهای inline هنوز به یه checker جدا روی API نسخه‌ی 7.1 نیاز دارن