@4riders/reform 3.0.24

package/src/yop/constraints/MinMaxConstraints.ts

@@ -0,0 +1,53 @@
+import { Constraint, validateConstraint } from "./Constraint"
+import { InternalValidationContext, ValuedContext } from "../ValidationContext"
+
+/**
+ * Interface for min and max constraints on a value.
+ * @template Value - The type of the value being validated.
+ * @template MinMax - The type for min/max values.
+ * @template Parent - The type of the parent object.
+ * @property min - Minimum constraint for the value, if any.
+ * @property max - Maximum constraint for the value, if any.
+ * @property isMinMaxType - Type guard for min/max values.
+ * @category Shared Constraints
+ */
+export interface MinMaxConstraints<Value, MinMax, Parent = unknown> {
+    /**
+     * Minimum constraint for the value. The value must be greater than or equal to this constraint.
+     */
+    min?: Constraint<NonNullable<Value>, MinMax | null | undefined, Parent>
+    /**
+     * Maximum constraint for the value. The value must be less than or equal to this constraint.
+     */
+    max?: Constraint<NonNullable<Value>, MinMax | null | undefined, Parent>
+    /**
+     * Optional type guard function to determine if a value is a valid min/max constraint. This can be used to ensure
+     * that the constraint values are of the expected type.
+     */
+    isMinMaxType?: (value: any) => value is MinMax
+}
+
+/**
+ * Validates min and max constraints for a value.
+ * @template Value - The type of the value being validated.
+ * @template MinMax - The type for min/max values.
+ * @template Parent - The type of the parent object.
+ * @param context - The validation context.
+ * @param constraints - The min/max constraints to validate.
+ * @param isConstraintValue - Type guard for min/max values.
+ * @param validateMin - Function to validate the min constraint.
+ * @param validateMax - Function to validate the max constraint.
+ * @returns True if both min and max constraints pass, false otherwise.
+ * @ignore
+ */
+export function validateMinMaxConstraints<Value, MinMax, Parent>(
+    context: InternalValidationContext<Value, Parent>,
+    constraints: MinMaxConstraints<Value, MinMax, Parent>,
+    isConstraintValue: (value: any) => value is MinMax,
+    validateMin: (value: NonNullable<Value>, min: NonNullable<MinMax>) => boolean,
+    validateMax: (value: NonNullable<Value>, max: NonNullable<MinMax>) => boolean) {
+    return (
+        validateConstraint(context as ValuedContext<Value, Parent>, constraints, "min", isConstraintValue, validateMin) &&
+        validateConstraint(context as ValuedContext<Value, Parent>, constraints, "max", isConstraintValue, validateMax)
+    )
+}

package/src/yop/constraints/OneOfConstraint.ts

@@ -0,0 +1,40 @@
+import { Constraint, validateConstraint } from "./Constraint"
+import { InternalValidationContext, ValuedContext } from "../ValidationContext"
+
+/**
+ * Interface for a constraint that checks if a value is one of a set of allowed values.
+ * @template Value - The type of the value being validated.
+ * @template Parent - The type of the parent object.
+ * @property oneOf - Constraint for allowed values, if any.
+ * @category Shared Constraints
+ */
+export interface OneOfConstraint<Value, Parent = unknown> {
+    oneOf?: Constraint<NonNullable<Value>, NoInfer<NonNullable<Value>>[], Parent>
+}
+
+/**
+ * Validates the oneOf constraint for a value.
+ * @template Value - The type of the value being validated.
+ * @template OneOfType - The type for the allowed values array.
+ * @template Parent - The type of the parent object.
+ * @param context - The validation context.
+ * @param constraints - The oneOf constraint to validate.
+ * @param isConstraintValue - Type guard for the allowed values array.
+ * @param equals - Optional equality function for comparing values.
+ * @returns True if the value is one of the allowed values, false otherwise.
+ * @ignore
+ */
+export function validateOneOfConstraint<Value, OneOfType extends NoInfer<NonNullable<Value>>[], Parent>(
+    context: InternalValidationContext<Value, Parent>,
+    constraints: OneOfConstraint<Value, Parent>,
+    isConstraintValue: (value: any) => value is OneOfType,
+    equals?: (value1: NonNullable<Value>, value2: NonNullable<Value>) => boolean
+) {
+    return validateConstraint(
+        context as ValuedContext<Value, Parent>,
+        constraints,
+        "oneOf",
+        isConstraintValue,
+        (value, array) => equals == null ? array.includes(value) : array.some((item) => equals(value, item))
+    )
+}

package/src/yop/constraints/TestConstraint.ts

@@ -0,0 +1,176 @@
+import { InternalValidationContext, Level, ValidationContext, ValidationStatus } from "../ValidationContext"
+import { ConstraintFunction, ConstraintMessage } from "./Constraint"
+import { isFunction, isObject } from "../TypesUtil"
+import { joinPath } from "../ObjectsUtil"
+
+/**
+ * Type for test constraint messages, which can be a simple message, a tuple of message and level, a boolean, or undefined.
+ * @category Shared Constraints
+ */
+export type TestConstraintMessage = ConstraintMessage | readonly [ConstraintMessage, Level] | boolean | undefined
+
+/**
+ * Type for a test constraint function, which can return a test constraint message or be undefined.
+ * @template Value - The type of the value being validated.
+ * @template Parent - The type of the parent object.
+ * @category Shared Constraints
+ */
+export type TestConstraintFunction<Value, Parent = unknown> = ConstraintFunction<NonNullable<Value>, TestConstraintMessage, Parent>
+
+/**
+ * Interface for an asynchronous test constraint.
+ * @template Value - The type of the value being validated.
+ * @template Parent - The type of the parent object.
+ * @property promise - Function returning a promise for the constraint message.
+ * @property pendingMessage - Message to show while pending.
+ * @property unavailableMessage - Message to show if async service is unavailable.
+ * @property dependencies - Function to get dependencies for revalidation.
+ * @property revalidate - Function to determine if revalidation is needed.
+ * @category Shared Constraints
+ */
+export interface AsyncTestConstraint<Value, Parent = unknown> {
+    promise: (context: ValidationContext<NonNullable<Value>, Parent>) => Promise<TestConstraintMessage>
+    pendingMessage?: ConstraintMessage
+    unavailableMessage?: ConstraintMessage
+    dependencies?: (context: InternalValidationContext<Value, Parent>) => any[],
+    revalidate?: (context: InternalValidationContext<Value, Parent>, previous: any[], current: any[], status: ValidationStatus | undefined) => boolean
+}
+
+/**
+ * Interface for a test constraint, which can be sync, async, or both.
+ * @template Value - The type of the value being validated.
+ * @template Parent - The type of the parent object.
+ * @property test - The test constraint function or async constraint.
+ * @category Shared Constraints
+ */
+export interface TestConstraint<Value, Parent = unknown> {
+    test?: TestConstraintFunction<Value, Parent> | AsyncTestConstraint<Value, Parent> | readonly [TestConstraintFunction<Value, Parent>, AsyncTestConstraint<Value, Parent>]
+}
+
+const defaultGetDependencies = (_context: InternalValidationContext<unknown>) => []
+const defaultShouldRevalidate = (_context: InternalValidationContext<unknown>, previous: any[], current: any[], status: ValidationStatus | undefined) =>
+    status?.level !== "unavailable" && current.some((v, i) => v !== previous[i])
+
+/**
+ * Validates a test constraint for a value, handling sync and async cases.
+ * @template Value - The type of the value being validated.
+ * @template Parent - The type of the parent object.
+ * @param context - The validation context.
+ * @param testConstraint - The test constraint to validate.
+ * @returns True if the constraint passes, false otherwise.
+ * @ignore
+ */
+export function validateTestConstraint<Value, Parent>(
+    context: InternalValidationContext<Value, Parent>,
+    testConstraint: TestConstraint<Value, Parent>
+) {
+    if (context.groups == null)
+        return testConstraint.test == null || _validateTestConstraint(context, testConstraint)
+
+    const groups = Array.isArray(context.groups) ? context.groups : [context.groups]
+    for (const group of groups) {
+        const test = (group == null ? testConstraint.test : (testConstraint as any).groups?.[group]?.test)
+        if (test != null && !_validateTestConstraint(context, { test }))
+            return false
+    }
+    return true
+}
+
+/**
+ * Internal helper to validate a test constraint (sync and async).
+ * @ignore
+ */
+function _validateTestConstraint<Value, Parent>(
+    context: InternalValidationContext<Value, Parent>,
+    testConstraint: TestConstraint<Value, Parent>
+) {
+    const test = testConstraint.test!
+
+    const syncTest = (isFunction(test) ? test : Array.isArray(test) ? test[0] : undefined) as TestConstraintFunction<Value, Parent> | undefined
+    if (syncTest != null && !_validateTestConstraintFunction(context as InternalValidationContext<NonNullable<Value>, Parent>, syncTest))
+        return false
+
+    const asyncTest = (isObject(test) ? test : Array.isArray(test) ? test[1] : undefined) as AsyncTestConstraint<Value, Parent> | undefined
+    return asyncTest == null || _validateAsyncTestConstraint(context as InternalValidationContext<NonNullable<Value>, Parent>, asyncTest)
+}
+
+/**
+ * Internal helper to validate a synchronous test constraint function.
+ * @ignore
+ */
+function _validateTestConstraintFunction<Value, Parent>(
+    context: InternalValidationContext<NonNullable<Value>, Parent>,
+    test: TestConstraintFunction<Value, Parent>
+) {
+    let constraint: any = undefined
+    let message: any = undefined
+    let level: Level | undefined = undefined
+
+    constraint = test(context)
+
+    if (Array.isArray(constraint)) {
+        const [maybeConstraint, maybeMessage, maybeLevel] = constraint
+        constraint = maybeConstraint
+        message = maybeMessage
+        level = maybeLevel ?? undefined
+    }
+
+    if (constraint == null || constraint === true)
+        return true
+    return context.setStatus("test", false, typeof constraint === "string" ? constraint : message, level ?? "error") == null
+}
+
+/**
+ * Internal helper to validate an asynchronous test constraint.
+ * @ignore
+ */
+function _validateAsyncTestConstraint<Value, Parent>(
+    context: InternalValidationContext<NonNullable<Value>, Parent>,
+    test: AsyncTestConstraint<Value, Parent>
+) {
+    if (context.settings?.skipAsync)
+        return true
+
+    const getDependencies = test.dependencies ?? defaultGetDependencies
+    const dependencies = [context.value].concat(getDependencies(context))
+
+    const path = joinPath(context.path)
+    let asyncStatus = context.yop.asyncStatuses.get(path)
+    if (asyncStatus != null) {
+        const previousDependencies = asyncStatus.dependencies
+        asyncStatus.dependencies = dependencies
+        const shouldRevalidate = test.revalidate ?? defaultShouldRevalidate
+        if (!shouldRevalidate(context, previousDependencies, dependencies, asyncStatus.status)) {
+            if (asyncStatus.status != null) {
+                context.statuses.set(path, asyncStatus.status)
+                return false
+            }
+            return true
+        }
+    }
+
+    asyncStatus = { dependencies }
+    
+    const promise = test.promise(context)
+        .then(message => {
+            if (message == null || message === true)
+                asyncStatus.status = undefined
+            else if (message === false)
+                asyncStatus.status = context.createStatus("test", false)
+            else if (!Array.isArray(message))
+                asyncStatus.status = context.createStatus("test", false, message as ConstraintMessage)
+            else {
+                const [maybeMessage, maybeLevel] = message as readonly [ConstraintMessage, Level]
+                asyncStatus.status = context.createStatus("test", false, maybeMessage, maybeLevel ?? "error")
+            }
+            return asyncStatus.status
+        })
+        .catch(error => {
+            asyncStatus.status = context.createStatus("test", false, error != null ? String(error) : test.unavailableMessage, "unavailable")
+            return Promise.resolve(asyncStatus.status)
+        })
+
+    asyncStatus.status = context.setStatus("test", promise, test.pendingMessage, "pending")
+    context.yop.asyncStatuses.set(path, asyncStatus)
+    return false
+}

package/src/yop/decorators/array.ts

@@ -0,0 +1,157 @@
+import { CommonConstraints, InternalCommonConstraints, validateTypeConstraint } from "../constraints/CommonConstraints"
+import { MinMaxConstraints, validateMinMaxConstraints } from "../constraints/MinMaxConstraints"
+import { TestConstraint, validateTestConstraint } from "../constraints/TestConstraint"
+import { fieldValidationDecorator, getValidationDecoratorKind, Groups, InternalClassConstraints } from "../Metadata"
+import { defineLazyProperty } from "../ObjectsUtil"
+import { ArrayElementType, Constructor, isNumber } from "../TypesUtil"
+import { InternalValidationContext } from "../ValidationContext"
+import { validationSymbol, Yop } from "../Yop"
+import { id } from "./id"
+import { string } from "./string"
+import { number } from "./number"
+
+/**
+ * Type for an array value, which can be an array, null, or undefined.
+ * @ignore
+ */
+export type ArrayValue = any[] | null | undefined
+
+/**
+ * Interface for array field constraints, combining common, min/max, test, and element type constraints.
+ * @template Value - The type of the array value.
+ * @template Parent - The type of the parent object.
+ * @see {@link id}
+ * @see {@link CommonConstraints}
+ * @see {@link MinMaxConstraints}
+ * @see {@link TestConstraint}
+ * @category Property Decorators
+ */
+export interface ArrayConstraints<Value extends ArrayValue, Parent> extends
+    CommonConstraints<Value, Parent>,
+    MinMaxConstraints<Value, number, Parent>,
+    TestConstraint<Value, Parent> {
+    /**
+     * A class constructor, a function returning a constructor, a validation decorator, or a class id (see {@link id}) to
+     * validate each array element against.
+     * @see {@link array}
+     */
+    of: (
+        Constructor<ArrayElementType<Value>> |
+        (() => Constructor<ArrayElementType<Value>>) |
+        ((_: any, context: ClassFieldDecoratorContext<Value, ArrayElementType<Value>>) => void) |
+        string
+    )
+}
+
+/**
+ * Traverses an array field to retrieve element constraints and value at a given index or property.
+ * @template Value - The type of the array value.
+ * @template Parent - The type of the parent object.
+ * @param context - The validation context for the array.
+ * @param constraints - The array constraints.
+ * @param propertyOrIndex - The property name or array index to traverse.
+ * @param traverseNullish - If true, traverses only if value is not nullish; otherwise, returns undefined for nullish values.
+ * @returns A tuple of the element constraints (if any) and the value at the given index/property.
+ * @ignore
+ */
+function traverseArray<Value extends ArrayValue, Parent>(
+    context: InternalValidationContext<Value, Parent>,
+    constraints: ArrayConstraints<Value, Parent>,
+    propertyOrIndex: string | number,
+    traverseNullish?: boolean
+): readonly [InternalCommonConstraints | undefined, any] {
+    if (traverseNullish ? context.value != null && (!Array.isArray(context.value) || typeof propertyOrIndex !== "number") : context.value == null)
+        return [undefined, undefined]
+    const of = constraints.of as any
+    const elementConstraints = of?.[Symbol.metadata]?.[validationSymbol]
+    return [elementConstraints, context.value?.[propertyOrIndex as number]]
+}
+
+/**
+ * Validates an array field against its constraints, including type, min/max length, and element validation.
+ * @template Value - The type of the array value.
+ * @template Parent - The type of the parent object.
+ * @param context - The validation context for the array.
+ * @param constraints - The array constraints to validate.
+ * @returns True if all constraints pass, false otherwise.
+ * @ignore
+ */
+function validateArray<Value extends ArrayValue, Parent>(context: InternalValidationContext<Value, Parent>, constraints: ArrayConstraints<Value, Parent>) {
+    if (!validateTypeConstraint(context, Array.isArray, "array") ||
+        !validateMinMaxConstraints(context, constraints, isNumber, (value, min) => value.length >= min, (value, max) => value.length <= max) ||
+        constraints.of == null)
+        return false
+
+    let valid = true
+    
+    const elementConstraints = (constraints.of as any)[Symbol.metadata]?.[validationSymbol] as InternalCommonConstraints | undefined
+    if (elementConstraints != null) {
+        for (const [index, element] of context.value!.entries()) {
+            const elementContext = context.createChildContext({
+                kind: elementConstraints.kind,
+                value: element,
+                key: index,
+            })
+            valid = elementConstraints.validate(elementContext, elementConstraints) && valid
+        }    
+    }
+    
+    return valid && validateTestConstraint(context, constraints)
+}
+
+/**
+ * Constant representing the kind of array validation decorator.
+ * @ignore
+ */
+export const arrayKind = "array"
+
+/**
+ * Decorator for validating a field value as an array of a specified element type. The `of` property can be set to a custom
+ * class constructor, or a validation decorator such as {@link string}, {@link number}, etc. Using a validation decorator allows
+ * applying constraints to each array element.
+ * 
+ * Example usage:
+ * ```tsx
+ * class Person {
+ * 
+ *     // the array itself must not be null, but its elements may be null
+ *     ＠array({ of: Dog, required: true })
+ *     dogs: Dog[] | null = null
+ * 
+ *     // the array must not be null, and all its elements must also be non-null
+ *     ＠array({ of: instance({ of: Cat, required: true }), required: true })
+ *     cats: Cat[] | null = null
+ * 
+ *     // a non-empty array of strings with at least 5 characters each
+ *     ＠array({ of: string({ required: true, min: 5 }), required: true, min: 1 })
+ *     names: string[] | null = null
+ * }
+ * const form = useForm(Person, ...)
+ * 
+ * // the array decorator can also be used as a function to allow standalone validation:
+ * Yop.validate([], array({ of: Dog, min: 1 })) // error: "At least 1 element"
+ * ```
+ * 
+ * @template Value - The type of the array value.
+ * @template Parent - The type of the parent object.
+ * @param constraints - The array constraints to apply.
+ * @param groups - Optional validation groups.
+ * @returns A field decorator function with validation.
+ * @category Property Decorators
+ */
+export function array<Value extends ArrayValue, Parent>(constraints?: ArrayConstraints<Value, Parent>, groups?: Groups<ArrayConstraints<Value, Parent>>) {
+    if (getValidationDecoratorKind(constraints?.of) != null) {
+        const of = constraints!.of as ((_: any, context: Partial<ClassFieldDecoratorContext<Value, ArrayElementType<Value>>>) => void)
+        defineLazyProperty(constraints, "of", (_this) => {
+            const metadata = { [validationSymbol]: {} as InternalClassConstraints }
+            of(null, { metadata, name: "of" })
+            return { [Symbol.metadata]: { [validationSymbol]: metadata[validationSymbol]!.fields!.of }}
+        })
+    }
+    else if (typeof constraints?.of === "string" || (typeof constraints?.of === "function" && constraints.of.prototype == null)) {
+        const of = constraints!.of
+        defineLazyProperty(constraints, "of", (_this) => Yop.resolveClass(of))
+    }
+    return fieldValidationDecorator(arrayKind, constraints ?? ({} as ArrayConstraints<Value, Parent>), groups, validateArray, isNumber, traverseArray)
+}
+

package/src/yop/decorators/boolean.ts

@@ -0,0 +1,69 @@
+import { CommonConstraints, validateTypeConstraint } from "../constraints/CommonConstraints"
+import { OneOfConstraint, validateOneOfConstraint } from "../constraints/OneOfConstraint"
+import { TestConstraint, validateTestConstraint } from "../constraints/TestConstraint"
+import { isBoolean, isBooleanArray } from "../TypesUtil"
+import { InternalValidationContext } from "../ValidationContext"
+import { fieldValidationDecorator, Groups } from "../Metadata"
+
+/**
+ * Type for a boolean value, which can be true, false, null, or undefined.
+ * @ignore
+ */
+export type BooleanValue = boolean | null | undefined
+
+/**
+ * Interface for boolean field constraints, combining common, oneOf, and test constraints.
+ * @template Value - The type of the boolean value.
+ * @template Parent - The type of the parent object.
+ * @see {@link CommonConstraints}
+ * @see {@link OneOfConstraint}
+ * @see {@link TestConstraint}
+ * @category Property Decorators
+ */
+export interface BooleanConstraints<Value extends BooleanValue, Parent> extends
+    CommonConstraints<Value, Parent>,
+    OneOfConstraint<Value, Parent>,
+    TestConstraint<Value, Parent> {
+}
+
+/**
+ * Validates a boolean field against its constraints.
+ * @template Value - The type of the boolean value.
+ * @template Parent - The type of the parent object.
+ * @param context - The validation context.
+ * @param constraints - The boolean constraints to validate.
+ * @returns True if all constraints pass, false otherwise.
+ * @ignore
+ */
+function validateBoolean<Value extends BooleanValue, Parent>(context: InternalValidationContext<Value, Parent>, constraints: BooleanConstraints<Value, Parent>) {
+    return (
+        validateTypeConstraint(context, isBoolean, "boolean") &&
+        validateOneOfConstraint(context, constraints, isBooleanArray) &&
+        validateTestConstraint(context, constraints)
+    )
+}
+
+/**
+ * Decorator for applying validation rules to a boolean field.
+ * 
+ * Example usage:
+ * ```tsx
+ * class Person {
+ *     ＠boolean({ required: true, oneOf: [[true], "Must be an adult"] })
+ *     adult: boolean | null = null
+ * }
+ * const form = useForm(Person, ...)
+ * 
+ * // the boolean decorator can also be used as a function to allow standalone validation:
+ * Yop.validate(false, boolean({ oneOf: [true] })) // error: "Must be one of: true"
+ * ```
+ * @template Value - The type of the boolean value.
+ * @template Parent - The type of the parent object.
+ * @param constraints - The boolean constraints to apply.
+ * @param groups - Optional validation groups.
+ * @returns A field decorator function with validation.
+ * @category Property Decorators
+ */
+export function boolean<Value extends BooleanValue, Parent>(constraints?: BooleanConstraints<Value, Parent>, groups?: Groups<BooleanConstraints<Value, Parent>>) {
+    return fieldValidationDecorator("boolean", constraints ?? {}, groups, validateBoolean)
+}

package/src/yop/decorators/date.ts

@@ -0,0 +1,73 @@
+import { CommonConstraints, validateTypeConstraint } from "../constraints/CommonConstraints"
+import { MinMaxConstraints, validateMinMaxConstraints } from "../constraints/MinMaxConstraints"
+import { OneOfConstraint, validateOneOfConstraint } from "../constraints/OneOfConstraint"
+import { TestConstraint, validateTestConstraint } from "../constraints/TestConstraint"
+import { isDate, isDateArray } from "../TypesUtil"
+import { InternalValidationContext } from "../ValidationContext"
+import { fieldValidationDecorator, Groups } from "../Metadata"
+
+/**
+ * Type for a date value, which can be a Date object, null, or undefined.
+ * @ignore
+ */
+export type DateValue = Date | null | undefined
+
+/**
+ * Interface for date field constraints, combining common, min/max, oneOf, and test constraints.
+ * @template Value - The type of the date value.
+ * @template Parent - The type of the parent object.
+ * @see {@link CommonConstraints}
+ * @see {@link MinMaxConstraints}
+ * @see {@link OneOfConstraint}
+ * @see {@link TestConstraint}
+ * @category Property Decorators
+ */
+export interface DateConstraints<Value extends DateValue, Parent> extends
+    CommonConstraints<Value, Parent>,
+    MinMaxConstraints<Value, Date, Parent>,
+    OneOfConstraint<Value, Parent>,
+    TestConstraint<Value, Parent> {
+}
+
+/**
+ * Validates a date field against its constraints.
+ * @template Value - The type of the date value.
+ * @template Parent - The type of the parent object.
+ * @param context - The validation context.
+ * @param constraints - The date constraints to validate.
+ * @returns True if all constraints pass, false otherwise.
+ * @ignore
+ */
+function validateDate<Value extends DateValue, Parent>(context: InternalValidationContext<Value, Parent>, constraints: DateConstraints<Value, Parent>) {
+    return (
+        validateTypeConstraint(context, isDate, "date") &&
+        validateMinMaxConstraints(context, constraints, isDate, (value, min) => value >= min, (value, max) => value <= max) &&
+        validateOneOfConstraint(context, constraints, isDateArray, (date1, date2) => date1.getTime() === date2.getTime()) &&
+        validateTestConstraint(context, constraints)
+    )
+}
+
+/**
+ * Decorator for applying validation rules to a Date field.
+ * 
+ * Example usage:
+ * ```tsx
+ * class Person {
+ *     ＠date({ required: true, min: new Date("1900-01-01") })
+ *     dateOfBirth: Date | null = null
+ * }
+ * const form = useForm(Person, ...)
+ * 
+ * // the date decorator can also be used as a function to allow standalone validation:
+ * Yop.validate(null, date({ required: true })) // error: "Required field"
+ * ```
+ * @template Value - The type of the date value.
+ * @template Parent - The type of the parent object.
+ * @param constraints - The date constraints to apply.
+ * @param groups - Optional validation groups.
+ * @returns A field decorator function with validation.
+ * @category Property Decorators
+ */
+export function date<Value extends DateValue, Parent>(constraints?: DateConstraints<Value, Parent>, groups?: Groups<DateConstraints<Value, Parent>>) {
+    return fieldValidationDecorator("date", constraints ?? {}, groups, validateDate, isDate)
+}

package/src/yop/decorators/email.ts

@@ -0,0 +1,66 @@
+import { Message } from "../constraints/Constraint"
+import { InternalValidationContext } from "../ValidationContext"
+import { fieldValidationDecorator, Groups } from "../Metadata"
+import { StringConstraints, StringValue, validateString } from "./string"
+import { isNumber } from "../TypesUtil"
+
+/**
+ * Interface for email field constraints, extending string constraints but omitting 'match'.
+ * @template Value - The type of the string value.
+ * @template Parent - The type of the parent object.
+ * @property formatError - Custom error message for invalid email format.
+ * @see {@link StringConstraints}
+ * @category Property Decorators
+ */
+export interface EmailConstraints<Value extends StringValue, Parent> extends
+    Omit<StringConstraints<Value, Parent>, "match"> {
+    /**
+     * Custom error message for invalid email format. `formatError` can be a {@link Message} or a function that returns a {@link Message}.
+     * @see {@link emailRegex}
+     */
+    formatError?: Message<Value, Parent>
+}
+
+/**
+ * Regular expression for validating email addresses (RFC 5322 compliant).
+ * @ignore
+ */
+export const emailRegex = /^((([a-z]|\d|[!#\$%&'\*\+\-\/=\?\^_`{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+(\.([a-z]|\d|[!#\$%&'\*\+\-\/=\?\^_`{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+)*)|((\x22)((((\x20|\x09)*(\x0d\x0a))?(\x20|\x09)+)?(([\x01-\x08\x0b\x0c\x0e-\x1f\x7f]|\x21|[\x23-\x5b]|[\x5d-\x7e]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(\\([\x01-\x09\x0b\x0c\x0d-\x7f]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF]))))*(((\x20|\x09)*(\x0d\x0a))?(\x20|\x09)+)?(\x22)))@((([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.)+(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([a-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([a-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))$/i
+
+/**
+ * Validates an email field against its constraints and the email regex.
+ * @template Value - The type of the string value.
+ * @template Parent - The type of the parent object.
+ * @param context - The validation context.
+ * @param constraints - The email constraints to validate.
+ * @returns True if the value is a valid email, false otherwise.
+ * @ignore
+ */
+export function validateEmail<Value extends StringValue, Parent>(context: InternalValidationContext<Value, Parent>, constraints: EmailConstraints<Value, Parent>) {
+    return validateString(context, constraints, emailRegex, constraints.formatError, "email")
+}
+
+/**
+ * Decorator for applying validation rules to an email field. Emails are validated against a standard email regex pattern (RFC 5322 compliant).
+ * 
+ * Example usage:
+ * ```tsx
+ * class Person {
+ *     ＠email({ required: true, formatError: "Invalid email address" })
+ *     email: string | null = null
+ * }
+ * const form = useForm(Person, ...)
+ * 
+ * // the email decorator can also be used as a function to allow standalone validation:
+ * Yop.validate(null, email({ required: true })) // error: "Required field"
+ * ```
+ * @template Value - The type of the string value.
+ * @template Parent - The type of the parent object.
+ * @param constraints - The email constraints to apply.
+ * @param groups - Optional validation groups.
+ * @returns A field decorator function with validation.
+ * @category Property Decorators
+ */
+export function email<Value extends StringValue, Parent>(constraints?: EmailConstraints<Value, Parent>, groups?: Groups<EmailConstraints<Value, Parent>>) {
+    return fieldValidationDecorator("email", constraints ?? {}, groups, validateEmail, isNumber)
+}