@resk/core
Version:
An innovative TypeScript framework that empowers developers to build applications with a fully decorator-based architecture for efficient resource management. By combining the power of decorators with a resource-oriented design, DecorRes enhances code cla
750 lines (749 loc) • 22.5 kB
TypeScript
/**
* ### IsEmail Decorator
*
* Validates that a property value is a properly formatted email address.
* Uses comprehensive email validation that checks for valid email format
* according to RFC standards.
*
* @example
* ```typescript
* class Contact {
* @IsRequired
* @IsEmail
* primaryEmail: string;
*
* @IsEmail // Optional email
* secondaryEmail?: string;
* }
*
* // Valid data
* const contact = {
* primaryEmail: "user@example.com",
* secondaryEmail: "backup@company.org"
* };
*
* // Invalid data
* const invalid = {
* primaryEmail: "not-an-email",
* secondaryEmail: "user@"
* };
* // Will fail validation with errors about invalid email format
* ```
*
* @decorator
* @since 1.0.0
* @see {@link IsRequired} - Often used together
* @public
*/
export declare const IsEmail: PropertyDecorator;
/**
* ### IsUrl Decorator
*
* Validates that a property value is a properly formatted URL. Checks for
* valid URL structure including protocol, domain, and optional path components.
*
* @example
* ```typescript
* class Website {
* @IsRequired
* @IsUrl
* homepage: string;
*
* @IsUrl
* blogUrl?: string;
*
* @IsUrl
* apiEndpoint: string;
* }
*
* // Valid data
* const website = {
* homepage: "https://example.com",
* blogUrl: "https://blog.example.com/posts",
* apiEndpoint: "https://api.example.com/v1"
* };
*
* // Invalid data
* const invalid = {
* homepage: "not-a-url",
* apiEndpoint: "ftp://invalid-protocol"
* };
* ```
*
* @decorator
* @since 1.0.0
* @public
*/
export declare const IsUrl: PropertyDecorator;
/**
* A validator decorator to check if a phone number is valid.
*
* @param phoneNumber The phone number to validate.
* @param ruleParams.countryCode The optional country code to validate the phone number against.
* @returns A validator decorator that checks if the phone number is valid.
* @example
* ```typescript
* class User {
* @IsPhoneNumber()
* phoneNumber: string;
* }
* ```
*/
export declare const IsPhoneNumber: (ruleParameters?: [countryCode?: "AF" | "AL" | "DZ" | "AS" | "AD" | "AO" | "AI" | "AG" | "AR" | "AM" | "AW" | "AU" | "AT" | "AZ" | "BS" | "BH" | "BD" | "BB" | "BY" | "BE" | "BZ" | "BJ" | "BM" | "BT" | "BO" | "BA" | "BW" | "BR" | "IO" | "VG" | "BN" | "BG" | "BF" | "BI" | "KH" | "CM" | "CA" | "CV" | "BQ" | "KY" | "CF" | "TD" | "CL" | "CN" | "CX" | "CC" | "CO" | "KM" | "CD" | "CG" | "CK" | "CR" | "CI" | "HR" | "CU" | "CW" | "CY" | "CZ" | "DK" | "DJ" | "DM" | "DO" | "EC" | "EG" | "SV" | "GQ" | "ER" | "EE" | "ET" | "FK" | "FO" | "FJ" | "FI" | "FR" | "GF" | "PF" | "GA" | "GM" | "GE" | "DE" | "GH" | "GI" | "GR" | "GL" | "GD" | "GP" | "GU" | "GT" | "GG" | "GN" | "GW" | "GY" | "HT" | "HN" | "HK" | "HU" | "IS" | "IN" | "ID" | "IR" | "IQ" | "IE" | "IM" | "IL" | "IT" | "JM" | "JP" | "JE" | "JO" | "KZ" | "KE" | "KI" | "KW" | "KG" | "LA" | "LV" | "LB" | "LS" | "LR" | "LY" | "LI" | "LT" | "LU" | "MO" | "MK" | "MG" | "MW" | "MY" | "MV" | "ML" | "MT" | "MH" | "MQ" | "MR" | "MU" | "YT" | "MX" | "FM" | "MD" | "MC" | "MN" | "ME" | "MS" | "MA" | "MZ" | "MM" | "NA" | "NR" | "NP" | "NL" | "NC" | "NZ" | "NI" | "NE" | "NG" | "NU" | "NF" | "KP" | "MP" | "NO" | "OM" | "PK" | "PW" | "PS" | "PA" | "PG" | "PY" | "PE" | "PH" | "PL" | "PT" | "PR" | "QA" | "RE" | "RO" | "RU" | "RW" | "BL" | "SH" | "KN" | "LC" | "MF" | "PM" | "VC" | "WS" | "SM" | "ST" | "SA" | "SN" | "RS" | "SC" | "SL" | "SG" | "SX" | "SK" | "SI" | "SB" | "SO" | "ZA" | "KR" | "SS" | "ES" | "LK" | "SD" | "SR" | "SJ" | "SZ" | "SE" | "CH" | "SY" | "TW" | "TJ" | "TZ" | "TH" | "TL" | "TG" | "TK" | "TO" | "TT" | "TN" | "TR" | "TM" | "TC" | "TV" | "VI" | "UG" | "UA" | "AE" | "GB" | "US" | "UY" | "UZ" | "VU" | "VA" | "VE" | "VN" | "WF" | "EH" | "YE" | "ZM" | "ZW" | "AX" | undefined] | undefined) => PropertyDecorator;
/**
* A validator decorator to check if value is a valid email or phone number.
*
* @param value The email or phone number to validate.
* @returns A validator decorator that checks if the email or phone number is valid.
* @example
* ```typescript
* class User {
* @IsEmailOrPhone
* emailOrPhoneNumber : string;
* }
* ```
*/
export declare const IsEmailOrPhone: PropertyDecorator;
/**
* ### IsFileName Decorator
*
* Validates that a property value is a valid filename. Checks for proper
* filename format and excludes invalid characters that are not allowed
* in file systems.
*
* @example
* ```typescript
* class FileUpload {
* @IsRequired
* @IsFileName
* filename: string;
*
* @IsFileName
* thumbnailName?: string;
* }
*
* // Valid data
* const upload = {
* filename: "document.pdf",
* thumbnailName: "thumb_001.jpg"
* };
*
* // Invalid data
* const invalid = {
* filename: "file<with>invalid:chars.txt"
* };
* ```
*
* @decorator
* @since 1.0.0
* @public
*/
export declare const IsFileName: PropertyDecorator;
/**
* ### UUID Rule
*
* Validates that the field under validation is a valid UUID (v1-v5).
*
* @example
* ```typescript
* // Class validation
* class Entity {
* @IsRequired
* @IsUUID
* id: string;
* }
* ```
*
* @param options - Validation options containing value and context
* @returns Promise resolving to true if valid, rejecting with error message if invalid
*
* @since 1.22.0
* @public
*/
export declare const IsUUID: PropertyDecorator;
/**
* ### JSON Rule
*
* Validates that the field under validation is valid JSON.
*
* @example
* ```typescript
* // Class validation
* class Config {
* @IsRequired
* @IsJSON
* settings: string;
* }
* ```
*
* @param options - Validation options containing value and context
* @returns Promise resolving to true if valid, rejecting with error message if invalid
*
* @since 1.22.0
* @public
*/
export declare const IsJSON: PropertyDecorator;
/**
* ### Base64 Rule
*
* Validates that the field under validation is valid Base64 encoded string.
*
* @example
* ```typescript
* // Class validation
* class ImageData {
* @IsRequired
* @IsBase64
* data: string;
* }
* ```
*
* @param options - Validation options containing value and context
* @returns Promise resolving to true if valid, rejecting with error message if invalid
*
* @since 1.22.0
* @public
*/
export declare const IsBase64: PropertyDecorator;
/**
* ### HexColor Rule
*
* Validates that the field under validation is a valid hexadecimal color code.
*
* @example
* ```typescript
* // Class validation
* class Theme {
* @IsRequired
* @IsHexColor
* primaryColor: string;
* }
* ```
*
* @param options - Validation options containing value and context
* @returns Promise resolving to true if valid, rejecting with error message if invalid
*
* @since 1.22.0
* @public
*/
export declare const IsHexColor: PropertyDecorator;
/**
* ### CreditCard Rule
*
* Validates that the field under validation is a valid credit card number using Luhn algorithm.
*
* @example
* ```typescript
* // Class validation
* class Payment {
* @IsRequired
* @IsCreditCard
* cardNumber: string;
* }
* ```
*
* @param options - Validation options containing value and context
* @returns Promise resolving to true if valid, rejecting with error message if invalid
*
* @since 1.22.0
* @public
*/
export declare const IsCreditCard: PropertyDecorator;
/**
* ### IP Rule
*
* Validates that the field under validation is a valid IP address.
*
* #### Parameters
* - IP version: "4", "6", or "4/6" (default: "4/6")
*
* @example
* ```typescript
* // Class validation
* class Server {
* @IsIP(['4']) // IPv4 only
* ipv4Address: string;
*
* @IsIP(['6']) // IPv6 only
* ipv6Address: string;
*
* @IsIP() // IPv4 or IPv6
* ipAddress: string;
* }
* ```
*
* @param options - Validation options with rule parameters
* @param options.ruleParams - Array containing IP version ("4", "6", or "4/6")
* @returns Promise resolving to true if valid, rejecting with error message if invalid
*
* @since 1.22.0
* @public
*/
export declare const IsIP: (ruleParameters: string[]) => PropertyDecorator;
/**
* ### MACAddress Rule
*
* Validates that the field under validation is a valid MAC address.
*
* @example
* ```typescript
* // Class validation
* class NetworkDevice {
* @IsRequired
* @IsMACAddress
* macAddress: string;
* }
* ```
*
* @param options - Validation options containing value and context
* @returns Promise resolving to true if valid, rejecting with error message if invalid
*
* @since 1.22.0
* @public
*/
export declare const IsMACAddress: PropertyDecorator;
/**
* ### Matches Rule
*
* Validates that the field under validation matches the specified regular expression.
*
* #### Parameters
* - Regular expression pattern (string)
*
* @example
* ```typescript
* // Class validation
* class CustomFormat {
* @Matches(['^[A-Z]{2}\\d{4}$','Invalid custom code format']) // Two letters followed by 4 digits
* customCode: string;
* }
* ```
*
* @param options - Validation options with rule parameters
* @param options.ruleParams - Array containing regex pattern
* @param options.ruleParams[0] - Regex pattern
* @param options.ruleParams[1] - Optional error message or error message translation key
* @returns Promise resolving to true if valid, rejecting with error message if invalid
*
* @since 1.22.0
* @public
*/
export declare const Matches: (ruleParameters: [rule: RegExp, errorMessage?: string | undefined]) => PropertyDecorator;
declare module "../types" {
interface IValidatorRulesMap<Context = unknown> {
/**
* ### UUID Rule
*
* Validates that the field under validation is a valid UUID (v1-v5).
*
* @example
* ```typescript
* // Valid UUIDs
* await Validator.validate({
* value: '550e8400-e29b-41d4-a716-446655440000',
* rules: ['UUID']
* }); // ✓ Valid
*
* await Validator.validate({
* value: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
* rules: ['UUID']
* }); // ✓ Valid
*
* // Invalid examples
* await Validator.validate({
* value: 'not-a-uuid',
* rules: ['UUID']
* }); // ✗ Invalid
*
* await Validator.validate({
* value: '550e8400-e29b-41d4-a716', // Too short
* rules: ['UUID']
* }); // ✗ Invalid
*
* await Validator.validate({
* value: 123,
* rules: ['UUID']
* }); // ✗ Invalid
*
* // Class validation
* class Entity {
* @Required
* @UUID
* id: string;
* }
* ```
*
* @param options - Validation options containing value and context
* @returns Promise resolving to true if valid, rejecting with error message if invalid
*
* @since 1.22.0
* @public
*/
UUID: IValidatorRuleParams<[], Context>;
/**
* ### JSON Rule
*
* Validates that the field under validation is valid JSON.
*
* @example
* ```typescript
* // Valid JSON strings
* await Validator.validate({
* value: '{"name": "John", "age": 30}',
* rules: ['JSON']
* }); // ✓ Valid
*
* await Validator.validate({
* value: '[1, 2, 3]',
* rules: ['JSON']
* }); // ✓ Valid
*
* // Invalid examples
* await Validator.validate({
* value: '{"name": "John", "age": }', // Invalid JSON
* rules: ['JSON']
* }); // ✗ Invalid
*
* await Validator.validate({
* value: 123,
* rules: ['JSON']
* }); // ✗ Invalid
*
* // Class validation
* class Config {
* @Required
* @JSON
* settings: string;
* }
* ```
*
* @param options - Validation options containing value and context
* @returns Promise resolving to true if valid, rejecting with error message if invalid
*
* @since 1.22.0
* @public
*/
JSON: IValidatorRuleParams<[], Context>;
/**
* ### Base64 Rule
*
* Validates that the field under validation is valid Base64 encoded string.
*
* @example
* ```typescript
* // Valid Base64 strings
* await Validator.validate({
* value: 'SGVsbG8gV29ybGQ=', // "Hello World"
* rules: ['Base64']
* }); // ✓ Valid
*
* await Validator.validate({
* value: 'dGVzdA==', // "test"
* rules: ['Base64']
* }); // ✓ Valid
*
* // Invalid examples
* await Validator.validate({
* value: 'not-base64!',
* rules: ['Base64']
* }); // ✗ Invalid
*
* await Validator.validate({
* value: 123,
* rules: ['Base64']
* }); // ✗ Invalid
*
* // Class validation
* class ImageData {
* @Required
* @Base64
* data: string;
* }
* ```
*
* @param options - Validation options containing value and context
* @returns Promise resolving to true if valid, rejecting with error message if invalid
*
* @since 1.22.0
* @public
*/
Base64: IValidatorRuleParams<[], Context>;
/**
* ### HexColor Rule
*
* Validates that the field under validation is a valid hexadecimal color code.
*
* @example
* ```typescript
* // Valid hex colors
* await Validator.validate({
* value: '#FF0000',
* rules: ['HexColor']
* }); // ✓ Valid
*
* await Validator.validate({
* value: '#3366cc',
* rules: ['HexColor']
* }); // ✓ Valid
*
* await Validator.validate({
* value: '#abc', // Short format
* rules: ['HexColor']
* }); // ✓ Valid
*
* await Validator.validate({
* value: '#FF000080', // With alpha
* rules: ['HexColor']
* }); // ✓ Valid
*
* // Invalid examples
* await Validator.validate({
* value: '#GGG', // Invalid characters
* rules: ['HexColor']
* }); // ✗ Invalid
*
* await Validator.validate({
* value: '#12', // Too short
* rules: ['HexColor']
* }); // ✗ Invalid
*
* await Validator.validate({
* value: 123,
* rules: ['HexColor']
* }); // ✗ Invalid
*
* // Class validation
* class Theme {
* @Required
* @HexColor
* primaryColor: string;
* }
* ```
*
* @param options - Validation options containing value and context
* @returns Promise resolving to true if valid, rejecting with error message if invalid
*
* @since 1.22.0
* @public
*/
HexColor: IValidatorRuleParams<[], Context>;
/**
* ### CreditCard Rule
*
* Validates that the field under validation is a valid credit card number using Luhn algorithm.
*
* @example
* ```typescript
* // Valid credit card numbers
* await Validator.validate({
* value: '4532015112830366', // Visa test number
* rules: ['CreditCard']
* }); // ✓ Valid
*
* await Validator.validate({
* value: '4532-0151-1283-0366', // With dashes
* rules: ['CreditCard']
* }); // ✓ Valid
*
* // Invalid examples
* await Validator.validate({
* value: '4532015112830367', // Invalid checksum
* rules: ['CreditCard']
* }); // ✗ Invalid
*
* await Validator.validate({
* value: '123',
* rules: ['CreditCard']
* }); // ✗ Invalid
*
* await Validator.validate({
* value: 4532015112830366,
* rules: ['CreditCard']
* }); // ✗ Invalid
*
* // Class validation
* class Payment {
* @Required
* @CreditCard
* cardNumber: string;
* }
* ```
*
* @param options - Validation options containing value and context
* @returns Promise resolving to true if valid, rejecting with error message if invalid
*
* @since 1.22.0
* @public
*/
CreditCard: IValidatorRuleParams<[], Context>;
/**
* ### IP Rule
*
* Validates that the field under validation is a valid IP address.
*
* #### Parameters
* - IP version: "4", "6", or "4/6" (default: "4/6")
*
* @example
* ```typescript
* // Valid IP addresses
* await Validator.validate({
* value: '192.168.1.1',
* rules: ['IP[4]']
* }); // ✓ Valid IPv4
*
* await Validator.validate({
* value: '2001:0db8:85a3:0000:0000:8a2e:0370:7334',
* rules: ['IP[6]']
* }); // ✓ Valid IPv6
*
* await Validator.validate({
* value: '192.168.1.1',
* rules: ['IP'] // Default allows both
* }); // ✓ Valid
*
* // Invalid examples
* await Validator.validate({
* value: '256.1.1.1', // Invalid IPv4
* rules: ['IP[4]']
* }); // ✗ Invalid
*
* await Validator.validate({
* value: '192.168.1.1',
* rules: ['IP[6]'] // IPv4 not valid for IPv6 only
* }); // ✗ Invalid
*
* await Validator.validate({
* value: 123,
* rules: ['IP']
* }); // ✗ Invalid
*
* // Class validation
* class Server {
* @IsIP(['4']) // IPv4 only
* ipv4Address: string;
*
* @IsIP(['6']) // IPv6 only
* ipv6Address: string;
*
* @IsIP() // IPv4 or IPv6
* ipAddress: string;
* }
* ```
*
* @param options - Validation options with rule parameters
* @param options.ruleParams - Array containing IP version ("4", "6", or "4/6")
* @returns Promise resolving to true if valid, rejecting with error message if invalid
*
* @since 1.22.0
* @public
*/
IP: IValidatorRuleParams<string[], Context>;
/**
* ### MACAddress Rule
*
* Validates that the field under validation is a valid MAC address.
*
* @example
* ```typescript
* // Valid MAC addresses
* await Validator.validate({
* value: '00:1B:44:11:3A:B7',
* rules: ['MACAddress']
* }); // ✓ Valid
*
* await Validator.validate({
* value: '00-1B-44-11-3A-B7',
* rules: ['MACAddress']
* }); // ✓ Valid
*
* await Validator.validate({
* value: '001B44113AB7',
* rules: ['MACAddress']
* }); // ✓ Valid
*
* // Invalid examples
* await Validator.validate({
* value: '00:1B:44:11:3A', // Too short
* rules: ['MACAddress']
* }); // ✗ Invalid
*
* await Validator.validate({
* value: 'GG:1B:44:11:3A:B7', // Invalid characters
* rules: ['MACAddress']
* }); // ✗ Invalid
*
* await Validator.validate({
* value: 123,
* rules: ['MACAddress']
* }); // ✗ Invalid
*
* // Class validation
* class NetworkDevice {
* @Required
* @MACAddress
* macAddress: string;
* }
* ```
*
* @param options - Validation options containing value and context
* @returns Promise resolving to true if valid, rejecting with error message if invalid
*
* @since 1.22.0
* @public
*/
MACAddress: IValidatorRuleParams<[], Context>;
/**
* ### Matches Rule
*
* Validates that the field under validation matches the specified regular expression.
*
* #### Parameters
* - Regular expression pattern (string)
*
* @example
* ```typescript
* // Valid examples
* await Validator.validate({
* value: 'ABC1234',
* rules: ['Matches[^[A-Z]{3}\\d{4}$]']
* }); // ✓ Valid (3 letters + 4 digits)
*
* await Validator.validate({
* value: 'user@example.com',
* rules: ['Matches[^\\S+@\\S+\\.\\S+$]']
* }); // ✓ Valid email pattern
*
* // Invalid examples
* await Validator.validate({
* value: 'abc123',
* rules: ['Matches[^[A-Z]{3}\\d{4}$]']
* }); // ✗ Invalid (lowercase letters)
*
* await Validator.validate({
* value: 'invalid-pattern(',
* rules: ['Matches[(]'] // Invalid regex
* }); // ✗ Invalid
*
* await Validator.validate({
* value: 123,
* rules: ['Matches[\\d+]']
* }); // ✗ Invalid (not a string)
*
* // Class validation
* class CustomFormat {
* @Matches(['^[A-Z]{2}\\d{4}$','Invalid custom code format']) // Two letters followed by 4 digits
* customCode: string;
* }
* ```
*
* @param options - Validation options with rule parameters
* @param options.ruleParams - Array containing regex pattern
* @returns Promise resolving to true if valid, rejecting with error message if invalid
*
* @since 1.22.0
* @public
*/
Matches: IValidatorRuleParams<string[], Context>;
}
}