@crypto-oracle/core

Базовый модуль ядра для системы Crypto Oracle, предоставляющий общую функциональность для всех компонентов.

Описание

@crypto-oracle/core представляет собой фундаментальный модуль, который содержит общие компоненты, утилиты и типы данных, используемые всеми другими модулями системы. Он является основой архитектуры приложения и обеспечивает единообразие кода во всем проекте.

Важно: Core является независимым модулем, управляемым отдельно от других компонентов системы. Он не входит в управление Lerna и имеет собственный жизненный цикл версионирования.

Текущая версия: 1.0.8

Установка

npm install @crypto-oracle/core

Структура модуля

core/
├── src/
│   ├── index.ts         # Главный экспорт модуля
│   ├── types/           # TypeScript типы и интерфейсы
│   │   ├── alert-types.ts     # Типы системы оповещений
│   │   ├── analytic-types.ts  # Типы аналитических данных
│   │   ├── indicator-types.ts # Типы индикаторов
│   │   ├── market-data-types.ts # Типы рыночных данных
│   │   └── prediction-types.ts # Типы предсказаний
│   ├── enums/           # Перечисления (enums)
│   │   ├── alert-enums.ts     # Перечисления оповещений
│   │   ├── market-enums.ts    # Перечисления рыночных данных
│   │   └── model-enums.ts     # Перечисления моделей
│   ├── utils/           # Утилитарные функции
│   │   ├── common.ts          # Общие утилиты
│   │   ├── date-utils.ts      # Утилиты для работы с датами
│   │   ├── formatting.ts      # Форматирование данных
│   │   ├── number-utils.ts    # Работа с числами
│   │   └── validation.ts      # Валидация данных
│   ├── tools/           # Инструменты
│   │   └── logger.ts          # Система логирования
│   ├── config.ts        # Конфигурационные настройки
│   └── constants.ts     # Константы

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

Модуль доступен как npm-пакет @crypto-oracle/core и может использоваться несколькими способами:

1. Импорт всего модуля

import { 
  createLogger, 
  CONFIG_DEFAULTS, 
  AlertType, 
  formatDate 
} from '@crypto-oracle/core';

2. Импорт из конкретных подмодулей (рекомендуется)

// Импорт типов
import { AlertType, IndicatorType } from '@crypto-oracle/core/types';

// Импорт утилит
import { formatDate, addDays } from '@crypto-oracle/core/utils';

// Импорт перечислений
import { AlertSeverity, TimeseriesResolution } from '@crypto-oracle/core/enums';

// Импорт конфигураций
import { CONFIG_DEFAULTS } from '@crypto-oracle/core/config';

// Импорт логгера
import { createLogger } from '@crypto-oracle/core/tools/logger';

// Импорт утилит для работы с переменными окружения
import { getEnvVar, getEnvNumber, getEnvBool } from '@crypto-oracle/core/utils/env';

Основные компоненты

Логирование

Модуль предоставляет унифицированную систему логирования на основе Pino:

import { createLogger } from '@crypto-oracle/core';

const logger = createLogger('ComponentName');
logger.info('Сообщение', { context: 'дополнительные данные' });
logger.error('Произошла ошибка', error);

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

Централизованная система конфигурации с настройками по умолчанию:

import { CONFIG_DEFAULTS } from '@crypto-oracle/core';

const defaultThrottleLimit = CONFIG_DEFAULTS.THROTTLE_LIMIT;

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

Модуль предоставляет унифицированный способ работы с переменными окружения:

import { 
  getEnvVar, 
  getEnvNumber, 
  getEnvBool, 
  getEnvArray,
  getEnvJson,
  hasEnvVar
} from '@crypto-oracle/core';

// Получение строкового значения (с проверкой на обязательность)
const apiUrl = getEnvVar('API_URL'); // Бросит ошибку, если переменная не установлена
const apiKey = getEnvVar('API_KEY', 'default-key'); // Использует значение по умолчанию

// Получение числового значения
const port = getEnvNumber('PORT', 3000);

// Получение булева значения
const isProduction = getEnvBool('PRODUCTION', false);

// Получение массива строк (разделенных запятыми)
const allowedHosts = getEnvArray('ALLOWED_HOSTS', ['localhost']);

// Получение JSON объекта
const config = getEnvJson('APP_CONFIG', { debug: false });

// Проверка наличия переменной
if (hasEnvVar('DATABASE_URL')) {
  // Переменная существует
}

Типы данных

Модуль предоставляет общие типы для всей системы:

import { 
  AlertType, 
  AlertSeverity,
  IndicatorType,
  MarketData,
  TokenData
} from '@crypto-oracle/core';

const alert: AlertType = {
  id: '123',
  title: 'Резкое изменение цены',
  message: 'Обнаружено резкое изменение цены BTC',
  severity: 'high',
  timestamp: new Date(),
  source: 'price-monitor'
};

Утилитарные функции

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

import { formatDate, addDays, differenceInDays } from '@crypto-oracle/core';

const date = new Date();
const formattedDate = formatDate(date); // ISO строка
const nextWeek = addDays(date, 7);
const daysBetween = differenceInDays(nextWeek, date); // 7

Работа с объектами

import { getNestedProperty } from '@crypto-oracle/core';

const data = { user: { profile: { name: 'John' } } };
const name = getNestedProperty(data, 'user.profile.name'); // 'John'
const missing = getNestedProperty(data, 'user.settings.theme', 'default'); // 'default'

Работа со строками

import { capitalize, capitalizeFirstLetter } from '@crypto-oracle/core';

const text1 = capitalize('hello'); // 'Hello'
const text2 = capitalizeFirstLetter('world'); // 'World'

Работа с числами

import { round, formatNumber, formatCurrency } from '@crypto-oracle/core';

const rounded = round(123.456, 1); // 123.5
const formatted = formatNumber(1000000); // "1 000 000"
const currency = formatCurrency(1234.56); // "$1,234.56"

Валидация данных

import { isValidEmail, isValidUrl, isEmpty } from '@crypto-oracle/core';

const validEmail = isValidEmail('[email protected]'); // true
const validUrl = isValidUrl('https://example.com'); // true
const empty = isEmpty(null); // true

Технологический стек

Модуль использует следующие технологии:

• TypeScript: Строгая типизация для надежности кода
• Pino: Высокопроизводительная система логирования
• Zod: Валидация схем данных
• ESLint: Статический анализ кода

Управление версиями

Core модуль следует принципам семантического версионирования (SemVer):

• MAJOR (x.0.0) - несовместимые API изменения
• MINOR (0.x.0) - добавление функциональности с обратной совместимостью
• PATCH (0.0.x) - исправление ошибок с обратной совместимостью

Публикация

Для создания новой версии и публикации пакета:

# Тестовая публикация без фактической выгрузки
npm run publish:dry-run

# Фактическая публикация
npm run publish:npm

Разработка и расширение

При добавлении новых утилит или типов данных, пожалуйста:

1. Размещайте их в соответствующих категориях/директориях
2. Экспортируйте через индексные файлы (index.ts)
3. Обновляйте документацию
4. Добавляйте TypeScript-типы для всех функций и классов
5. При необходимости добавьте экспорты в секцию exports файла package.json

Лицензия

MIT

Схемы конфигурации

После миграции схем конфигурации в директорию schemas, все конфигурации теперь следует импортировать оттуда:

// Импорт отдельных схем и типов
import { MLConfigSchema, MLConfig } from '@crypto-oracle/core/schemas';
import { APIConfigSchema, APIConfig } from '@crypto-oracle/core/schemas';
import { DataPreprocessingConfigSchema } from '@crypto-oracle/core/schemas';

// Импорт всех схем и типов
import { 
  MLConfig, 
  APIConfig,
  SystemConfig,
  // ... другие импорты
} from '@crypto-oracle/core/schemas';

Доступные схемы конфигурации

Core модуль предоставляет следующие схемы конфигурации:

| Схема | Описание | |-------|----------| | MLConfigSchema | Схема конфигурации для ML модуля | | APIConfigSchema | Схема конфигурации для API модуля | | DataPreprocessingConfigSchema | Схема конфигурации для модуля предобработки данных | | StorageConfigSchema | Схема конфигурации для модуля хранения данных | | DataIngestionConfigSchema | Схема конфигурации для модуля загрузки данных | | AlertSystemConfigSchema | Схема конфигурации для модуля системы оповещений | | AnalyticsConfigSchema | Схема конфигурации для модуля аналитики |

Для каждой схемы также доступен соответствующий тип, например MLConfig, APIConfig и т.д.

Системная конфигурация

Для конфигурации всей системы можно использовать тип SystemConfig:

import { SystemConfig } from '@crypto-oracle/core/schemas';

const config: SystemConfig = {
  dataIngestion: { /* ... */ },
  dataPreprocessing: { /* ... */ },
  storage: { /* ... */ },
  analytics: { /* ... */ },
  ml: { /* ... */ },
  api: { /* ... */ },
  alertSystem: { /* ... */ }
};

Работа с типами, имеющими одинаковые имена

В модуле были унифицированы типы с одинаковыми именами. Теперь тип TokenData используется только из types/market-data-types, а схема TokenDataSchema в schemas/data-preprocessing-schemas ссылается на этот тип:

| Тип | Описание | |-----|----------| | TokenData | Унифицированный тип данных токена из types/market-data-types | | AlertMetrics | Метрики оповещений, переименованные внутри модуля для избежания конфликтов |

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

// Импорт типа данных токена
import { TokenData } from '@crypto-oracle/core';

// Альтернативный способ импорта при необходимости явного указания источника:
import { TokenData } from '@crypto-oracle/core/types/market-data-types';

// Импорт схемы валидации для TokenData:
import { TokenDataSchema } from '@crypto-oracle/core/schemas/data-preprocessing-schemas';