@shanewas/form-validation

A powerful and flexible validation engine for forms with support for complex rules, dependencies, type validation, and custom validation logic.

Features

• Comprehensive Validation Types: Supports required fields, comparisons, dependencies, type checking, regex, and more.
• Flexible Actions: Execute form actions like CLEAR_FORMFIELD, UPDATE_VALUE, or custom actions based on validations.
• Complex Field Dependencies: Define validations based on the values of other fields.
• Custom Validations: Implement application-specific validation logic.
• Detailed Error Reporting: Easy-to-understand validation results.
• Flexible Rule Structure: Configure validations using a simple and extensible rule schema.
• Works Everywhere: Compatible with both Node.js and browsers.

Installation

Install via npm:

npm install @shanewas/form-validation

Quick Start

import { ValidationController } from "@shanewas/form-validation";

// Initialize the validator
const validator = new ValidationController();

// Define form data
const formData = {
  name: { fieldId: "name", value: "john" },
  age: { fieldId: "age", value: 18 },
  email: { fieldId: "email", value: "[email protected]" },
};

// Define validation rules
const rules = [
  {
    ruleId: "userValidation",
    conditions: [
      {
        fieldId: "name",
        type: "REQUIRED",
        errorMessage: "Name is required",
      },
      {
        fieldId: "age",
        type: "COMPARISON",
        operator: "GREATER_THAN",
        value: 17,
        errorMessage: "Must be 18 or older",
      },
    ],
  },
];

// Validate
(async () => {
  try {
    const result = await validator.validateForm(formData, rules);
    console.log(result);
  } catch (error) {
    console.error("Validation failed:", error);
  }
})();

Validation Types

• REQUIRED: Ensure the field is not empty.
• COMPARISON: Compare field values using supported operators.
• DEPENDENCY: Validate a field based on another field's value.
• TYPE_CHECK: Check the field value's data type.
• LENGTH_CHECK: Validate the length of string or array fields.
• EMPTY_CHECK: Ensure fields are empty or non-empty.
• REGEX: Match field values against regular expressions.
• CUSTOM: Apply user-defined validation functions.

Rule Structure

Rules are defined as objects and support a wide range of properties:

{ ruleId: string, conditions: [ { fieldId: string, type: string, operator: string, value: any, expectedType: string, minLength: number, maxLength: number, dependentFieldId: string, dependentOperator: string, dependentValue: any, action: string, // e.g., "CLEAR_FORMFIELD", "UPDATE_VALUE" actionValue: any, // Additional data for the action errorMessage: string, description: string, }, ], }

Actions

The following actions are supported for rule conditions:

• CLEAR_FORMFIELD: Clears the value of the specified field.
• UPDATE_VALUE: Updates the field's value to a specified value.
• Custom Actions: Define custom actions in your implementation.

Operators

The following operators are supported in COMPARISON and DEPENDENCY validations:

• EQUALS
• NOT_EQUALS
• GREATER_THAN
• LESS_THAN
• GREATER_THAN_OR_EQUAL
• LESS_THAN_OR_EQUAL
• CONTAINS
• STARTS_WITH
• ENDS_WITH
• BETWEEN
• EMPTY
• NOT_EMPTY

Advanced Usage

Custom Validation

You can define your own validation logic using the CUSTOM type:

const rules = [
  {
    ruleId: "passwordValidation",
    conditions: [
      {
        fieldId: "password",
        type: "CUSTOM",
        customFunction: async (value, formData) => {
          return value.length < 8
            ? "Password must be at least 8 characters"
            : null;
        },
      },
    ],
  },
];

Dependent Fields

Validate a field based on the value of another field using DEPENDENCY:

const rules = [
  {
    ruleId: "dependencyCheck",
    conditions: [
      {
        fieldId: "state",
        type: "DEPENDENCY",
        dependentFieldId: "country",
        dependentOperator: "EQUALS",
        dependentValue: "USA",
        errorMessage: "State is required for USA",
      },
    ],
  },
];

Validation Result

The validation result provides detailed information about errors:

{
  hasErrors: true,
  errorCount: 2,
  details: {
    name: [{ message: "Name is required", type: "REQUIRED" }],
    age: [{ message: "Must be 18 or older", type: "COMPARISON" }],
  },
  summary: [
    { type: "error", fieldId: "name", message: "Name is required" },
    { type: "error", fieldId: "age", message: "Must be 18 or older" },
  ],
}

Example Validation with All Types

const formData = {
  username: { fieldId: "username", value: "" },
  age: { fieldId: "age", value: 17 },
  email: { fieldId: "email", value: "invalid-email" },
};

const rules = [
  {
    fieldId: "username",
    type: "REQUIRED",
    errorMessage: "Username is required",
  },
  {
    fieldId: "age",
    type: "COMPARISON",
    operator: "GREATER_THAN",
    value: 18,
    errorMessage: "Must be 18 or older",
  },
  {
    fieldId: "email",
    type: "REGEX",
    value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
    errorMessage: "Invalid email format",
  },
];

(async () => {
  try {
    const result = await validator.validateForm(formData, rules);
    console.log(result);
  } catch (error) {
    console.error("Validation failed:", error);
  }
})();

Requirements

• Node.js: Version 16 or later.
• Browser Support: ES Modules and modern browsers.

Contributing

We welcome contributions! Please see our Contributing Guidelines.

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

Support

• GitHub Issues
• Documentation

Acknowledgments

Special thanks to all contributors for their efforts in making this library robust and versatile!