Kadmium Framework: From Schema to SQL

Kadmium - это современный, декларативный и типобезопасный TypeScript-фреймворк для создания data-driven приложений.

Основная философия: схема данных является единственным источником правды. Вы описываете данные один раз, а фреймворк использует эту информацию для автоматической генерации типов, валидации, построения SQL-запросов и, в будущем, для маршрутизации.

Архитектура и компоненты

Kadmium состоит из нескольких взаимосвязанных, но независимых модулей, каждый из которых выполняет свою задачу.

1. Schema: Декларативное ядро

Все начинается здесь. С помощью простых функций (schema, string, email, password) вы описываете вашу модель данных, ее поля, типы и метаданные для БД.

// src/example-schemas/user.schema.ts
export const userSchema = schema({
    collection: "users",
    primary: primary({ name: "id", db_type: "uuid" }),
    form: form({
        fields: [
            string({ name: "first_name", required: true }),
            email({ name: "email", required: true, db: { unique: true } }),
        ],
    }),
});

2. CLI / generate-types: Кодогенератор

Этот инструмент читает ваши файлы .schema.ts и генерирует на их основе TypeScript-классы.

npm run kadmium:generate:schema

• Что делает: [Schema Definition] -> [Generator] -> [TypeScript Class]
• Результат:

  // src/cli/generated/schemas/Users.ts
  export class Users implements __generated_schema__ {
      id!: string;
      first_name!: string;
      email!: string;
  }

Эти классы используются во всей системе для обеспечения строгой типизации.

3. Validation: Автоматическая валидация

Метаданные из схемы (например, required: true, min: 8 у пароля) автоматически используются для создания правил валидации. Благодаря адаптеру (ValidationAdapter), вы можете легко подменить библиотеку валидации (по умолчанию используется Zod), не меняя код приложения или ядра.

4. Repo и Sqb: Слой доступа к данным

Это самый мощный компонент системы.

• KadmiumRepo: Ваш основной инструмент для работы с данными. Он предоставляет типобезопасный "Verb-first" Fluent API.
• Sqb (Schema Query Builder): Внутренний механизм, который преобразует вызовы .select(), .where() и т.д. в абстрактное синтаксическое дерево (AST) запроса.
• DbAdapter: Финальное звено, которое берет AST от Sqb и генерирует на его основе SQL-код для конкретной СУБД (например, PostgreSQL).

Жизненный цикл запроса: repo.select(...).where(...) -> Sqb (AST) -> DbAdapter -> SQL Query

5. Core (AppCore и SchemaCore)

• AppCore: Легковесный Singleton для хранения глобальной конфигурации (настройки БД, адаптеры).
• SchemaCore: "Живое" представление вашей схемы в памяти приложения, содержащее нормализованные данные и реестры для быстрого доступа.

Ключевые возможности

• Fluent API: Интуитивно понятный "Verb-first" API (repo.create().go()).
• Статические транзакции: Децентрализованный и типобезопасный API (KadmiumRepo.transaction(async (trx) => ...)), который предотвращает случайное использование нетранзакционных репозиториев.
• Автоматическая безопасность: Встроенное хэширование паролей и фильтрация "чувствительных" полей.
• Адаптеры: Возможность легко заменить библиотеку для валидации или СУБД.
• Кодогенерация: Гарантия того, что типы в коде всегда соответствуют схеме.

Пример полного цикла

1. Определение и регистрация схемы (user.schema.ts)

// ... импорты Schema, KadmiumRepo, Users ...
export const userSchema = schema({ ... });

// Инициализация ядра схемы
const core = Schema.from(userSchema).core.init();
// Регистрация в системе репозиториев
KadmiumRepo.register(Users, core);

2. Запуск приложения (app.ts)

// ... импорты AppCore, KadmiumRepo, Users ...
const app = AppCore.getInstance();
app.configure({ schemaSources: ["./src/example-schemas/**/*.ts"] });

// app.start() импортирует все схемы, запуская их само-регистрацию
await app.start(); 

3. Использование в коде

// Получаем репозиторий через статический метод
const userRepo = KadmiumRepo.get(Users);

// Создаем пользователя
await userRepo.create({ name: 'John', ... }).go();

// Выполняем транзакцию с несколькими репозиториями
await KadmiumRepo.transaction(async (trx) => {
    const trxUserRepo = trx.get(Users);
    const trxPostRepo = trx.get(Posts);

    const user = await trxUserRepo.create({ ... }).go();
    await trxPostRepo.create({ userId: user.id, ... }).go();
});

Планы на будущее

Текущая архитектура закладывает фундамент для следующих модулей:

• Route: Декларативный слой для создания роутов, который будет использовать схемы для автоматической валидации входящих данных.
• cli/cluster-sync: CLI-инструмент для генерации типобезопасных клиентов для межсервисного взаимодействия.