Q.Sockets TS Client (Russian)

Production-ready WebSocket SDK для Q.Sockets. Изоморфная, типизированная и расширяемая библиотека. https://qsockets.ru/ru

https://github.com/qstart-soft/qsockets-ts-client

English Version

Особенности

• Изоморфность: Работает в Node.js, браузерах и React Native.
• Жизненный цикл соединения: Автоматический реконнект с экспоненциальной задержкой и джиттером.
• Аутентификация: Встроенная поддержка аутентификации соединения и пользователя.
• Типизированный API: Полная поддержка TypeScript с дженериками для запросов и ответов.
• Интерцепторы: Система перехватчиков (как в Axios) для запросов, ответов и ошибок.
• Очередь сообщений: Буферизация сообщений при отсутствии сети.
• Управление подписками: Автоматическое переподписание после восстановления соединения.
• Кастомные сообщения: Сопоставление по correlation_id и поддержка таймаутов.

Установка

Node.js / TypeScript / JavaScript

npm install @qstart/qsockets-client
# или
yarn add @qstart/qsockets-client
# или
pnpm add @qstart/qsockets-client

React

Библиотека не зависит от фреймворка, но её легко использовать с хуками React:

import { useEffect, useState } from 'react';
import { WsClient } from '@qstart/qsockets-client';

const client = new WsClient({
  url: 'wss://api.example.com/ws',
  connectionToken: 'your-token'
});

function App() {
  const [connected, setConnected] = useState(false);

  useEffect(() => {
    client.on('connected', () => setConnected(true));
    client.on('disconnected', () => setConnected(false));
    client.connect();
    
    return () => {
      client.disconnect();
    };
  }, []);

  return <div>Статус: {connected ? 'Подключено' : 'Отключено'}</div>;
}

Быстрый старт

import { WsClient } from '@qstart/qsockets-client';

const client = new WsClient({
  url: 'wss://api.example.com/ws',
  connectionToken: 'SECRET_TOKEN',
  reconnect: {
    enabled: true,
    retries: 5
  }
});

// 1. Подключение
await client.connect();

// 2. Аутентификация пользователя (опционально)
await client.authUser('USER_JWT');

// 3. Подписка на события
await client.subscribe('orders.updates');

client.on('message', (msg) => {
  console.log('Получено:', msg);
});

// 4. Отправка запроса (с ожиданием ответа по correlation_id)
const response = await client.request({
  type: 'get_profile',
  data: { id: '123' }
});

Справочник API

Конфигурация WsClient

const client = new WsClient({
  url: string;               // URL WebSocket сервера
  connectionToken: string;    // Секретный токен соединения
  reconnect?: {
    enabled?: boolean;       // Включить авто-реконнект (по умолчанию: true)
    retries?: number;       // Макс. попыток (по умолчанию: 10)
    baseDelay?: number;     // Базовая задержка в мс (по умолчанию: 1000)
    maxDelay?: number;      // Макс. задержка в мс (по умолчанию: 30000)
    jitter?: boolean;       // Добавлять ли случайность в задержку (по умолчанию: true)
  };
  timeout?: number;          // Таймаут запроса в мс (по умолчанию: 10000)
  debug?: boolean;           // Включить логирование (по умолчанию: false)
});

Основные методы

• await client.connect(): Установить соединение и пройти аутентификацию.
• await client.authUser(token): Авторизовать сессию пользователя.
• await client.logout(): Разлогинить пользователя.
• await client.subscribe(event): Подписаться на событие/канал.
• await client.unsubscribe(event): Отписаться от события.
• await client.request(type, payload): Отправить кастомный запрос и ждать ответа.
• client.disconnect(): Явное отключение.
• client.destroy(): Очистка всех слушателей и отключение.

События

WsClient расширяет типизированный EventEmitter. Доступные события:

• connected: Успешное подключение и аутентификация.
• disconnected: Соединение потеряно.
• reconnecting: Попытка переподключения.
• reconnected: Успешное восстановление соединения.
• message: Входящее информационное сообщение (не ответ на запрос).
• raw_message: Сырое событие сообщения WebSocket.
• error: Ошибка протокола или соединения.
• auth_success / auth_failed: Статус аутентификации соединения.
• user_auth: Статус аутентификации пользователя.
• logout: Статус выхода пользователя.
• subscribe / unsubscribe: Статус подписки/отписки.

Интерцепторы (Перехватчики)

Система перехватчиков для запросов, ответов и ошибок.

// Перехватчик запросов
client.interceptors.request.use(async (config) => {
  console.log('Отправка запроса:', config.type);
  return config;
});

// Перехватчик ответов
client.interceptors.response.use((response) => {
  console.log('Глобальный обработчик ответов:', response);
  return response;
});

// Перехватчик ошибок
client.interceptors.error.use((error) => {
  console.error('Перехваченная ошибка:', error);
  return error;
});

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

Больше примеров можно найти в директории examples:

• Базовое использование
• Интеграция с React
• Обработка ошибок и интерцепторы

Лицензия

MIT