@vvlad1973/data-processor

Модуль для загрузки, объединения и валидации конфигурационных данных с поддержкой include-структур, валидации по JSON-схемам и гибкой логики слияния. Предназначен для использования в платформе BotApp и аналогичных системах, работающих с многоуровневыми структурами данных.

Возможности

• Рекурсивная обработка включений: { include: 'file' } и { file: 'file' }
• Множественные форматы: JSON, JSONC (с комментариями) и YAML
• Защита от циклов: Автоматическое обнаружение циклических включений (O(1) через Set)
• Валидация данных: Интеграция с DataValidator и JSON Schema
• Гибкое слияние: 4 режима синхронизации (MERGE, FULL_REPLACE, APPEND_NEW_ONLY, UPSERT_AND_PRUNE)
• Glob patterns: Поддержка wildcards (*, **) для управления слиянием
• Удаление ключей: По значению (например, null, "__DELETE__")
• Отслеживание источников: Сохранение имени исходного файла в поле $source
• Кэширование файлов: Опциональное in-memory кэширование для производительности
• Защита от Path Traversal: Безопасная загрузка файлов
• Логирование: Декораторы LogClass, LogMethod, LogSyncMethod для автоматического логирования (опционально через pino-logger-tree)

Установка

npm install @vvlad1973/data-processor

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

npm install @vvlad1973/data-processor @vvlad1973/pino-logger-tree

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

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

import { DataValidator } from '@vvlad1973/data-validator';
import { BaseDataProcessor } from '@vvlad1973/data-processor';

class MyProcessor extends BaseDataProcessor<MyInput, MyOutput> {
  async prepareData(data: MyInput): Promise<MyOutput> {
    return Promise.resolve({ ...data, processed: true });
  }
}

const validator = new DataValidator();
await validator.loadSchemasFromDirectory('./schemas');

const processor = new MyProcessor({
  dataValidator: validator,
  enableFileCache: true,
});

const destination = {};
const result = await processor.loadData('data.yaml', destination, {
  basePath: __dirname,
  schemaKey: 'route.schema',
  deleteKeysWith: [null],
  nonMergeKeys: ['*.id'],
  needsSaveSourceFileName: true,
});

Использование с декораторами (рекомендуется)

import { BaseDataProcessor, LogClass } from '@vvlad1973/data-processor';
import { LoggerTree } from '@vvlad1973/pino-logger-tree';

@LogClass({
  asyncMethodOptions: { level: 'trace', maskSensitive: true },
  syncMethodOptions: { level: 'trace', maskSensitive: true }
})
class MyProcessor extends BaseDataProcessor<MyInput, MyOutput> {
  async prepareData(data: MyInput): Promise<MyOutput> {
    // Все методы автоматически логируются через декоратор
    return Promise.resolve({ ...data, processed: true });
  }
}

const loggerTree = new LoggerTree();
const processor = new MyProcessor({
  logger: loggerTree.root().child('processor'),
});

const result = await processor.loadData('data.yaml');

Примечание: Если @vvlad1973/pino-logger-tree не установлен, декораторы работают как no-op (класс функционирует без логирования).

Подробная документация по логированию и декораторам: docs/LOGGING.md

Параметры конструктора

| Параметр | Тип | Описание | | ------------------- | ------------- | ------------------------------------------------- | | dataValidator | DataValidator | Валидатор для проверки данных по JSON Schema | | schemaDir | string | Директория со схемами | | logger | ILogger | Экземпляр логгера (optional) | | enableFileCache | boolean | Включить кэширование файлов | | includeResolvePaths | string[] | Glob-паттерны whitelist для разрешения include | | excludeResolvePaths | string[] | Glob-паттерны blacklist для блокировки include |

Режимы синхронизации

• MERGE (по умолчанию): глубокое слияние с поддержкой deleteKeysWith и nonMergeKeys
• FULL_REPLACE: полная замена через Object.assign
• APPEND_NEW_ONLY: добавление только новых ключей без перезаписи
• UPSERT_AND_PRUNE: обновление + добавление + удаление лишних ключей

Детали по каждому режиму см. в документации TypeDoc или в исходном коде.

Документация

• Полная API документация (TypeDoc)
• Руководство по логированию
• CHANGELOG

Разработка

Текущий статус

• Версия: 2.5.0
• Test coverage: 94.11% (с декораторами)
• ESLint: 0 ошибок
• TypeScript: Strict mode

Команды

npm run build          # Компиляция TypeScript
npm run test           # Запуск тестов
npm run test:coverage  # Тесты с покрытием
npm run lint           # Проверка ESLint
npm run lint:fix       # Исправление ESLint

Лицензия

MIT License with Commercial Use

Copyright (c) 2025 Vladislav Vnukovskiy