npm package: @karkardmitry/kadmium-core
Description: A powerful, schema-driven backend framework for TypeScript, designed for high type-safety and developer productivity.
Author: Dmitry Karmanov
Latest version: 0.1.0

# Kadmium Framework: From Schema to SQL

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

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

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

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

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

```typescript
// 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]`
*   **Результат:**
    ```typescript
    // 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`)**
```typescript
// ... импорты Schema, KadmiumRepo, Users ...
export const userSchema = schema({ ... });

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

**2. Запуск приложения (`app.ts`)**
```typescript
// ... импорты AppCore, KadmiumRepo, Users ...
const app = AppCore.getInstance();
app.configure({ schemaSources: ["./src/example-schemas/**/*.ts"] });

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

**3. Использование в коде**
```typescript
// Получаем репозиторий через статический метод
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-инструмент для генерации типобезопасных клиентов для межсервисного взаимодействия.