Merge pull request #23 from Isqanderm/feature/22-validation-jit

feat: Add high-performance validation with JIT compilation (MVP)

This PR implements a comprehensive validation system with:
- JIT compilation engine (70-909x faster than baseline)
- 30+ validation decorators (class-validator compatible)
- 518 tests with 95.08% statement coverage
- Property-based testing (~2,000 random checks)
- Benchmark tests (performance validation)
- Memory leak tests (no leaks detected)
- Integration tests (5 real-world scenarios)

Closes #22

Author: Isqanderm

.augment/rules/rule-release.md

@@ -48,6 +48,11 @@ jobs:
           npm run bench:compat > benchmark-compat.txt 2>&1 || echo "Comparison benchmark failed" > benchmark-compat.txt
           cat benchmark-compat.txt
 
+      - name: Run class-validator comparison benchmark
+        run: |
+          npm run bench:validation > benchmark-validation.txt 2>&1 || echo "Validation benchmark failed" > benchmark-validation.txt
+          cat benchmark-validation.txt
+
       - name: Run simple benchmark
         continue-on-error: true
         run: |
@@ -72,6 +77,12 @@ jobs:
           echo "Benchmark results for tracking:"
           cat bench-results.json
 
+      - name: Generate JSON validation benchmark results
+        run: |
+          node benchmarks/suites/compat/validation-comparison-json.js > bench-validation-results.json 2>&1 || echo "[]" > bench-validation-results.json
+          echo "Validation benchmark results for tracking:"
+          cat bench-validation-results.json
+
       - name: Clean up benchmark text files before switching branches
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         run: |
@@ -101,9 +112,11 @@ jobs:
           name: benchmark-results
           path: |
             bench-results.json
+            bench-validation-results.json
             benchmark-simple.txt
             benchmark-complex.txt
             benchmark-compat.txt
+            benchmark-validation.txt
           retention-days: 30
 
       - name: Comment PR with comparison results
@@ -115,6 +128,7 @@ jobs:
 
             // Read all benchmark results
             let compatResults = '';
+            let validationResults = '';
             let simpleResults = '';
             let complexResults = '';
 
@@ -124,6 +138,12 @@ jobs:
               compatResults = 'Comparison benchmark not available';
             }
 
+            try {
+              validationResults = fs.readFileSync('benchmark-validation.txt', 'utf8');
+            } catch (e) {
+              validationResults = 'Validation benchmark not available';
+            }
+
             try {
               simpleResults = fs.readFileSync('benchmark-simple.txt', 'utf8');
             } catch (e) {
@@ -182,9 +202,14 @@ jobs:
             }
 
             const body = '## 🚀 Performance Benchmark Results\n\n' +
+              '### 📦 class-transformer Compatibility\n\n' +
               improvedSummary +
-              '<details>\n<summary>📋 Full Benchmark Output</summary>\n\n' +
+              '<details>\n<summary>📋 Full class-transformer Benchmark Output</summary>\n\n' +
               '```\n' + compatResults + '\n```\n\n</details>\n\n' +
+              '### ✅ class-validator Compatibility\n\n' +
+              '<details>\n<summary>📋 Full class-validator Benchmark Output</summary>\n\n' +
+              '```\n' + validationResults + '\n```\n\n</details>\n\n' +
+              '### 🎯 Core Performance\n\n' +
               '<details>\n<summary>⚡ Simple Mapping Benchmark</summary>\n\n' +
               '```\n' + simpleResults + '\n```\n\n</details>\n\n' +
               '<details>\n<summary>🔧 Complex Transformations Benchmark</summary>\n\n' +

.github/workflows/benchmark.yml

@@ -3,3 +3,8 @@ node_modules
 coverage
 build
 bench-results.json
+
+# Ignore compiled JavaScript files in src directory
+# (TypeScript source files only, compiled output goes to dist/)
+src/**/*.js
+src/**/*.js.map

.gitignore

@@ -7,6 +7,86 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.1.0] - 2025-10-16
+
+### Added
+
+#### Testing Infrastructure
+
+- **Property-Based Testing** - Added comprehensive property-based tests using fast-check library
+  - 25 new property-based tests with ~2,000 random data checks
+  - Validators tested: @IsEmail, @IsURL, @IsUUID, @IsISO8601, @IsInt, @IsPositive, @IsNegative, @Min, @Max, @MinLength, @MaxLength, @IsAlpha, @IsAlphanumeric, @IsHexColor, @IsPort
+  - Ensures validators work correctly with edge cases and random inputs
+  - File: `tests/unit/compat/class-validator/property-based.test.ts`
+
+- **Integration Tests** - Added 5 real-world scenario tests
+  - User registration with nested address validation
+  - API order request with items array and shipping address
+  - Contact form with optional fields
+  - API response transformation + validation
+  - Nested objects transformation (posts with comments)
+  - File: `tests/integration/real-world-scenarios.test.ts`
+
+- **Benchmark Regression Tests** - Added 7 performance regression tests
+  - Simple validation: **0.0023ms** (217x faster than baseline)
+  - Complex validation: **0.0022ms** (909x faster than baseline)
+  - Nested arrays: **0.0050ms** (600x faster than baseline)
+  - Transformation: **0.0043ms** (70x faster than baseline)
+  - Transform + Validate: **0.0042ms** (238x faster than baseline)
+  - Async validation: **0.0076ms**
+  - File: `tests/benchmarks/regression.test.ts`
+
+- **Memory Leak Tests** - Added 6 memory leak detection tests
+  - Tests validate no memory leaks after 3,000-10,000 iterations
+  - Simple validation: -4.06MB (-30.53%) - Memory freed!
+  - Create + validate: -0.99MB (-8.83%) - Memory freed!
+  - Nested validation: -0.19MB (-1.68%) - Stable!
+  - Array validation: -0.03MB (-0.26%) - Stable!
+  - Transformation: -1.49MB (-13.13%) - Memory freed!
+  - Transform + validate: +0.65MB (+5.47%) - Minimal growth!
+  - File: `tests/benchmarks/memory-leak.test.ts`
+
+- **Branch Coverage Tests** - Added 25 tests to improve branch coverage
+  - Validation groups with constraints
+  - Optional properties with groups
+  - Conditional validation (@ValidateIf)
+  - Nested validation for arrays and objects
+  - Multiple constraints with different groups
+  - Async validation with groups
+  - Files: `tests/unit/compat/class-validator/branch-coverage-boost.test.ts`, `tests/unit/compat/class-validator/complex-combinations.test.ts`
+
+#### Dependencies
+
+- **fast-check@4.3.0** - Added for property-based testing (dev dependency)
+
+### Changed
+
+#### Test Coverage Improvements
+
+- **Total tests**: 450 → 518 (+68 tests, +15.1%)
+- **Test files**: 30 → 34 (+4 files)
+- **Statements coverage**: 94.69% → 95.08% (+0.39%)
+- **Branches coverage**: 76.29% → 77.58% (+1.29%)
+- **Functions coverage**: 90.64% (maintained)
+- **Lines coverage**: 94.69% → 95.08% (+0.39%)
+
+### Performance
+
+- **Validation Performance** - Confirmed exceptional performance in benchmark tests
+  - 70-909x faster than baseline expectations
+  - All performance regression tests pass with 10% tolerance
+  - No performance degradation detected
+
+- **Memory Efficiency** - Confirmed no memory leaks
+  - All memory leak tests pass
+  - Memory usage stable or decreasing after repeated operations
+  - Garbage collection working effectively
+
+### Related
+
+- PR [#23](https://github.com/Isqanderm/data-mapper/pull/23) - Add high-performance validation with JIT compilation (MVP)
+- Commit: cb2532c6bd2245105f52a786ed30009498f4ff12
+
 ## [4.0.0] - 2025-10-14
 
 ### BREAKING CHANGES
@@ -187,5 +267,7 @@ For existing users:
 
 This changelog was introduced after version 2.0.5. Previous version history can be found in git commit messages.
 
-[Unreleased]: https://github.com/Isqanderm/data-mapper/compare/v2.0.5...HEAD
+[Unreleased]: https://github.com/Isqanderm/data-mapper/compare/v4.1.0...HEAD
+[4.1.0]: https://github.com/Isqanderm/data-mapper/compare/v4.0.0...v4.1.0
+[4.0.0]: https://github.com/Isqanderm/data-mapper/compare/v2.0.5...v4.0.0
 [2.0.5]: https://github.com/Isqanderm/data-mapper/releases/tag/v2.0.5

CHANGELOG.md

@@ -11,6 +11,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
 [![Downloads](https://img.shields.io/npm/dm/om-data-mapper.svg)](https://www.npmjs.com/package/om-data-mapper)
+[![Documentation](https://img.shields.io/badge/docs-English%20%7C%20Russian-blue)](./docs/README.md)
 
 `om-data-mapper` is a high-performance, type-safe object mapping library for TypeScript and JavaScript. It features a modern **Decorator API** with JIT compilation that delivers **up to 42.7x better performance** than class-transformer, while providing a clean, declarative syntax and zero runtime dependencies.
 
@@ -67,7 +68,7 @@ const user = plainToInstance(UserMapper, data);  // 4.3M ops/sec (13.2x faster!)
 | Array (100 items) | 5.2K ops/sec | 69K ops/sec | **12.3x faster** |
 | Custom Logic | 333K ops/sec | 4.8M ops/sec | **13.4x faster** |
 
-[📊 See full comparison](./docs/COMPARISON.md)
+📊 See [Transformer Usage Guide](./docs/transformer-usage.md) for detailed performance comparisons
 
 ## ✨ Features
 
@@ -266,7 +267,7 @@ Your existing code works exactly the same, but **17.28x faster** on average!
 - ✅ 70% smaller bundle size
 - ✅ TC39 Stage 3 decorators
 
-[📖 Full migration guide](./docs/COMPARISON.md#migration-guide)
+[📖 Full migration guide](./docs/transformer-usage.md#migration-from-class-transformer)
 
 ### Legacy API (Still Supported)
 
@@ -311,7 +312,7 @@ om-data-mapper delivers **exceptional performance** through JIT compilation and
 
 ### vs class-transformer
 
-**17.28x faster on average!** See [full comparison](./docs/COMPARISON.md).
+**17.28x faster on average!** See [Transformer Usage Guide](./docs/transformer-usage.md) for detailed comparisons.
 
 | Scenario | class-transformer | om-data-mapper | Improvement |
 |----------|-------------------|----------------|-------------|
@@ -365,7 +366,6 @@ We use automated benchmarks to track performance regressions:
 - 📊 **PR Comments**: Results posted automatically to pull requests
 - 📈 **Historical Tracking**: Performance trends on [GitHub Pages](https://isqanderm.github.io/data-mapper/dev/bench/)
 - 🔔 **Alerts**: Automatic notifications on regressions >150%
-- 📚 **Documentation**: See [Benchmark Setup Guide](./docs/BENCHMARK_SETUP.md) for details
 
 **Run benchmarks locally:**
 ```bash
@@ -596,11 +596,6 @@ console.log(user.password); // undefined
 - ✅ **Type Safe** - Full TypeScript support
 - ✅ **Zero Breaking Changes** - Works exactly like class-transformer
 
-### Documentation
-
-- [Class-Transformer Compatibility Guide](./docs/CLASS_TRANSFORMER_COMPATIBILITY.md) - Complete API reference
-- [TC39 Decorators Migration Guide](./docs/TC39_DECORATORS_MIGRATION.md) - Migration from legacy decorators
-
 ---
 
 ## Real-World Examples
@@ -745,7 +740,37 @@ const formData = new FormData(form);
 const registration = plainToInstance(RegistrationMapper, Object.fromEntries(formData));
 ```
 
-## API Documentation
+## 📚 Documentation
+
+Complete documentation is available in both **English** and **Russian**:
+
+### English Documentation
+
+📖 **[Documentation Index](./docs/README.md)** - Start here for complete guides
+
+**User Guides:**
+- [Validation Module - User Guide](./docs/validation-usage.md) - Complete guide to validation decorators and functions
+- [Transformer Module - User Guide](./docs/transformer-usage.md) - Complete guide to transformation APIs (Decorator API & class-transformer compatibility)
+
+**Internal Architecture:**
+- [Validation JIT Compilation Internals](./docs/validation-jit-internals.md) - Deep dive into validation JIT compilation
+- [Transformer JIT Compilation Internals](./docs/transformer-jit-internals.md) - Deep dive into transformer JIT compilation
+
+### Russian Documentation (Русская документация)
+
+📖 **[Индекс документации](./docs-ru/README.md)** - Начните отсюда для полных руководств
+
+**Руководства пользователя:**
+- [Модуль валидации - Руководство пользователя](./docs-ru/validation-usage.md) - Полное руководство по декораторам и функциям валидации
+- [Модуль трансформации - Руководство пользователя](./docs-ru/transformer-usage.md) - Полное руководство по API трансформации
+
+**Внутренняя архитектура:**
+- [Внутреннее устройство JIT-компиляции валидации](./docs-ru/validation-jit-internals.md) - Глубокое погружение в JIT-компиляцию валидации
+- [Внутреннее устройство JIT-компиляции трансформации](./docs-ru/transformer-jit-internals.md) - Глубокое погружение в JIT-компиляцию трансформации
+
+---
+
+## API Quick Reference
 
 ### Decorators
 
@@ -765,14 +790,7 @@ const registration = plainToInstance(RegistrationMapper, Object.fromEntries(form
 - **`tryPlainToInstance<S, T>(MapperClass, source)`** - Safe transformation with error handling
 - **`createMapper<S, T>(MapperClass)`** - Create reusable mapper instance
 
-### Advanced Usage
-
-For more detailed examples and advanced patterns:
-
-- [📖 Decorator API Guide](./docs/DECORATOR_API.md) - Complete decorator reference
-- [🔄 Migration Guide](./docs/MIGRATION_GUIDE.md) - Migrating from class-transformer
-- [🏗️ Nested Mapper Composition](./docs/nested-mapper-composition.md) - Complex mapping patterns
-- [📁 Examples Directory](./examples) - Real-world code examples
+For complete API documentation, see the [Transformer Usage Guide](./docs/transformer-usage.md).
 
 ## Contributing