Welcome to the om-data-mapper documentation! This directory contains comprehensive guides for both users and contributors.
- Validation Usage Guide - Complete guide on how to use the validation module
- Available validators and decorators
- Validation functions (validate, validateSync, etc.)
- Custom validators
- Nested validation
- Validation groups
- Best practices and examples
- Transformer Usage Guide - Complete guide on how to use the transformer module
- Decorator API (recommended for new projects)
- class-transformer Compatibility API (for migration)
- Transformation decorators (@Map, @MapFrom, @Transform, etc.)
- Transformation functions (plainToInstance, plainToClass, etc.)
- Nested transformations
- Common patterns and examples
- Migration guide from class-transformer
- Validation JIT Internals - Deep dive into validation JIT compilation
- Architecture components
- Metadata storage system
- Code generation strategy
- Optimization techniques
- Performance characteristics
- Custom validator integration
- Debugging and profiling
- Transformer JIT Internals - Deep dive into transformer JIT compilation
- Architecture components
- Metadata storage (Symbol-based vs WeakMap-based)
- Code generation strategy
- Safe property access generation
- Error handling strategies
- Optimization techniques
- Performance characteristics
- Comparison with BaseMapper
If you're new to om-data-mapper, start here:
- Validation: Read Validation Usage Guide
- Transformation: Read Transformer Usage Guide
If you want to understand the internals or contribute:
- Validation Internals: Read Validation JIT Internals
- Transformer Internals: Read Transformer JIT Internals
- ✅ Installation and setup
- ✅ All available validators with examples
- ✅ Validation functions (async and sync)
- ✅ Custom validators
- ✅ Nested validation
- ✅ Validation groups and conditional validation
- ✅ Error messages customization
- ✅ Best practices
- ✅ Migration from class-validator
- ✅ Two APIs: Decorator API and Compatibility API
- ✅ All transformation decorators with examples
- ✅ Transformation functions
- ✅ Nested transformations
- ✅ Common patterns (API responses, form data, etc.)
- ✅ Troubleshooting guide
- ✅ Performance tips
- ✅ Migration from class-transformer
- ✅ Architecture overview
- ✅ Metadata storage with Symbols
- ✅ Validator registry and caching
- ✅ JIT compilation process
- ✅ Code generation for sync and async validation
- ✅ Optimization techniques (caching, inlining, etc.)
- ✅ Performance benchmarks
- ✅ Custom validator integration
- ✅ Debugging generated code
- ✅ Architecture overview
- ✅ Two metadata storage systems
- ✅ JIT compilation process
- ✅ Code generation strategies
- ✅ Safe property access with optional chaining
- ✅ Error handling (safe vs unsafe mode)
- ✅ Optimization techniques
- ✅ Performance benchmarks
- ✅ Comparison with class-transformer
- ✅ Debugging generated code
→ Start with Validation Usage Guide
→ Start with Transformer Usage Guide
→ Read the "Migration from class-validator" section in Validation Usage Guide
→ Read the "Migration from class-transformer" section in Transformer Usage Guide
→ Read Validation JIT Internals and Transformer JIT Internals
→ Read all internal architecture docs, then check the main repository README for contribution guidelines
- 10x faster than class-validator
- 100% API compatible - drop-in replacement
- No dependencies - no reflect-metadata needed
- JIT compilation for maximum performance
- Custom validators supported
- Nested validation with full type safety
- 10x faster than class-transformer
- Two powerful APIs - Decorator API and Compatibility API
- 100% compatible with class-transformer
- No dependencies - no reflect-metadata needed
- JIT compilation for maximum performance
- Type-safe with full TypeScript support
Both modules use JIT compilation to achieve exceptional performance:
| Validation Type | class-validator | om-data-mapper | Speedup |
|---|---|---|---|
| Simple (1 field) | ~50K ops/sec | ~500K ops/sec | 10x |
| Complex (10 fields) | ~10K ops/sec | ~100K ops/sec | 10x |
| Nested objects | ~5K ops/sec | ~50K ops/sec | 10x |
| Transformation Type | class-transformer | om-data-mapper | Speedup |
|---|---|---|---|
| Simple mapping | 326K ops/sec | 3.2M ops/sec | 10x |
| Complex transformations | 150K ops/sec | 1.5M ops/sec | 10x |
| Nested objects | 80K ops/sec | 800K ops/sec | 10x |
- Use TypeScript - Full type safety and better developer experience
- Reuse instances - Mappers and validators are compiled once
- Enable strict mode - Catch errors early
- Read the guides - Comprehensive examples for common scenarios
- Use validateSync when you don't need async validators
- Leverage validation groups for different scenarios
- Create custom validators for complex business logic
- Use @IsOptional() for optional fields
- Choose the right API - Decorator API for new projects, Compatibility API for migration
- Reuse mapper instances - Use createMapper() or getMapper()
- Use @MapNested() for nested objects
- Enable unsafe mode for maximum performance when data is trusted
We welcome contributions! If you find issues or want to improve the documentation:
- Read the internal architecture docs to understand the system
- Check the main repository for contribution guidelines
- Submit issues or pull requests on GitHub
This project is licensed under the MIT License.
- GitHub Repository: https://github.com/Isqanderm/data-mapper
- NPM Package: https://www.npmjs.com/package/om-data-mapper
If you have questions or need help:
- Check the documentation guides
- Search existing GitHub issues
- Create a new issue with a detailed description
Happy coding! 🚀