metal-orm 1.0.92 → 1.0.94

package/src/decorators/transformers/transformer-metadata.ts

@@ -0,0 +1,73 @@
+import type { ColumnType } from '../../schema/column-types.js';
+
+// Transform context provides metadata about the transformation
+export interface TransformContext {
+  entityName: string;
+  propertyName: string;
+  columnType: ColumnType;
+  isUpdate: boolean;
+  originalValue?: unknown;
+  autoTransform: boolean; // Whether auto-correction is enabled
+}
+
+// Auto-transform result for validators that can fix data
+export interface AutoTransformResult<T = unknown> {
+  success: boolean;
+  correctedValue?: T;
+  message?: string;
+}
+
+// Base transformer interface
+export interface PropertyTransformer<TInput = unknown, TOutput = unknown> {
+  readonly name: string;
+  transform(value: TInput, context: TransformContext): TOutput;
+}
+
+// Validator interface (read-only, throws on failure)
+export interface PropertyValidator<T = unknown> {
+  readonly name: string;
+  validate(value: T, context: TransformContext): ValidationResult;
+}
+
+// Sanitizer interface (mutates, never throws)
+export interface PropertySanitizer<T = unknown> {
+  readonly name: string;
+  sanitize(value: T, context: TransformContext): T;
+}
+
+// Combined transformer that can validate and transform
+export interface CompositeTransformer<TInput = unknown, TOutput = unknown>
+  extends PropertyTransformer<TInput, TOutput>,
+    PropertyValidator<TInput> {}
+
+// Extended validator interface with auto-transform capability
+export interface AutoTransformableValidator<T = unknown> extends PropertyValidator<T> {
+  /**
+   * Attempts to automatically correct an invalid value.
+   * Returns undefined if auto-correction is not possible.
+   */
+  autoTransform?(value: T, context: TransformContext): AutoTransformResult<T>;
+}
+
+// Validation result
+export interface ValidationResult {
+  isValid: boolean;
+  error?: string;
+  message?: string;
+}
+
+// Transformer metadata stored during decoration phase
+export interface TransformerMetadata {
+  propertyName: string;
+  transformers: PropertyTransformer[];
+  validators: PropertyValidator[];
+  sanitizers: PropertySanitizer[];
+  executionOrder: 'before-save' | 'after-load' | 'both';
+}
+
+// Transformer configuration options
+export interface TransformerConfig {
+  auto?: boolean; // Enable auto-transform mode (default: false)
+  execute?: 'before-save' | 'after-load' | 'both'; // When to execute (default: 'both')
+  stopOnFirstError?: boolean; // Stop validation on first error (default: false)
+}

package/src/decorators/validators/built-in/br-cep-validator.ts

@@ -0,0 +1,55 @@
+import type { CountryValidator, ValidationOptions, ValidationResult, AutoCorrectionResult } from '../country-validators.js';
+
+/**
+ * Brazilian CEP validator
+ * Format: XXXXX-XXX (8 digits)
+ */
+export class CEPValidator implements CountryValidator<string> {
+  readonly countryCode = 'BR';
+  readonly identifierType = 'cep';
+  readonly name = 'br-cep';
+  
+  validate(value: string, options: ValidationOptions = {}): ValidationResult {
+    const normalized = this.normalize(value);
+    
+    // Validate format
+    if (!/^\d{8}$/.test(normalized)) {
+      return { 
+        isValid: false, 
+        error: options.errorMessage || 'CEP must contain exactly 8 numeric digits' 
+      };
+    }
+    
+    return { 
+      isValid: true, 
+      normalizedValue: normalized, 
+      formattedValue: this.format(value) 
+    };
+  }
+  
+  normalize(value: string): string {
+    return value.replace(/[^0-9]/g, '');
+  }
+  
+  format(value: string): string {
+    const normalized = this.normalize(value);
+    if (normalized.length !== 8) return value;
+    return normalized.replace(/(\d{5})(\d{3})/, '$1-$2');
+  }
+  
+  autoCorrect(value: string): AutoCorrectionResult<string> {
+    const normalized = this.normalize(value);
+    
+    if (normalized.length === 8) {
+      return { success: true, correctedValue: this.format(normalized) };
+    }
+    
+    if (normalized.length < 8) {
+      const padded = normalized.padEnd(8, '0');
+      return { success: true, correctedValue: this.format(padded) };
+    }
+    
+    const truncated = normalized.slice(0, 8);
+    return { success: true, correctedValue: this.format(truncated) };
+  }
+}

package/src/decorators/validators/built-in/br-cnpj-validator.ts

@@ -0,0 +1,105 @@
+import type { CountryValidator, ValidationOptions, ValidationResult, AutoCorrectionResult } from '../country-validators.js';
+
+/**
+ * Brazilian CNPJ validator
+ * Format: XX.XXX.XXX/XXXX-XX (14 digits)
+ * Checksum: Mod 11 algorithm
+ */
+export class CNPJValidator implements CountryValidator<string> {
+  readonly countryCode = 'BR';
+  readonly identifierType = 'cnpj';
+  readonly name = 'br-cnpj';
+  
+  validate(value: string, options: ValidationOptions = {}): ValidationResult {
+    const normalized = this.normalize(value);
+    
+    // Validate format
+    if (!/^\d{14}$/.test(normalized)) {
+      return { 
+        isValid: false, 
+        error: options.errorMessage || 'CNPJ must contain exactly 14 numeric digits' 
+      };
+    }
+    
+    // Check for known invalid CNPJs
+    if (this.isKnownInvalid(normalized) && options.strict !== false) {
+      return { 
+        isValid: false, 
+        error: options.errorMessage || 'Invalid CNPJ number' 
+      };
+    }
+    
+    // Validate checksum
+    if (!this.validateChecksum(normalized)) {
+      return { 
+        isValid: false, 
+        error: options.errorMessage || 'Invalid CNPJ checksum' 
+      };
+    }
+    
+    return { 
+      isValid: true, 
+      normalizedValue: normalized, 
+      formattedValue: this.format(value) 
+    };
+  }
+  
+  normalize(value: string): string {
+    return value.replace(/[^0-9]/g, '');
+  }
+  
+  format(value: string): string {
+    const normalized = this.normalize(value);
+    if (normalized.length !== 14) return value;
+    return normalized.replace(/(\d{2})(\d{3})(\d{3})(\d{4})(\d{2})/, '$1.$2.$3/$4-$5');
+  }
+  
+  autoCorrect(value: string): AutoCorrectionResult<string> {
+    const normalized = this.normalize(value);
+    
+    if (normalized.length === 14) {
+      return { success: true, correctedValue: this.format(normalized) };
+    }
+    
+    if (normalized.length < 14) {
+      const padded = normalized.padEnd(14, '0');
+      return { success: true, correctedValue: this.format(padded) };
+    }
+    
+    const truncated = normalized.slice(0, 14);
+    return { success: true, correctedValue: this.format(truncated) };
+  }
+  
+  private isKnownInvalid(cnpj: string): boolean {
+    // Check for CNPJs with all digits the same (e.g., 00.000.000/0000-00)
+    return /^(\d)\1{13}$/.test(cnpj);
+  }
+  
+  private validateChecksum(cnpj: string): boolean {
+    const digits = cnpj.split('').map(Number);
+    const weights1 = [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
+    const weights2 = [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2];
+    
+    // Calculate first check digit
+    let sum = 0;
+    for (let i = 0; i < 12; i++) {
+      sum += digits[i] * weights1[i];
+    }
+    let check1 = sum % 11;
+    check1 = check1 < 2 ? 0 : 11 - check1;
+    
+    if (check1 !== digits[12]) {
+      return false;
+    }
+    
+    // Calculate second check digit
+    sum = 0;
+    for (let i = 0; i < 13; i++) {
+      sum += digits[i] * weights2[i];
+    }
+    let check2 = sum % 11;
+    check2 = check2 < 2 ? 0 : 11 - check2;
+    
+    return check2 === digits[13];
+  }
+}

package/src/decorators/validators/built-in/br-cpf-validator.ts

@@ -0,0 +1,103 @@
+import type { CountryValidator, ValidationOptions, ValidationResult, AutoCorrectionResult } from '../country-validators.js';
+
+/**
+ * Brazilian CPF validator
+ * Format: XXX.XXX.XXX-XX (11 digits)
+ * Checksum: Mod 11 algorithm
+ */
+export class CPFValidator implements CountryValidator<string> {
+  readonly countryCode = 'BR';
+  readonly identifierType = 'cpf';
+  readonly name = 'br-cpf';
+  
+  validate(value: string, options: ValidationOptions = {}): ValidationResult {
+    const normalized = this.normalize(value);
+    
+    // Validate format
+    if (!/^\d{11}$/.test(normalized)) {
+      return { 
+        isValid: false, 
+        error: options.errorMessage || 'CPF must contain exactly 11 numeric digits' 
+      };
+    }
+    
+    // Check for known invalid CPFs
+    if (this.isKnownInvalid(normalized) && options.strict !== false) {
+      return { 
+        isValid: false, 
+        error: options.errorMessage || 'Invalid CPF number' 
+      };
+    }
+    
+    // Validate checksum
+    if (!this.validateChecksum(normalized)) {
+      return { 
+        isValid: false, 
+        error: options.errorMessage || 'Invalid CPF checksum' 
+      };
+    }
+    
+    return { 
+      isValid: true, 
+      normalizedValue: normalized, 
+      formattedValue: this.format(value) 
+    };
+  }
+  
+  normalize(value: string): string {
+    return value.replace(/[^0-9]/g, '');
+  }
+  
+  format(value: string): string {
+    const normalized = this.normalize(value);
+    if (normalized.length !== 11) return value;
+    return normalized.replace(/(\d{3})(\d{3})(\d{3})(\d{2})/, '$1.$2.$3-$4');
+  }
+  
+  autoCorrect(value: string): AutoCorrectionResult<string> {
+    const normalized = this.normalize(value);
+    
+    if (normalized.length === 11) {
+      return { success: true, correctedValue: this.format(normalized) };
+    }
+    
+    if (normalized.length < 11) {
+      const padded = normalized.padEnd(11, '0');
+      return { success: true, correctedValue: this.format(padded) };
+    }
+    
+    const truncated = normalized.slice(0, 11);
+    return { success: true, correctedValue: this.format(truncated) };
+  }
+  
+  private isKnownInvalid(cpf: string): boolean {
+    // Check for CPFs with all digits the same (e.g., 111.111.111-11)
+    return /^(\d)\1{10}$/.test(cpf);
+  }
+  
+  private validateChecksum(cpf: string): boolean {
+    const digits = cpf.split('').map(Number);
+    
+    // Calculate first check digit
+    let sum = 0;
+    for (let i = 0; i < 9; i++) {
+      sum += digits[i] * (10 - i);
+    }
+    let check1 = sum % 11;
+    check1 = check1 < 2 ? 0 : 11 - check1;
+    
+    if (check1 !== digits[9]) {
+      return false;
+    }
+    
+    // Calculate second check digit
+    sum = 0;
+    for (let i = 0; i < 10; i++) {
+      sum += digits[i] * (11 - i);
+    }
+    let check2 = sum % 11;
+    check2 = check2 < 2 ? 0 : 11 - check2;
+    
+    return check2 === digits[10];
+  }
+}

package/src/decorators/validators/country-validator-registry.ts

@@ -0,0 +1,64 @@
+import type { CountryValidator, CountryValidatorFactory } from './country-validators.js';
+
+/**
+ * Registry for country-specific identifier validators
+ * Mirrors the INFLECTOR_FACTORIES pattern from scripts/inflection/index.mjs
+ */
+const VALIDATOR_FACTORIES = new Map<string, CountryValidatorFactory>();
+
+/**
+ * Registers a country validator factory
+ * @param countryCode - ISO 3166-1 alpha-2 country code (e.g., 'BR', 'US')
+ * @param identifierType - Identifier type (e.g., 'cpf', 'ssn')
+ * @param factory - Factory function that creates a validator instance
+ */
+export const registerValidator = (
+  countryCode: string,
+  identifierType: string,
+  factory: CountryValidatorFactory
+): void => {
+  const key = `${countryCode.toLowerCase()}-${identifierType.toLowerCase()}`;
+  if (!countryCode) throw new Error('countryCode is required');
+  if (!identifierType) throw new Error('identifierType is required');
+  if (typeof factory !== 'function') {
+    throw new Error('factory must be a function that returns a validator');
+  }
+  VALIDATOR_FACTORIES.set(key, factory);
+};
+
+/**
+ * Resolves a validator for a given country and identifier type
+ * @param countryCode - ISO 3166-1 alpha-2 country code
+ * @param identifierType - Identifier type
+ * @returns Validator instance or undefined if not found
+ */
+export const resolveValidator = (
+  countryCode: string,
+  identifierType: string
+): CountryValidator | undefined => {
+  const key = `${countryCode.toLowerCase()}-${identifierType.toLowerCase()}`;
+  const factory = VALIDATOR_FACTORIES.get(key);
+  return factory ? factory() : undefined;
+};
+
+/**
+ * Gets all registered validator keys
+ * @returns Array of validator keys (e.g., ['br-cpf', 'us-ssn'])
+ */
+export const getRegisteredValidators = (): string[] => {
+  return Array.from(VALIDATOR_FACTORIES.keys());
+};
+
+/**
+ * Checks if a validator is registered
+ * @param countryCode - ISO 3166-1 alpha-2 country code
+ * @param identifierType - Identifier type
+ * @returns True if validator is registered
+ */
+export const hasValidator = (
+  countryCode: string,
+  identifierType: string
+): boolean => {
+  const key = `${countryCode.toLowerCase()}-${identifierType.toLowerCase()}`;
+  return VALIDATOR_FACTORIES.has(key);
+};

package/src/decorators/validators/country-validators-decorators.ts

@@ -0,0 +1,209 @@
+import { getOrCreateMetadataBag } from '../decorator-metadata.js';
+import { registerValidator } from './country-validator-registry.js';
+import { CPFValidator } from './built-in/br-cpf-validator.js';
+import { CNPJValidator } from './built-in/br-cnpj-validator.js';
+import { CEPValidator } from './built-in/br-cep-validator.js';
+
+// Register built-in validators
+registerValidator('BR', 'cpf', () => new CPFValidator());
+registerValidator('BR', 'cnpj', () => new CNPJValidator());
+registerValidator('BR', 'cep', () => new CEPValidator());
+
+const normalizePropertyName = (name: string | symbol): string => {
+  if (typeof name === 'symbol') {
+    return name.description ?? name.toString();
+  }
+  return name;
+};
+
+/**
+ * Decorator to validate a Brazilian CPF number
+ * @param options - Validation options
+ * @returns Property decorator for CPF validation
+ */
+export function CPF(options?: { strict?: boolean; errorMessage?: string }) {
+  return function (_value: unknown, context: ClassFieldDecoratorContext) {
+    const propertyName = normalizePropertyName(context.name);
+    const bag = getOrCreateMetadataBag(context);
+    
+    // Find or create transformer metadata for this property
+    let existing = bag.transformers.find(t => t.propertyName === propertyName);
+    if (!existing) {
+      existing = {
+        propertyName,
+        metadata: {
+          propertyName,
+          transformers: [],
+          validators: [],
+          sanitizers: [],
+          executionOrder: 'both'
+        }
+      };
+      bag.transformers.push(existing);
+    }
+    
+    // Create validator instance
+    const validator = new CPFValidator();
+    
+    // Add validator to metadata
+    existing.metadata.validators.push({
+      name: validator.name,
+      validate: (value: string) => {
+        const result = validator.validate(value, {
+          strict: options?.strict ?? true,
+          errorMessage: options?.errorMessage
+        });
+        return {
+          isValid: result.isValid,
+          error: result.error,
+          message: result.error
+        };
+      },
+      autoTransform: (value: string) => {
+        const correction = validator.autoCorrect(value);
+        if (correction?.success) {
+          return {
+            success: true,
+            correctedValue: correction.correctedValue,
+            message: correction.message
+          };
+        }
+        return { success: false };
+      }
+    } as unknown as never);
+    
+    // Add sanitizer to normalize and format
+    existing.metadata.sanitizers.push({
+      name: 'cpf-formatter',
+      sanitize: (value: string) => validator.format(value)
+    });
+  };
+}
+
+/**
+ * Decorator to validate a Brazilian CNPJ number
+ * @param options - Validation options
+ * @returns Property decorator for CNPJ validation
+ */
+export function CNPJ(options?: { strict?: boolean; errorMessage?: string }) {
+  return function (_value: unknown, context: ClassFieldDecoratorContext) {
+    const propertyName = normalizePropertyName(context.name);
+    const bag = getOrCreateMetadataBag(context);
+    
+    // Find or create transformer metadata for this property
+    let existing = bag.transformers.find(t => t.propertyName === propertyName);
+    if (!existing) {
+      existing = {
+        propertyName,
+        metadata: {
+          propertyName,
+          transformers: [],
+          validators: [],
+          sanitizers: [],
+          executionOrder: 'both'
+        }
+      };
+      bag.transformers.push(existing);
+    }
+    
+    // Create validator instance
+    const validator = new CNPJValidator();
+    
+    // Add validator to metadata
+    existing.metadata.validators.push({
+      name: validator.name,
+      validate: (value: string) => {
+        const result = validator.validate(value, {
+          strict: options?.strict ?? true,
+          errorMessage: options?.errorMessage
+        });
+        return {
+          isValid: result.isValid,
+          error: result.error,
+          message: result.error
+        };
+      },
+      autoTransform: (value: string) => {
+        const correction = validator.autoCorrect(value);
+        if (correction?.success) {
+          return {
+            success: true,
+            correctedValue: correction.correctedValue,
+            message: correction.message
+          };
+        }
+        return { success: false };
+      }
+    } as unknown as never);
+    
+    // Add sanitizer to normalize and format
+    existing.metadata.sanitizers.push({
+      name: 'cnpj-formatter',
+      sanitize: (value: string) => validator.format(value)
+    });
+  };
+}
+
+/**
+ * Decorator to validate a Brazilian CEP number
+ * @param options - Validation options
+ * @returns Property decorator for CEP validation
+ */
+export function CEP(options?: { strict?: boolean; errorMessage?: string }) {
+  return function (_value: unknown, context: ClassFieldDecoratorContext) {
+    const propertyName = normalizePropertyName(context.name);
+    const bag = getOrCreateMetadataBag(context);
+    
+    // Find or create transformer metadata for this property
+    let existing = bag.transformers.find(t => t.propertyName === propertyName);
+    if (!existing) {
+      existing = {
+        propertyName,
+        metadata: {
+          propertyName,
+          transformers: [],
+          validators: [],
+          sanitizers: [],
+          executionOrder: 'both'
+        }
+      };
+      bag.transformers.push(existing);
+    }
+    
+    // Create validator instance
+    const validator = new CEPValidator();
+    
+    // Add validator to metadata
+    existing.metadata.validators.push({
+      name: validator.name,
+      validate: (value: string) => {
+        const result = validator.validate(value, {
+          strict: options?.strict ?? true,
+          errorMessage: options?.errorMessage
+        });
+        return {
+          isValid: result.isValid,
+          error: result.error,
+          message: result.error
+        };
+      },
+      autoTransform: (value: string) => {
+        const correction = validator.autoCorrect(value);
+        if (correction?.success) {
+          return {
+            success: true,
+            correctedValue: correction.correctedValue,
+            message: correction.message
+          };
+        }
+        return { success: false };
+      }
+    } as unknown as never);
+    
+    // Add sanitizer to normalize and format
+    existing.metadata.sanitizers.push({
+      name: 'cep-formatter',
+      sanitize: (value: string) => validator.format(value)
+    });
+  };
+}