smartformvalidate

A schema-driven, extensible, and level-based form validation library for JavaScript and TypeScript.

Designed for developers who want:

• Full control over validation logic
• Clean separation between form data and validation rules
• Extensible validators and schemas
• Customizable error output (messages, suggestions, localization)

✨ Key Features

• 🔌 Schema-based fields (email, password, age, etc.)
• 🎚 Validation levels (soft, normal, strict)
• 🧩 Pluggable validators (register your own rules)
• 🎨 Custom error formatting (i18n-ready)
• 🧠 Smart merging logic (base rules → level rules → field overrides)
• 🧪 Fully typed with TypeScript

✅ This package supports a comprehensive set of commonly-used fields across real-world websites (auth forms, profiles, payments, admin panels, etc.).

📁 Project Structure (Important)

If you want to inspect or extend the internals, here is where things live:

Built-in Field Schemas

src/fields/

Each file defines a reusable field schema (e.g. email, password, age, phone, etc.).

Built-in Validator Functions

src/validators/

Each validator is an isolated function responsible for a single rule (minLength, required, isEmail, ...).

📌 If you want to understand how a rule works internally, start here.

📦 Installation

npm install smartformvalidate

or

yarn add smartformvalidate

🚀 Quick Start

Basic Usage

import { smartValidate } from 'smartformvalidate';

const formData = {
  email: '[email protected]',
  age: 25,
};

const result = smartValidate(formData);

console.log(result.valid); // true | false
console.log(result.errors);

🧱 Core Concepts

Form Data

smartformvalidate never mutates your data. It only reads from it.

const formData = {
  emailField: '[email protected]',
  age: 18,
};

Field Configuration

Each field can define how it should be validated.

const config = {
  fields: {
    emailField: {
      extends: 'email',
      level: 'strict',
      overrideRules: { minLength: 5 }
    },
  },
};

🧬 Schemas & extends

Schemas define reusable validation logic.

Example built-in schema:

email: {
  base: { required: true },
  soft: { email: true },
  strict: { email: true, minLength: 8 },
}

Usage:

emailField: {
  extends: 'email'
}

🎚 Validation Levels

Levels allow you to control strictness dynamically.

const config = {
  defaultLevel: 'strict',
};

Field-level override:

age: {
  extends: 'age',
  level: 'soft'
}

Priority:

Field Level → Form Default Level → Schema Default Level

⚖️ Rule Priority Order

Rules are merged in the following order (lowest → highest priority):

1. Schema base rules
2. Schema level rules
3. fieldConfig.required
4. fieldConfig.overrideRules

This guarantees predictable behavior.

🧩 Built-in Validators

The package ships with a large, production-ready set of validators covering most real-world use cases.

Basic Validators

• required
• requiredIf
• minLength
• maxLength
• regex
• mustInclude
• mustExclude
• isSameAs

Number Validators

• isNumber
• isInteger
• minNumber
• maxNumber

Array Validators

• minItems
• maxItems
• uniqueItems

Date Validators

• isDate
• minDate
• maxDate
• isValidBirthDate

String Validators

• isString
• isNumericString
• isStrongPassword

Enum / Boolean Validators

• isEnum
• isBoolean

Identification Validators

• isBloodType
• isNationalId
• isSocial
• isPhoneNumber
• isUuid
• isNationalCompanyId

URL / File / Object Validators

• isUrl
• isFileType
• isObject
• maxProperties
• mustHaveKeys

Financial / Payment Validators

• isCreditCard
• isIban
• cardExpire
• isCryptoAddress

Misc Validators

• isCoordinate
• isTimezone

Example:

overrideRules: {
  minLength: 6,
  maxLength: 20,
}

🧠 Custom Validators (Field-Level)

You can attach validators directly to a field.

age: {
  customValidators: [
    (value) => {
      if (value % 2 !== 0) {
        return {
          rule: 'evenNumber',
          code: 'NOT_EVEN',
          message: 'Age must be an even number',
        };
      }
      return null;
    }
  ]
}

🔌 Registering Global Validators (Plugin System)

You can add your own validators globally.

import { registerValidator } from 'smartformvalidate';

registerValidator('startsWithA', (value) => {
  if (typeof value === 'string' && !value.startsWith('A')) {
    return {
      rule: 'startsWithA',
      code: 'INVALID_START',
      message: 'Value must start with letter A',
    };
  }
  return null;
});

Usage in config:

overrideRules: {
  startsWithA: true
}

🎨 Error Formatter (Localization & Custom Output)

You can fully control error messages and suggestions.

const config = {
  errorFormatter: (error, ctx) => {
    if (error.rule === 'required') {
      return {
        ...error,
        message: 'This field is mandatory',
        suggestion: 'Please provide a value',
      };
    }

    if (error.rule === 'minLength') {
      return {
        ...error,
        message: `Minimum length is ${ctx.ruleConfig}`,
      };
    }

    return error;
  }
};

Perfect for:

• i18n
• UX customization
• Product-specific wording

📊 Validation Result Structure

{
  valid: boolean,
  errors: {
    [fieldName]: {
      valid: boolean,
      errors: FieldError[]
    }
  }
}

🧪 Full Example

const formData = {
  email: 'wrong-email',
  age: 15,
};

const config = {
  defaultLevel: 'strict',
  fields: {
    email: { extends: 'email' },
    age: { extends: 'age' }
  }
};

const result = smartValidate(formData, config);

🧠 Philosophy

This library is built around predictability, explicitness, and extensibility.

• No magic strings
• No hidden mutations
• No hard-coded messages

You control everything.

🛣 Roadmap

• Async validators
• Cross-field dependency helpers
• Built-in i18n packs
• React / Vue adapters

📄 License

MIT

🟦 Github

https://github.com/a-terohid/smartformvalidate