@shanewas/form-validation NPM

@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: "john@example.com" },
};

// 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);
  }
})();