Генерация типов из баз данных: 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, relations } 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. Автоматическая генерация Runtime Zod-схем через drizzle-zod
// Базовая схема для валидации входящих данных при регистрации
export const rawUserInsertSchema = createInsertSchema(usersTable);

// Кастомизация схемы для публичного API (исключение служебных полей и строгая валидация)
export const apiRegisterUserSchema = createInsertSchema(usersTable, {
  // Переопределение валидации email строгим парсером Zod
  email: (schema) => schema.email({ message: 'Некорректный формат корпоративного email' }),
  fullName: (schema) => schema.min(2).max(100),
  // Валидация JSONB структуры
  metadata: z.object({
    role: z.enum(['admin', 'member']),
    permissions: z.array(z.string()),
  }),
}).omit({
  // Исключаем поля, которые не должны приниматься от внешнего клиента
  id: true,
  createdAt: true,
  updatedAt: true,
  passwordHash: true, // Хэш генерируется на сервере, клиент присылает raw password!
}).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>
// Позволяет задать разные типы для чтения, вставки и обновления колонки
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, при обновлении 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 строго проверяет наличие таблиц 'accounts' и 'transactions',
  // а также корректность условий соединения 'accounts.id' = 'transactions.accountId'
  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;
}