Генерація типів із баз даних: Drizzle ORM, Kysely та Type Providers

+-------------------------------------------------------------------------+
|             SINGLE SOURCE OF TRUTH: ТИПІЗАЦІЯ БАЗ ДАНИХ У TS            |
|              (Drizzle Schema / Database Contract Interface)             |
+-------------------------------------------------------------------------+
|                                    |                                    |
|      +-----------------------------+-----------------------------+      |
|      |                             |                             |      |
|      v                             v                             v      |
| [ DDL / Міграції ]       [ Статичні Типи ]          [ Runtime Валідація ]|
| Drizzle Kit / SQL        Select / Insert / Update   drizzle-zod /        |
| CREATE TABLE ...         InferSelectModel<T>        createInsertSchema   |
| ALTER TABLE ...          Generated<T>               Zod / TypeBox DTO    |
|                                    |                                    |
|                    +---------------+---------------+                    |
|                    |                               |                    |
|                    v                               v                    |
|          [ Type-Safe Query Builder ]   [ API Boundaries (RPC/REST) ]    |
|          Drizzle / Kysely:             tRPC, Fastify, Hono:             |
|          Повний autocomplete SQL       Гарантія валідності DTO          |
|          на рівні компілятора          без дублювання схем              |
+-------------------------------------------------------------------------+

import { pgTable, serial, varchar, text, timestamp, boolean, jsonb, integer, index } from 'drizzle-orm/pg-core';
import { InferSelectModel, InferInsertModel } from 'drizzle-orm';
import { createInsertSchema, createSelectSchema } from 'drizzle-zod';
import { z } from 'zod';

// 1. Декларація схеми таблиці (Single Source of Truth)
export const organizationsTable = pgTable('organizations', {
  id: serial('id').primaryKey(),
  name: varchar('name', { length: 256 }).notNull(),
  slug: varchar('slug', { length: 128 }).notNull().unique(),
  createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
});

export const usersTable = pgTable('users', {
  id: serial('id').primaryKey(),
  organizationId: integer('organization_id')
    .notNull()
    .references(() => organizationsTable.id, { onDelete: 'cascade' }),
  email: varchar('email', { length: 320 }).notNull().unique(),
  fullName: varchar('full_name', { length: 256 }).notNull(),
  passwordHash: text('password_hash').notNull(),
  isActive: boolean('is_active').default(true).notNull(),
  metadata: jsonb('metadata').$type<{ role: 'admin' | 'member'; permissions: string[] }>().notNull(),
  createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
  updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull(),
}, (table) => [
  index('users_org_idx').on(table.organizationId),
  index('users_email_idx').on(table.email),
]);

// 2. Статичний інференс моделей через утиліти Drizzle
// Модель Select: усі поля обов'язкові, id та createdAt виводяться як number і Date
export type UserSelect = InferSelectModel<typeof usersTable>;
// Сучасний еквівалент: typeof usersTable.$inferSelect;

// Модель Insert: поля з defaultNow() та serial стають опціональними (?):
// { email: string; fullName: string; passwordHash: string; organizationId: number; metadata: {...}; id?: number; ... }
export type UserInsert = InferInsertModel<typeof usersTable>;
// Сучасний еквівалент: typeof usersTable.$inferInsert;

// 3. Автоматична генерація схем Zod через drizzle-zod
// Базова схема для валідації вхідних даних
export const rawUserInsertSchema = createInsertSchema(usersTable);

// Кастомізація схеми для публічного API (вилучення внутрішніх полей і строга валідація)
export const apiRegisterUserSchema = createInsertSchema(usersTable, {
  email: (schema) => schema.email({ message: 'Некоректний формат корпоративної пошти' }),
  fullName: (schema) => schema.min(2).max(100),
  metadata: z.object({
    role: z.enum(['admin', 'member']),
    permissions: z.array(z.string()),
  }),
}).omit({
  id: true,
  createdAt: true,
  updatedAt: true,
  passwordHash: true, // Генерується на сервері; клієнт надсилає сирий пароль!
}).extend({
  password: z.string().min(12, 'Пароль повинен містити не менше 12 символів'),
});

export type ApiRegisterUserDTO = z.infer<typeof apiRegisterUserSchema>;

// Схема відповіді API (санітизація: ніколи не повертаємо passwordHash клієнту!)
export const apiUserResponseSchema = createSelectSchema(usersTable).omit({
  passwordHash: true,
});

export type ApiUserResponseDTO = z.infer<typeof apiUserResponseSchema>;

import { Kysely, PostgresDialect, Generated, ColumnType, Selectable, Insertable, Updateable, sql } from 'kysely';
import { Pool } from 'pg';

// 1. Паттерн ColumnType<SelectType, InsertType, UpdateType>
// Дозволяє задати окремі статичні типи для SELECT, INSERT та UPDATE операцій на одній колонці
export interface AccountsTable {
  // Generated<T> еквівалентний ColumnType<T, T | undefined, never>
  id: Generated<number>;
  
  accountNumber: string;
  
  // У PostgreSQL зберігається як numeric(18, 4).
  // Читається як string (для запобігання втрати точності IEEE 754 float); приймає string | number при записі
  balance: ColumnType<string, string | number, string | number>;
  
  currency: 'USD' | 'EUR' | 'GBP';
  
  // Метадані JSONB
  settings: ColumnType<
    { notificationsEnabled: boolean; twoFactorRequired: boolean },
    string, // Драйвер може очікувати JSON-рядок при вставці
    string  // При оновленні
  >;
  
  createdAt: ColumnType<Date, string | undefined, never>;
  updatedAt: ColumnType<Date, string | undefined, string>;
}

export interface TransactionsTable {
  id: Generated<string>; // UUID v4
  accountId: number;
  amount: ColumnType<string, string | number, never>; // Незмінність: суму завершеної транзакції не можна змінювати!
  status: 'PENDING' | 'SETTLED' | 'REJECTED';
  executedAt: ColumnType<Date, string | undefined, never>;
}

// 2. Головний інтерфейс бази даних (Контракт для Kysely)
export interface DatabaseContract {
  accounts: AccountsTable;
  transactions: TransactionsTable;
}

// Допоміжні утиліти Kysely для отримання пласких типів
export type Account = Selectable<AccountsTable>;
export type NewAccount = Insertable<AccountsTable>;
export type AccountUpdate = Updateable<AccountsTable>;

// 3. Ініціалізація клієнта Kysely
export const db = new Kysely<DatabaseContract>({
  dialect: new PostgresDialect({
    pool: new Pool({ connectionString: process.env.DATABASE_URL }),
  }),
});

// 4. Складний запит з аналітичною агрегацією та JOIN
export async function getAccountAnalytics(accountId: number) {
  // Kysely перевіряє коректність імен таблиць, колонок і умов з'єднання під час компіляції
  const result = await db
    .selectFrom('accounts')
    .innerJoin('transactions', 'transactions.accountId', 'accounts.id')
    .where('accounts.id', '=', accountId)
    .where('transactions.status', '=', 'SETTLED')
    .select([
      'accounts.id as accountId',
      'accounts.accountNumber',
      'accounts.currency',
      // Сирі вирази SQL типізуються за допомогою sql<T>`...`
      sql<number>`cast(count(transactions.id) as int)`.as('totalTransactions'),
      sql<string>`cast(coalesce(sum(cast(transactions.amount as numeric)), 0) as text)`.as('totalVolume'),
      sql<Date>`max(transactions.executed_at)`.as('lastTransactionDate'),
    ])
    .groupBy(['accounts.id', 'accounts.accountNumber', 'accounts.currency'])
    .executeTakeFirst();

  // Результуючий тип виводиться автоматично:
  // {
  //   accountId: number;
  //   accountNumber: string;
  //   currency: 'USD' | 'EUR' | 'GBP';
  //   totalTransactions: number;
  //   totalVolume: string;
  //   lastTransactionDate: Date;
  // } | undefined
  return result;
}