snap-validate 0.2.0 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Mini Validator Contributors
+Copyright (c) 2025 Snap Validate Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1,9 +1,9 @@
 # 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)
+[![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.
 
@@ -14,6 +14,9 @@ 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
 - 🧪 **Well Tested**: Comprehensive test suite with high coverage
 - 📦 **Easy Integration**: Works in Node.js and browsers
 - 🔗 **Chainable API**: Intuitive fluent interface
@@ -126,6 +129,89 @@ 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);
+```
+
 ## Custom Validation
 
 ### Using BaseValidator
@@ -157,6 +243,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 +272,16 @@ 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);
+}
 ```
 
 ## Browser Usage
@@ -212,7 +309,12 @@ if (!schemaResult.isValid) {
 - `min(length, message?)` - Minimum length validation
 - `max(length, message?)` - Maximum length validation
 - `pattern(regex, message?)` - Pattern matching validation
-- `validate()` - Execute validation and return result
+- `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 +327,10 @@ 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
 
 ## Contributing
 
@@ -264,14 +370,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## Changelog
 
-### v1.0.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.
 
 ---
 

package/package.json

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

package/src/index.js

@@ -1,6 +1,6 @@
 /**
- * Snap Validate - Lightweight validator library
- * @version 0.0.1
+ * Snap Validate - Enhanced Lightweight validator library
+ * @version 0.3.0
  */
 
 // Core validation class
@@ -22,10 +22,17 @@ class BaseValidator {
   constructor(value) {
     this.value = value;
     this.rules = [];
+    this.asyncRules = [];
+    this.isOptional = false;
   }
 
   required(message = 'This field is required') {
     this.rules.push(() => {
+      // 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]);
       }
@@ -34,10 +41,33 @@ class BaseValidator {
     return this;
   }
 
+  optional() {
+    this.isOptional = true;
+    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 +76,26 @@ 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);
     });
@@ -56,22 +104,155 @@ class BaseValidator {
 
   pattern(regex, message = 'Invalid format') {
     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);
+        if (!regex.test(stringValue)) {
+          return new ValidationResult(false, [message]);
+        }
+      }
+      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}`);
       }
     }
 
@@ -106,8 +287,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;
@@ -122,12 +306,27 @@ const validators = {
     };
 
     const validator = new BaseValidator(value)
-      .required('Credit card number is required')
-      .pattern(/^\d{13,19}$/, 'Credit card must be 13-19 digits');
+      .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)
+        if (!/^\d{13,19}$/.test(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);
     });
@@ -174,7 +373,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 +397,88 @@ 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 +502,6 @@ module.exports = {
   BaseValidator,
   ValidationResult,
   validators,
-  validate
+  validate,
+  validateAsync
 };

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>;
 }