‏Reylo: فایل SQL رو مستقیم تو TypeScript import کن، با type کامل

Reylo یه ابزار جدید از colinhacks هست که کمک می‌کنه فایل‌های .sql رو مستقیم تو کد TypeScript import کنی و typeها کامل infer بشن. ایده‌ش اینه که کوئری رو به همون SQL خود دیتابیست بنویسی، با هر تابع و syntax که پشتیبانی می‌کنه، و typeها از خود SQL دربیان. یعنی دیگه نه row type دستی لازمه و نه یه فایل schema که باید همیشه همگامش نگه داری.

Reylo یه content mapper هست؛ یعنی نوع جدیدی از پلاگین که TypeScript 7.1 برای فایل‌های غیر TypeScript آورده. هر وقت type checker به یه import از فایل .sql برسه، چه تو tsc چه تو ادیتور، فایل رو به Reylo می‌ده و typeهای ماژول رو پس می‌گیره. Reylo هم کوئری رو به دیتابیس زنده می‌فرسته تا prepare بشه، بدون اینکه اجرا بشه، و catalog رو می‌خونه. نتیجه‌ش typeهای پارامترها، typeهای ستون‌ها، nullable بودن (از NOT NULL و outer joinها) و تعداد ردیف‌های خروجی‌ه.

همین cardinality یکی از نکته‌های جالبشه: کوئری‌ای که روی یه unique key match بشه یه ردیف یا null برمی‌گردونه، aggregate بدون group by دقیقاً یه ردیف، و insert با returning همون ردیف. اگه موقع اجرا تعداد ردیف‌ها با type جور درنیاد، .run() خطا می‌ده. با JSON Schema توی check constraint یا cast پارامتر هم typeهای JSON تو در تو، bulk insert و discriminated union ساخته می‌شن و مقدار قبل از اجرا چک می‌شه.

سازنده‌ها Reylo رو مخصوص دوران agentها معرفی کردن. استدلالشون اینه که هر واقعیت فقط یه جا تعریف شده، پس یه agent نمی‌تونه type کهنه جا بذاره و type check هر callerی که جا انداخته رو پیدا می‌کنه. خطاها هم سر خط و ستون خودشون تو ادیتور و tsc نشون داده می‌شن؛ مثلاً ستون اشتباه همون خطای خود دیتابیسه. Reylo مقدارها رو خودش decode می‌کنه تا همهٔ driverها type یکسان بدن: عدد ۶۴ بیتی bigint می‌شه، decimal متن دقیقش و زمان رشتهٔ ISO 8601 به UTC، و هیچ مقداری Date نیست.

پیش‌نیازهاش رو هم باید جدی گرفت: TypeScript 7.1 که الان beta هست، Node 24 به بالا و یه دیتابیس توسعهٔ در حال اجرا. Postgres نسخهٔ ۱۴ تا ۱۸ (با Neon و PGlite)، MySQL از 8.0.22 (با PlanetScale) و SQLite (با Cloudflare D1، Turso و libSQL) پشتیبانی می‌شن. type check باید با فلگ --runExternalCode اجرا بشه و برای Node، Bun، Vite، Next.js، esbuild، webpack، Rspack و Jest پلاگین داره. driverهایی مثل pg، mysql2، better-sqlite3 و Bun.sql رو هم خودت انتخاب می‌کنی.

چند تا محدودیت هم هست: Reylo ابزار migration نداره و باید از Prisma Migrate، Drizzle Kit یا ابزار خودت استفاده کنی. بدون دیتابیس زنده هم type check و build جواب نمی‌ده، پس CI باید دیتابیس رو بالا بیاره. نتیجه‌ها تو پوشهٔ .reylo/ کش می‌شن و کلیدشون fingerprint اسکیماست. یعنی بعد از هر migration، ستون حذف‌شده هم تو فایل .sql خطا می‌ده هم تو کدی که می‌خوندش.

نکات کلیدی:

• Reylo یه content mapper برای TypeScript 7.1 (beta) هست و codegen یا watcher نداره.
• typeها رو از prepare کردن کوئری روی دیتابیس توسعهٔ زنده می‌گیره و کوئری اجرا نمی‌شه.
• Postgres ۱۴ تا ۱۸، MySQL 8.0.22 به بالا و SQLite پشتیبانی می‌شن.
• type check با tsc --noEmit --runExternalCode و Node 24 به بالا انجام می‌شه.
• عدد ۶۴ بیتی bigint و زمان رشتهٔ ISO 8601 به UTC برمی‌گرده و Date استفاده نمی‌شه.
• ابزار migration نداره و build بدون دیتابیس زنده کار نمی‌کنه.