reslib 2.2.0 → 2.3.0

package/build/validator/validator.d.ts

@@ -1,7 +1,7 @@
-import { ClassConstructor, MakeOptional } from '../types';
+import { ClassConstructor, MakeOptional, MakeRequired } from '../types';
 import { I18n } from '../i18n';
 import { ValidatorBulkError, ValidatorClassError, ValidatorCreateBulkErrorPayload, ValidatorCreateClassErrorPayload, ValidatorCreateErrorPayload, ValidatorError } from './errors';
-import { ValidatorAsyncRuleResult, ValidatorBulkOptions, ValidatorBulkResult, ValidatorClassOptions, ValidatorClassResult, ValidatorDefaultMultiRule, ValidatorMultiRuleFunction, ValidatorMultiRuleNames, ValidatorMultiRuleOptions, ValidatorNestedRuleFunctionOptions, ValidatorObjectOptions, ValidatorObjectResult, ValidatorObjectRules, ValidatorObjectSchema, ValidatorOptions, ValidatorResult, ValidatorRule, ValidatorRuleFunction, ValidatorRuleFunctionsMap, ValidatorRuleName, ValidatorRuleObject, ValidatorRuleParams, ValidatorRuleResult, ValidatorRules, ValidatorSanitizedRuleObject, ValidatorSanitizedRules, ValidatorSuccess } from './types';
+import { ValidatorAsyncRuleResult, ValidatorBulkOptions, ValidatorBulkResult, ValidatorClassOptions, ValidatorClassResult, ValidatorDefaultMultiRule, ValidatorIfResolver, ValidatorIfRuleFunction, ValidatorIfRuleOptions, ValidatorMultiRuleFunction, ValidatorMultiRuleNames, ValidatorMultiRuleOptions, ValidatorNestedRuleFunctionOptions, ValidatorObjectOptions, ValidatorObjectResult, ValidatorObjectRules, ValidatorObjectSchema, ValidatorOptions, ValidatorResult, ValidatorRule, ValidatorRuleConfigMessage, ValidatorRuleFunction, ValidatorRuleFunctionsMap, ValidatorRuleName, ValidatorRuleObject, ValidatorRuleParams, ValidatorRuleResult, ValidatorRules, ValidatorSanitizedRuleObject, ValidatorSanitizedRules, ValidatorSuccess } from './types';
 export declare class Validator {
     private static readonly RULES_METADATA_KEY;
     /**
@@ -290,7 +290,7 @@ export declare class Validator {
      * @see {@link ValidatorOptionalOrEmptyRuleNames} - Type constraint for registered rules
      * @public
      */
-    static getRule<Context = unknown>(ruleName: ValidatorRuleName): ValidatorRuleFunction<[options?: import("../utils/index").IsEmailOptions | undefined], Context> | ValidatorRuleFunction<[options?: import("../utils/index").IsUrlOptions | undefined], Context> | ValidatorRuleFunction<[], Context> | ValidatorRuleFunction<[minLength: number], Context> | ValidatorRuleFunction<[maxLength: number], Context> | ValidatorRuleFunction<[length: number], Context> | ValidatorRuleFunction<any[], Context> | ValidatorRuleFunction<[date: string | number | Date], Context> | ValidatorRuleFunction<[date: string | number | Date], Context> | ValidatorRuleFunction<[minDate: string | number | Date, maxDate: string | number | Date], Context> | ValidatorRuleFunction<[date: string | number | Date], Context> | ValidatorRuleFunction<unknown[], Context> | ValidatorRuleFunction<[size: number], Context> | ValidatorRuleFunction<string[], Context> | ValidatorRuleFunction<[minSize: number], Context> | ValidatorRuleFunction<[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], Context> | ValidatorRuleFunction<[options?: {
+    static getRule<Context = unknown>(ruleName: ValidatorRuleName): ValidatorRuleFunction<[options?: import("../utils/index").IsEmailOptions | undefined], Context> | ValidatorRuleFunction<[options?: import("../utils/index").IsUrlOptions | undefined], Context> | ValidatorRuleFunction<[], Context> | ValidatorRuleFunction<[minLength: number], Context> | ValidatorRuleFunction<[maxLength: number], Context> | ValidatorRuleFunction<[length: number], Context> | ValidatorRuleFunction<any[], Context> | ValidatorRuleFunction<[date: string | number | Date], Context> | ValidatorRuleFunction<[date: string | number | Date], Context> | ValidatorRuleFunction<[minDate: string | number | Date, maxDate: string | number | Date], Context> | ValidatorRuleFunction<[date: string | number | Date], Context> | ValidatorRuleFunction<unknown[], Context> | ValidatorRuleFunction<[size: number], Context> | ValidatorRuleFunction<string[], Context> | ValidatorRuleFunction<[minSize: number], Context> | ValidatorRuleFunction<[countryCode?: "KM" | "BD" | "CF" | "FR" | "SR" | "TL" | "AF" | "AL" | "DZ" | "AS" | "AD" | "AO" | "AI" | "AG" | "AR" | "AM" | "AW" | "AU" | "AT" | "AZ" | "BS" | "BH" | "BB" | "BY" | "BE" | "BZ" | "BJ" | "BM" | "BT" | "BO" | "BA" | "BW" | "BR" | "IO" | "VG" | "BN" | "BG" | "BF" | "BI" | "KH" | "CM" | "CA" | "CV" | "BQ" | "KY" | "TD" | "CL" | "CN" | "CX" | "CC" | "CO" | "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" | "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" | "SJ" | "SZ" | "SE" | "CH" | "SY" | "TW" | "TJ" | "TZ" | "TH" | "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], Context> | ValidatorRuleFunction<[options?: {
         email?: import("../utils/index").IsEmailOptions;
         phoneNumber?: {
             countryCode?: import("../countries").CountryCode;
@@ -752,6 +752,79 @@ export declare class Validator {
      * @returns `true` if the value matches the sanitized rule structure, `false` otherwise
      */
     static isSanitizedRuleObject<TRuleParams extends ValidatorDefaultArray = ValidatorDefaultArray, Context = unknown>(rule: any): rule is ValidatorSanitizedRuleObject<TRuleParams, Context>;
+    /**
+     * ## Translate Rule Config Message
+     *
+     * Translates or processes a custom rule message from a `ValidatorRuleConfigMessage`.
+     * This method handles both static string messages (with optional i18n translation)
+     * and dynamic function-based messages.
+     *
+     * ### Purpose
+     * This method extracts the rule message translation logic into a reusable function
+     * that can be called independently of the `validate` method. It's particularly useful
+     * when you need to process custom rule messages in custom validation pipelines or
+     * when building custom error handling logic.
+     *
+     * ### Message Types
+     * 1. **Static String**: Can be a direct message or an i18n translation key
+     *    - If the string is a valid i18n key, it will be translated
+     *    - Otherwise, the string is used as-is
+     * 2. **Dynamic Function**: A function that receives validation options and returns a message
+     *    - If the function throws an error, an empty string is returned
+     *
+     * ### Examples
+     *
+     * #### Static String Message
+     * ```typescript
+     * const message = Validator.translateRuleConfigMessage({
+     *   message: 'This field is required',
+     *   i18n: i18nInstance,
+     *   validateOptions: { value: '', ruleName: 'Required', ruleParams: [] }
+     * });
+     * // message = 'This field is required'
+     * ```
+     *
+     * #### i18n Translation Key
+     * ```typescript
+     * const message = Validator.translateRuleConfigMessage({
+     *   message: 'validation.required',
+     *   i18n: i18nInstance,
+     *   validateOptions: { value: '', ruleName: 'Required', ruleParams: [] }
+     * });
+     * // message = 'Ce champ est obligatoire' (if i18n is set to French)
+     * ```
+     *
+     * #### Dynamic Function Message
+     * ```typescript
+     * const message = Validator.translateRuleConfigMessage({
+     *   message: ({ value, ruleName }) => `Value "${value}" failed ${ruleName} rule`,
+     *   i18n: i18nInstance,
+     *   validateOptions: { value: 'test', ruleName: 'Email', ruleParams: [] }
+     * });
+     * // message = 'Value "test" failed Email rule'
+     * ```
+     *
+     * @template Context - The type of the optional validation context
+     *
+     * @param options - The options for translating the rule message
+     * @param options.message - The rule message to translate (string or function)
+     * @param options.i18n - The i18n instance for translation
+     * @param options.validateOptions - The validation options passed to function messages
+     *
+     * @returns The translated/processed message string, or empty string if:
+     *          - The message is undefined/null
+     *          - The function message throws an error
+     *          - The message is not a valid string or function
+     *
+     * @see {@link ValidatorRuleConfigMessage} - Type definition for rule messages
+     * @see {@link validate} - Main validation method that uses this internally
+     * @public
+     */
+    static translateRuleConfigMessage<Context = unknown>({ message, i18n, validateOptions, }: {
+        message: ValidatorRuleConfigMessage | undefined;
+        i18n: I18n;
+        validateOptions: MakeRequired<Omit<ValidatorOptions<ValidatorDefaultArray, Context>, 'sanitizedRules' | 'rules' | 'rule'>, 'i18n' | 'ruleName' | 'ruleParams'>;
+    }): string;
     static validate<Context = unknown>({ rules, ...extra }: MakeOptional<ValidatorOptions<ValidatorDefaultArray, Context>, 'i18n' | 'ruleParams'>): Promise<ValidatorResult<Context>>;
     /**
      * ## Should Skip Validation
@@ -857,6 +930,122 @@ export declare class Validator {
      *
      */
     static validateArrayOfRule<Context = unknown, RulesFunctions extends ValidatorDefaultMultiRule<Context> = ValidatorDefaultMultiRule<Context>>(options: ValidatorMultiRuleOptions<Context, RulesFunctions>): ValidatorAsyncRuleResult;
+    /**
+     * ## Validate If Rule
+     *
+     * Conditional validation method that applies rules based on a resolver function.
+     * The resolver dynamically determines which rules to apply (if any) based on
+     * runtime conditions, enabling flexible, context-aware validation.
+     *
+     * ### Resolver Pattern
+     * Unlike traditional condition + then/otherwise approach, this method uses a single
+     * resolver function that returns:
+     * - **Rules array**: Apply these validation rules
+     * - **Object with `rules` and `message`**: Apply rules with custom error message
+     * - **Empty array, `undefined`, or `null`**: Skip validation (return success)
+     *
+     * ### Use Cases
+     * - **Optional Validation**: Only validate if a value is present
+     * - **Role-Based Rules**: Different validation based on user role
+     * - **Context-Aware Validation**: Rules that depend on application state
+     * - **Dynamic Messages**: Custom error messages based on context
+     * - **Feature Flags**: Enable/disable validation based on configuration
+     *
+     * ### Examples
+     *
+     * #### Optional field validation
+     * ```typescript
+     * const result = await Validator.validateIfRule({
+     *   value: optionalEmail,
+     *   resolver: ({ value }) => {
+     *     if (!value) return [];  // Skip validation
+     *     return ['Email'];
+     *   },
+     *   fieldName: 'email'
+     * });
+     * ```
+     *
+     * #### Role-based validation with custom message
+     * ```typescript
+     * const result = await Validator.validateIfRule({
+     *   value: password,
+     *   data: { role: 'admin' },
+     *   resolver: ({ data }) => {
+     *     if (data?.role === 'admin') {
+     *       return {
+     *         rules: ['Required', 'StrongPassword'],
+     *         message: 'Admin passwords must be strong',
+     *       };
+     *     }
+     *     return ['Required', { MinLength: [6] }];
+     *   },
+     *   fieldName: 'password'
+     * });
+     * ```
+     *
+     * #### Context-aware validation
+     * ```typescript
+     * const result = await Validator.validateIfRule({
+     *   value: username,
+     *   context: { strictMode: true },
+     *   resolver: ({ context }) => {
+     *     if (context?.strictMode) {
+     *       return ['Required', 'Alphanumeric', { MinLength: [5] }];
+     *     }
+     *     return ['Required'];
+     *   },
+     *   fieldName: 'username'
+     * });
+     * ```
+     *
+     * #### Async resolver - Load rules from database
+     * ```typescript
+     * const result = await Validator.validateIfRule({
+     *   value: password,
+     *   context: { tenantId: 'tenant-123' },
+     *   resolver: async ({ context }) => {
+     *     // Load validation config from database
+     *     const config = await loadValidationConfig(context?.tenantId);
+     *     return config.passwordRules;
+     *   },
+     *   fieldName: 'password'
+     * });
+     * ```
+     *
+     * #### Async resolver - Feature flag check
+     * ```typescript
+     * const result = await Validator.validateIfRule({
+     *   value: username,
+     *   resolver: async () => {
+     *     const useStrictValidation = await featureFlags.isEnabled('strict-username');
+     *     if (useStrictValidation) {
+     *       return ['Required', 'Alphanumeric', { MinLength: [5] }];
+     *     }
+     *     return ['Required'];
+     *   },
+     *   fieldName: 'username'
+     * });
+     * ```
+     *
+     * @template Context - Type of the optional validation context
+     *
+     * @param options - The validation options including resolver function
+     * @param options.resolver - Function that returns rules to apply (sync or async)
+     * @param options.value - The value to validate
+     * @param options.data - Optional additional data (other fields)
+     * @param options.context - Optional application-specific context
+     * @param options.message - Optional fallback message (used if resolver doesn't provide one)
+     *
+     * @returns ValidatorAsyncRuleResult - `true` if validation passes, error string otherwise
+     *
+     * @public
+     * @async
+     * @see {@link if} - Factory method to create reusable If rules
+     * @see {@link ValidatorIfRuleOptions} - Options interface
+     * @see {@link ValidatorIfResolver} - Resolver function type (supports sync/async)
+     * @see {@link ValidatorIfResolverResult} - Resolver return type
+     */
+    static validateIfRule<Context = unknown>(options: ValidatorIfRuleOptions<Context>): ValidatorAsyncRuleResult;
     static getI18nTranslateOptions<Context = unknown>({ fieldName, propertyName, fieldLabel, translatedPropertyName, context, ...rest }: Partial<ValidatorOptions<ValidatorDefaultArray, Context>>): Partial<ValidatorOptions<ValidatorDefaultArray, Context>>;
     /**
      * ## Validate Nested Rule (Core Nested Validation Executor)
@@ -1043,7 +1232,7 @@ export declare class Validator {
      * @public
      * @async
      */
-    static validateMultiRule<Context = unknown, RulesFunctions extends ValidatorDefaultMultiRule<Context> = ValidatorDefaultMultiRule<Context>>(ruleName: ValidatorMultiRuleNames, { value, ruleParams, startTime, ...extra }: ValidatorMultiRuleOptions<Context, RulesFunctions>): Promise<string | true>;
+    static validateMultiRule<Context = unknown, RulesFunctions extends ValidatorDefaultMultiRule<Context> = ValidatorDefaultMultiRule<Context>>(ruleName: ValidatorMultiRuleNames, { value, ruleParams, startTime, message, ...extra }: ValidatorMultiRuleOptions<Context, RulesFunctions>): Promise<string | true>;
     /**
      * ## Create OneOf Validation Rule
      *
@@ -1237,6 +1426,129 @@ export declare class Validator {
      *
      */
     static arrayOf<Context = unknown>(ruleParams: ValidatorDefaultMultiRule<Context>): ValidatorRuleFunction<ValidatorDefaultArray, Context>;
+    /**
+     * ## Create If Validation Rule
+     *
+     * Factory method that creates a conditional validation rule function. This method provides
+     * a programmatic way to create validation rules that apply different sub-rules based on
+     * a runtime resolver function.
+     *
+     * ### Resolver Pattern
+     * Unlike traditional condition + then/otherwise approach, this factory accepts a single
+     * resolver function that returns the rules to apply. This enables:
+     * - **Complex conditional logic**: Multi-branch conditions, nested checks
+     * - **Dynamic messages**: Different messages based on context
+     * - **Rule composition**: Build rules dynamically from multiple sources
+     * - **Early exit**: Return empty array to skip validation entirely
+     *
+     * ### Return Value
+     * Returns a `ValidatorRuleFunction` that can be used:
+     * - In `Validator.validate()` calls
+     * - In validation decorators like `@IsProperty()`
+     * - As part of rule arrays in class-based validation
+     *
+     * ### Examples
+     *
+     * #### Optional Field Validation
+     * ```typescript
+     * // Only validate email format if value is present
+     * const optionalEmail = Validator.if(({ value }) => {
+     *   if (!value) return [];  // Skip validation
+     *   return ['Email'];
+     * });
+     *
+     * await optionalEmail({ value: '' }); // true (resolver returns [])
+     * await optionalEmail({ value: 'invalid' }); // error (Email fails)
+     * await optionalEmail({ value: 'user@example.com' }); // true
+     * ```
+     *
+     * #### Role-Based Validation
+     * ```typescript
+     * const passwordRule = Validator.if(({ data }) => {
+     *   if (data?.role === 'admin') {
+     *     return ['Required', 'StrongPassword'];
+     *   }
+     *   if (data?.role === 'moderator') {
+     *     return ['Required', { MinLength: [8] }];
+     *   }
+     *   return ['Required', { MinLength: [6] }];
+     * });
+     * ```
+     *
+     * #### With Custom Message
+     * ```typescript
+     * const strictModeRule = Validator.if(({ context, i18n }) => {
+     *   if (context?.strictMode) {
+     *     return {
+     *       rules: ['Required', { MinLength: [10] }],
+     *       message: i18n.t('validation.strict_mode_required'),
+     *     };
+     *   }
+     *   return ['Required'];
+     * });
+     * ```
+     *
+     * #### Dependent Field Validation
+     * ```typescript
+     * const confirmPasswordRule = Validator.if(({ value, data }) => {
+     *   if (!data?.password) return [];  // Skip if no password
+     *   return {
+     *     rules: ['Required', { Equals: [data.password] }],
+     *     message: 'Passwords must match',
+     *   };
+     * });
+     * ```
+     *
+     * #### Async Resolver - Load from Database
+     * ```typescript
+     * const dynamicRule = Validator.if(async ({ context }) => {
+     *   const config = await loadValidationConfig(context?.tenantId);
+     *   return config.rules;
+     * });
+     * ```
+     *
+     * #### Async Resolver - Feature Flag
+     * ```typescript
+     * const featureFlagRule = Validator.if(async () => {
+     *   const enabled = await featureFlags.isEnabled('strict-validation');
+     *   return enabled ? ['Required', 'StrictFormat'] : ['Required'];
+     * });
+     * ```
+     *
+     * ### Decorator Usage
+     * ```typescript
+     * class UserForm {
+     *   @IsProperty([
+     *     Validator.if(({ data }) => {
+     *       if (data?.userType === 'business') {
+     *         return ['Required', { MinLength: [3] }];
+     *       }
+     *       return [];  // No validation for non-business users
+     *     })
+     *   ])
+     *   companyName?: string;
+     * }
+     * ```
+     *
+     * ### Sync vs Async
+     * The resolver supports both synchronous and asynchronous operations:
+     * - **Sync**: Return the result directly for simple, non-blocking logic
+     * - **Async**: Return a Promise for database lookups, API calls, or async configuration
+     *
+     * @template Context - Type of the optional validation context
+     *
+     * @param resolver - Resolver function (sync or async) that returns rules to apply
+     *
+     * @returns A `ValidatorRuleFunction` that performs conditional validation
+     *
+     * @public
+     * @see {@link validateIfRule} - The underlying validation method
+     * @see {@link ValidatorIfResolver} - Resolver function type (supports sync/async)
+     * @see {@link ValidatorIfResolverResult} - Resolver return type
+     * @see {@link oneOf} - Similar factory for OR logic validation
+     * @see {@link allOf} - Similar factory for AND logic validation
+     */
+    static if<Context = unknown>(resolver: ValidatorIfResolver<Context>): ValidatorRuleFunction<ValidatorDefaultArray, Context>;
     /**
      * ## Create Nested Validation Rule Factory
      *
@@ -3237,7 +3549,27 @@ export declare class Validator {
      */
     static isAnyError(result: unknown): result is ValidatorError | ValidatorClassError | ValidatorBulkError;
     private static _prepareRuleDecorator;
-    private static _buildRuleDecorator;
+    /**
+     * ## Create Property Decorator from Rule
+     *
+     * Creates a property decorator for a validation rule with specific parameters.
+     * This method combines rule registration (if a name is provided) with property decorator creation.
+     * Unlike `buildRuleDecorator` which returns a factory, this returns the actual decorator
+     * bound to the provided rule parameters.
+     *
+     * @remarks
+     * **Naming Guide**:
+     * - `buildRuleDecorator`: Creates a **Factory** (e.g. `IsRequired()`) that produces decorators.
+     * - `createPropertyDecoratorFromRule`: Creates the **Decorator** instance directly from parameters.
+     *
+     * @param ruleParameters - The parameters for the validation rule
+     * @param ruleFunction - The validation rule logic
+     * @param ruleName - Optional name to register the rule with
+     * @param symbolMarker - Internal symbol marker
+     * @returns The PropertyDecorator
+     * @public
+     */
+    static createPropertyDecoratorFromRule<TRuleParams extends ValidatorRuleParams = ValidatorRuleParams, Context = unknown>(ruleParameters: TRuleParams, ruleFunction: ValidatorRuleFunction<TRuleParams, Context>, ruleName?: ValidatorRuleName, symbolMarker?: symbol): PropertyDecorator;
     /**
      * ## Build TClass Rule Decorator Factory
      *
@@ -3677,6 +4009,45 @@ export declare class Validator {
      * @public
      */
     static buildMultiRuleDecorator<Context = unknown, RulesFunctions extends ValidatorDefaultMultiRule<Context> = ValidatorDefaultMultiRule<Context>>(ruleFunction: ValidatorMultiRuleFunction<Context, RulesFunctions>, symbolMarker?: symbol): (ruleParameters: RulesFunctions) => PropertyDecorator;
+    /**
+     * ## Build If Rule Decorator Factory
+     *
+     * Creates a specialized decorator factory for the conditional `@If` rule.
+     * This method wraps `_buildRuleDecorator` to specifically handle the single
+     * resolver function argument pattern used by `Validator.if`.
+     *
+     * ### Purpose
+     * Standard decorators created by `buildRuleDecorator` typically accept rule parameters
+     * as a spread of arguments (`...args`). However, the `@If` decorator accepts a
+     * single resolver function argument. This factory method adapts the generic decorator
+     * builder to enforce this specific signature, providing better type safety and DX
+     * for conditional validation.
+     *
+     * ### How It Works
+     * 1. Takes the `If` validation function as input
+     * 2. Returns a new decorator factory function
+     * 3. This factory takes a single `ValidatorIfResolver` argument
+     * 4. It passes this resolver as a single-element array to the underlying `_buildRuleDecorator`
+     *
+     * ### Benefits
+     * - **Type Safety**: Enforces that exactly one resolver is passed
+     * - **Simplified API**: Users just pass the function: `@If(({ value }) => ...)`
+     * - **Internal consistency**: Reuses the core decorator infrastructure
+     *
+     * @template Context - Type of the optional validation context
+     *
+     * @param ruleFunction - The core validation logic function (processes the rule)
+     * @param symbolMarker - Optional symbol to tag the decorator for reflection
+     *
+     * @returns A decorator factory that accepts a resolver function
+     *
+     * @public
+     * @see {@link createPropertyDecoratorFromRule} - The internal decorator builder
+     * @see {@link ValidatorIfRuleFunction} - The type of the validation function
+     * @see {@link ValidatorIfResolver} - The resolver type accepted by the decorator
+     * @see {@link ValidatorIfResolver} - The resolver type accepted by the decorator
+     */
+    static buildIfRuleDecorator<Context = unknown>(ruleFunction: ValidatorIfRuleFunction<Context>, symbolMarker?: symbol): (ifRuleResolver: ValidatorIfResolver<Context>) => PropertyDecorator;
     /**
      * ## Build Property Decorator Factory
      *