@ticatec/web-bean-validator

A powerful TypeScript/JavaScript library for rule-based entity validation with comprehensive boundary checking. Perfect for form validation, API data validation, and any scenario requiring robust data integrity checks.

中文文档 | English Documentation

Features

• ✨ Type-Safe: Full TypeScript support with comprehensive type definitions
• 🎯 Rule-Based: Define validation rules declaratively
• 🌐 I18n Ready: Built-in internationalization support
• 🔧 Extensible: Easy to create custom validators
• 📦 Lightweight: Minimal dependencies
• 🎨 Flexible: Support for conditional validation and custom checks

Supported Validators

| Validator | Description | Options | |-----------|-------------|---------| | StringValidator | String validation with length and format checks | minLen, format | | NumberValidator | Number validation with range checks | minValue, maxValue | | DateValidator | Date validation with range and relative date checks | from, to, maxDaysBefore, maxDaysAfter | | BooleanValidator | Boolean validation with type conversion | - | | EnumValidator | Enumeration validation | values | | ArrayValidator | Array validation with length and item validation | minLen, maxLen, rules | | ObjectValidator | Object validation with nested rules | rules |

Installation

npm install @ticatec/web-bean-validator

Dependencies

This package requires the following peer dependencies:

npm install @ticatec/i18n dayjs

Quick Start

Basic Usage

import BeanValidator from '@ticatec/web-bean-validator';
import { StringValidator, NumberValidator } from '@ticatec/web-bean-validator';

// Define validation rules
const rules = [
  new StringValidator('name', { 
    required: true, 
    minLen: 2,
    name: 'Full Name'
  }),
  new NumberValidator('age', { 
    required: true, 
    minValue: 0, 
    maxValue: 120,
    name: 'Age'
  })
];

// Validate data
const data = { name: 'John', age: 25 };
const result = BeanValidator.validate(data, rules);

if (result.valid) {
  console.log('Validation passed!');
} else {
  console.log('Validation errors:', result.errors);
}

Advanced Examples

String Validation with Format

import { StringValidator } from '@ticatec/web-bean-validator';

const emailValidator = new StringValidator('email', {
  required: true,
  name: 'Email Address',
  format: {
    regex: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
    message: 'Please enter a valid email address'
  }
});

Date Validation

import { DateValidator } from '@ticatec/web-bean-validator';

const birthdateValidator = new DateValidator('birthdate', {
  required: true,
  name: 'Birth Date',
  maxDaysBefore: 36500, // 100 years ago
  to: new Date() // Cannot be in the future
});

Array Validation

import { ArrayValidator, StringValidator } from '@ticatec/web-bean-validator';

const tagsValidator = new ArrayValidator('tags', {
  required: true,
  minLen: 1,
  maxLen: 5,
  name: 'Tags',
  rules: [
    new StringValidator('tag', { 
      required: true, 
      minLen: 2,
      name: 'Tag'
    })
  ]
});

Object Validation

import { ObjectValidator, StringValidator, NumberValidator } from '@ticatec/web-bean-validator';

const addressValidator = new ObjectValidator('address', {
  required: true,
  name: 'Address',
  rules: [
    new StringValidator('street', { required: true, name: 'Street' }),
    new StringValidator('city', { required: true, name: 'City' }),
    new StringValidator('zipCode', { required: true, name: 'ZIP Code' })
  ]
});

Conditional Validation

import { StringValidator } from '@ticatec/web-bean-validator';

const phoneValidator = new StringValidator('phone', {
  name: 'Phone Number',
  required: (data) => data.contactMethod === 'phone', // Required only if contact method is phone
  ignoreWhen: (data) => data.contactMethod === 'email' // Ignore if contact method is email
});

Custom Validation

import { StringValidator } from '@ticatec/web-bean-validator';

const passwordValidator = new StringValidator('password', {
  required: true,
  minLen: 8,
  name: 'Password',
  check: (value, data) => {
    if (!/(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/.test(value)) {
      return 'Password must contain at least one uppercase letter, one lowercase letter, and one number';
    }
    return null; // No error
  }
});

Complete Form Example

import BeanValidator from '@ticatec/web-bean-validator';
import { 
  StringValidator, 
  NumberValidator, 
  DateValidator, 
  EnumValidator,
  BooleanValidator 
} from '@ticatec/web-bean-validator';

// User registration form validation
const userRegistrationRules = [
  new StringValidator('username', {
    required: true,
    minLen: 3,
    name: 'Username',
    format: {
      regex: /^[a-zA-Z0-9_]+$/,
      message: 'Username can only contain letters, numbers, and underscores'
    }
  }),
  
  new StringValidator('email', {
    required: true,
    name: 'Email',
    format: {
      regex: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
      message: 'Please enter a valid email address'
    }
  }),
  
  new StringValidator('password', {
    required: true,
    minLen: 8,
    name: 'Password',
    check: (value) => {
      if (!/(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/.test(value)) {
        return 'Password must contain uppercase, lowercase, and number';
      }
      return null;
    }
  }),
  
  new NumberValidator('age', {
    required: true,
    minValue: 13,
    maxValue: 120,
    name: 'Age'
  }),
  
  new EnumValidator('country', {
    required: true,
    name: 'Country',
    values: ['US', 'CA', 'UK', 'AU', 'DE', 'FR', 'JP', 'CN']
  }),
  
  new BooleanValidator('agreeToTerms', {
    required: true,
    name: 'Terms Agreement',
    check: (value) => value === true ? null : 'You must agree to the terms'
  })
];

// Validate user data
const userData = {
  username: 'john_doe',
  email: '[email protected]',
  password: 'SecurePass123',
  age: 25,
  country: 'US',
  agreeToTerms: true
};

const validationResult = BeanValidator.validate(userData, userRegistrationRules);

if (validationResult.valid) {
  console.log('User registration data is valid!');
  // Proceed with registration...
} else {
  console.log('Validation errors:', validationResult.errors);
  // Display errors to user...
}

API Reference

BaseValidator Options

All validators inherit from BaseValidator and support these common options:

interface ValidatorOptions {
  name?: string;                    // Display name for error messages
  required?: boolean | RequiredCheck; // Whether field is required
  check?: CustomCheck;              // Custom validation function
  ignoreWhen?: IgnoreWhen;         // Condition to skip validation
}

type RequiredCheck = (data: any) => boolean;
type CustomCheck = (value: any, data: any) => string | null;
type IgnoreWhen = (data: any) => boolean;

ValidationResult

class ValidationResult {
  valid: boolean;     // Whether validation passed
  errors: any;        // Object containing field errors
}

Error Messages & Internationalization

The library includes built-in error messages that support internationalization through the @ticatec/i18n package. You can customize error messages by providing your own i18n resources.

Resource json file

{
  "ticatec": {
    "validation": {
      "required": "Please enter a value",
      "stringShortage": "The value must be at least {{length}} characters long",
      "earliestDate": "The value cannot be earlier than {{date}}",
      "finalDate": "The value cannot be later than {{date}}",
      "numberExceed": "The value cannot exceed {{max}}",
      "numberShortage": "The value cannot be less than {{min}}",
      "arrayExceed": "The value cannot contain more than {{length}} records",
      "arrayShortage": "The value must contain at least {{length}} records"
    }
  }
}

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📄 Documentation
• 🐛 Report Issues
• 💬 Discussions

Changelog

See CHANGELOG.md for details about changes in each version.