autovalidator-sdk/index.d.ts

A lightweight frontend JavaScript SDK for real-time input validation with built-in support for Malaysian IC, car plates, postcodes, and extensible custom validators

// Auto Input Validator - TypeScript Definitions

/**
 * Configuration object for custom validators
 */
export interface ValidatorConfig {
  /** Regular expression defining allowed characters during keypress */
  allowedChars?: RegExp;
  
  /** Maximum allowed length of the input value */
  maxLength?: number;
  
  /** Function to transform the input value (e.g., toUpperCase, formatting) */
  transform?: (value: string) => string;
  
  /** Regular expression pattern for final validation */
  pattern?: RegExp;
  
  /** Error message displayed when invalid character is entered */
  keypressError?: string;
  
  /** Error message displayed when input format is invalid */
  validationError?: string;
  
  /** Duration in milliseconds to display error messages (default: 2000) */
  errorTimeout?: number;
}

/**
 * Input Validator class providing validation methods for form inputs
 */
declare class InputValidator {
  /** Internal storage for registered custom validators */
  private static customValidators: Record<string, ValidatorConfig>;

  /**
   * Validates Malaysian IC (Identity Card) number input with automatic formatting
   * 
   * Features:
   * - Only accepts digits (0-9)
   * - Maximum 12 digits
   * - Auto-formats to XXXXXX-XX-XXXX pattern
   * - Real-time validation feedback
   * 
   * @param input - HTML input element to apply IC validation to
   * @throws {Error} If input element is null or undefined
   * 
   * @example
   * ```typescript
   * const icInput = document.getElementById('icInput') as HTMLInputElement;
   * InputValidator.validateIC(icInput);
   * ```
   */
  static validateIC(input: HTMLInputElement): void;

  /**
   * Validates Malaysian car plate number input with format validation
   * 
   * Features:
   * - Accepts letters and numbers only
   * - Automatically converts to uppercase
   * - Removes spaces and symbols
   * - Must contain at least one letter and one number
   * - Maximum 12 characters
   * - Supports various Malaysian plate formats
   * 
   * @param input - HTML input element to apply car plate validation to
   * @throws {Error} If input element is null or undefined
   * 
   * @example
   * ```typescript
   * const plateInput = document.getElementById('plateInput') as HTMLInputElement;
   * InputValidator.validateCarPlate(plateInput);
   * ```
   */
  static validateCarPlate(input: HTMLInputElement): void;

  /**
   * Validates Malaysian postcode input (5-digit format)
   * 
   * Features:
   * - Only accepts digits (0-9)
   * - Exactly 5 digits required
   * - Real-time validation feedback
   * 
   * @param input - HTML input element to apply postcode validation to
   * @throws {Error} If input element is null or undefined
   * 
   * @example
   * ```typescript
   * const postcodeInput = document.getElementById('postcodeInput') as HTMLInputElement;
   * InputValidator.validatePostcode(postcodeInput);
   * ```
   */
  static validatePostcode(input: HTMLInputElement): void;

  /**
   * Validates email address input with format validation
   * 
   * Features:
   * - Accepts letters, numbers, @, ., _, - only
   * - Automatically converts to lowercase
   * - Maximum 254 characters (RFC standard)
   * - Real-time email format validation
   * 
   * @param input - HTML input element to apply email validation to
   * @throws {Error} If input element is null or undefined
   * 
   * @example
   * ```typescript
   * const emailInput = document.getElementById('emailInput') as HTMLInputElement;
   * InputValidator.validateEmail(emailInput);
   * ```
   */
  static validateEmail(input: HTMLInputElement): void;

  /**
   * Register a custom validator with specified configuration
   * 
   * @param name - Unique identifier for the validator
   * @param config - Validator configuration object
   * @throws {Error} If validator name already exists
   * @throws {Error} If config is invalid
   * 
   * @example
   * ```typescript
   * InputValidator.registerValidator('phoneNumber', {
   *   allowedChars: /[0-9+-]/,
   *   maxLength: 15,
   *   pattern: /^[+]?[0-9]{10,15}$/,
   *   keypressError: "Only numbers, + and - are allowed",
   *   validationError: "Phone number must be 10-15 digits",
   *   errorTimeout: 3000
   * });
   * ```
   */
  static registerValidator(name: string, config: ValidatorConfig): void;

  /**
   * Apply a previously registered custom validator to an input element
   * 
   * @param input - HTML input element to apply validation to
   * @param validatorName - Name of the registered validator
   * @throws {Error} If input element is null or undefined
   * @throws {Error} If validator with specified name is not found
   * 
   * @example
   * ```typescript
   * const phoneInput = document.getElementById('phoneInput') as HTMLInputElement;
   * InputValidator.applyCustomValidator(phoneInput, 'phoneNumber');
   * ```
   */
  static applyCustomValidator(input: HTMLInputElement, validatorName: string): void;
}

export default InputValidator;