@dieugene/ydb-serverless/README.md

Работа с YDB.

# @dieugene/ydb-serverless

[![NPM Version](https://img.shields.io/npm/v/@dieugene/ydb-serverless.svg)](https://www.npmjs.com/package/@dieugene/ydb-serverless)
[![License](https://img.shields.io/npm/l/@dieugene/ydb-serverless.svg)](https://github.com/niviron-ai/ydb-serverless/blob/main/LICENSE)

Модуль для работы с Yandex Database (YDB) в serverless режиме. Предоставляет удобный интерфейс для выполнения запросов, массовых операций и управления данными в YDB.

## Возможности

- 🔄 Выполнение SELECT запросов с возвратом результатов
- 💾 Выполнение DML операций (INSERT, UPDATE, DELETE, UPSERT)
- 📦 Массовые операции (bulk upsert)
- 🏗️ Структурированные операции через JSON
- 🔍 Получение записей по списку ID
- 📊 Автоматическое логирование запросов и потребления RU
- 🔧 Автоматическая типизация данных для YDB
- 🔄 Автоматический retry при ошибках

## Установка

```bash
npm install @dieugene/ydb-serverless
```

### Зависимости

Модуль использует следующие зависимости:
- `@yandex-cloud/nodejs-sdk`: ^2.9.0
- `ydb-sdk`: ^5.11.0

## Переменные окружения

```env
YDB_ADDRESS=et1...b5/database_name          # Адрес YDB базы данных
YDB_LOG=YDB                                  # Включить логирование (опционально)
YDB_LOG=QUERY_MONITORING_OFF                 # Отключить мониторинг запросов (опционально)
ADMIN_YDB_ADDRESS=et1...admin/admin_db       # Административная БД для логирования (опционально)
FUNCTION_NAME=my_function                    # Имя функции для логирования (опционально)
```
Переменная YDB_LOG может содержать несколько значений, разделенных любым разделителем

## Использование

### Инициализация

```javascript
const { init } = require('@dieugene/ydb-serverless');

// Инициализация с переменной окружения YDB_ADDRESS
const ydb = init();

// Или инициализация с конкретным адресом базы
const ydb = init('et1...b5/my_database');
```

### SELECT запросы

```javascript
// Простой SELECT запрос
const users = await ydb.execute(`
    SELECT id, name, email 
    FROM users 
    WHERE status = 'active'
`);

// SELECT с параметрами
const user = await ydb.execute(`
    DECLARE $user_id AS Uint64;
    SELECT * FROM users WHERE id = $user_id
`, { 
    $user_id: 123 
});
```

### DML операции

```javascript
// INSERT/UPSERT
await ydb.apply(`
    DECLARE $name AS Utf8;
    DECLARE $email AS Utf8;
    
    UPSERT INTO users (name, email, created_at)
    VALUES ($name, $email, CurrentUtcDatetime())
`, {
    $name: 'John Doe',
    $email: 'john@example.com'
});

// UPDATE
await ydb.apply(`
    DECLARE $user_id AS Uint64;
    DECLARE $status AS Utf8;
    
    UPDATE users SET status = $status 
    WHERE id = $user_id
`, {
    $user_id: 123,
    $status: 'inactive'
});
```

### Массовые операции

```javascript
// Bulk upsert для простых данных
const users = [
    { id: 1, name: 'Alice', age: 25 },
    { id: 2, name: 'Bob', age: 30 },
    { id: 3, name: 'Charlie', age: 35 }
];

await ydb.upsert('users', users);
```

### Структурированные операции

```javascript
// Upsert через JSON с описанием типов
const orders = [
    { 
        id: 1, 
        user_id: 123, 
        amount: 99.99, 
        created_at: { ydb_data_type: 'datetime', value: new Date() },
        metadata: { product: 'laptop', quantity: 1 }
    }
];

const description = {
    id: { not_null: true, type: 'Uint64' },
    amount: { type: 'Double' }
};

await ydb.upsert_struct('orders', orders, description);
```

### Получение записей по списку ID

```javascript
// Получить пользователей по списку ID
const userIds = ['user1', 'user2', 'user3'];
const users = await ydb.get_by_id_list('users', userIds, 'user_id');

// По умолчанию ищет по полю 'id'
const posts = await ydb.get_by_id_list('posts', [1, 2, 3]);
```

### Работа с датами

```javascript
// Использование специального типа для дат
const event = {
    id: 1,
    name: 'Conference',
    event_date: { 
        ydb_data_type: 'datetime', 
        value: new Date('2024-06-15T10:00:00Z') 
    }
};

await ydb.upsert_struct('events', [event]);
```

### Хелперы

```javascript
// Генерация уникального ID
const idHelper = ydb.helpers.uint64_id_definition('users');

await ydb.apply(`
    ${idHelper.declaration}
    ${idHelper.assignment}
    
    UPSERT INTO users (id, name, created_at)
    SELECT $id, $name, ${ydb.helpers.date_time}
`, {
    $name: 'New User'
});
```

## API Reference

### init(database)
Инициализирует модуль для работы с указанной базой данных.

### execute(query, params, tryAgain, make_log)
Выполняет SELECT запрос и возвращает результат.

### apply(query, params, tryAgain, make_log)
Выполняет DML запрос (INSERT, UPDATE, DELETE, UPSERT).

### upsert(table_name, values)
Выполняет массовую вставку/обновление записей.

### upsert_struct(table_name, values, description)
Выполняет UPSERT через JSON с возможностью описания типов полей.

### get_by_id_list(table_name, id_list, id_field_name)
Получает записи по списку ID.

### destroy()
Закрывает соединение с базой данных.

## Особенности

- **Автоматическая типизация**: Модуль автоматически определяет типы YDB на основе JavaScript значений
- **Retry механизм**: При ошибках выполняется повторная попытка
- **Логирование**: Автоматическое логирование запросов и потребления RU
- **Поддержка массивов**: Специальная обработка массивов с параметром `unfold_arrays`
- **JSON поддержка**: Работа со сложными объектами через JSON типы

## Примеры типов данных

```javascript
// Строки
$param: 'Hello World'

// Числа  
$param: 123

// Булевы значения
$param: true

// Даты
$param: { ydb_data_type: 'datetime', value: new Date() }

// JSON объекты
$param: { key: 'value', nested: { data: 123 } }

// Массивы (с unfold_arrays: true)
$param_list: ['item1', 'item2', 'item3']
```

## Автор

**Eugene Ditkovsky**

## Ссылки

- [GitHub Repository](https://github.com/niviron-ai/ydb-serverless)
- [NPM Package](https://www.npmjs.com/package/@dieugene/ydb-serverless)
- [Issues](https://github.com/niviron-ai/ydb-serverless/issues)

## Ключевые слова

YDB, Yandex, Cloud, Database, Serverless

## Лицензия

ISC