Package Exports

@ticatec/web-bean-validator
@ticatec/web-bean-validator/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@ticatec/web-bean-validator) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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: 'john@example.com',
  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

Changelog

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