Skip to content

README.md

Latest commit

 

History

History
239 lines (177 loc) · 13.3 KB

README.md

File metadata and controls

239 lines (177 loc) · 13.3 KB

Документация om-data-mapper

Добро пожаловать в документацию om-data-mapper! Этот каталог содержит исчерпывающие руководства как для пользователей, так и для контрибьюторов.

📚 Оглавление документации

Руководства пользователя

Модуль валидации

  • Руководство по использованию валидации - Полное руководство по использованию модуля валидации
    • Доступные валидаторы и декораторы
    • Функции валидации (validate, validateSync и др.)
    • Пользовательские валидаторы
    • Вложенная валидация
    • Группы валидации
    • Лучшие практики и примеры

Модуль трансформации

  • Руководство по использованию трансформации - Полное руководство по использованию модуля трансформации
    • Decorator API (рекомендуется для новых проектов)
    • API совместимости с class-transformer (для миграции)
    • Декораторы трансформации (@Map, @MapFrom, @Transform и др.)
    • Функции трансформации (plainToInstance, plainToClass и др.)
    • Вложенные трансформации
    • Распространённые паттерны и примеры
    • Руководство по миграции с class-transformer

Внутренняя архитектура

JIT-компиляция валидации

  • Внутреннее устройство JIT валидации - Глубокое погружение в JIT-компиляцию валидации
    • Компоненты архитектуры
    • Система хранения метаданных
    • Стратегия генерации кода
    • Техники оптимизации
    • Характеристики производительности
    • Интеграция пользовательских валидаторов
    • Отладка и профилирование

JIT-компиляция трансформации

  • Внутреннее устройство JIT трансформации - Глубокое погружение в JIT-компиляцию трансформации
    • Компоненты архитектуры
    • Хранение метаданных (на основе Symbol vs WeakMap)
    • Стратегия генерации кода
    • Генерация безопасного доступа к свойствам
    • Стратегии обработки ошибок
    • Техники оптимизации
    • Характеристики производительности
    • Сравнение с BaseMapper

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

Для пользователей

Если вы новичок в om-data-mapper, начните здесь:

  1. Валидация: Прочитайте Руководство по использованию валидации
  2. Трансформация: Прочитайте Руководство по использованию трансформации

Для контрибьюторов

Если вы хотите понять внутреннее устройство или внести вклад:

  1. Внутреннее устройство валидации: Прочитайте Внутреннее устройство JIT валидации
  2. Внутреннее устройство трансформации: Прочитайте Внутреннее устройство JIT трансформации

📖 Что содержится в каждом руководстве?

Руководство по использованию валидации

  • ✅ Установка и настройка
  • ✅ Все доступные валидаторы с примерами
  • ✅ Функции валидации (асинхронные и синхронные)
  • ✅ Пользовательские валидаторы
  • ✅ Вложенная валидация
  • ✅ Группы валидации и условная валидация
  • ✅ Настройка сообщений об ошибках
  • ✅ Лучшие практики
  • ✅ Миграция с class-validator

Руководство по использованию трансформации

  • ✅ Два API: Decorator API и Compatibility API
  • ✅ Все декораторы трансформации с примерами
  • ✅ Функции трансформации
  • ✅ Вложенные трансформации
  • ✅ Распространённые паттерны (ответы API, данные форм и др.)
  • ✅ Руководство по устранению неполадок
  • ✅ Советы по производительности
  • ✅ Миграция с class-transformer

Внутреннее устройство JIT валидации

  • ✅ Обзор архитектуры
  • ✅ Хранение метаданных с использованием Symbol
  • ✅ Реестр валидаторов и кэширование
  • ✅ Процесс JIT-компиляции
  • ✅ Генерация кода для синхронной и асинхронной валидации
  • ✅ Техники оптимизации (кэширование, встраивание и др.)
  • ✅ Бенчмарки производительности
  • ✅ Интеграция пользовательских валидаторов
  • ✅ Отладка сгенерированного кода

Внутреннее устройство JIT трансформации

  • ✅ Обзор архитектуры
  • ✅ Две системы хранения метаданных
  • ✅ Процесс JIT-компиляции
  • ✅ Стратегии генерации кода
  • ✅ Безопасный доступ к свойствам с optional chaining
  • ✅ Обработка ошибок (безопасный vs небезопасный режим)
  • ✅ Техники оптимизации
  • ✅ Бенчмарки производительности
  • ✅ Сравнение с class-transformer
  • ✅ Отладка сгенерированного кода

🎯 Выберите свой путь

Я хочу валидировать объекты

→ Начните с Руководства по использованию валидации

Я хочу трансформировать объекты

→ Начните с Руководства по использованию трансформации

Я мигрирую с class-validator

→ Прочитайте раздел "Миграция с class-validator" в Руководстве по использованию валидации

Я мигрирую с class-transformer

→ Прочитайте раздел "Миграция с class-transformer" в Руководстве по использованию трансформации

Я хочу понять, как это работает внутри

→ Прочитайте Внутреннее устройство JIT валидации и Внутреннее устройство JIT трансформации

Я хочу внести вклад

→ Прочитайте всю документацию по внутренней архитектуре, затем ознакомьтесь с руководством по внесению вклада в основном репозитории

🔥 Ключевые возможности

Модуль валидации

  • В 10 раз быстрее, чем class-validator
  • 100% совместимость API - прямая замена
  • Без зависимостей - не требуется reflect-metadata
  • JIT-компиляция для максимальной производительности
  • Поддержка пользовательских валидаторов
  • Вложенная валидация с полной типобезопасностью

Модуль трансформации

  • В 10 раз быстрее, чем class-transformer
  • Два мощных API - Decorator API и Compatibility API
  • 100% совместимость с class-transformer
  • Без зависимостей - не требуется reflect-metadata
  • JIT-компиляция для максимальной производительности
  • Типобезопасность с полной поддержкой TypeScript

📊 Производительность

Оба модуля используют JIT-компиляцию для достижения исключительной производительности:

Производительность валидации

Тип валидации class-validator om-data-mapper Ускорение
Простая (1 поле) ~50K оп/сек ~500K оп/сек 10x
Сложная (10 полей) ~10K оп/сек ~100K оп/сек 10x
Вложенные объекты ~5K оп/сек ~50K оп/сек 10x

Производительность трансформации

Тип трансформации class-transformer om-data-mapper Ускорение
Простое отображение 326K оп/сек 3.2M оп/сек 10x
Сложные трансформации 150K оп/сек 1.5M оп/сек 10x
Вложенные объекты 80K оп/сек 800K оп/сек 10x

💡 Лучшие практики

Общие

  1. Используйте TypeScript - Полная типобезопасность и лучший опыт разработки
  2. Переиспользуйте экземпляры - Мапперы и валидаторы компилируются один раз
  3. Включите строгий режим - Выявляйте ошибки на ранних этапах
  4. Читайте руководства - Исчерпывающие примеры для распространённых сценариев

Валидация

  1. Используйте validateSync, когда не нужны асинхронные валидаторы
  2. Используйте группы валидации для различных сценариев
  3. Создавайте пользовательские валидаторы для сложной бизнес-логики
  4. Используйте @IsOptional() для необязательных полей

Трансформация

  1. Выбирайте правильный API - Decorator API для новых проектов, Compatibility API для миграции
  2. Переиспользуйте экземпляры мапперов - Используйте createMapper() или getMapper()
  3. Используйте @MapNested() для вложенных объектов
  4. Включайте небезопасный режим для максимальной производительности, когда данные доверенные

🤝 Внесение вклада

Мы приветствуем вклад! Если вы нашли проблемы или хотите улучшить документацию:

  1. Прочитайте документацию по внутренней архитектуре, чтобы понять систему
  2. Ознакомьтесь с руководством по внесению вклада в основном репозитории
  3. Отправляйте issues или pull requests на GitHub

📝 Лицензия

Этот проект лицензирован под лицензией MIT.

🔗 Ссылки

📧 Поддержка

Если у вас есть вопросы или нужна помощь:

  1. Проверьте руководства в документации
  2. Поищите в существующих issues на GitHub
  3. Создайте новый issue с подробным описанием

Приятного кодирования! 🚀