‏Kanel: تبدیل خودکار اسکیمای PostgreSQL به TypeScript

Kanel یه ابزار code generation هست که به یه دیتابیس PostgreSQL زنده وصل می‌شه و از روی اسکیمای اون، خروجی‌های مختلف تولید می‌کنه. رایج‌ترین کاربردش اینه که تایپ‌های TypeScript می‌سازه — به صورت خودکار و دقیق، بر اساس جدول‌ها و ستون‌های دیتابیس.

ایده اصلی اینه که دیتابیس منبع حقیقت باشه، نه کد. یعنی به جای اینکه اول تایپ‌های TypeScript بنویسی و بعد امیدوار باشی با دیتابیس هماهنگ بمونن، Kanel مستقیم از ساختار دیتابیس می‌خونه و تایپ‌ها رو می‌سازه. اگه اسکیمای دیتابیس عوض بشه، کافیه دوباره Kanel رو اجرا کنی.

برای هر جدول، Kanel سه interface جداگانه می‌سازه: یکی برای خواندن داده (City)، یکی برای ایجاد رکورد جدید (CityInitializer) که فیلدهای دارای مقدار پیش‌فرض اختیاری هستن، و یکی برای ویرایش (CityMutator) که همه فیلدها اختیاری‌ان. همچنین ID‌ها به صورت branded type تعریف می‌شن تا اشتباه گرفتن آن‌ها با هم ممکن نباشه.

export interface City {
  city_id: CityId;
  city: string;
  country_id: CountryId;
  last_update: Date;
}

معماری Kanel v4 بر پایه یه سیستم generator پلاگین‌پذیر ساخته شده. PgTsGenerator برای تایپ‌های TypeScript، MarkdownGenerator برای مستندات، و امکان نوشتن generator سفارشی برای هر زبان یا فرمت دیگه‌ای وجود داره. از طریق hook هم می‌شه یکپارچه‌سازی‌هایی مثل Kysely (یه query builder تایپ‌سیف) یا Zod (برای اعتبارسنجی داده) رو فعال کرد.

module.exports = {
  connection: /* ... */,
  generators: [
    makePgTsGenerator({ preRenderHooks: [makeKyselyHook()] }),
    makeMarkdownGenerator(),
  ],
};

کد تولیدشده قرار نیست موقتی باشه — توصیه می‌شه اون رو در git کامیت کنی و به عنوان بخشی از کدبیس پروژه باهاش رفتار کنی. این رویکرد هم تغییرات اسکیما رو قابل ردیابی می‌کنه و هم با ابزارهای review استاندارد سازگاره.

نکات کلیدی:

• Kanel مستقیم از اسکیمای PostgreSQL تایپ‌های TypeScript می‌سازه
• برای هر جدول سه interface (خواندن، ایجاد، ویرایش) تولید می‌کنه
• ID‌ها به صورت branded type ساخته می‌شن تا type safety بیشتری داشته باشی
• از Zod، Kysely و Knex از طریق hook پشتیبانی می‌کنه
• می‌شه generator سفارشی برای Python، Rust، GraphQL و غیره نوشت
• کد تولیدشده رو می‌شه مستقیم توی git نگه داشت