‏pg-typesafe؛ تایپ‌های تایپ‌اسکریپت از خود پستگرس

pg-typesafe یه ابزار متن‌بازه که برای کوئری‌های پستگرس تو پروژه‌های تایپ‌اسکریپت، تایپ تولید می‌کنه. ادعای اصلی‌ای که تو معرفی پروژه اومده اینه که این کار رو بدون هیچ وابستگی زمان اجرا و بدون ذره‌ای verbosity اضافه انجام می‌ده: کوئری دقیقاً همون شکل همیشگی pg رو داره، ولی کامل تایپ شده.

const { rows } = client.query(
  "select id, name, last_modified from tbl where id = $1",
  [42],
);

تو این مثال، پارامتر اجباریه و باید عدد باشه، و rows خودش تایپ { id: number; name: string; last_modified: Date }[] می‌گیره. راه‌اندازیش هم سه قدمه: پکیج رو به‌عنوان dev dependency نصب می‌کنی، یه بار با connection string اجراش می‌کنی تا فایل src/defs.gen.ts ساخته بشه، و بعد Pool خودت رو به تایپ TypesafePool کست می‌کنی. همین کست باعث می‌شه ابزار دفعهٔ بعد کوئری‌ها رو پیدا و تایپ کنه.

محدودیت اصلی که خود پروژه بهش اشاره می‌کنه اینه که فقط کوئری‌هایی تایپ می‌شن که رشتهٔ SQLشون ثابت باشه؛ کوئری داینامیک قابل تحلیل نیست. البته به گفتهٔ نویسنده این خودش عادت خوبیه، چون کوئری ثابت هم جلوی SQL injection رو می‌گیره و هم سریع‌تره. برای حالت‌های خاص هم یه فایل کانفیگ داری: مثلاً با transformField و transformParameter می‌تونی BIGINT رو به‌جای رشته به bigint جاوااسکریپتی مپ کنی، یا ستون‌های JSONB رو بر اساس نام جدول و ستون به تایپ‌های دقیق خودشون وصل کنی.

پروژه خودش رو در برابر گزینه‌های موجود هم موقعیت‌یابی می‌کنه: pgtyped کوئری تو فایل‌های .ts و .sql رو پشتیبانی می‌کنه ولی هلپرهای خودش رو می‌آره و پرگوتره، kysely یه کوئری‌بیلدر تایپ‌سیفه، و Zapatos کوئری‌های شبیه SQL با میان‌برهای CRUD می‌ده. جای pg-typesafe دقیقاً همون‌جاییه که نمی‌خوای از pg خام فاصله بگیری.

نکات کلیدی:

• تولید تایپ تایپ‌اسکریپت برای کوئری‌های پستگرس، بدون وابستگی زمان اجرا
• کوئری‌ها همون فرم معمولی pg رو نگه می‌دارن؛ فقط Pool به TypesafePool کست می‌شه
• هم پارامترها و هم تایپ ردیف‌های خروجی چک می‌شن
• فقط کوئری‌های با SQL ثابت پشتیبانی می‌شن؛ کوئری داینامیک تحلیل نمی‌شه
• کانفیگ اختیاری برای مپ‌کردن BIGINT به bigint و تایپ‌دادن به ستون‌های JSONB