snap-validate 0.2.1 → 0.3.1

package/README.md

@@ -1,11 +1,13 @@
 # Snap Validate ⚡
 
-[![npm version](https://badge.fury.io/js/snap-validate.svg)](https://badge.fury.io/js/snap-validate)
+[![npm version](https://img.shields.io/npm/v/snap-validate.svg?style=flat-square)](https://www.npmjs.com/package/snap-validate)
 [![Build Status](https://github.com/aniru-dh21/snap-validate/workflows/CI%2FCD%20Pipeline/badge.svg)](https://github.com/aniru-dh21/snap-validate/actions)
-[![Coverage Status](https://codecov.io/gh/aniru-dh21/snap-validate/branch/main/graph/badge.svg)](https://codecov.io/gh/aniru-dh21/snap-validate)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![install size](https://img.shields.io/badge/dynamic/json?url=https://packagephobia.com/v2/api.json?p=snap-validate&query=$.install.pretty&label=install%20size&style=flat-square)](https://packagephobia.now.sh/result?p=snap-validate)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/snap-validate?style=flat-square)](https://bundlephobia.com/package/snap-validate@latest)
+[![npm downloads](https://img.shields.io/npm/dm/snap-validate.svg?style=flat-square)](https://npm-stat.com/charts.html?package=snap-validate)
 
-A lightning-fast, lightweight validation library for common patterns without heavy dependencies. Perfect for client-side and server-side validation with zero external dependencies.
+A lightning-fast, lightweight validation library for common patterns without heavy dependencies. Perfect for client-side and server-side validation with zero external dependencies and built-in protection against ReDoS (Regular Expression Denial of Service) attacks.
 
 ## Features
 
@@ -14,6 +16,11 @@ A lightning-fast, lightweight validation library for common patterns without hea
 - 🔧 **Flexible**: Chainable validation rules and custom validators
 - 📧 **Common Patterns**: Email, phone, credit card, URL, password validation
 - 🌍 **International**: Support for different formats (US/International phone, postal codes)
+- 🔄 **Async Support**: Full async validation support for database checks and API calls
+- 🎯 **Conditional**: Advanced conditional validation with `when()` and `optional()`
+- 🛠️ **Custom Validators**: Add your own sync and async validation logic
+- 🔒 **Security First**: Built-in protection against ReDoS attacks and unsafe regex patterns
+- 🛡️ **Timeout Protection**: Configurable timeout for regex operations to prevent DoS attacks
 - 🧪 **Well Tested**: Comprehensive test suite with high coverage
 - 📦 **Easy Integration**: Works in Node.js and browsers
 - 🔗 **Chainable API**: Intuitive fluent interface
@@ -50,6 +57,30 @@ const result = validate(schema, data);
 console.log(result.isValid); // true
 ```
 
+## Security Features
+
+### ReDoS Protection
+
+Snap Validate includes built-in protection against Regular Expression Denial of Service (ReDoS) attacks:
+
+- **Regex Safety Detection**: Automatically detects and prevents potentially dangerous regex patterns
+- **Input Length Limits**: Protects against extremely long input strings (10,000 character limit)
+- **Timeout Protection**: Configurable timeout for regex operations (default: 1 second)
+- **Safe Defaults**: All predefined validators use safe, optimized regex patterns
+
+```javascript
+// Set custom timeout for regex operations
+const validator = new BaseValidator(value)
+  .setRegexTimeout(2000) // 2 second timeout
+  .pattern(/your-pattern/, 'Error message');
+
+// Use async pattern validation for complex patterns with timeout protection
+const validator = new BaseValidator(value)
+  .patternAsync(/complex-pattern/, 'Error message');
+
+const result = await validator.validateAsync();
+```
+
 ## Available Validators
 
 ### Email Validation
@@ -126,6 +157,122 @@ validators.zipCode('K1A 0A6', 'ca').validate();
 validators.zipCode('SW1A 1AA', 'uk').validate();
 ```
 
+## Advanced Validation Features
+
+### Conditional Validation
+
+```javascript
+const { BaseValidator } = require('snap-validate');
+
+// Validate only when condition is met
+const validator = new BaseValidator(value)
+  .when(user.isAdmin, validators.required('Admin field required'))
+  .min(5, 'Must be at least 5 characters');
+
+// Optional validation - skip if empty/null/undefined
+const optionalValidator = new BaseValidator(value)
+  .optional()
+  .email('Must be a valid email if provided');
+
+// Function-based conditions
+const conditionalValidator = new BaseValidator(value)
+  .when(() => user.role === 'admin', validators.required())
+  .max(100);
+```
+
+### Custom Validators
+
+```javascript
+const { BaseValidator } = require('snap-validate');
+
+// Synchronous custom validation
+const customValidator = new BaseValidator(value)
+  .custom((val) => val !== 'forbidden', 'Value cannot be forbidden')
+  .custom((val) => {
+    if (val.includes('admin') && !user.isAdmin) {
+      return 'Only admins can use this value';
+    }
+    return true;
+  });
+
+// Asynchronous custom validation
+const asyncValidator = new BaseValidator(email)
+  .email()
+  .customAsync(async (email) => {
+    const exists = await checkEmailExists(email);
+    return !exists || 'Email already exists';
+  }, 'Email validation failed');
+
+// Use async validation
+const result = await asyncValidator.validateAsync();
+```
+
+### Async Validation
+
+```javascript
+// Async validation for single field
+const validator = new BaseValidator(username)
+  .required()
+  .min(3)
+  .customAsync(async (username) => {
+    const available = await checkUsernameAvailable(username);
+    return available || 'Username is already taken';
+  });
+
+const result = await validator.validateAsync();
+
+// Async schema validation
+const asyncSchema = {
+  username: (value) => new BaseValidator(value)
+    .required()
+    .customAsync(async (val) => {
+      const available = await checkUsernameAvailable(val);
+      return available || 'Username taken';
+    }),
+  
+  email: (value) => validators.email(value)
+    .customAsync(async (val) => {
+      const exists = await checkEmailExists(val);
+      return !exists || 'Email already registered';
+    })
+};
+
+const asyncResult = await validate.async(asyncSchema, userData);
+```
+
+## Security and Pattern Validation
+
+### Safe Pattern Validation
+
+```javascript
+const { BaseValidator } = require('snap-validate');
+
+// Synchronous pattern validation with built-in safety checks
+const validator = new BaseValidator(value)
+  .pattern(/^[a-zA-Z0-9]+$/, 'Only alphanumeric characters allowed');
+
+// Asynchronous pattern validation with timeout protection
+const asyncValidator = new BaseValidator(value)
+  .patternAsync(/^[a-zA-Z0-9]+$/, 'Only alphanumeric characters allowed')
+  .setRegexTimeout(5000); // 5 second timeout
+
+const result = await asyncValidator.validateAsync();
+```
+
+### Configurable Security Settings
+
+```javascript
+const validator = new BaseValidator(value)
+  .setRegexTimeout(3000) // Set custom timeout (3 seconds)
+  .pattern(/your-pattern/, 'Error message');
+
+// The library automatically:
+// - Detects unsafe regex patterns
+// - Limits input length to prevent ReDoS
+// - Applies timeout protection for complex patterns
+// - Provides clear error messages for security violations
+```
+
 ## Custom Validation
 
 ### Using BaseValidator
@@ -157,6 +304,7 @@ const schema = {
   age: (value) => new BaseValidator(value)
     .required()
     .pattern(/^\d+$/, 'Age must be a number')
+    .custom((val) => parseInt(val) >= 18, 'Must be 18 or older')
 };
 
 const userData = {
@@ -185,6 +333,23 @@ if (!schemaResult.isValid) {
   console.log('Field errors:', errors);
   // Output: { email: ['Invalid email format'], password: ['Password too weak'] }
 }
+
+// Async error handling
+try {
+  const asyncResult = await validator.validateAsync();
+  if (!asyncResult.isValid) {
+    console.log('Async validation errors:', asyncResult.errors);
+  }
+} catch (error) {
+  console.log('Validation exception:', error.message);
+}
+
+// Security-related errors
+const unsafeResult = validator.pattern(/potentially-dangerous-pattern/, 'Error').validate();
+if (!unsafeResult.isValid) {
+  console.log('Security errors:', unsafeResult.errors);
+  // Output: ['Potentially unsafe regex pattern detected']
+}
 ```
 
 ## Browser Usage
@@ -211,8 +376,15 @@ if (!schemaResult.isValid) {
 - `required(message?)` - Field is required
 - `min(length, message?)` - Minimum length validation
 - `max(length, message?)` - Maximum length validation
-- `pattern(regex, message?)` - Pattern matching validation
-- `validate()` - Execute validation and return result
+- `pattern(regex, message?)` - Pattern matching validation with safety checks
+- `patternAsync(regex, message?)` - Async pattern validation with timeout protection
+- `setRegexTimeout(timeoutMs)` - Set custom timeout for regex operations
+- `when(condition, validator)` - Conditional validation
+- `optional()` - Skip validation if empty/null/undefined
+- `custom(fn, message?)` - Custom synchronous validation
+- `customAsync(fn, message?)` - Custom asynchronous validation
+- `validate()` - Execute synchronous validation
+- `validateAsync()` - Execute asynchronous validation
 
 ### Available Validators
 
@@ -225,6 +397,23 @@ if (!schemaResult.isValid) {
 - `validators.numeric(value)`
 - `validators.zipCode(value, country?)`
 
+### Validation Functions
+
+- `validate(schema, data)` - Synchronous schema validation
+- `validate.async(schema, data)` - Asynchronous schema validation
+
+### Security Functions
+
+- `isRegexSafe(regex)` - Check if a regex pattern is safe to use
+- `safeRegexText(regex, str, timeoutMs)` - Execute regex with timeout protection
+
+## Security Best Practices
+
+1. **Use Built-in Validators**: The predefined validators are optimized for security and performance
+2. **Validate Input Length**: Large inputs are automatically limited to prevent ReDoS attacks
+3. **Set Appropriate Timeouts**: Configure regex timeouts based on your application's needs
+4. **Test Custom Patterns**: Use `isRegexSafe()` to check custom regex patterns before deployment
+5. **Handle Async Errors**: Always use try-catch blocks with async validation
 
 ## Contributing
 
@@ -256,6 +445,9 @@ npm run lint
 
 # Format code
 npm run format
+
+# Security audit
+npm audit
 ```
 
 ## License
@@ -264,15 +456,8 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Changelog
 
-### v0.1.0
-
-- Initial release
-- Basic validation patterns (email, phone, credit card, URL, password)
-- Schema validation support
-- Comprehensive test suite
-- CI/CD pipeline setup
-- Lightning-fast performance optimizations
+See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.
 
 ---
 
-Made with ⚡ by [Ramachandra Anirudh Vemulapalli](https://github.com/aniru-dh21)
+Made with ⚡ by [Ramachandra Anirudh Vemulapalli](https://github.com/aniru-dh21)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snap-validate",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Lightweight validation library for common patterns without heavy dependencies",
   "main": "src/index.js",
   "types": "types/index.d.ts",

package/src/index.js

@@ -1,8 +1,77 @@
 /**
- * Snap Validate - Lightweight validator library
- * @version 0.0.1
+ * Snap Validate - Enhanced Lightweight validator library
+ * @version 0.3.1 - Security Fixes
  */
 
+// Utility function to safely test regex with timeout protection
+// Utility function to safely test regex with timeout protection
+const safeRegexTest = (regex, str, timeoutMs = 1000) => {
+  return new Promise((resolve, reject) => {
+    // SECURITY FIX: Add input length validation before regex test
+    if (str.length > 10000) {
+      reject(new Error('Input too long for regex validation'));
+      return;
+    }
+
+    // SECURITY FIX: Add regex safety check before execution
+    if (!isRegexSafe(regex)) {
+      reject(new Error('Unsafe regex pattern detected'));
+      return;
+    }
+
+    const timeout = setTimeout(() => {
+      reject(new Error('Regex execution timeout - potential ReDoS attack'));
+    }, timeoutMs);
+
+    try {
+      const result = regex.test(str);
+      clearTimeout(timeout);
+      resolve(result);
+    } catch (error) {
+      clearTimeout(timeout);
+      reject(error);
+    }
+  });
+};
+
+// Synchronous safe regex test with input length protection
+const safeRegexTestSync = (regex, str, maxLength = 10000) => {
+  // Limit input length to prevent ReDoS
+  if (str.length > maxLength) {
+    throw new Error('Input too long for pattern validation');
+  }
+
+  // For additional safety, we could add a timeout using a worker thread or 
+  // other mechanism, but for now we rely on input length limiting
+  return regex.test(str);
+};
+
+// Function to detect potentially dangerous regex patterns
+const isRegexSafe = (regex) => {
+  const regexStr = regex.toString();
+
+  // Check for common ReDoS patterns - more precise detection
+  const dangerousPatterns = [
+    // Nested quantifiers like (a+)+ or (a*)* or (a?)?
+    /\([^)]*[+*?][^)]*\)[+*?]/,
+    // Alternation with overlapping and quantifiers like (a|a)*
+    /\([^)]*\|[^)]*\)[+*]/,
+    // Catastrophic backtracking with greedy quantifiers
+    /\([^)]*\.\*[^)]*\)\*/,
+    // Multiple consecutive quantifiers (not separated by characters)
+    /[+*?]{2,}/,
+    // Exponential alternation patterns
+    /\([^)]*\|[^)]*\)\+.*\([^)]*\|[^)]*\)\+/
+  ];
+
+  // Check if the pattern has obvious ReDoS vulnerabilities
+  const isDangerous = dangerousPatterns.some((pattern) =>
+    pattern.test(regexStr)
+  );
+
+  return !isDangerous;
+};
+
 // Core validation class
 class ValidationResult {
   constructor(isValid, errors = []) {
@@ -22,11 +91,26 @@ class BaseValidator {
   constructor(value) {
     this.value = value;
     this.rules = [];
+    this.asyncRules = [];
+    this.isOptional = false;
+    this.regexTimeout = 1000; // Default timeout for regex operations
   }
 
   required(message = 'This field is required') {
     this.rules.push(() => {
-      if (this.value === null || this.value === undefined || this.value === '') {
+      // Skip validation if optional and empty
+      if (
+        this.isOptional &&
+        (this.value === null || this.value === undefined || this.value === '')
+      ) {
+        return new ValidationResult(true);
+      }
+
+      if (
+        this.value === null ||
+        this.value === undefined ||
+        this.value === ''
+      ) {
         return new ValidationResult(false, [message]);
       }
       return new ValidationResult(true);
@@ -34,10 +118,43 @@ class BaseValidator {
     return this;
   }
 
+  optional() {
+    this.isOptional = true;
+    return this;
+  }
+
+  setRegexTimeout(timeoutMs) {
+    this.regexTimeout = timeoutMs;
+    return this;
+  }
+
   min(length, message = `Minimum length is ${length}`) {
     this.rules.push(() => {
-      if (this.value && this.value.length < length) {
-        return new ValidationResult(false, [message]);
+      // Skip validation if optional and empty
+      if (
+        this.isOptional &&
+        (this.value === null || this.value === undefined || this.value === '')
+      ) {
+        return new ValidationResult(true);
+      }
+
+      // Only validate if value exists and a length property
+      if (this.value != null && this.value !== '') {
+        // Check if value has length property (string, array)
+        if (typeof this.value === 'string' || Array.isArray(this.value)) {
+          if (this.value.length < length) {
+            return new ValidationResult(false, [message]);
+          }
+        } else if (typeof this.value === 'number') {
+          // For numbers, compare the value itself
+          if (this.value < length) {
+            return new ValidationResult(false, [message]);
+          }
+        } else {
+          return new ValidationResult(false, [
+            'Value must be a string, array, or number'
+          ]);
+        }
       }
       return new ValidationResult(true);
     });
@@ -46,8 +163,31 @@ class BaseValidator {
 
   max(length, message = `Maximum length is ${length}`) {
     this.rules.push(() => {
-      if (this.value && this.value.length > length) {
-        return new ValidationResult(false, [message]);
+      // Skip validation if optional and empty
+      if (
+        this.isOptional &&
+        (this.value === null || this.value === undefined || this.value === '')
+      ) {
+        return new ValidationResult(true);
+      }
+
+      // Only validate if value exists and has a length property
+      if (this.value != null && this.value !== '') {
+        // Check if value has length property (string, array)
+        if (typeof this.value === 'string' || Array.isArray(this.value)) {
+          if (this.value.length > length) {
+            return new ValidationResult(false, [message]);
+          }
+        } else if (typeof this.value === 'number') {
+          // For numbers, compare the value itself
+          if (this.value > length) {
+            return new ValidationResult(false, [message]);
+          }
+        } else {
+          return new ValidationResult(false, [
+            'Value must be a string, array or number'
+          ]);
+        }
       }
       return new ValidationResult(true);
     });
@@ -55,23 +195,246 @@ class BaseValidator {
   }
 
   pattern(regex, message = 'Invalid format') {
+    // SECURITY FIX: Add regex safety check
+    if (!isRegexSafe(regex)) {
+      throw new Error(
+        'Potentially unsafe regex pattern detected. Please use a simple pattern.'
+      );
+    }
+
     this.rules.push(() => {
-      if (this.value && !regex.test(this.value)) {
-        return new ValidationResult(false, [message]);
+      // Skip validation if optional and empty
+      if (
+        this.isOptional &&
+        (this.value === null || this.value === undefined || this.value === '')
+      ) {
+        return new ValidationResult(true);
+      }
+
+      // Only test pattern if value exists and is not empty
+      if (this.value != null && this.value !== '') {
+        // Ensure value is a string before testing regex
+        const stringValue = String(this.value);
+
+        try {
+          // SECURITY FIX: Use safe regex test with input length protection
+          if (!safeRegexTestSync(regex, stringValue)) {
+            return new ValidationResult(false, [message]);
+          }
+        } catch (error) {
+          if (error.message.includes('Input too long')) {
+            return new ValidationResult(false, [
+              'Input too long for pattern validation'
+            ]);
+          }
+          return new ValidationResult(false, ['Pattern validation failed']);
+        }
+      }
+      return new ValidationResult(true);
+    });
+    return this;
+  }
+
+  // New method for async pattern validation with timeout protection
+  patternAsync(regex, message = 'Invalid format') {
+    // Security Fix: Add regex safety check
+    if (!isRegexSafe(regex)) {
+      throw new Error(
+        'Potentially unsafe regex pattern detected. Please use a simple pattern.'
+      );
+    }
+
+    this.asyncRules.push(async () => {
+      // Skip validation if optional and empty
+      if (
+        this.isOptional &&
+        (this.value === null || this.value === undefined || this.value === '')
+      ) {
+        return new ValidationResult(true);
+      }
+
+      // Only test pattern if value exists and is not empty
+      if (this.value != null && this.value !== '') {
+        // Ensure value is a string before testing regex
+        const stringValue = String(this.value);
+
+        // Security Fix: Limit input length to prevent ReDoS
+        if (stringValue.length > 10000) {
+          return new ValidationResult(false, [
+            'Input too long for pattern validation'
+          ]);
+        }
+
+        try {
+          // Security Fix: Use timeout protection for regex execution
+          const result = await safeRegexTest(
+            regex,
+            stringValue,
+            this.regexTimeout
+          );
+          if (!result) {
+            return new ValidationResult(false, [message]);
+          }
+        } catch (error) {
+          if (error.message.includes('timeout')) {
+            return new ValidationResult(false, [
+              'Pattern validation timeout - pattern too complex'
+            ]);
+          }
+          return new ValidationResult(false, ['Pattern validation failed']);
+        }
+      }
+      return new ValidationResult(true);
+    });
+    return this;
+  }
+
+  when(condition, validator) {
+    this.rules.push(() => {
+      // Evaluate condition
+      const shouldValidate =
+        typeof condition === 'function' ? condition(this.value) : condition;
+
+      if (shouldValidate) {
+        // Apply the conditional validator
+        if (typeof validator === 'function') {
+          const conditionalValidator = validator(this.value);
+          return conditionalValidator.validate();
+        } else {
+          // If validator is already a BaseValidator instance
+          return validator.validate();
+        }
       }
+
       return new ValidationResult(true);
     });
     return this;
   }
 
+  custom(validatorFn, message = 'Custom validation failed') {
+    this.rules.push(() => {
+      // Skip validation if optional and empty
+      if (
+        this.isOptional &&
+        (this.value === null || this.value === undefined || this.value === '')
+      ) {
+        return new ValidationResult(true);
+      }
+
+      try {
+        const result = validatorFn(this.value);
+
+        // Handle boolean result
+        if (typeof result === 'boolean') {
+          return result
+            ? new ValidationResult(true)
+            : new ValidationResult(false, [message]);
+        }
+
+        // Handle ValidationResult object
+        if (result && typeof result === 'object' && 'isValid' in result) {
+          return result;
+        }
+
+        // Handle string result (error message)
+        if (typeof result === 'string') {
+          return new ValidationResult(false, [result]);
+        }
+
+        // Default to true if no clear result
+        return new ValidationResult(true);
+      } catch (error) {
+        return new ValidationResult(false, [
+          `Custom validation error: ${error.message}`
+        ]);
+      }
+    });
+    return this;
+  }
+
+  customAsync(validatorFn, message = 'Async validation failed') {
+    this.asyncRules.push(async () => {
+      // Skip validation if optional and empty
+      if (
+        this.isOptional &&
+        (this.value === null || this.value === undefined || this.value === '')
+      ) {
+        return new ValidationResult(true);
+      }
+
+      try {
+        const result = await validatorFn(this.value);
+
+        // Handle boolean result
+        if (typeof result === 'boolean') {
+          return result
+            ? new ValidationResult(true)
+            : new ValidationResult(false, [message]);
+        }
+
+        // Handle ValidationResult object
+        if (result && typeof result === 'object' && 'isValid' in result) {
+          return result;
+        }
+
+        // Handle string result (error message)
+        if (typeof result === 'string') {
+          return new ValidationResult(false, [result]);
+        }
+
+        // Default to true if no clear result
+        return new ValidationResult(true);
+      } catch (error) {
+        return new ValidationResult(false, [
+          `Async validation error: ${error.message}`
+        ]);
+      }
+    });
+    return this;
+  }
+
   validate() {
     const result = new ValidationResult(true);
 
     for (const rule of this.rules) {
-      const ruleResult = rule();
-      if (!ruleResult.isValid) {
+      try {
+        const ruleResult = rule();
+        if (!ruleResult.isValid) {
+          result.isValid = false;
+          result.errors.push(...ruleResult.errors);
+        }
+      } catch (error) {
+        // Handle any unexpected errors during validation
+        result.isValid = false;
+        result.errors.push(`Validation error: ${error.message}`);
+      }
+    }
+
+    return result;
+  }
+
+  async validateAsync() {
+    // First run synchronous validations
+    const syncResult = this.validate();
+
+    if (!syncResult.isValid) {
+      return syncResult;
+    }
+
+    // Then run asynchronous validations
+    const result = new ValidationResult(true, [...syncResult.errors]);
+
+    for (const asyncRule of this.asyncRules) {
+      try {
+        const ruleResult = await asyncRule();
+        if (!ruleResult.isValid) {
+          result.isValid = false;
+          result.errors.push(...ruleResult.errors);
+        }
+      } catch (error) {
+        // Handle any unexpected errors during async validation
         result.isValid = false;
-        result.errors.push(...ruleResult.errors);
+        result.errors.push(`Async validation error: ${error.message}`);
       }
     }
 
@@ -80,6 +443,7 @@ class BaseValidator {
 }
 
 // Predefined validators
+// Security Fix: Updated predefined validators with safer regex patterns
 const validators = {
   email: (value) => {
     const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
@@ -89,15 +453,25 @@ const validators = {
   },
 
   phone: (value, format = 'us') => {
+    // FIXED: Much simpler phone regex patterns to avoid ReDoS detection
     const phoneRegex = {
-      us: /^\+?1?[-.\s]?\(?([0-9]{3})\)?[-.\s]?([0-9]{3})[-.\s]?([0-9]{4})$/,
-      international: /^\+[1-9]\d{1,14}$/,
-      simple: /^\d{10,15}$/
+      us: /^[+]?[1]?[0-9]{10}$/,
+      international: /^[+][1-9][0-9]{7,14}$/,
+      simple: /^[0-9]{10,15}$/
     };
 
     return new BaseValidator(value)
       .required('Phone number is required')
-      .pattern(phoneRegex[format] || phoneRegex.simple, 'Invalid phone number format');
+      .custom((val) => {
+        // Remove all non-digit characters except +
+        const cleaned = String(val).replace(/[^+0-9]/g, '');
+        const regex = phoneRegex[format] || phoneRegex.simple;
+
+        if (!safeRegexTestSync(regex, cleaned)) {
+          return 'Invalid phone number format';
+        }
+        return true;
+      });
   },
 
   creditCard: (value) => {
@@ -106,8 +480,11 @@ const validators = {
       let sum = 0;
       let isEven = false;
 
-      for (let i = num.length - 1; i >= 0; i--) {
-        let digit = parseInt(num[i]);
+      // Remove spaces and ensure we have a string
+      const cleanNum = String(num).replace(/\s/g, '');
+
+      for (let i = cleanNum.length - 1; i >= 0; i--) {
+        let digit = parseInt(cleanNum[i]);
 
         if (isEven) {
           digit *= 2;
@@ -121,13 +498,36 @@ const validators = {
       return sum % 10 === 0;
     };
 
-    const validator = new BaseValidator(value)
-      .required('Credit card number is required')
-      .pattern(/^\d{13,19}$/, 'Credit card must be 13-19 digits');
+    const validator = new BaseValidator(value).required(
+      'Credit card number is required'
+    );
 
+    // Add custom validation for credit card format and Luhn check
     validator.rules.push(() => {
-      if (value && !luhnCheck(value.replace(/\s/g, ''))) {
-        return new ValidationResult(false, ['Invalid credit card number']);
+      // Skip validation if optional and empty
+      if (
+        validator.isOptional &&
+        (validator.value === null ||
+          validator.value === undefined ||
+          validator.value === '')
+      ) {
+        return new ValidationResult(true);
+      }
+
+      if (validator.value) {
+        const cleanValue = String(validator.value).replace(/\s/g, '');
+
+        // Check length (13-19 digits) using safe regex
+        if (!safeRegexTestSync(/^\d{13,19}$/, cleanValue)) {
+          return new ValidationResult(false, [
+            'Credit card must be 13-19 digits'
+          ]);
+        }
+
+        // Check Luhn algorithm
+        if (!luhnCheck(cleanValue)) {
+          return new ValidationResult(false, ['Invalid credit card number']);
+        }
       }
       return new ValidationResult(true);
     });
@@ -156,16 +556,25 @@ const validators = {
       .min(minLength, `Password must be at least ${minLength} characters`);
 
     if (requireUppercase) {
-      validator.pattern(/[A-Z]/, 'Password must contain at least one uppercase letter');
+      validator.pattern(
+        /[A-Z]/,
+        'Password must contain at least one uppercase letter'
+      );
     }
     if (requireLowercase) {
-      validator.pattern(/[a-z]/, 'Password must contain at least one lowercase letter');
+      validator.pattern(
+        /[a-z]/,
+        'Password must contain at least one lowercase letter'
+      );
     }
     if (requireNumbers) {
       validator.pattern(/\d/, 'Password must contain at least one number');
     }
     if (requireSpecialChars) {
-      validator.pattern(/[!@#$%^&*(),.?":{}|<>]/, 'Password must contain at least one special character');
+      validator.pattern(
+        /[!@#$%^&*(),.?":{}|<>]/,
+        'Password must contain at least one special character'
+      );
     }
 
     return validator;
@@ -174,7 +583,7 @@ const validators = {
   alphanumeric: (value) => {
     return new BaseValidator(value)
       .required('This field is required')
-      .pattern(/^[a-zA-Z0-9]+$/, 'Only letters and number are allowed');
+      .pattern(/^[a-zA-Z0-9]+$/, 'Only letters and numbers are allowed');
   },
 
   numeric: (value) => {
@@ -198,17 +607,95 @@ const validators = {
 
 // Main validation function
 const validate = (schema, data) => {
+  // Input validation
+  if (!schema || typeof schema !== 'object') {
+    throw new Error('Schema must be a valid object');
+  }
+
+  if (!data || typeof data !== 'object') {
+    throw new Error('Data must be a valid object');
+  }
+
+  const results = {};
+  let isValid = true;
+
+  for (const [field, validator] of Object.entries(schema)) {
+    try {
+      const fieldValue = data[field];
+      const result =
+        typeof validator === 'function'
+          ? validator(fieldValue).validate()
+          : validator.validate();
+
+      results[field] = result;
+      if (!result.isValid) {
+        isValid = false;
+      }
+    } catch (error) {
+      // Handle validation setup errors
+      results[field] = new ValidationResult(false, [
+        `Validation setup error: ${error.message}`
+      ]);
+      isValid = false;
+    }
+  }
+
+  return {
+    isValid,
+    errors: results,
+    getErrors: () => {
+      const errors = {};
+      for (const [field, result] of Object.entries(results)) {
+        if (!result.isValid) {
+          errors[field] = result.errors;
+        }
+      }
+      return errors;
+    }
+  };
+};
+
+// Async validation function
+const validateAsync = async (schema, data) => {
+  // Input validation
+  if (!schema || typeof schema !== 'object') {
+    throw new Error('Schema must be a valid object');
+  }
+
+  if (!data || typeof data !== 'object') {
+    throw new Error('Data must be a valid object');
+  }
+
   const results = {};
   let isValid = true;
 
   for (const [field, validator] of Object.entries(schema)) {
-    const fieldValue = data[field];
-    const result = typeof validator === 'function'
-      ? validator(fieldValue).validate()
-      : validator.validate();
+    try {
+      const fieldValue = data[field];
+
+      let result;
+      if (typeof validator === 'function') {
+        const validatorInstance = validator(fieldValue);
+        result =
+          validatorInstance.asyncRules.length > 0
+            ? await validatorInstance.validateAsync()
+            : validatorInstance.validate();
+      } else {
+        result =
+          validator.asyncRules && validator.asyncRules.length > 0
+            ? await validator.validateAsync()
+            : validator.validate();
+      }
 
-    results[field] = result;
-    if (!result.isValid) {
+      results[field] = result;
+      if (!result.isValid) {
+        isValid = false;
+      }
+    } catch (error) {
+      // Handle validation setup errors
+      results[field] = new ValidationResult(false, [
+        `Validation setup error: ${error.message}`
+      ]);
       isValid = false;
     }
   }
@@ -232,5 +719,9 @@ module.exports = {
   BaseValidator,
   ValidationResult,
   validators,
-  validate
+  validate,
+  validateAsync,
+  safeRegexTest,
+  safeRegexTestSync,
+  isRegexSafe
 };

package/types/index.d.ts

@@ -1,10 +1,17 @@
-declare module 'mini-validator' {
-  export interface ValidationResult {
+declare module 'snap-validate' {
+  /**
+   * Result of a validation operation
+   */
+  export class ValidationResult {
+    constructor(isValid: boolean, errors?: string[]);
     isValid: boolean;
     errors: string[];
     addError(message: string): ValidationResult;
   }
 
+  /**
+   * Password validation options
+   */
   export interface PasswordOptions {
     minLength?: number;
     requireUppercase?: boolean;
@@ -13,25 +20,113 @@ declare module 'mini-validator' {
     requireSpecialChars?: boolean;
   }
 
+  /**
+   * Phone number format types
+   */
   export type PhoneFormat = 'us' | 'international' | 'simple';
+
+  /**
+   * Country codes for zip code validation
+   */
   export type CountryCode = 'us' | 'ca' | 'uk';
 
+  /**
+   * Custom validation function that returns boolean
+   */
+  export type CustomValidatorFunction = (
+    value: any
+  ) => boolean | string | ValidationResult;
+
+  /**
+   * Async custom validation function
+   */
+  export type AsyncValidatorFunction = (
+    value: any
+  ) => Promise<boolean | string | ValidationResult>;
+
+  /**
+   * Conditional validation condition
+   */
+  export type ConditionalFunction = (value: any) => boolean;
+
+  /**
+   * Conditional validator function
+   */
+  export type ConditionalValidatorFunction = (value: any) => BaseValidator;
+
+  /**
+   * Base validator class with chainable validation methods
+   */
   export class BaseValidator {
     constructor(value: any);
+    value: any;
+    rules: Array<() => ValidationResult>;
+    asyncRules: Array<() => Promise<ValidationResult>>;
+    isOptional: boolean;
+
+    /**
+     * Make field required
+     */
     required(message?: string): BaseValidator;
+
+    /**
+     * Make field optional (skips validation if empty)
+     */
+    optional(): BaseValidator;
+
+    /**
+     * Set minimum length/value
+     */
     min(length: number, message?: string): BaseValidator;
+
+    /**
+     * Set maximum length/value
+     */
     max(length: number, message?: string): BaseValidator;
+
+    /**
+     * Validate against regex pattern
+     */
     pattern(regex: RegExp, message?: string): BaseValidator;
+
+    /**
+     * Conditional validation
+     */
+    when(
+      condition: boolean | ConditionalFunction,
+      validator: BaseValidator | ConditionalValidatorFunction
+    ): BaseValidator;
+
+    /**
+     * Custom synchronous validation
+     */
+    custom(
+      validatorFn: CustomValidatorFunction,
+      message?: string
+    ): BaseValidator;
+
+    /**
+     * Custom asynchronous validation
+     */
+    customAsync(
+      validatorFn: AsyncValidatorFunction,
+      message?: string
+    ): BaseValidator;
+
+    /**
+     * Execute synchronous validation
+     */
     validate(): ValidationResult;
-  }
 
-  export class ValidationResult {
-    constructor(isValid: boolean, errors?: string[]);
-    isValid: boolean;
-    errors: string[];
-    addError(message: string): ValidationResult;
+    /**
+     * Execute asynchronous validation (includes sync rules)
+     */
+    validateAsync(): Promise<ValidationResult>;
   }
 
+  /**
+   * Predefined validators
+   */
   export interface Validators {
     email(value: string): BaseValidator;
     phone(value: string, format?: PhoneFormat): BaseValidator;
@@ -43,18 +138,43 @@ declare module 'mini-validator' {
     zipCode(value: string, country?: CountryCode): BaseValidator;
   }
 
+  /**
+   * Result of schema validation
+   */
   export interface SchemaValidationResult {
     isValid: boolean;
     errors: { [field: string]: ValidationResult };
     getErrors(): { [field: string]: string[] };
   }
 
+  /**
+   * Validation function type for schema
+   */
   export type ValidationFunction = (value: any) => BaseValidator;
-  export type Schema = { [field: string]: ValidationFunction };
 
+  /**
+   * Schema definition type
+   */
+  export type Schema = { [field: string]: ValidationFunction | BaseValidator };
+
+  /**
+   * Predefined validator instances
+   */
   export const validators: Validators;
+
+  /**
+   * Validate data against schema synchronously
+   */
   export function validate(
     schema: Schema,
     data: { [key: string]: any }
   ): SchemaValidationResult;
+
+  /**
+   * Validate data against schema asynchronously
+   */
+  export function validateAsync(
+    schema: Schema,
+    data: { [key: string]: any }
+  ): Promise<SchemaValidationResult>;
 }