metal-orm 1.0.92 → 1.0.94

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metal-orm",
-  "version": "1.0.92",
+  "version": "1.0.94",
   "type": "module",
   "types": "./dist/index.d.ts",
   "engines": {
@@ -27,13 +27,14 @@
     "build": "tsup",
     "check": "tsc --noEmit",
     "gen:entities": "node scripts/generate-entities.mjs",
-    "test": "vitest",
+    "test": "vitest --run",
+    "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "test:mysql": "vitest --run tests/e2e/mysql-memory.test.ts tests/e2e/decorators-mysql-memory.test.ts tests/e2e/save-graph-mysql-memory.test.ts",
     "test:mysql:optimized": "vitest --run --config tests/e2e/mysql/vitest.config.ts",
     "test:sqlite": "vitest --run tests/e2e/sqlite-memory.test.ts tests/e2e/decorators-sqlite-memory.test.ts tests/e2e/save-graph-sqlite-memory.test.ts",
     "test:pglite": "vitest --run tests/e2e/pglite-memory.test.ts",
-    "test:e2e": "vitest tests/e2e",
+    "test:e2e": "vitest --run tests/e2e",
     "show-sql": "node scripts/show-sql.mjs",
     "lint": "node scripts/run-eslint.mjs",
     "lint:fix": "node scripts/run-eslint.mjs --fix"
@@ -59,9 +60,10 @@
     }
   },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.3.14",
     "@typescript-eslint/eslint-plugin": "^8.20.0",
     "@typescript-eslint/parser": "^8.20.0",
-    "@vitest/ui": "^4.0.14",
+    "@vitest/ui": "^4.0.18",
     "eslint": "^8.57.0",
     "eslint-plugin-deprecation": "^3.0.0",
     "express": "^5.2.1",
@@ -72,10 +74,8 @@
     "supertest": "^7.2.2",
     "tedious": "^19.1.3",
     "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
     "typescript": "^5.5.0",
-    "vitest": "^4.0.14"
-  },
-  "dependencies": {
-    "@electric-sql/pglite": "^0.3.14"
+    "vitest": "^4.0.18"
   }
 }

package/src/decorators/bootstrap.ts

@@ -20,8 +20,10 @@ import {
   EntityOrTableTarget,
   EntityOrTableTargetResolver,
   getAllEntityMetadata,
-  getEntityMetadata
+  getEntityMetadata,
+  addTransformerMetadata
 } from '../orm/entity-metadata.js';
+import { getDecoratorMetadata } from './decorator-metadata.js';
 
 import { tableRef, type TableRef } from '../schema/table.js';
 import {
@@ -156,7 +158,15 @@ export const bootstrapEntities = (): TableDef[] => {
   const metas = getAllEntityMetadata();
   const tableMap = new Map<EntityConstructor, TableDef>();
 
+  // Process decorator metadata for each entity
   for (const meta of metas) {
+    const decoratorMetadata = getDecoratorMetadata(meta.target);
+    if (decoratorMetadata?.transformers) {
+      for (const { propertyName, metadata } of decoratorMetadata.transformers) {
+        addTransformerMetadata(meta.target, propertyName, metadata);
+      }
+    }
+
     const table = buildTableDef(meta);
     tableMap.set(meta.target, table);
   }

package/src/decorators/decorator-metadata.ts

@@ -1,4 +1,5 @@
 import { ColumnDefLike, RelationMetadata } from '../orm/entity-metadata.js';
+import type { TransformerMetadata } from './transformers/transformer-metadata.js';
 
 /**
  * Bag for storing decorator metadata during the decoration phase.
@@ -6,6 +7,7 @@ import { ColumnDefLike, RelationMetadata } from '../orm/entity-metadata.js';
 export interface DecoratorMetadataBag {
   columns: Array<{ propertyName: string; column: ColumnDefLike }>;
   relations: Array<{ propertyName: string; relation: RelationMetadata }>;
+  transformers: Array<{ propertyName: string; metadata: TransformerMetadata }>;
 }
 
 const METADATA_KEY = 'metal-orm:decorators';
@@ -23,7 +25,7 @@ export const getOrCreateMetadataBag = (context: MetadataCarrier): DecoratorMetad
   const metadata = context.metadata || (context.metadata = {} as Record<PropertyKey, unknown>);
   let bag = metadata[METADATA_KEY] as DecoratorMetadataBag | undefined;
   if (!bag) {
-    bag = { columns: [], relations: [] };
+    bag = { columns: [], relations: [], transformers: [] };
     metadata[METADATA_KEY] = bag;
   }
   return bag;

package/src/decorators/index.ts

@@ -7,6 +7,33 @@ export * from './relations.js';
 export * from './bootstrap.js';
 export { getDecoratorMetadata } from './decorator-metadata.js';
 
+// Transformer Decorators
+export * from './transformers/transformer-decorators.js';
+export type { 
+  PropertyTransformer, 
+  PropertyValidator, 
+  PropertySanitizer, 
+  CompositeTransformer, 
+  AutoTransformableValidator, 
+  TransformContext, 
+  AutoTransformResult, 
+  ValidationResult, 
+  TransformerMetadata, 
+  TransformerConfig 
+} from './transformers/transformer-metadata.js';
+
+// Country Identifier Validators
+export * from './validators/country-validators-decorators.js';
+export { registerValidator, resolveValidator, getRegisteredValidators, hasValidator } from './validators/country-validator-registry.js';
+export type { 
+  CountryValidator, 
+  CountryValidatorFactory, 
+  ValidationOptions, 
+  ValidationResult as CountryValidationResult, 
+  AutoCorrectionResult, 
+  ValidatorFactoryOptions 
+} from './validators/country-validators.js';
+
 // Entity Materialization - convert query results to real class instances
 export { materializeAs, DefaultEntityMaterializer, PrototypeMaterializationStrategy, ConstructorMaterializationStrategy } from '../orm/entity-materializer.js';
 export type { EntityMaterializer, EntityMaterializationStrategy } from '../orm/entity-materializer.js';

package/src/decorators/transformers/built-in/string-transformers.ts

@@ -0,0 +1,231 @@
+import type { PropertySanitizer, AutoTransformableValidator, AutoTransformResult, ValidationResult } from '../transformer-metadata.js';
+
+// TrimTransformer
+export class TrimTransformer implements PropertySanitizer<string> {
+  readonly name = 'trim';
+  
+  constructor(private readonly options: { trimStart?: boolean; trimEnd?: boolean; trimAll?: boolean } = {}) {}
+  
+  sanitize(value: string): string {
+    if (typeof value !== 'string') return value;
+    
+    if (this.options.trimAll) {
+      return value.trim();
+    }
+    
+    let result = value;
+    if (this.options.trimStart) {
+      result = result.trimStart();
+    }
+    if (this.options.trimEnd) {
+      result = result.trimEnd();
+    }
+    if (!this.options.trimStart && !this.options.trimEnd && !this.options.trimAll) {
+      result = result.trim();
+    }
+    
+    return result;
+  }
+}
+
+// CaseTransformer
+export class CaseTransformer implements PropertySanitizer<string> {
+  readonly name: string;
+  
+  constructor(private readonly caseType: 'lower' | 'upper' | 'capitalize' | 'title') {
+    this.name = `case-${caseType}`;
+  }
+  
+  sanitize(value: string): string {
+    if (typeof value !== 'string') return value;
+    
+    switch (this.caseType) {
+      case 'lower':
+        return value.toLowerCase();
+      case 'upper':
+        return value.toUpperCase();
+      case 'capitalize':
+        return value.charAt(0).toUpperCase() + value.slice(1).toLowerCase();
+      case 'title':
+        return value.split(' ').map(word => 
+          word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()
+        ).join(' ');
+      default:
+        return value;
+    }
+  }
+}
+
+// AlphanumericValidator
+export class AlphanumericValidator implements AutoTransformableValidator<string> {
+  readonly name = 'alphanumeric';
+  
+  constructor(private readonly options: { allowSpaces?: boolean; allowUnderscores?: boolean; allowHyphens?: boolean } = {}) {}
+  
+  validate(value: string): ValidationResult {
+    if (typeof value !== 'string') {
+      return { isValid: false, error: 'Value must be a string' };
+    }
+    
+    const pattern = new RegExp(
+      `^[a-zA-Z0-9${this.options.allowSpaces ? ' ' : ''}${this.options.allowUnderscores ? '_' : ''}${this.options.allowHyphens ? '-' : ''}]*$`
+    );
+    
+    return pattern.test(value) 
+      ? { isValid: true } 
+      : { isValid: false, error: 'Value must contain only alphanumeric characters' };
+  }
+  
+  autoTransform(value: string): AutoTransformResult<string> {
+    if (typeof value !== 'string') {
+      return { success: false };
+    }
+    
+    let result = value;
+    result = result.replace(/[^a-zA-Z0-9]/g, char => {
+      if (char === ' ' && this.options.allowSpaces) return ' ';
+      if (char === '_' && this.options.allowUnderscores) return '_';
+      if (char === '-' && this.options.allowHyphens) return '-';
+      return '';
+    });
+    
+    return { 
+      success: true, 
+      correctedValue: result, 
+      message: 'Removed non-alphanumeric characters' 
+    };
+  }
+}
+
+// EmailValidator
+export class EmailValidator implements AutoTransformableValidator<string> {
+  readonly name = 'email';
+  
+  constructor(private readonly options: { allowPlus?: boolean; requireTLD?: boolean } = {}) {}
+  
+  validate(value: string): ValidationResult {
+    if (typeof value !== 'string') {
+      return { isValid: false, error: 'Value must be a string' };
+    }
+    
+    // Simple email regex - RFC 5322 is very complex, this covers most cases
+    const emailPattern = this.options.allowPlus 
+      ? /^[^\s@]+@[^\s@]+\.[^\s@]+$/ 
+      : /^[^\s@+]+@[^\s@]+\.[^\s@]+$/;
+    
+    if (!emailPattern.test(value)) {
+      return { isValid: false, error: 'Value must be a valid email address' };
+    }
+    
+    if (this.options.requireTLD) {
+      const parts = value.split('.');
+      if (parts.length < 3 || parts[parts.length - 1].length < 2) {
+        return { isValid: false, error: 'Email must have a valid top-level domain' };
+      }
+    }
+    
+    return { isValid: true };
+  }
+  
+  autoTransform(value: string): AutoTransformResult<string> {
+    if (typeof value !== 'string') {
+      return { success: false };
+    }
+    
+    let result = value.trim().toLowerCase();
+    if (!this.options.allowPlus) {
+      result = result.replace(/\+.*@/, '@');
+    }
+    
+    return { 
+      success: true, 
+      correctedValue: result, 
+      message: 'Trimmed and lowercased email' 
+    };
+  }
+}
+
+// LengthValidator
+export class LengthValidator implements AutoTransformableValidator<string> {
+  readonly name = 'length';
+  
+  constructor(private readonly options: { min?: number; max?: number; exact?: number } = {}) {}
+  
+  validate(value: string): ValidationResult {
+    if (typeof value !== 'string') {
+      return { isValid: false, error: 'Value must be a string' };
+    }
+    
+    if (this.options.exact !== undefined && value.length !== this.options.exact) {
+      return { isValid: false, error: `Value must be exactly ${this.options.exact} characters long` };
+    }
+    
+    if (this.options.min !== undefined && value.length < this.options.min) {
+      return { isValid: false, error: `Value must be at least ${this.options.min} characters long` };
+    }
+    
+    if (this.options.max !== undefined && value.length > this.options.max) {
+      return { isValid: false, error: `Value must be at most ${this.options.max} characters long` };
+    }
+    
+    return { isValid: true };
+  }
+  
+  autoTransform(value: string): AutoTransformResult<string> {
+    if (typeof value !== 'string') {
+      return { success: false };
+    }
+    
+    let result = value;
+    
+    if (this.options.max !== undefined && result.length > this.options.max) {
+      result = result.slice(0, this.options.max);
+    }
+    
+    if (this.options.min !== undefined && result.length < this.options.min) {
+      result = result.padEnd(this.options.min);
+    }
+    
+    return { 
+      success: true, 
+      correctedValue: result, 
+      message: 'Adjusted string length' 
+    };
+  }
+}
+
+// PatternValidator
+export class PatternValidator implements AutoTransformableValidator<string> {
+  readonly name = 'pattern';
+  
+  constructor(private readonly options: { pattern: RegExp; flags?: string; errorMessage?: string; replacement?: string } = { pattern: /.*/ }) {}
+  
+  validate(value: string): ValidationResult {
+    if (typeof value !== 'string') {
+      return { isValid: false, error: 'Value must be a string' };
+    }
+    
+    const pattern = new RegExp(this.options.pattern.source, this.options.flags);
+    
+    if (!pattern.test(value)) {
+      return { isValid: false, error: this.options.errorMessage || 'Value does not match required pattern' };
+    }
+    
+    return { isValid: true };
+  }
+  
+  autoTransform(value: string): AutoTransformResult<string> {
+    if (typeof value !== 'string' || !this.options.replacement) {
+      return { success: false };
+    }
+    
+    const pattern = new RegExp(this.options.pattern.source, this.options.flags);
+    const result = value.replace(pattern, this.options.replacement);
+    
+    return { 
+      success: true, 
+      correctedValue: result, 
+      message: 'Replaced pattern matches' 
+    };
+  }
+}

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

@@ -0,0 +1,137 @@
+import { getOrCreateMetadataBag } from '../decorator-metadata.js';
+import type { TransformerMetadata } from './transformer-metadata.js';
+import { 
+  TrimTransformer, 
+  CaseTransformer, 
+  AlphanumericValidator, 
+  EmailValidator, 
+  LengthValidator, 
+  PatternValidator 
+} from './built-in/string-transformers.js';
+
+const normalizePropertyName = (name: string | symbol): string => {
+  if (typeof name === 'symbol') {
+    return name.description ?? name.toString();
+  }
+  return name;
+};
+
+const registerTransformerMetadata = (
+  context: ClassFieldDecoratorContext, 
+  metadata: Partial<TransformerMetadata>
+): void => {
+  const propertyName = normalizePropertyName(context.name);
+  const bag = getOrCreateMetadataBag(context);
+  
+  // Find existing 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);
+  }
+  
+  // Merge metadata
+  if (metadata.transformers) {
+    existing.metadata.transformers.push(...metadata.transformers);
+  }
+  if (metadata.validators) {
+    existing.metadata.validators.push(...metadata.validators);
+  }
+  if (metadata.sanitizers) {
+    existing.metadata.sanitizers.push(...metadata.sanitizers);
+  }
+  if (metadata.executionOrder) {
+    existing.metadata.executionOrder = metadata.executionOrder;
+  }
+};
+
+// Trim decorator
+export function Trim(options?: { trimStart?: boolean; trimEnd?: boolean; trimAll?: boolean }) {
+  return function (_value: unknown, context: ClassFieldDecoratorContext) {
+    registerTransformerMetadata(context, {
+      sanitizers: [new TrimTransformer(options)]
+    });
+  };
+}
+
+// Lower case decorator
+export function Lower() {
+  return function (_value: unknown, context: ClassFieldDecoratorContext) {
+    registerTransformerMetadata(context, {
+      sanitizers: [new CaseTransformer('lower')]
+    });
+  };
+}
+
+// Upper case decorator
+export function Upper() {
+  return function (_value: unknown, context: ClassFieldDecoratorContext) {
+    registerTransformerMetadata(context, {
+      sanitizers: [new CaseTransformer('upper')]
+    });
+  };
+}
+
+// Capitalize decorator
+export function Capitalize() {
+  return function (_value: unknown, context: ClassFieldDecoratorContext) {
+    registerTransformerMetadata(context, {
+      sanitizers: [new CaseTransformer('capitalize')]
+    });
+  };
+}
+
+// Title case decorator
+export function Title() {
+  return function (_value: unknown, context: ClassFieldDecoratorContext) {
+    registerTransformerMetadata(context, {
+      sanitizers: [new CaseTransformer('title')]
+    });
+  };
+}
+
+// Alphanumeric decorator
+export function Alphanumeric(options?: { allowSpaces?: boolean; allowUnderscores?: boolean; allowHyphens?: boolean }) {
+  return function (_value: unknown, context: ClassFieldDecoratorContext) {
+    registerTransformerMetadata(context, {
+      validators: [new AlphanumericValidator(options)]
+    });
+  };
+}
+
+// Email decorator
+export function Email(options?: { allowPlus?: boolean; requireTLD?: boolean }) {
+  return function (_value: unknown, context: ClassFieldDecoratorContext) {
+    registerTransformerMetadata(context, {
+      validators: [new EmailValidator(options)]
+    });
+  };
+}
+
+// Length decorator
+export function Length(options: { min?: number; max?: number; exact?: number }) {
+  return function (_value: unknown, context: ClassFieldDecoratorContext) {
+    registerTransformerMetadata(context, {
+      validators: [new LengthValidator(options)]
+    });
+  };
+}
+
+// Pattern decorator
+export function Pattern(options: { pattern: RegExp; flags?: string; errorMessage?: string; replacement?: string }) {
+  return function (_value: unknown, context: ClassFieldDecoratorContext) {
+    registerTransformerMetadata(context, {
+      validators: [new PatternValidator(options)]
+    });
+  };
+}

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

@@ -0,0 +1,172 @@
+import { getEntityMetadata } from '../../orm/entity-metadata.js';
+import type { EntityConstructor, EntityMetadata } from '../../orm/entity-metadata.js';
+import type { 
+  TransformContext, 
+  TransformerConfig, 
+  PropertyTransformer, 
+  PropertyValidator, 
+  PropertySanitizer, 
+  TransformerMetadata
+} from './transformer-metadata.js';
+
+export class TransformerExecutor {
+  private config: TransformerConfig = {
+    auto: false,
+    execute: 'both',
+    stopOnFirstError: false
+  };
+
+  constructor(options?: TransformerConfig) {
+    this.config = { ...this.config, ...options };
+  }
+
+  /**
+   * Applies all transformers to an entity instance
+   */
+  async applyTransformers(entity: Record<string, unknown>, entityClass: EntityConstructor, context: Partial<TransformContext> = {}): Promise<void> {
+    const meta = getEntityMetadata(entityClass);
+    if (!meta || !meta.transformers) return;
+
+    // Get column types from entity metadata
+    const columnTypes = this.getColumnTypes(meta);
+
+    for (const [propertyName, transformerMeta] of Object.entries(meta.transformers)) {
+      const typedMeta = transformerMeta as unknown as TransformerMetadata;
+      
+      // Skip if transformer should not execute in current context
+      if (!this.shouldExecute(typedMeta.executionOrder, context.isUpdate)) {
+        continue;
+      }
+
+      // Get current value
+      const value = entity[propertyName];
+
+      // Skip if value is null or undefined
+      if (value === null || value === undefined) continue;
+
+      // Create transform context
+      const transformContext: TransformContext = {
+        entityName: entityClass.name,
+        propertyName,
+        columnType: columnTypes[propertyName] || 'VARCHAR',
+        isUpdate: context.isUpdate || false,
+        originalValue: context.originalValue,
+        autoTransform: this.config.auto
+      };
+
+      try {
+        // Apply sanitizers first
+        let transformedValue = this.applySanitizers(value, typedMeta.sanitizers, transformContext);
+        
+        // Apply transformers
+        transformedValue = this.applyTransformersToValue(transformedValue, typedMeta.transformers, transformContext);
+        
+        // Apply validation
+        this.applyValidators(transformedValue, typedMeta.validators, transformContext);
+        
+        // Update the entity with the transformed value
+        entity[propertyName] = transformedValue;
+      } catch (_error) {
+        // Handle errors based on config
+        if (this.config.stopOnFirstError) {
+          throw _error;
+        }
+        // Continue with other properties
+      }
+    }
+  }
+
+  private shouldExecute(executionOrder: 'before-save' | 'after-load' | 'both', isUpdate: boolean): boolean {
+    if (executionOrder === 'both') return true;
+    if (isUpdate && executionOrder === 'before-save') return true;
+    if (!isUpdate && executionOrder === 'after-load') return true;
+    return false;
+  }
+
+  private getColumnTypes(meta: EntityMetadata): Record<string, string> {
+    if (!meta || !meta.columns) return {};
+
+    const columnTypes: Record<string, string> = {};
+    for (const [propertyName, columnDef] of Object.entries(meta.columns)) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      columnTypes[propertyName] = (columnDef as any).type || 'VARCHAR';
+    }
+    return columnTypes;
+  }
+
+  private applySanitizers(value: unknown, sanitizers: PropertySanitizer[], context: TransformContext): unknown {
+    let result = value;
+    for (const sanitizer of sanitizers) {
+      try {
+        result = sanitizer.sanitize(result, context);
+      } catch (_error: unknown) {
+        // Continue with next sanitizer if this one fails
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const error = _error;
+      }
+    }
+    return result;
+  }
+
+  private applyTransformersToValue(value: unknown, transformers: PropertyTransformer[], context: TransformContext): unknown {
+    let result = value;
+    for (const transformer of transformers) {
+      try {
+        result = transformer.transform(result, context);
+      } catch (_error: unknown) {
+        // Continue with next transformer if this one fails
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const error = _error;
+      }
+    }
+    return result;
+  }
+
+  private applyValidators(value: unknown, validators: PropertyValidator[], context: TransformContext): void {
+    const errors: string[] = [];
+
+    for (const validator of validators) {
+      try {
+        const result = validator.validate(value, context);
+        
+        if (!result.isValid) {
+          if (context.autoTransform && 'autoTransform' in validator) {
+            const autoResult = (validator as { autoTransform?: (v: unknown, c: TransformContext) => { success: boolean; correctedValue?: unknown; message?: string } }).autoTransform?.(value, context);
+            if (typeof autoResult === 'object' && autoResult !== null && 'success' in autoResult && autoResult.success && 'correctedValue' in autoResult && autoResult.correctedValue !== undefined) {
+              // Auto-correct the value
+              (context as { correctedValue?: unknown }).correctedValue = autoResult.correctedValue;
+              return; // Value is now valid
+            }
+          }
+          errors.push(result.error || `Validation failed for ${validator.name}`);
+          
+          if (this.config.stopOnFirstError) {
+            break;
+          }
+        }
+      } catch (_error: unknown) {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const error = _error;
+        if (_error instanceof Error) {
+          errors.push(_error.message);
+        } else {
+          errors.push('Validation failed');
+        }
+        if (this.config.stopOnFirstError) {
+          break;
+        }
+      }
+    }
+
+    if (errors.length > 0) {
+      throw new Error(errors.join(', '));
+    }
+  }
+}
+
+/**
+ * Creates a transformer executor with specified config
+ */
+export const createTransformerExecutor = (config?: TransformerConfig): TransformerExecutor => {
+  return new TransformerExecutor(config);
+};