A TypeScript/JavaScript library for rule-based entity validation with boundary checking for strings, numbers, dates, enums, objects, and arrays.
npm install @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.
- ✨ 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
| 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 |
``bash`
npm install @ticatec/web-bean-validator
This package requires the following peer dependencies:
`bash`
npm install @ticatec/i18n dayjs
`typescript
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);
}
`
#### String Validation with Format
`typescript
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
`typescript
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
`typescript
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
`typescript
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
`typescript
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
`typescript
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
`typescript
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...
}
`
All validators inherit from BaseValidator and support these common options:
`typescript
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;
`
`typescript`
class ValidationResult {
valid: boolean; // Whether validation passed
errors: any; // Object containing field errors
}
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.
`json``
{
"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"
}
}
}
We welcome contributions! Please see our Contributing Guide for details.
This project is licensed under the MIT License - see the LICENSE file for details.
- 📄 Documentation
- 🐛 Report Issues
- 💬 Discussions
See CHANGELOG.md for details about changes in each version.