@fluojs/validation 1.0.5 → 2.0.0

package/dist/decorators.js

@@ -1,81 +1,18 @@
+import { createArrayValidationDecorator, createFlagValidationDecorator, createValidationDecorator, createValidationOptionsWithConfigDecorator, createValidatorJsDecorator } from './internal/decorator-factories.js';
+import { appendStandardClassValidationRule } from './internal/decorator-metadata.js';
+import { normalizeEnumValues } from './internal/enum-values.js';
 import { createClassValidatorFromStandardSchema, isStandardSchemaLike } from './standard-schema.js';
-const standardDtoValidationMetadataKey = Symbol.for('fluo.standard.dto-validation');
-const standardClassValidationMetadataKey = Symbol.for('fluo.standard.class-validation');
-function getStandardMetadataBag(metadata) {
-  if (metadata === null || metadata === undefined) {
-    throw new Error('Decorator metadata is not available. Ensure your environment supports TC39 decorator metadata (Stage 3).');
-  }
-  return metadata;
-}
-function getStandardDtoValidationMap(metadata) {
-  const bag = getStandardMetadataBag(metadata);
-  const current = bag[standardDtoValidationMetadataKey];
-  if (current) {
-    return current;
-  }
-  const created = new Map();
-  bag[standardDtoValidationMetadataKey] = created;
-  return created;
-}
-function getStandardClassValidationList(metadata) {
-  const bag = getStandardMetadataBag(metadata);
-  const current = bag[standardClassValidationMetadataKey];
-  if (current) {
-    return current;
-  }
-  const created = [];
-  bag[standardClassValidationMetadataKey] = created;
-  return created;
-}
-function appendStandardDtoValidationRule(metadata, propertyKey, rule) {
-  const map = getStandardDtoValidationMap(metadata);
-  map.set(propertyKey, [...(map.get(propertyKey) ?? []), rule]);
-}
-function appendStandardClassValidationRule(metadata, rule) {
-  getStandardClassValidationList(metadata).push(rule);
-}
 function resolveClassValidator(validate) {
   if (!isStandardSchemaLike(validate)) {
     return validate;
   }
   return createClassValidatorFromStandardSchema(validate);
 }
-function createValidationDecorator(ruleFactory) {
-  const decorator = (_value, context) => {
-    appendStandardDtoValidationRule(context.metadata, context.name, ruleFactory());
-  };
-  return decorator;
-}
-function createValidationOptionsWithConfigDecorator(ruleFactory) {
-  return (value, options) => {
-    return createValidationDecorator(() => ruleFactory(value, options));
-  };
-}
-function createFlagValidationDecorator(ruleFactory) {
-  return options => {
-    return createValidationDecorator(() => ruleFactory(options));
-  };
-}
-function createArrayValidationDecorator(ruleFactory) {
-  return (values, options) => {
-    return createValidationDecorator(() => ruleFactory(values, options));
-  };
-}
-function createValidatorJsDecorator(validator) {
-  return (args, options) => {
-    return createValidationDecorator(() => ({
-      args,
-      kind: 'validatorjs',
-      validator,
-      ...options
-    }));
-  };
-}
 
 /**
  * Validates that the decorated field is a string value.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a string validation rule.
  */
 export function IsString(options) {
@@ -88,7 +25,7 @@ export function IsString(options) {
 /**
  * Validates that the decorated field is a number value.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`, `allowNaN`).
  * @returns A field decorator that registers a number validation rule.
  */
 export function IsNumber(options) {
@@ -101,7 +38,7 @@ export function IsNumber(options) {
 /**
  * Validates that the decorated field is a boolean value.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a boolean validation rule.
  */
 export function IsBoolean(options) {
@@ -115,7 +52,7 @@ export function IsBoolean(options) {
  * Applies subsequent validators only when the condition returns `true`.
  *
  * @param validateIf Predicate that decides whether subsequent validators should run.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that adds conditional validation execution.
  */
 export const ValidateIf = (validateIf, options) => createValidationDecorator(() => ({
@@ -127,7 +64,7 @@ export const ValidateIf = (validateIf, options) => createValidationDecorator(()
 /**
  * Validates that the decorated field is neither `null` nor `undefined`.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a required-value rule.
  */
 export const IsDefined = createFlagValidationDecorator(options => ({
@@ -137,7 +74,7 @@ export const IsDefined = createFlagValidationDecorator(options => ({
 /**
  * Skips subsequent validators when the decorated field is `null` or `undefined`.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers optional-value semantics.
  */
 export const IsOptional = createFlagValidationDecorator(options => ({
@@ -148,7 +85,7 @@ export const IsOptional = createFlagValidationDecorator(options => ({
  * Validates that the decorated field strictly equals the expected value.
  *
  * @param value Expected value to compare against the field value.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an equality rule.
  */
 export const Equals = createValidationOptionsWithConfigDecorator((value, options) => ({
@@ -160,7 +97,7 @@ export const Equals = createValidationOptionsWithConfigDecorator((value, options
  * Validates that the decorated field does not strictly equal the forbidden value.
  *
  * @param value Forbidden value to compare against the field value.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an inequality rule.
  */
 export const NotEquals = createValidationOptionsWithConfigDecorator((value, options) => ({
@@ -171,7 +108,7 @@ export const NotEquals = createValidationOptionsWithConfigDecorator((value, opti
 /**
  * Validates that the decorated field is empty.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an empty-value rule.
  */
 export const IsEmpty = createFlagValidationDecorator(options => ({
@@ -181,7 +118,7 @@ export const IsEmpty = createFlagValidationDecorator(options => ({
 /**
  * Validates that the decorated field is not empty.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a non-empty-value rule.
  */
 export const IsNotEmpty = createFlagValidationDecorator(options => ({
@@ -192,7 +129,7 @@ export const IsNotEmpty = createFlagValidationDecorator(options => ({
  * Validates that the decorated field is included in the accepted values.
  *
  * @param values Accepted values for the field.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an inclusion rule.
  */
 export const IsIn = createArrayValidationDecorator((values, options) => ({
@@ -204,7 +141,7 @@ export const IsIn = createArrayValidationDecorator((values, options) => ({
  * Validates that the decorated field is not included in the rejected values.
  *
  * @param values Rejected values for the field.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an exclusion rule.
  */
 export const IsNotIn = createArrayValidationDecorator((values, options) => ({
@@ -215,7 +152,7 @@ export const IsNotIn = createArrayValidationDecorator((values, options) => ({
 /**
  * Validates that the decorated field is a `Date` value.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a date validation rule.
  */
 export const IsDate = createFlagValidationDecorator(options => ({
@@ -225,7 +162,7 @@ export const IsDate = createFlagValidationDecorator(options => ({
 /**
  * Validates that the decorated field is an array.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an array validation rule.
  */
 export const IsArray = createFlagValidationDecorator(options => ({
@@ -233,9 +170,10 @@ export const IsArray = createFlagValidationDecorator(options => ({
   ...options
 }));
 /**
- * Validates that the decorated field is an object value.
+ * Validates that the decorated field is a plain object value, including a null-prototype record.
+ * Class instances, `Date`, `Map`, and `Set` values are rejected.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an object validation rule.
  */
 export const IsObject = createFlagValidationDecorator(options => ({
@@ -245,7 +183,7 @@ export const IsObject = createFlagValidationDecorator(options => ({
 /**
  * Validates that the decorated field is an integer.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an integer validation rule.
  */
 export const IsInt = createFlagValidationDecorator(options => ({
@@ -255,7 +193,7 @@ export const IsInt = createFlagValidationDecorator(options => ({
 /**
  * Validates that the decorated field is a positive number.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a positive-number rule.
  */
 export const IsPositive = createFlagValidationDecorator(options => ({
@@ -265,7 +203,7 @@ export const IsPositive = createFlagValidationDecorator(options => ({
 /**
  * Validates that the decorated field is a negative number.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a negative-number rule.
  */
 export const IsNegative = createFlagValidationDecorator(options => ({
@@ -277,11 +215,11 @@ export const IsNegative = createFlagValidationDecorator(options => ({
  * Validates that the field value is included in the given enum-like set.
  *
  * @param values Enum object or literal value list that defines the accepted set.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an enum-membership rule.
  */
 export function IsEnum(values, options) {
-  const normalized = Array.isArray(values) ? values : Object.values(values);
+  const normalized = normalizeEnumValues(values);
   return createValidationDecorator(() => ({
     kind: 'enum',
     values: normalized,
@@ -293,7 +231,7 @@ export function IsEnum(values, options) {
  * Validates that the decorated field is divisible by the given divisor.
  *
  * @param value Divisor used for the numeric divisibility check.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a divisibility rule.
  */
 export const IsDivisibleBy = createValidationOptionsWithConfigDecorator((value, options) => ({
@@ -305,7 +243,7 @@ export const IsDivisibleBy = createValidationOptionsWithConfigDecorator((value,
  * Validates that the decorated field is greater than or equal to the minimum.
  *
  * @param value Inclusive minimum allowed numeric value.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a minimum-value rule.
  */
 export const Min = createValidationOptionsWithConfigDecorator((value, options) => ({
@@ -317,7 +255,7 @@ export const Min = createValidationOptionsWithConfigDecorator((value, options) =
  * Validates that the decorated field is less than or equal to the maximum.
  *
  * @param value Inclusive maximum allowed numeric value.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a maximum-value rule.
  */
 export const Max = createValidationOptionsWithConfigDecorator((value, options) => ({
@@ -329,7 +267,7 @@ export const Max = createValidationOptionsWithConfigDecorator((value, options) =
  * Validates that the decorated field is on or after the minimum date.
  *
  * @param value Inclusive minimum allowed date.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a minimum-date rule.
  */
 export const MinDate = createValidationOptionsWithConfigDecorator((value, options) => ({
@@ -341,7 +279,7 @@ export const MinDate = createValidationOptionsWithConfigDecorator((value, option
  * Validates that the decorated field is on or before the maximum date.
  *
  * @param value Inclusive maximum allowed date.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a maximum-date rule.
  */
 export const MaxDate = createValidationOptionsWithConfigDecorator((value, options) => ({
@@ -353,7 +291,7 @@ export const MaxDate = createValidationOptionsWithConfigDecorator((value, option
  * Validates that the decorated field contains the required substring.
  *
  * @param value Required substring.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a substring-presence rule.
  */
 export const Contains = createValidationOptionsWithConfigDecorator((value, options) => ({
@@ -365,7 +303,7 @@ export const Contains = createValidationOptionsWithConfigDecorator((value, optio
  * Validates that the decorated field does not contain the forbidden substring.
  *
  * @param value Forbidden substring.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a substring-exclusion rule.
  */
 export const NotContains = createValidationOptionsWithConfigDecorator((value, options) => ({
@@ -379,7 +317,7 @@ export const NotContains = createValidationOptionsWithConfigDecorator((value, op
  *
  * @param min Minimum inclusive length.
  * @param max Optional maximum inclusive length.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a bounded-length rule.
  */
 export function Length(min, max, options) {
@@ -393,9 +331,10 @@ export function Length(min, max, options) {
 
 /**
  * Validates a nested DTO instance using the provided constructor.
+ * Arrays, Sets, and Maps are traversed automatically without requiring `each`.
  *
  * @param dto DTO constructor (or lazy constructor factory) used for nested validation/materialization.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`); collection traversal is automatic.
  * @returns A field decorator that registers recursive nested DTO validation.
  */
 export function ValidateNested(dto, options) {
@@ -410,7 +349,7 @@ export function ValidateNested(dto, options) {
  * Validates that the decorated field has at least the given length.
  *
  * @param value Inclusive minimum string length.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a minimum-length rule.
  */
 export const MinLength = createValidationOptionsWithConfigDecorator((value, options) => ({
@@ -422,7 +361,7 @@ export const MinLength = createValidationOptionsWithConfigDecorator((value, opti
  * Validates that the decorated field has at most the given length.
  *
  * @param value Inclusive maximum string length.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a maximum-length rule.
  */
 export const MaxLength = createValidationOptionsWithConfigDecorator((value, options) => ({
@@ -460,196 +399,196 @@ export function Matches(pattern, modifiersOrOptions, options) {
 /**
  * Validates that the decorated field contains only alphabetic characters.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an alphabetic string rule.
  */
 export const IsAlpha = options => createValidatorJsDecorator('alpha')(undefined, options);
 /**
  * Validates that the decorated field contains only alphanumeric characters.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an alphanumeric string rule.
  */
 export const IsAlphanumeric = options => createValidatorJsDecorator('alphanumeric')(undefined, options);
 /**
  * Validates that the decorated field contains only ASCII characters.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an ASCII string rule.
  */
 export const IsAscii = options => createValidatorJsDecorator('ascii')(undefined, options);
 /**
  * Validates that the decorated field is a Base64 string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a Base64 string rule.
  */
 export const IsBase64 = options => createValidatorJsDecorator('base64')(undefined, options);
 /**
  * Validates that the decorated field is a boolean-like string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a boolean-string rule.
  */
 export const IsBooleanString = options => createValidatorJsDecorator('booleanString')(undefined, options);
 /**
  * Validates that the decorated field is a data URI string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a data URI rule.
  */
 export const IsDataURI = options => createValidatorJsDecorator('dataURI')(undefined, options);
 /**
  * Validates that the decorated field is a date string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a date-string rule.
  */
 export const IsDateString = options => createValidatorJsDecorator('dateString')(undefined, options);
 /**
  * Validates that the decorated field is a decimal string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a decimal-string rule.
  */
 export const IsDecimal = options => createValidatorJsDecorator('decimal')(undefined, options);
 /**
  * Validates that the decorated field is an email address.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an email-address rule.
  */
 export const IsEmail = options => createValidatorJsDecorator('email')(undefined, options);
 /**
  * Validates that the decorated field is a fully qualified domain name.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an FQDN rule.
  */
 export const IsFQDN = options => createValidatorJsDecorator('fqdn')(undefined, options);
 /**
  * Validates that the decorated field is a hexadecimal color string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a hex-color rule.
  */
 export const IsHexColor = options => createValidatorJsDecorator('hexColor')(undefined, options);
 /**
  * Validates that the decorated field is a hexadecimal string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a hexadecimal string rule.
  */
 export const IsHexadecimal = options => createValidatorJsDecorator('hexadecimal')(undefined, options);
 /**
  * Validates that the decorated field is a JSON string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a JSON-string rule.
  */
 export const IsJSON = options => createValidatorJsDecorator('json')(undefined, options);
 /**
  * Validates that the decorated field is a JSON Web Token string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a JWT-string rule.
  */
 export const IsJWT = options => createValidatorJsDecorator('jwt')(undefined, options);
 /**
  * Validates that the decorated field is a locale identifier.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a locale-string rule.
  */
 export const IsLocale = options => createValidatorJsDecorator('locale')(undefined, options);
 /**
  * Validates that the decorated field is lowercase.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a lowercase-string rule.
  */
 export const IsLowercase = options => createValidatorJsDecorator('lowercase')(undefined, options);
 /**
  * Validates that the decorated field is a magnet URI string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a magnet URI rule.
  */
 export const IsMagnetURI = options => createValidatorJsDecorator('magnetURI')(undefined, options);
 /**
  * Validates that the decorated field is a MIME type string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a MIME type rule.
  */
 export const IsMimeType = options => createValidatorJsDecorator('mimeType')(undefined, options);
 /**
  * Validates that the decorated field is a MongoDB object ID string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a MongoDB object ID rule.
  */
 export const IsMongoId = options => createValidatorJsDecorator('mongoId')(undefined, options);
 /**
  * Validates that the decorated field is a numeric string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a numeric-string rule.
  */
 export const IsNumberString = options => createValidatorJsDecorator('numberString')(undefined, options);
 /**
  * Validates that the decorated field is a network port string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a port-string rule.
  */
 export const IsPort = options => createValidatorJsDecorator('port')(undefined, options);
 /**
  * Validates that the decorated field is an RFC 3339 date-time string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an RFC 3339 string rule.
  */
 export const IsRFC3339 = options => createValidatorJsDecorator('rfc3339')(undefined, options);
 /**
  * Validates that the decorated field is a semantic version string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a semantic-version rule.
  */
 export const IsSemVer = options => createValidatorJsDecorator('semVer')(undefined, options);
 /**
  * Validates that the decorated field is uppercase.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an uppercase-string rule.
  */
 export const IsUppercase = options => createValidatorJsDecorator('uppercase')(undefined, options);
 /**
  * Validates that the decorated field is an ISO 8601 date-time string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an ISO 8601 string rule.
  */
 export const IsISO8601 = options => createValidatorJsDecorator('iso8601')(undefined, options);
 /**
  * Validates that the decorated field is a latitude value.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a latitude rule.
  */
 export const IsLatitude = options => createValidatorJsDecorator('latitude')(undefined, options);
 /**
  * Validates that the decorated field is a longitude value.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a longitude rule.
  */
 export const IsLongitude = options => createValidatorJsDecorator('longitude')(undefined, options);
 /**
  * Validates that the decorated field is a latitude/longitude coordinate string.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a latitude/longitude rule.
  */
 export const IsLatLong = options => createValidatorJsDecorator('latLong')(undefined, options);
@@ -662,7 +601,7 @@ export const IsLatLong = options => createValidatorJsDecorator('latLong')(undefi
  * version only.
  *
  * @param version Optional IP version filter (`'4'`, `'6'`, or `'4_or_6'`).
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an IP-address rule.
  */
 export function IsIP(version, options) {
@@ -758,7 +697,7 @@ export function IsCurrency(options) {
  * Validates that the decorated array contains all required values.
  *
  * @param values Required values that must be present in the array.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an array-contains rule.
  */
 export const ArrayContains = createArrayValidationDecorator((values, options) => ({
@@ -770,7 +709,7 @@ export const ArrayContains = createArrayValidationDecorator((values, options) =>
  * Validates that the decorated array excludes all forbidden values.
  *
  * @param values Forbidden values that must not be present in the array.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers an array-exclusion rule.
  */
 export const ArrayNotContains = createArrayValidationDecorator((values, options) => ({
@@ -781,7 +720,7 @@ export const ArrayNotContains = createArrayValidationDecorator((values, options)
 /**
  * Validates that the decorated array is not empty.
  *
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a non-empty-array rule.
  */
 export const ArrayNotEmpty = createFlagValidationDecorator(options => ({
@@ -792,7 +731,7 @@ export const ArrayNotEmpty = createFlagValidationDecorator(options => ({
  * Validates that the decorated array has at least the given size.
  *
  * @param value Inclusive minimum array length.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a minimum-array-size rule.
  */
 export const ArrayMinSize = createValidationOptionsWithConfigDecorator((value, options) => ({
@@ -804,7 +743,7 @@ export const ArrayMinSize = createValidationOptionsWithConfigDecorator((value, o
  * Validates that the decorated array has at most the given size.
  *
  * @param value Inclusive maximum array length.
- * @param options Optional validation behavior (`message`, `groups`, `always`, `each`).
+ * @param options Optional validation behavior (`message`, `code`, `each`).
  * @returns A field decorator that registers a maximum-array-size rule.
  */
 export const ArrayMaxSize = createValidationOptionsWithConfigDecorator((value, options) => ({
@@ -833,7 +772,8 @@ export function ArrayUnique(selectorOrOptions, options) {
 /**
  * Registers a custom field-level validation function.
  *
- * @param validate Custom validator callback invoked with `(dto, value)`.
+ * @param validate Custom validator callback invoked with `(value, context)`, where `context.dto`
+ * is the containing DTO and `context.propertyKey` is the decorated field key.
  * @param options Optional custom-validator metadata (`message`, `code`, `source`, `each`).
  * @returns A field decorator that registers a custom validation rule.
  */

package/dist/internal/decorator-factories.d.ts

@@ -0,0 +1,12 @@
+import type { DtoFieldValidationRule, ValidationDecoratorOptions } from '@fluojs/core/request-pipeline';
+import { type FieldDecoratorFn } from './decorator-metadata.js';
+type ValidatorJsRuleName = Extract<DtoFieldValidationRule, {
+    kind: 'validatorjs';
+}>['validator'];
+export declare function createValidationDecorator(ruleFactory: () => DtoFieldValidationRule): FieldDecoratorFn;
+export declare function createValidationOptionsWithConfigDecorator<T>(ruleFactory: (value: T, options: ValidationDecoratorOptions | undefined) => DtoFieldValidationRule): (value: T, options?: ValidationDecoratorOptions) => FieldDecoratorFn;
+export declare function createFlagValidationDecorator(ruleFactory: (options: ValidationDecoratorOptions | undefined) => DtoFieldValidationRule): (options?: ValidationDecoratorOptions) => FieldDecoratorFn;
+export declare function createArrayValidationDecorator<T>(ruleFactory: (values: readonly T[], options: ValidationDecoratorOptions | undefined) => DtoFieldValidationRule): (values: readonly T[], options?: ValidationDecoratorOptions) => FieldDecoratorFn;
+export declare function createValidatorJsDecorator(validator: ValidatorJsRuleName): (args?: readonly unknown[], options?: ValidationDecoratorOptions) => FieldDecoratorFn;
+export {};
+//# sourceMappingURL=decorator-factories.d.ts.map

package/dist/internal/decorator-factories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorator-factories.d.ts","sourceRoot":"","sources":["../../src/internal/decorator-factories.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAExG,OAAO,EAAmC,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEjG,KAAK,mBAAmB,GAAG,OAAO,CAAC,sBAAsB,EAAE;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC,CAAC,WAAW,CAAC,CAAC;AAEjG,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,sBAAsB,GAAG,gBAAgB,CAMrG;AAED,wBAAgB,0CAA0C,CAAC,CAAC,EAC1D,WAAW,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,0BAA0B,GAAG,SAAS,KAAK,sBAAsB,IAE1F,OAAO,CAAC,EAAE,UAAU,0BAA0B,KAAG,gBAAgB,CAG1E;AAED,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,CAAC,OAAO,EAAE,0BAA0B,GAAG,SAAS,KAAK,sBAAsB,IAEhF,UAAU,0BAA0B,KAAG,gBAAgB,CAGhE;AAED,wBAAgB,8BAA8B,CAAC,CAAC,EAC9C,WAAW,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,0BAA0B,GAAG,SAAS,KAAK,sBAAsB,IAEtG,QAAQ,SAAS,CAAC,EAAE,EAAE,UAAU,0BAA0B,KAAG,gBAAgB,CAGtF;AAED,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,mBAAmB,IAC/D,OAAO,SAAS,OAAO,EAAE,EAAE,UAAU,0BAA0B,KAAG,gBAAgB,CAQ3F"}