snap-validate 0.4.1 → 0.4.3

package/src/schema/runner.js

@@ -0,0 +1,32 @@
+/**
+ * Snap Validate - Shared schema-runner helpers
+ * Extracted from the duplicated bodies of validate / validateAsync.
+ */
+
+function assertSchemaAndData(schema, data) {
+  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');
+  }
+}
+
+function buildResponse(results, isValid) {
+  return {
+    isValid,
+    errors: results,
+    getErrors: () => {
+      const errors = {};
+      for (const [field, result] of Object.entries(results)) {
+        if (!result.isValid) {
+          errors[field] = result.errors;
+        }
+      }
+      return errors;
+    }
+  };
+}
+
+module.exports = { assertSchemaAndData, buildResponse };

package/src/schema/validate.js

@@ -0,0 +1,78 @@
+/**
+ * Snap Validate - Schema validation entry points
+ */
+
+const { ValidationResult } = require('../core/ValidationResult');
+const { assertSchemaAndData, buildResponse } = require('./runner');
+
+// Main validation function
+const validate = (schema, data) => {
+  assertSchemaAndData(schema, data);
+
+  const results = {};
+  let isValid = true;
+
+  for (const [field, validator] of Object.entries(schema)) {
+    try {
+      const fieldValue = data[field];
+      const validatorInstance =
+        typeof validator === 'function' ? validator(fieldValue) : validator;
+
+      // Set field name for better error context
+      validatorInstance.setFieldName(field);
+
+      const result = validatorInstance.validate();
+
+      results[field] = result;
+      if (!result.isValid) {
+        isValid = false;
+      }
+    } catch (error) {
+      results[field] = new ValidationResult(false, [
+        `${field}: Validation setup error - ${error.message}`
+      ]);
+      isValid = false;
+    }
+  }
+
+  return buildResponse(results, isValid);
+};
+
+// Async validation function
+const validateAsync = async (schema, data) => {
+  assertSchemaAndData(schema, data);
+
+  const results = {};
+  let isValid = true;
+
+  for (const [field, validator] of Object.entries(schema)) {
+    try {
+      const fieldValue = data[field];
+
+      const validatorInstance =
+        typeof validator === 'function' ? validator(fieldValue) : validator;
+
+      // Set field name for better error context
+      validatorInstance.setFieldName(field);
+
+      const result =
+        validatorInstance.asyncRules && validatorInstance.asyncRules.length > 0
+          ? await validatorInstance.validateAsync()
+          : validatorInstance.validate();
+
+      results[field] = result;
+      if (!result.isValid) {
+        isValid = false;
+      }
+    } catch (error) {
+      results[field] = new ValidationResult(false, [
+        `${field}: Validation setup error - ${error.message}`
+      ]);
+      isValid = false;
+    }
+  }
+
+  return buildResponse(results, isValid);
+};
+
+module.exports = { validate, validateAsync };

package/src/utils/safeRegex.js

@@ -0,0 +1,72 @@
+/**
+ * Snap Validate - Safe regex utilities
+ *
+ * Honest note on ReDoS protection
+ * --------------------------------
+ * JavaScript runs regexes synchronously on a single thread, so a timer CANNOT
+ * interrupt a regex that is mid-backtrack: the event loop is blocked until
+ * regex.test() returns on its own. This module therefore does NOT attempt
+ * (fake) timeout-based interruption. The protections that actually work are:
+ *   1. an input-length cap, which rejects oversized inputs before matching; and
+ *   2. isRegexSafe(), a best-effort STATIC check that flags a few common
+ *      catastrophic-backtracking shapes.
+ * isRegexSafe is a heuristic - it can miss dangerous patterns and can
+ * occasionally over-reject safe ones. For guaranteed linear-time matching you
+ * need a non-backtracking engine (e.g. the native `re2` module) or a worker /
+ * subprocess with a real timeout.
+ */
+
+const MAX_INPUT_LENGTH = 10000;
+
+// Best-effort STATIC detection of a few catastrophic-backtracking shapes.
+// Heuristic only - see the module note above.
+const isRegexSafe = (regex) => {
+  const regexStr = regex.toString();
+
+  const dangerousPatterns = [
+    /\([^)]*[+*?][^)]*\)[+*?]/,
+    /\([^)]*\|[^)]*\)[+*]/,
+    /\([^)]*\.\*[^)]*\)\*/,
+    /[+*?]{2,}/,
+    /\([^)]*\|[^)]*\)\+.*\([^)]*\|[^)]*\)\+/
+  ];
+
+  const isDangerous = dangerousPatterns.some((pattern) =>
+    pattern.test(regexStr)
+  );
+
+  return !isDangerous;
+};
+
+// Asynchronous wrapper, kept returning a Promise for API compatibility.
+// Applies the two REAL guards (length cap + static safety check) and then runs
+// the match. It does NOT - and cannot - interrupt a running regex.
+const safeRegexTest = (regex, str) => {
+  return new Promise((resolve, reject) => {
+    if (str.length > MAX_INPUT_LENGTH) {
+      reject(new Error('Input too long for regex validation'));
+      return;
+    }
+
+    if (!isRegexSafe(regex)) {
+      reject(new Error('Unsafe regex pattern detected'));
+      return;
+    }
+
+    try {
+      resolve(regex.test(str));
+    } catch (error) {
+      reject(error);
+    }
+  });
+};
+
+// Synchronous safe regex test with input-length protection.
+const safeRegexTestSync = (regex, str, maxLength = MAX_INPUT_LENGTH) => {
+  if (str.length > maxLength) {
+    throw new Error('Input too long for pattern validation');
+  }
+  return regex.test(str);
+};
+
+module.exports = { isRegexSafe, safeRegexTest, safeRegexTestSync };

package/src/validators/alphanumeric.js

@@ -0,0 +1,9 @@
+const { BaseValidator } = require('../core/BaseValidator');
+
+const alphanumeric = (value) => {
+  return new BaseValidator(value)
+    .required('This field is required')
+    .pattern(/^[a-zA-Z0-9]+$/, 'Only letters and numbers are allowed');
+};
+
+module.exports = { alphanumeric };

package/src/validators/creditCard.js

@@ -0,0 +1,49 @@
+const { BaseValidator } = require('../core/BaseValidator');
+const { safeRegexTestSync } = require('../utils/safeRegex');
+
+const luhnCheck = (num) => {
+  let sum = 0;
+  let isEven = false;
+
+  const cleanNum = String(num).replace(/\s/g, '');
+
+  for (let i = cleanNum.length - 1; i >= 0; i--) {
+    let digit = parseInt(cleanNum[i], 10);
+
+    if (isEven) {
+      digit *= 2;
+      if (digit > 9) digit -= 9;
+    }
+
+    sum += digit;
+    isEven = !isEven;
+  }
+
+  return sum % 10 === 0;
+};
+
+const creditCard = (value) => {
+  return new BaseValidator(value)
+    .required('Credit card number is required')
+    .custom((val) => {
+      // required() already handles emptiness; skip the digit/Luhn checks
+      // for falsy values to avoid emitting a second error.
+      if (!val) {
+        return true;
+      }
+
+      const cleanValue = String(val).replace(/\s/g, '');
+
+      if (!safeRegexTestSync(/^\d{13,19}$/, cleanValue)) {
+        return 'Credit card must be 13-19 digits';
+      }
+
+      if (!luhnCheck(cleanValue)) {
+        return 'Invalid credit card number';
+      }
+
+      return true;
+    });
+};
+
+module.exports = { creditCard };

package/src/validators/email.js

@@ -0,0 +1,11 @@
+const { BaseValidator } = require('../core/BaseValidator');
+
+const email = (value) => {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return new BaseValidator(value)
+    .transform((v) => (typeof v === 'string' ? v.trim().toLowerCase() : v))
+    .required('Email is required')
+    .pattern(emailRegex, 'Invalid email format');
+};
+
+module.exports = { email };

package/src/validators/index.js

@@ -0,0 +1,19 @@
+const { email } = require('./email');
+const { phone } = require('./phone');
+const { creditCard } = require('./creditCard');
+const { url } = require('./url');
+const { password } = require('./password');
+const { alphanumeric } = require('./alphanumeric');
+const { numeric } = require('./numeric');
+const { zipCode } = require('./zipCode');
+
+module.exports = {
+  email,
+  phone,
+  creditCard,
+  url,
+  password,
+  alphanumeric,
+  numeric,
+  zipCode
+};

package/src/validators/numeric.js

@@ -0,0 +1,9 @@
+const { BaseValidator } = require('../core/BaseValidator');
+
+const numeric = (value) => {
+  return new BaseValidator(value)
+    .required('This field is required')
+    .pattern(/^\d+$/, 'Only numbers are allowed');
+};
+
+module.exports = { numeric };

package/src/validators/password.js

@@ -0,0 +1,41 @@
+const { BaseValidator } = require('../core/BaseValidator');
+
+const password = (value, options = {}) => {
+  const {
+    minLength = 8,
+    requireUppercase = true,
+    requireLowercase = true,
+    requireNumbers = true,
+    requireSpecialChars = false
+  } = options;
+
+  const validator = new BaseValidator(value)
+    .required('Password is required')
+    .min(minLength, `Password must be at least ${minLength} characters`);
+
+  if (requireUppercase) {
+    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'
+    );
+  }
+  if (requireNumbers) {
+    validator.pattern(/\d/, 'Password must contain at least one number');
+  }
+  if (requireSpecialChars) {
+    validator.pattern(
+      /[!@#$%^&*(),.?":{}|<>]/,
+      'Password must contain at least one special character'
+    );
+  }
+
+  return validator;
+};
+
+module.exports = { password };

package/src/validators/phone.js

@@ -0,0 +1,24 @@
+const { BaseValidator } = require('../core/BaseValidator');
+const { safeRegexTestSync } = require('../utils/safeRegex');
+
+const phone = (value, format = 'us') => {
+  const phoneRegex = {
+    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')
+    .custom((val) => {
+      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;
+    });
+};
+
+module.exports = { phone };

package/src/validators/url.js

@@ -0,0 +1,10 @@
+const { BaseValidator } = require('../core/BaseValidator');
+
+const url = (value) => {
+  const urlRegex = /^(https?|ftp):\/\/[^\s/$.?#].[^\s]*$/i;
+  return new BaseValidator(value)
+    .required('URL is required')
+    .pattern(urlRegex, 'Invalid URL format');
+};
+
+module.exports = { url };

package/src/validators/zipCode.js

@@ -0,0 +1,15 @@
+const { BaseValidator } = require('../core/BaseValidator');
+
+const zipCode = (value, country = 'us') => {
+  const zipRegex = {
+    us: /^\d{5}(-\d{4})?$/,
+    ca: /^[A-Za-z]\d[A-Za-z][ -]?\d[A-Za-z]\d$/,
+    uk: /^[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}$/i
+  };
+
+  return new BaseValidator(value)
+    .required('Zip code is required')
+    .pattern(zipRegex[country] || zipRegex.us, 'Invalid zip code format');
+};
+
+module.exports = { zipCode };

package/types/index.d.ts

@@ -31,7 +31,8 @@ declare module 'snap-validate' {
   export type CountryCode = 'us' | 'ca' | 'uk';
 
   /**
-   * Custom validation function that returns boolean
+   * Custom validation function that returns boolean, an error string, or a
+   * ValidationResult
    */
   export type CustomValidatorFunction = (
     value: any
@@ -44,6 +45,11 @@ declare module 'snap-validate' {
     value: any
   ) => Promise<boolean | string | ValidationResult>;
 
+  /**
+   * Value transform/sanitize function used by transform()
+   */
+  export type TransformFunction = (value: any) => any;
+
   /**
    * Conditional validation condition
    */
@@ -63,8 +69,17 @@ declare module 'snap-validate' {
     rules: Array<() => ValidationResult>;
     asyncRules: Array<() => Promise<ValidationResult>>;
     isOptional: boolean;
+    /**
+     * @deprecated No-op. A timer cannot interrupt a synchronous regex on a
+     * single thread, so this value is ignored. Retained for compatibility.
+     */
     regexTimeout: number;
 
+    /**
+     * Set the field name used to prefix contextual error messages
+     */
+    setFieldName(name: string): BaseValidator;
+
     /**
      * Make field required
      */
@@ -76,27 +91,82 @@ declare module 'snap-validate' {
     optional(): BaseValidator;
 
     /**
-     * Set timeout for regex operations in milliseconds
+     * @deprecated No-op, retained for backward compatibility and chainability.
+     * Regex execution cannot be interrupted by a timeout on a single thread, so
+     * this setting is ignored.
      */
     setRegexTimeout(timeoutMs: number): BaseValidator;
 
     /**
-     * Set minimum length/value
+     * Transform/sanitize the value before subsequent rules run
+     */
+    transform(fn: TransformFunction, errorMessage?: string): BaseValidator;
+
+    /**
+     * Require the value to strictly equal compareValue
+     */
+    equals(compareValue: any, message?: string): BaseValidator;
+
+    /**
+     * Require the value to be one of the allowed values
+     */
+    oneOf(allowedValues: any[], message?: string): BaseValidator;
+
+    /**
+     * Require a numeric value between min and max (inclusive)
+     */
+    between(min: number, max: number, message?: string): BaseValidator;
+
+    /**
+     * Set minimum length (string/array) or minimum value (number)
      */
     min(length: number, message?: string): BaseValidator;
 
     /**
-     * Set maximum length/value
+     * Set maximum length (string/array) or maximum value (number)
      */
     max(length: number, message?: string): BaseValidator;
 
+    /**
+     * Require the value to be an array
+     */
+    array(message?: string): BaseValidator;
+
+    /**
+     * Validate each item of an array (synchronous)
+     */
+    arrayOf(
+      validator: BaseValidator | ValidationFunction,
+      message?: string
+    ): BaseValidator;
+
+    /**
+     * Validate each item of an array (asynchronous)
+     */
+    arrayOfAsync(
+      validator: BaseValidator | ValidationFunction,
+      message?: string
+    ): BaseValidator;
+
+    /**
+     * Validate a nested object against a schema (synchronous)
+     */
+    object(schema: Schema, message?: string): BaseValidator;
+
+    /**
+     * Validate a nested object against a schema (asynchronous)
+     */
+    objectAsync(schema: Schema, message?: string): BaseValidator;
+
     /**
      * Validate against regex pattern (synchronous)
      */
     pattern(regex: RegExp, message?: string): BaseValidator;
 
     /**
-     * Validate against regex pattern with timeout protection (asynchronous)
+     * Validate against a regex pattern (asynchronous). Input-length and
+     * static-safety guards apply; there is no runtime timeout interruption
+     * (impossible for synchronous regex execution).
      */
     patternAsync(regex: RegExp, message?: string): BaseValidator;
 
@@ -190,7 +260,13 @@ declare module 'snap-validate' {
   ): Promise<SchemaValidationResult>;
 
   /**
-   * Safely test regex with timeout protection (asynchronous)
+   * Safely test a regex asynchronously. Applies an input-length cap and the
+   * isRegexSafe static heuristic, then runs the match. Returns a Promise.
+   *
+   * Note: there is NO runtime timeout interruption - a timer cannot stop a
+   * synchronous regex on a single thread.
+   *
+   * @param timeoutMs @deprecated Ignored; retained for backward compatibility.
    */
   export function safeRegexTest(
     regex: RegExp,
@@ -208,7 +284,9 @@ declare module 'snap-validate' {
   ): boolean;
 
   /**
-   * Check if a regex pattern is safe to use (ReDoS protection)
+   * Best-effort STATIC heuristic that flags a few common catastrophic-
+   * backtracking regex shapes. Not a guarantee: it can miss dangerous patterns
+   * and occasionally over-reject safe ones.
    */
   export function isRegexSafe(regex: RegExp): boolean;
 }