{"id":32195058,"url":"https://github.com/visaruruqi/oop-validator","last_synced_at":"2025-10-22T02:08:55.106Z","repository":{"id":251020389,"uuid":"836161069","full_name":"visaruruqi/oop-validator","owner":"visaruruqi","description":"oop-validator is a versatile and robust validation library designed to seamlessly integrate with any UI framework or library. Whether you're building applications with Vue.js, React, Angular, or any other front-end technology, oop-validator provides a comprehensive and flexible solution for all your validation needs.","archived":false,"fork":false,"pushed_at":"2025-10-16T15:16:20.000Z","size":16349,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-17T18:00:26.668Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/visaruruqi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-07-31T09:20:10.000Z","updated_at":"2025-10-16T15:16:24.000Z","dependencies_parsed_at":"2025-06-04T08:25:13.282Z","dependency_job_id":"2a4bf204-3eb9-493e-9f73-b4bbd0efc8d3","html_url":"https://github.com/visaruruqi/oop-validator","commit_stats":null,"previous_names":["visaruruqi/flexivalidate"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/visaruruqi/oop-validator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/visaruruqi%2Foop-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/visaruruqi%2Foop-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/visaruruqi%2Foop-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/visaruruqi%2Foop-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/visaruruqi","download_url":"https://codeload.github.com/visaruruqi/oop-validator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/visaruruqi%2Foop-validator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280365621,"owners_count":26318385,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-22T02:00:06.515Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-22T02:01:49.322Z","updated_at":"2025-10-22T02:08:55.093Z","avatar_url":"https://github.com/visaruruqi.png","language":"TypeScript","readme":"# oop-validator\n\noop-validator is a versatile and robust validation library designed to seamlessly integrate with any UI framework or library. Whether you're building applications with Vue.js, React, Angular, or any other front-end technology, oop-validator provides a comprehensive and flexible solution for all your validation needs.\n\n## Key Features\n\n- **Framework-Agnostic**: Designed to work with any UI framework, ensuring maximum flexibility for your projects.\n- **HMR Compatible**: Full compatibility with Vite, Webpack, and other modern development tools with Hot Module Reload.\n- **Extensible**: Easily extend the library with custom validation rules to meet specific application requirements.\n- **Comprehensive Rule Set**: Includes built-in validation rules such as required, minimum and maximum length, email format, domain validation, and more.\n- **Customizable Error Messages**: Configure error messages for each validation rule to provide clear and user-friendly feedback.\n- **Easy Integration**: Simple setup and intuitive API make it easy to integrate into existing projects.\n- **Lightweight and Performant**: Optimized for performance, ensuring minimal impact on application load times and responsiveness.\n\n## Installation\n\nYou can install oop-validator via npm:\n\n```sh\nnpm install oop-validator\n```\n\n## Development Experience\n\n### Hot Module Reload (HMR) Compatibility\n\n**v0.3.0+** oop-validator is fully compatible with Vite's Hot Module Reload (HMR) and other modern development tools. The library has been optimized to work seamlessly with:\n\n- **Vite + Vue 3** projects\n- **Vite + React** projects\n- **Webpack** with hot reloading\n- **Other modern bundlers** with HMR support\n\nPrevious versions (\u003c 0.3.0) had module resolution issues that could break HMR when importing the library. These issues have been completely resolved by:\n\n- Removing TypeScript file extensions from imports/exports\n- Optimizing module resolution for modern bundlers\n- Externalizing framework dependencies (Vue, React, etc.)\n- Using proper ES module export maps\n\n### Framework Dependencies\n\nThe core validation library is **completely framework-agnostic** and works in any environment:\n\n- ✅ **Node.js** - Server-side validation\n- ✅ **React** - Client-side validation\n- ✅ **Angular** - Any Angular version\n- ✅ **Vanilla JavaScript** - No framework needed\n- ✅ **Vue.js** - Includes optional Vue composables\n\n**Vue Dependency**: Vue is only required if you use the Vue composables. All other features work without any framework dependencies.\n\n## Table of Contents\n\n- [Pure JavaScript API](#pure-javascript-api)\n  - [Basic Validation Engine](#basic-validation-engine)\n  - [Form Validation Engine](#form-validation-engine)\n- [Vue.js Composables](#vuejs-composables)\n  - [Validation Configuration Options](#validation-configuration-options)\n- [React Integration](#react-integration)\n  - [React Hook Examples](#react-hook-examples)\n  - [Component Integration](#component-integration)\n- [Node.js Environment](#nodejs-environment)\n  - [Server-side Validation](#server-side-validation)\n  - [API Request Validation](#api-request-validation)\n- [Available Validation Rules](#available-validation-rules)\n- [API Reference](#api-reference)\n\n---\n\n## Pure JavaScript API\n\nThe core validation library works in any JavaScript environment without framework dependencies. Perfect for vanilla JavaScript, any framework, or server-side validation.\n\n## Return Object Structures\n\nAll validation methods return consistent, predictable objects to make error handling straightforward:\n\n### Single Field Validation Result\n\n```javascript\n// ValidationEngine.validateValue() always returns:\n{\n  isValid: boolean,    // true if validation passed, false if failed\n  errors: string[]     // array of error messages (empty when valid)\n}\n```\n\n### Form Validation Result\n\n```javascript\n// FormValidationEngine.validate() always returns:\n{\n  isValid: boolean,        // true only if ALL fields pass validation\n  fieldErrors: {           // object with field names as keys\n    fieldName: string[]    // arrays of error messages per field\n  },\n  summary: string[]        // flat array of ALL errors with field prefixes\n}\n```\n\n### Basic Validation Engine\n\nUse `ValidationEngine` for validating individual fields or values. Perfect for real-time field validation, search inputs, or any single-value validation.\n\n```javascript\nimport { ValidationEngine } from 'oop-validator';\n\n// Product name validation - ensure it meets business requirements\nconst productRules = [\n  'required', // Field must not be empty\n  {\n    rule: 'min',\n    params: { length: 3 },\n    message: 'Product name must be at least 3 characters.',\n  },\n  {\n    rule: 'max',\n    params: { length: 50 },\n    message: 'Product name cannot exceed 50 characters.',\n  },\n];\n\nconst productValidation = new ValidationEngine(productRules);\n\n// Validate product name input from user\nconst productResult = productValidation.validateValue('Premium Coffee Beans');\n// Returns: { isValid: true, errors: [] }\n\nif (!productResult.isValid) {\n  // Show validation errors to user (e.g., in form field)\n  console.log('Product name errors:', productResult.errors);\n}\n\n// Email validation for contact forms - check format is correct\nconst emailValidation = new ValidationEngine(['required', 'email']);\n\nconst emailResult = emailValidation.validateValue('user@company.com');\n// Returns: { isValid: true, errors: [] }\n\n// Currency validation for financial applications\nconst priceValidation = new ValidationEngine(['required', 'currency']);\nconst priceResult = priceValidation.validateValue('$99.99');\n// Returns: { isValid: true, errors: [] }\n```\n\n#### Stateful API (NEW in v0.5.0)\n\n`ValidationEngine` now tracks validation state internally, making it easier to check current validation status:\n\n```javascript\nimport { ValidationEngine } from 'oop-validator';\n\nconst emailValidation = new ValidationEngine(['required', 'email']);\n\n// Validate a value\nemailValidation.validateValue('invalid-email');\n\n// Get current validation state (without re-validating)\nconsole.log(emailValidation.getIsValid());  // false\nconsole.log(emailValidation.getErrors());   // ['This field must be a valid email address.']\n\n// Validate again with valid input\nemailValidation.validateValue('valid@example.com');\n\nconsole.log(emailValidation.getIsValid());  // true\nconsole.log(emailValidation.getErrors());   // []\n\n// Reset validation state (useful for clearing form errors)\nemailValidation.reset();\n\nconsole.log(emailValidation.getIsValid());  // true\nconsole.log(emailValidation.getErrors());   // []\n```\n\n**Stateful methods:**\n- `getIsValid()` - Returns current validation status (true/false)\n- `getErrors()` - Returns array of current error messages\n- `reset()` - Clears validation state (sets isValid to true, clears errors)\n\n**Use cases:**\n- ✅ Check validation status without re-running validation\n- ✅ Reset form fields after successful submission\n- ✅ Clear errors when user starts typing\n- ✅ Track validation state across multiple validations\n```\n\n### Custom Validation Rules\n\nCreate your own validation rules for business-specific requirements:\n\n```javascript\nimport { IValidationRule } from 'oop-validator'\n\n// Create a custom rule for business-specific validation needs\nexport class PhoneNumberValidationRule extends IValidationRule {\n    // Private property to store the error message\n    private errorMessage = \"This field must be a valid phone number.\"\n\n    // Main validation logic - returns [isValid, errorMessage]\n    isValid(param) {\n        // Simple international phone number pattern\n        const phonePattern = /^\\+?[1-9]\\d{1,14}$/\n        const isValid = phonePattern.test(param)\n        // Return array: [boolean success, string error message]\n        return [isValid, isValid ? \"\" : this.errorMessage]\n    }\n\n    // Check if this rule handles a specific validation type\n    isMatch(type) {\n        return type.toLowerCase() === 'phone'\n    }\n\n    // Configure rule parameters (not used for phone validation)\n    setParams(params) {\n        // No parameters needed for phone number rule\n    }\n\n    // Allow customizing the error message\n    setErrorMessage(message) {\n        this.errorMessage = message\n    }\n}\n\n// Register and use the custom rule\nconst validationEngine = new ValidationEngine(['required', 'phone'])\nvalidationEngine.addRule(new PhoneNumberValidationRule())\n\nconst phoneResult = validationEngine.validateValue('+1234567890')\nif (!phoneResult.isValid) {\n    // Handle phone validation errors in your UI\n    console.log('Phone validation errors:', phoneResult.errors)\n}\n```\n\n### Form Validation Engine\n\nUse `FormValidationEngine` for validating multiple fields at once. Perfect for forms, API requests, or any multi-field validation.\n\n```javascript\nimport { FormValidationEngine } from 'oop-validator';\n\n// Sample contact form data (typically from user input)\nconst contactForm = {\n  firstName: '',\n  lastName: '',\n  email: '',\n  phone: '',\n  country: '',\n};\n\n// Define validation rules for each field\nconst contactFormEngine = new FormValidationEngine({\n  firstName: ['required', { rule: 'min', params: { length: 2 } }], // Must exist and be at least 2 chars\n  lastName: ['required', { rule: 'min', params: { length: 2 } }], // Must exist and be at least 2 chars\n  email: ['required', 'email'], // Must exist and be valid email format\n  phone: ['required', 'phone'], // Must exist and be valid phone format\n  country: ['required'], // Must exist (not empty)\n});\n\n// Validate the entire form at once\nconst contactResult = contactFormEngine.validate(contactForm);\n// contactResult is a plain JavaScript object with this structure:\n// {\n//   isValid: false,        // boolean - true only if ALL fields pass validation\n//   fieldErrors: {         // object with errors grouped by field name (for showing errors per field)\n//     firstName: [\"This field is required.\"],\n//     lastName: [\"This field is required.\"],\n//     email: [\"This field is required.\", \"This field must be a valid email address.\"],\n//     phone: [\"This field is required.\", \"This field must be a valid phone number.\"],\n//     country: [\"This field is required.\"]\n//   },\n//   summary: [             // array of ALL error messages with field prefixes (for error summary lists)\n//     \"firstName: This field is required.\",\n//     \"lastName: This field is required.\",\n//     \"email: This field is required.\",\n//     \"email: This field must be a valid email address.\",\n//     \"phone: This field is required.\",\n//     \"phone: This field must be a valid phone number.\",\n//     \"country: This field is required.\"\n//   ]\n// }\nconsole.log(contactResult.fieldErrors); // Use to show errors next to specific input fields\nconsole.log(contactResult.summary); // Use to show all errors in an error summary box\n```\n\n### Banking Form Example\n\n```javascript\nimport { FormValidationEngine } from 'oop-validator';\n\nconst bankingForm = {\n  accountNumber: '',\n  routingNumber: '',\n  accountType: '',\n  currency: '',\n  initialDeposit: '',\n};\n\nconst bankingEngine = new FormValidationEngine({\n  accountNumber: ['required', 'bankAccount'],\n  routingNumber: ['required', { rule: 'min', params: { length: 9 } }],\n  accountType: ['required'],\n  currency: ['required', 'currency'],\n  initialDeposit: ['required', { rule: 'min', params: { amount: 25 } }],\n});\n\nconst bankingResult = bankingEngine.validate(bankingForm);\n```\n\n---\n\n## Vue.js Composables\n\nThe library includes optional Vue.js composables that provide reactive validation with automatic updates when your form data changes. Perfect for Vue 3 Composition API projects.\n\n**Installation for Vue projects:**\n\n```bash\nnpm install oop-validator vue\n```\n\n### useValidation - Single Field Validation\n\nThe `useValidation` composable is perfect for validating individual form fields with real-time reactive feedback.\n\n```javascript\nimport { ref } from 'vue';\nimport { useValidation } from 'oop-validator';\n\n// Single field validation with automatic reactivity\nconst email = ref('');\n\n// Setup validation rules\nconst emailRules = ['required', 'email'];\n\n// Get reactive validation state\nconst { errors, isValid, validate } = useValidation(email, emailRules);\n\n// Validation runs automatically when email.value changes\n// errors.value will contain array of error messages\n// isValid.value will be true/false\n\n// You can also manually trigger validation\nconst manualCheck = () =\u003e {\n  validate(email.value);\n};\n```\n\n**Usage in Vue component:**\n\n```vue\n\u003ctemplate\u003e\n  \u003cdiv class=\"field\"\u003e\n    \u003cinput\n      v-model=\"email\"\n      type=\"email\"\n      placeholder=\"Enter your email\"\n      :class=\"{ error: !isValid }\"\n    /\u003e\n    \u003cspan v-if=\"errors.length\" class=\"error-message\"\u003e\n      {{ errors[0] }}\n    \u003c/span\u003e\n  \u003c/div\u003e\n\u003c/template\u003e\n\n\u003cscript setup\u003e\nimport { ref } from 'vue';\nimport { useValidation } from 'oop-validator';\n\nconst email = ref('');\nconst { errors, isValid } = useValidation(email, ['required', 'email']);\n\u003c/script\u003e\n```\n\n### useFormValidation - Multi-Field Form Validation\n\nThe `useFormValidation` composable handles complex forms with multiple fields and provides comprehensive error management with the new unified `fields` API.\n\n\u003e **Note:** Works with any reactive type - `ref()`, `reactive()`, computed values, and props like `modelValue`.\n\n#### New Unified Fields API (Recommended)\n\n```javascript\nimport { ref } from 'vue';\nimport { useFormValidation } from 'oop-validator';\n\n// Form data - works with ref(), reactive(), or any reactive type\nconst formData = ref({\n  firstName: '',\n  lastName: '',\n  email: '',\n  phone: '',\n});\n\n// Validation configuration\nconst validationConfig = {\n  firstName: ['required', { rule: 'min', params: { length: 2 } }],\n  lastName: ['required', { rule: 'min', params: { length: 2 } }],\n  email: ['required', 'email'],\n  phone: ['required', 'phone'],\n};\n\n// Get reactive validation state with new fields API\nconst {\n  fields,         // NEW: Unified field state object (recommended)\n  isValid,        // Form-level validity\n  isModelDirty,   // Form-level dirty state (true if any field changed)\n  validate,       // Manual validation trigger\n  reset,          // Reset form to initial state\n  touch,          // Mark specific field as touched\n  touchAll,       // Mark all fields as touched\n} = useFormValidation(formData, validationConfig);\n\n// Access complete field state through fields object\nconsole.log(fields.value.email.isValid)    // true/false - field is valid\nconsole.log(fields.value.email.errors)     // string[] - error messages\nconsole.log(fields.value.email.isDirty)    // true/false - value changed from initial\nconsole.log(fields.value.email.isTouched)  // true/false - field was focused/blurred\n\n// Check if form has unsaved changes\nconsole.log(isModelDirty.value)            // true/false - any field is dirty\n\n// Handle form submission\nconst handleSubmit = () =\u003e {\n  touchAll() // Show errors on all fields\n  const result = validate();\n  if (result.isValid) {\n    console.log('Form is valid, submitting...', formData.value);\n    reset() // Reset form after successful submission\n  }\n};\n\n// Handle field blur\nconst handleBlur = (fieldName) =\u003e {\n  touch(fieldName) // Mark field as touched when user leaves it\n};\n\n// Warn user about unsaved changes\nconst handleNavigation = () =\u003e {\n  if (isModelDirty.value) {\n    const confirmed = confirm('You have unsaved changes. Are you sure you want to leave?');\n    if (!confirmed) return false;\n  }\n  // Navigate away\n  return true;\n};\n```\n\n**Full Vue component example with new fields API:**\n\n```vue\n\u003ctemplate\u003e\n  \u003cform @submit.prevent=\"handleSubmit\"\u003e\n    \u003c!-- Unsaved changes indicator --\u003e\n    \u003cdiv v-if=\"isModelDirty\" class=\"alert alert-warning\"\u003e\n      You have unsaved changes\n    \u003c/div\u003e\n\n    \u003cdiv class=\"field\"\u003e\n      \u003cinput\n        v-model=\"formData.firstName\"\n        placeholder=\"First Name\"\n        @blur=\"touch('firstName')\"\n        :class=\"{ \n          error: fields.firstName.isTouched \u0026\u0026 !fields.firstName.isValid,\n          success: fields.firstName.isValid \u0026\u0026 fields.firstName.isDirty\n        }\"\n      /\u003e\n      \u003c!-- Show checkmark if field is valid and modified --\u003e\n      \u003cspan v-if=\"fields.firstName.isValid \u0026\u0026 fields.firstName.isDirty\" class=\"valid-icon\"\u003e✓\u003c/span\u003e\n      \u003c!-- Only show errors after field is touched --\u003e\n      \u003cspan v-if=\"fields.firstName.isTouched \u0026\u0026 fields.firstName.errors.length\" class=\"error-message\"\u003e\n        {{ fields.firstName.errors[0] }}\n      \u003c/span\u003e\n    \u003c/div\u003e\n\n    \u003cdiv class=\"field\"\u003e\n      \u003cinput\n        v-model=\"formData.email\"\n        type=\"email\"\n        placeholder=\"Email\"\n        @blur=\"touch('email')\"\n        :class=\"{ \n          error: fields.email.isTouched \u0026\u0026 !fields.email.isValid,\n          success: fields.email.isValid \u0026\u0026 fields.email.isDirty\n        }\"\n      /\u003e\n      \u003cspan v-if=\"fields.email.isValid \u0026\u0026 fields.email.isDirty\" class=\"valid-icon\"\u003e✓\u003c/span\u003e\n      \u003cspan v-if=\"fields.email.isTouched \u0026\u0026 fields.email.errors.length\" class=\"error-message\"\u003e\n        {{ fields.email.errors[0] }}\n      \u003c/span\u003e\n    \u003c/div\u003e\n\n    \u003cbutton type=\"submit\" :disabled=\"!isValid\"\u003eSubmit Form\u003c/button\u003e\n    \u003cbutton type=\"button\" @click=\"reset\"\u003eReset Form\u003c/button\u003e\n  \u003c/form\u003e\n\u003c/template\u003e\n\n\u003cscript setup\u003e\nimport { ref } from 'vue';\nimport { useFormValidation } from 'oop-validator';\n\nconst formData = ref({\n  firstName: '',\n  email: '',\n});\n\nconst config = {\n  firstName: ['required'],\n  email: ['required', 'email'],\n};\n\nconst { fields, isValid, validate, reset, touch, touchAll } =\n  useFormValidation(formData, config);\n\nconst handleSubmit = () =\u003e {\n  touchAll() // Show all errors on submit attempt\n  const result = validate();\n  if (result.isValid) {\n    console.log('Submitting:', formData.value);\n    // After successful API call:\n    reset() // Reset form state\n  }\n};\n\u003c/script\u003e\n```\n\n#### Legacy API (Deprecated)\n\nThe old API is still supported for backward compatibility but we recommend migrating to the new `fields` API:\n\n```javascript\n// OLD API (still works but deprecated)\nconst {\n  errors,           // Use fields.fieldName.errors instead\n  getFieldErrors,   // Use fields.fieldName.errors instead\n  isFieldValid,     // Use fields.fieldName.isValid instead\n} = useFormValidation(formData, validationConfig);\n```\n\n### Working with Different Reactive Types\n\nThe composable works seamlessly with all Vue reactive types:\n\n```javascript\nimport { ref, reactive, computed } from 'vue';\n\n// ✅ Works with ref()\nconst formData = ref({ email: '', password: '' });\nuseFormValidation(formData, config);\n\n// ✅ Works with reactive()\nconst formData = reactive({ email: '', password: '' });\nuseFormValidation(formData, config);\n\n// ✅ Works with computed()\nconst formData = computed(() =\u003e ({ ...someState }));\nuseFormValidation(formData, config);\n\n// ✅ Works with props (like v-model)\nconst props = defineProps(['modelValue']);\nuseFormValidation(props.modelValue, config);\n```\n\n### Validation Configuration Options\n\nThe `useFormValidation` composable accepts an optional third parameter for configuration:\n\n```javascript\nconst { errors, isValid } = useFormValidation(formData, config, {\n  validationStrategy: 'all' | 'changed',  // How to validate (default: 'all')\n  validateOnMount: true | false            // Validate immediately (default: depends on strategy)\n})\n```\n\n#### Validation Strategies\n\n**`validationStrategy: 'all'`** (default)\n- Validates **all fields** whenever any field changes\n- Safest option for forms with cross-field validation (like password confirmation)\n- Default behavior - ensures consistency\n\n**`validationStrategy: 'changed'`**\n- Only validates **fields that changed** for better performance\n- Ideal for large forms or real-time validation scenarios\n- May miss cross-field validation dependencies\n\n#### Validate On Mount\n\n**`validateOnMount: boolean`**\n- Controls whether validation runs immediately when the form loads\n- **Default for 'all' strategy**: `true` (show all errors immediately)\n- **Default for 'changed' strategy**: `false` (wait for user interaction)\n\n#### Configuration Examples\n\n```javascript\n// Default: validate all fields immediately\nconst { errors, isValid } = useFormValidation(formData, config)\n\n// Performance mode: only validate changed fields, no initial errors\nconst { errors, isValid } = useFormValidation(formData, config, {\n  validationStrategy: 'changed'\n})\n\n// Validate all fields, but wait for user interaction\nconst { errors, isValid } = useFormValidation(formData, config, {\n  validationStrategy: 'all',\n  validateOnMount: false\n})\n\n// Show all errors immediately, but only revalidate changed fields\nconst { errors, isValid } = useFormValidation(formData, config, {\n  validationStrategy: 'changed',\n  validateOnMount: true\n})\n```\n\n### Vue Composable Returns\n\n```javascript\n// useValidation() returns reactive Vue refs:\n{\n  errors: /* Vue ref containing array */ string[],         // reactive array of error messages\n  isValid: /* Vue ref containing boolean */ boolean,       // reactive validation status\n  validate: (value?) =\u003e boolean  // manual validation function\n}\n\n// useFormValidation() returns reactive Vue refs and helper functions:\n{\n  // NEW: Unified fields API (recommended)\n  fields: /* Vue ref containing object */ {\n    [fieldName: string]: {\n      isValid: boolean,    // field is valid\n      errors: string[],    // error messages for this field\n      isDirty: boolean,    // value changed from initial\n      isTouched: boolean   // field was focused/blurred\n    }\n  },\n  \n  // Form-level state\n  isValid: /* Vue ref containing boolean */ boolean,              // reactive overall form validity\n  isModelDirty: /* Vue ref containing boolean */ boolean,         // true if any field is dirty\n  summary: /* Vue ref containing array */ string[],              // reactive array of all errors\n  \n  // Actions\n  validate: (values?) =\u003e FormValidationResult,  // manual validation trigger\n  reset: () =\u003e void,                            // reset form to initial state\n  touch: (fieldName: string) =\u003e void,           // mark specific field as touched\n  touchAll: () =\u003e void,                         // mark all fields as touched\n  \n  // DEPRECATED (still supported for backward compatibility):\n  errors: /* Vue ref containing object */ { [fieldName: string]: string[] },          // use fields.fieldName.errors instead\n  getFieldErrors: (field) =\u003e /* Vue ref */ string[],  // use fields.fieldName.errors instead\n  isFieldValid: (field) =\u003e /* Vue ref */ boolean      // use fields.fieldName.isValid instead\n}\n```\n\n---\n\n## React Integration\n\nThe core validation engines work perfectly with React's state management. Here are practical examples for different React patterns.\n\n### React Hook Examples\n\n```javascript\nimport { useEffect, useState } from 'react';\nimport { FormValidationEngine } from 'oop-validator';\n\n// Contact form with React hooks\nfunction ContactForm() {\n  const [formData, setFormData] = useState({\n    firstName: '',\n    lastName: '',\n    email: '',\n    phone: '',\n  });\n  const [errors, setErrors] = useState({});\n  const [isValid, setIsValid] = useState(false);\n\n  // Create validation engine\n  const contactEngine = new FormValidationEngine({\n    firstName: ['required', { rule: 'min', params: { length: 2 } }],\n    lastName: ['required', { rule: 'min', params: { length: 2 } }],\n    email: ['required', 'email'],\n    phone: ['required', 'phone'],\n  });\n\n  // Validate on form data changes\n  useEffect(() =\u003e {\n    const result = contactEngine.validate(formData);\n    setErrors(result.fieldErrors);\n    setIsValid(result.isValid);\n  }, [formData]);\n\n  const handleInputChange = (field, value) =\u003e {\n    setFormData((prev) =\u003e ({ ...prev, [field]: value }));\n  };\n\n  const handleSubmit = (e) =\u003e {\n    e.preventDefault();\n    if (isValid) {\n      console.log('Submitting form:', formData);\n      // API call or further processing\n    }\n  };\n\n  return (\n    \u003cform onSubmit={handleSubmit}\u003e\n      \u003cdiv\u003e\n        \u003cinput\n          type=\"text\"\n          placeholder=\"First Name\"\n          value={formData.firstName}\n          onChange={(e) =\u003e handleInputChange('firstName', e.target.value)}\n          className={errors.firstName?.length ? 'error' : ''}\n        /\u003e\n        {errors.firstName?.map((error, index) =\u003e (\n          \u003cspan key={index} className=\"error-message\"\u003e\n            {error}\n          \u003c/span\u003e\n        ))}\n      \u003c/div\u003e\n\n      \u003cdiv\u003e\n        \u003cinput\n          type=\"email\"\n          placeholder=\"Email\"\n          value={formData.email}\n          onChange={(e) =\u003e handleInputChange('email', e.target.value)}\n          className={errors.email?.length ? 'error' : ''}\n        /\u003e\n        {errors.email?.map((error, index) =\u003e (\n          \u003cspan key={index} className=\"error-message\"\u003e\n            {error}\n          \u003c/span\u003e\n        ))}\n      \u003c/div\u003e\n\n      \u003cbutton type=\"submit\" disabled={!isValid}\u003e\n        Submit Contact Form\n      \u003c/button\u003e\n    \u003c/form\u003e\n  );\n}\n```\n\n### Component Integration\n\n```javascript\nimport { useEffect, useState } from 'react';\nimport { ValidationEngine } from 'oop-validator';\n\n// Single field validation component\nfunction ValidatedInput({ value, onChange, rules, placeholder }) {\n  const [errors, setErrors] = useState([]);\n  const validationEngine = new ValidationEngine(rules);\n\n  useEffect(() =\u003e {\n    const result = validationEngine.validateValue(value);\n    setErrors(result.errors);\n  }, [value]);\n\n  return (\n    \u003cdiv className=\"field\"\u003e\n      \u003cinput\n        type=\"text\"\n        value={value}\n        onChange={onChange}\n        placeholder={placeholder}\n        className={errors.length ? 'error' : ''}\n      /\u003e\n      {errors.map((error, index) =\u003e (\n        \u003cspan key={index} className=\"error-message\"\u003e\n          {error}\n        \u003c/span\u003e\n      ))}\n    \u003c/div\u003e\n  );\n}\n\n// Usage in parent component\nfunction ProductForm() {\n  const [productName, setProductName] = useState('');\n  const [price, setPrice] = useState('');\n\n  return (\n    \u003cform\u003e\n      \u003cValidatedInput\n        value={productName}\n        onChange={(e) =\u003e setProductName(e.target.value)}\n        rules={['required', { rule: 'min', params: { length: 3 } }]}\n        placeholder=\"Product Name\"\n      /\u003e\n\n      \u003cValidatedInput\n        value={price}\n        onChange={(e) =\u003e setPrice(e.target.value)}\n        rules={['required', 'currency']}\n        placeholder=\"Price\"\n      /\u003e\n    \u003c/form\u003e\n  );\n}\n```\n\n---\n\n## Node.js Environment\n\nThe validation library is perfect for server-side validation in Node.js applications, API request validation, and data processing.\n\n### Server-side Validation\n\n```javascript\nconst { FormValidationEngine, ValidationEngine } = require('oop-validator');\n\n// Express.js middleware for request validation\nfunction validateContactForm(req, res, next) {\n  const contactEngine = new FormValidationEngine({\n    firstName: ['required', { rule: 'min', params: { length: 2 } }],\n    lastName: ['required', { rule: 'min', params: { length: 2 } }],\n    email: ['required', 'email'],\n    phone: ['required', 'phone'],\n    message: ['required', { rule: 'max', params: { length: 1000 } }],\n  });\n\n  const result = contactEngine.validate(req.body);\n\n  if (!result.isValid) {\n    return res.status(400).json({\n      error: 'Validation failed',\n      details: result.fieldErrors,\n      summary: result.summary,\n    });\n  }\n\n  next(); // Validation passed, continue to next middleware\n}\n\n// Use in Express routes\napp.post('/api/contact', validateContactForm, (req, res) =\u003e {\n  // Process validated contact form data\n  console.log('Valid contact form:', req.body);\n  res.json({ success: true, message: 'Contact form submitted successfully' });\n});\n```\n\n### API Request Validation\n\n```javascript\nconst { FormValidationEngine } = require('oop-validator');\n\n// User registration validation\nfunction validateUserRegistration(userData) {\n  const userEngine = new FormValidationEngine({\n    username: ['required', 'username'],\n    email: ['required', 'email'],\n    password: ['required', 'passwordStrength'],\n    confirmPassword: [\n      'required',\n      {\n        rule: 'matchField',\n        params: { fieldName: 'password' },\n      },\n    ],\n    age: ['required', { rule: 'min', params: { value: 18 } }],\n  });\n\n  return userEngine.validate(userData);\n}\n\n// Product validation for e-commerce API\nfunction validateProduct(productData) {\n  const productEngine = new FormValidationEngine({\n    name: ['required', { rule: 'min', params: { length: 3 } }],\n    sku: ['required', { rule: 'regex', params: { pattern: /^[A-Z0-9-]+$/ } }],\n    price: ['required', 'currency'],\n    category: ['required'],\n    description: [{ rule: 'max', params: { length: 2000 } }],\n    tags: [{ rule: 'max', params: { length: 10 } }], // Max 10 tags\n  });\n\n  return productEngine.validate(productData);\n}\n\n// Usage in API handlers\nasync function createProduct(req, res) {\n  const validationResult = validateProduct(req.body);\n\n  if (!validationResult.isValid) {\n    return res.status(400).json({\n      error: 'Invalid product data',\n      validation_errors: validationResult.fieldErrors,\n    });\n  }\n\n  try {\n    // Save to database\n    const product = await Product.create(req.body);\n    res.status(201).json({ success: true, product });\n  } catch (error) {\n    res.status(500).json({ error: 'Database error' });\n  }\n}\n\n// Database model validation\nclass User {\n  static validate(userData) {\n    const userEngine = new FormValidationEngine({\n      email: ['required', 'email'],\n      firstName: ['required'],\n      lastName: ['required'],\n      dateOfBirth: ['required', 'date'],\n      socialSecurity: ['socialSecurity'], // Optional field\n    });\n\n    return userEngine.validate(userData);\n  }\n\n  static async create(userData) {\n    const validation = User.validate(userData);\n\n    if (!validation.isValid) {\n      throw new Error(\n        `User validation failed: ${validation.summary.join(', ')}`\n      );\n    }\n\n    // Proceed with user creation\n    return await database.users.insert(userData);\n  }\n}\n```\n\n---\n\n## Available Validation Rules\n\nThe library includes a comprehensive set of built-in validation rules for common business needs:\n\n### Basic Rules\n\n- **`required`** - Field must not be empty\n- **`min`** - Minimum length or value: `{ rule: 'min', params: { length: 3 } }`\n- **`max`** - Maximum length or value: `{ rule: 'max', params: { length: 50 } }`\n\n### Format Rules\n\n- **`email`** - Valid email address format\n- **`url`** - Valid URL format\n- **`phone`** - Valid phone number format\n- **`date`** - Valid date format\n\n### Financial Rules\n\n- **`currency`** - Valid currency format ($123.45, €99.00, etc.)\n- **`bankAccount`** - Valid bank account number\n- **`creditCard`** - Valid credit card number\n\n### Geographic Rules\n\n- **`zipCode`** - Valid ZIP/postal code\n- **`domain`** - Valid domain name\n- **`ipAddress`** - Valid IP address\n\n### Identity Rules\n\n- **`socialSecurity`** - Valid social security number\n- **`username`** - Valid username format\n\n### Advanced Rules\n\n- **`regex`** - Custom regex pattern: `{ rule: 'regex', params: { pattern: /^[A-Z]+$/ } }`\n- **`passwordStrength`** - Password strength validation\n- **`MatchFieldValidationRule`** - Cross-field validation (matches another field)\n\n### Custom Messages\n\nAll rules support custom error messages:\n\n```javascript\n{\n  rule: 'min',\n  params: { length: 8 },\n  message: 'Password must be at least 8 characters long'\n}\n```\n\n---\n\n## API Reference\n\n### ValidationEngine\n\n**Constructor:**\n\n```javascript\nnew ValidationEngine(rules: Array\u003cstring | RuleConfig\u003e)\n```\n\n**Methods:**\n\n- `validateValue(value: string): ValidationResult` - Validates a single value\n- `addRule(rule: IValidationRule): void` - Adds a custom validation rule\n\n**Return Type:**\n\n```javascript\n{\n  isValid: boolean,\n  errors: string[]\n}\n```\n\n### FormValidationEngine\n\n**Constructor:**\n\n```javascript\nnew FormValidationEngine(config: { [fieldName: string]: Array\u003cstring | RuleConfig\u003e })\n```\n\n**Methods:**\n\n- `validate(data: object): FormValidationResult` - Validates all form fields\n\n**Return Type:**\n\n```javascript\n{\n  isValid: boolean,\n  fieldErrors: { [fieldName: string]: string[] },\n  summary: string[]\n}\n```\n\n### Vue Composables\n\n#### useValidation\n\n```javascript\nuseValidation(\n  value: Ref\u003cstring\u003e,\n  rules: Array\u003cstring | RuleConfig\u003e\n): {\n  errors: Ref\u003cstring[]\u003e,\n  isValid: Ref\u003cboolean\u003e,\n  validate: (value?: string) =\u003e boolean\n}\n```\n\n#### useFormValidation\n\n```javascript\nuseFormValidation(\n  formData: Ref\u003cobject\u003e,\n  config: { [fieldName: string]: Array\u003cstring | RuleConfig\u003e },\n  options?: {\n    validationStrategy?: 'all' | 'changed',  // default: 'all'\n    validateOnMount?: boolean                 // default: true for 'all', false for 'changed'\n  }\n): {\n  errors: Ref\u003c{ [fieldName: string]: string[] }\u003e,\n  isValid: Ref\u003cboolean\u003e,\n  summary: Ref\u003cstring[]\u003e,\n  validate: (values?: object) =\u003e FormValidationResult,\n  getFieldErrors: (field: string) =\u003e Ref\u003cstring[]\u003e,\n  isFieldValid: (field: string) =\u003e Ref\u003cboolean\u003e\n}\n```\n\n**Options:**\n\n- **`validationStrategy`**: \n  - `'all'` (default): Validates all fields when any field changes\n  - `'changed'`: Only validates fields that changed (better performance)\n  \n- **`validateOnMount`**: \n  - Controls whether validation runs immediately on mount\n  - Default: `true` for 'all' strategy, `false` for 'changed' strategy\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Changelog\n\nSee [CHANGELOG.md](./CHANGELOG.md) for version history and updates.\n","funding_links":[],"categories":["Third Party Components"],"sub_categories":["Form Validation"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvisaruruqi%2Foop-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvisaruruqi%2Foop-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvisaruruqi%2Foop-validator/lists"}