reslib 1.0.3 → 2.0.0

package/build/validator/rules/format.d.ts

@@ -144,7 +144,7 @@ import { IsUrlOptions } from '../../utils/uri';
  *
  * @returns {PropertyDecorator} A property decorator that validates email format
  *
- * @throws {ValidationError} When validation fails, containing localized error message
+ * @throws {ValidatorError} When validation fails, containing localized error message
  *
  * @example
  * ```typescript
@@ -168,6 +168,64 @@ import { IsUrlOptions } from '../../utils/uri';
  * @public
  */
 export declare const IsEmail: (options?: IsEmailOptions | undefined) => PropertyDecorator;
+/**
+ * ## IsMongoId Decorator
+ *
+ * Property decorator that validates a property value is a valid MongoDB ObjectId.
+ * MongoDB ObjectIds are 12-byte values typically represented as 24-character hexadecimal strings.
+ *
+ * ### Usage
+ * ```typescript
+ * class Document {
+ *   @IsMongoId()
+ *   _id: string;
+ * }
+ * ```
+ *
+ * ### Validation Behavior
+ * - **Passes**: When value is a valid 24-character hexadecimal string
+ * - **Fails**: When value is not a string, wrong length, or contains non-hex characters
+ *
+ * ### Error Messages
+ * - Default: "This field must be a valid MongoDB ObjectId"
+ * - I18n key: "validator.mongoId"
+ *
+ * ### Related Decorators
+ * - Often used for database document IDs and references
+ *
+ * @returns A property decorator function
+ * @public
+ */
+export declare const IsMongoId: () => PropertyDecorator;
+/**
+ * ## IsHexadecimal Decorator
+ *
+ * Property decorator that validates a property value is a valid hexadecimal string.
+ * Accepts hexadecimal strings with or without "0x" or "0X" prefix.
+ *
+ * ### Usage
+ * ```typescript
+ * class Color {
+ *   @IsHexadecimal()
+ *   hexValue: string;
+ * }
+ * ```
+ *
+ * ### Validation Behavior
+ * - **Passes**: When value is a valid hexadecimal string (e.g., "1a2b3c", "0xFFFF")
+ * - **Fails**: When value contains non-hex characters or is not a string
+ *
+ * ### Error Messages
+ * - Default: "This field must be a valid hexadecimal value"
+ * - I18n key: "validator.hexadecimal"
+ *
+ * ### Related Decorators
+ * - Often used for color codes, hash values, and binary data representations
+ *
+ * @returns A property decorator function
+ * @public
+ */
+export declare const IsHexadecimal: () => PropertyDecorator;
 /**
  * @summary IsUrl Decorator
  *
@@ -308,7 +366,7 @@ export declare const IsEmail: (options?: IsEmailOptions | undefined) => Property
  * @param options.allowedProtocols - Array of allowed protocols without colons
  * @returns A property decorator that validates URL format
  *
- * @throws {ValidationError} When validation fails, containing localized error message
+ * @throws {ValidatorError} When validation fails, containing localized error message
  *
  * @example
  * ```typescript
@@ -469,7 +527,7 @@ export declare const IsUrl: (options?: IsUrlOptions | undefined) => PropertyDeco
  * @param options.countryCode - Country code to validate against specific country's format
  * @returns A property decorator that validates phone number format
  *
- * @throws {ValidationError} When validation fails, containing localized error message
+ * @throws {ValidatorError} When validation fails, containing localized error message
  *
  * @example
  * ```typescript
@@ -636,7 +694,7 @@ export declare const IsPhoneNumber: (countryCode?: "AF" | "AL" | "DZ" | "AS" | "
  * @param options.phoneNumber - Phone validation options with country code
  * @returns A property decorator that validates email or phone number format
  *
- * @throws {ValidationError} When validation fails, containing localized error message
+ * @throws {ValidatorError} When validation fails, containing localized error message
  *
  * @example
  * ```typescript
@@ -782,7 +840,7 @@ export declare const IsEmailOrPhone: (options?: {
  *
  * @returns A property decorator that validates file name format
  *
- * @throws {ValidationError} When validation fails, containing localized error message
+ * @throws {ValidatorError} When validation fails, containing localized error message
  *
  * @example
  * ```typescript
@@ -922,7 +980,7 @@ export declare const IsFileName: () => PropertyDecorator;
  *
  * @returns A property decorator that validates UUID format
  *
- * @throws {ValidationError} When validation fails, containing localized error message
+ * @throws {ValidatorError} When validation fails, containing localized error message
  *
  * @example
  * ```typescript
@@ -1068,7 +1126,7 @@ export declare const IsUUID: () => PropertyDecorator;
  *
  * @returns A property decorator that validates JSON format
  *
- * @throws {ValidationError} When validation fails, containing localized error message
+ * @throws {ValidatorError} When validation fails, containing localized error message
  *
  * @example
  * ```typescript
@@ -1206,7 +1264,7 @@ export declare const IsJSON: () => PropertyDecorator;
  *
  * @returns A property decorator that validates Base64 format
  *
- * @throws {ValidationError} When validation fails, containing localized error message
+ * @throws {ValidatorError} When validation fails, containing localized error message
  *
  * @example
  * ```typescript
@@ -1348,7 +1406,7 @@ export declare const IsBase64: () => PropertyDecorator;
  *
  * @returns A property decorator that validates hexadecimal color format
  *
- * @throws {ValidationError} When validation fails, containing localized error message
+ * @throws {ValidatorError} When validation fails, containing localized error message
  *
  * @example
  * ```typescript
@@ -1496,7 +1554,7 @@ export declare const IsHexColor: () => PropertyDecorator;
  *
  * @returns A property decorator that validates credit card number format and checksum
  *
- * @throws {ValidationError} When validation fails, containing localized error message
+ * @throws {ValidatorError} When validation fails, containing localized error message
  *
  * @example
  * ```typescript
@@ -1660,7 +1718,7 @@ export declare const IsCreditCard: () => PropertyDecorator;
  * @param ruleParams[0] - IP version: "4" (IPv4 only), "6" (IPv6 only), or "4/6" (both, default)
  * @returns A property decorator that validates IP address format
  *
- * @throws {ValidationError} When validation fails, containing localized error message
+ * @throws {ValidatorError} When validation fails, containing localized error message
  *
  * @example
  * ```typescript
@@ -1817,7 +1875,7 @@ export declare const IsIP: (...ruleParameters: string[]) => PropertyDecorator;
  *
  * @returns A property decorator that validates MAC address format
  *
- * @throws {ValidationError} When validation fails, containing localized error message
+ * @throws {ValidatorError} When validation fails, containing localized error message
  *
  * @example
  * ```typescript
@@ -1977,7 +2035,7 @@ export declare const IsMACAddress: () => PropertyDecorator;
  * @param ruleParams[1] - Optional custom error message key for i18n translation
  * @returns A property decorator that validates string patterns using regular expressions
  *
- * @throws {ValidationError} When validation fails, containing localized error message
+ * @throws {ValidatorError} When validation fails, containing localized error message
  *
  * @example
  * ```typescript
@@ -2821,5 +2879,116 @@ declare module '../types' {
                 message?: string;
             }
         ]>;
+        /**
+         * @summary MongoId Rule
+         *
+         * @description Validates that the field under validation is a valid MongoDB ObjectId.
+         * MongoDB ObjectIds are 12-byte values represented as 24-character hexadecimal strings.
+         *
+         * #### Validation Logic
+         * - Must be exactly 24 characters long
+         * - Must contain only hexadecimal characters (0-9, a-f, A-F)
+         * - Does not accept "0x" prefix (unlike general hex validation)
+         *
+         * @example
+         * ```typescript
+         * // Valid MongoDB ObjectIds
+         * await Validator.validate({
+         *   value: '507f1f77bcf86cd799439011',
+         *   rules: ['MongoId']
+         * }); // ✓ Valid
+         *
+         * // Invalid examples
+         * await Validator.validate({
+         *   value: '507f1f77bcf86cd79943901', // Too short
+         *   rules: ['MongoId']
+         * }); // ✗ Invalid
+         *
+         * await Validator.validate({
+         *   value: '507f1f77bcf86cd799439011a', // Too long
+         *   rules: ['MongoId']
+         * }); // ✗ Invalid
+         *
+         * await Validator.validate({
+         *   value: 'gggggggggggggggggggggggg', // Non-hex characters
+         *   rules: ['MongoId']
+         * }); // ✗ Invalid
+         *
+         * // Class validation
+         * class Document {
+         *   @IsMongoId()
+         *   _id: string;
+         *
+         *   @IsMongoId()
+         *   userId: string;
+         * }
+         * ```
+         *
+         * @returns true if valid MongoDB ObjectId, rejecting with error message if invalid
+         *
+         * @public
+         */
+        MongoId: ValidatorRuleParams<[]>;
+        /**
+         * @summary Hexadecimal Rule
+         *
+         * @description Validates that the field under validation is a valid hexadecimal string.
+         * Accepts hexadecimal strings with or without "0x" or "0X" prefix.
+         *
+         * #### Validation Logic
+         * - Contains only characters 0-9, a-f, or A-F
+         * - Can optionally start with "0x" or "0X" prefix
+         * - Must have at least one hex digit after any prefix
+         * - Can be of any length (after prefix)
+         *
+         * @example
+         * ```typescript
+         * // Valid hexadecimal strings
+         * await Validator.validate({
+         *   value: '1a2b3c',
+         *   rules: ['Hexadecimal']
+         * }); // ✓ Valid
+         *
+         * await Validator.validate({
+         *   value: '0xFFFF',
+         *   rules: ['Hexadecimal']
+         * }); // ✓ Valid
+         *
+         * await Validator.validate({
+         *   value: '0X123ABC',
+         *   rules: ['Hexadecimal']
+         * }); // ✓ Valid
+         *
+         * // Invalid examples
+         * await Validator.validate({
+         *   value: 'GHI', // Non-hex characters
+         *   rules: ['Hexadecimal']
+         * }); // ✗ Invalid
+         *
+         * await Validator.validate({
+         *   value: '0x', // No hex digits after prefix
+         *   rules: ['Hexadecimal']
+         * }); // ✗ Invalid
+         *
+         * await Validator.validate({
+         *   value: '', // Empty string
+         *   rules: ['Hexadecimal']
+         * }); // ✗ Invalid
+         *
+         * // Class validation
+         * class Color {
+         *   @IsHexadecimal()
+         *   hexValue: string;
+         *
+         *   @IsHexadecimal()
+         *   rgbValue?: string;
+         * }
+         * ```
+         *
+         * @returns true if valid hexadecimal string, rejecting with error message if invalid
+         *
+         * @public
+         */
+        Hexadecimal: ValidatorRuleParams<[]>;
     }
 }