@dieugene/queuer/README.md

Node.js library for seamless integration with message queues through Yandex Cloud Functions

# Queuer

Node.js библиотека для работы с очередями сообщений через Yandex Cloud Functions.

## Описание

Queuer предоставляет простой и удобный интерфейс для отправки сообщений в очереди через Yandex Cloud Functions. Особенно полезна для работы с Telegram ботами и системами обработки сообщений.

## Установка

```bash
npm install @dieugene/queuer
```

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

```javascript
const queuer = require('@dieugene/queuer')();

// Или с указанием ID функции Yandex Cloud
const queuer = require('@dieugene/queuer')('your-yandex-cloud-function-id');
```

По умолчанию используется ID функции из переменной окружения `QUEUER_FUNCTION_ID` или значение по умолчанию.

## API

### `queuer.post(domain, body, queue_url)`

Отправляет сообщение в очередь.

**Параметры:**
- `domain` (string) - домен для категоризации сообщений
- `body` (object) - данные для отправки
- `queue_url` (string, optional) - URL очереди

**Пример:**
```javascript
await queuer.post('telegram-bot', {
    chat_id: 123456789,
    text: 'Привет, мир!'
});
```

### `queuer.post.item(item)`

Отправляет произвольный элемент в очередь.

**Параметры:**
- `item` (object|string) - элемент для отправки

**Пример:**
```javascript
await queuer.post.item({
    domain: 'notifications',
    user_id: 123,
    message: 'Новое уведомление'
});
```

### `queuer.send_to_queue(input, bot_token, queue_url, domain)`

Отправляет данные от бота в очередь.

**Параметры:**
- `input` - входные данные
- `bot_token` (string) - токен бота
- `queue_url` (string) - URL очереди
- `domain` (string) - домен

**Пример:**
```javascript
await queuer.send_to_queue(
    webhookData,
    'YOUR_BOT_TOKEN',
    'https://your-queue-url.com',
    'telegram-bot'
);
```

### `queuer.is_from_queue(input)`

Проверяет, пришли ли данные из очереди.

**Параметры:**
- `input` - входные данные для проверки

**Возвращает:** `boolean`

**Пример:**
```javascript
if (queuer.is_from_queue(webhookData)) {
    console.log('Данные пришли из очереди');
}
```

### `queuer.ensureQueueItem(input, value, field)`

Проверяет корректность элементов очереди и перенаправляет неправильные.

**Параметры:**
- `input` - входные данные
- `value` - ожидаемое значение
- `field` (string, optional) - поле для проверки ('queue_url' по умолчанию)

**Возвращает:** `boolean` - true если все элементы корректны

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

- `QUEUER_FUNCTION_ID` - ID функции Yandex Cloud (по умолчанию)
- `LOG` - включает логирование, если содержит 'QUEUER'

## Примеры использования

### Telegram бот с очередями

```javascript
const queuer = require('@dieugene/queuer')();

// Обработка входящего сообщения
async function handleMessage(update) {
    if (queuer.is_from_queue(update)) {
        // Обработка сообщения из очереди
        console.log('Обрабатываем сообщение из очереди');
        return;
    }
    
    // Отправка в очередь для обработки
    await queuer.send_to_queue(
        update,
        process.env.BOT_TOKEN,
        process.env.QUEUE_URL,
        'telegram-bot'
    );
}
```

### Отправка уведомлений

```javascript
const queuer = require('@dieugene/queuer')();

async function sendNotification(userId, message) {
    await queuer.post('notifications', {
        user_id: userId,
        message: message,
        timestamp: Date.now()
    });
}
```

## Логирование

Для включения логирования установите переменную окружения:

```bash
export LOG=QUEUER
```

Или в Node.js:
```javascript
process.env.LOG = 'QUEUER';
```

## Лицензия

ISC

## Автор

Eugene Ditkovsky

## Поддержка

Если у вас есть вопросы или предложения, создайте [issue](https://github.com/Dieugene/queuer/issues) в репозитории проекта.