@4riders/reform 3.0.24

package/src/yop/TypesUtil.ts

@@ -0,0 +1,148 @@
+
+/**
+ * Type for a class constructor of a given type.
+ * @template Type - The type of the class instance.
+ * @ignore
+ */
+export type ClassConstructor<Type> = new (...args: any) => NonNullable<Type>
+
+/**
+ * Checks if a class constructor is a subclass of another.
+ * @template T - The parent class type.
+ * @param value - The class constructor to check.
+ * @param parent - The parent class constructor.
+ * @returns True if value is a subclass of parent.
+ * @ignore
+ */
+export const isSubclassOf = <T>(value: ClassConstructor<any>, parent: ClassConstructor<T>): value is ClassConstructor<T> =>
+    value.prototype instanceof parent
+
+/**
+ * Type for a constructor of a given type, including primitive constructors.
+ * @template Type - The type to construct.
+ * @ignore
+ */
+export type Constructor<Type = unknown> =
+    Type extends unknown ? ClassConstructor<Type> | StringConstructor | BooleanConstructor | NumberConstructor :
+    [Type] extends [string | null | undefined] ? StringConstructor :
+    [Type] extends [boolean | null | undefined] ? BooleanConstructor :
+    [Type] extends [number | null | undefined] ? NumberConstructor :
+    ClassConstructor<Type>
+
+/**
+ * Type for extracting the element type from an array type.
+ * @template ArrayType - The array type.
+ * @ignore
+ */
+export type ArrayElementType<ArrayType> = ArrayType extends Array<infer ElementType> ? ElementType : never
+
+/**
+ * Checks if a value is a boolean.
+ * @template T - The boolean type.
+ * @param value - The value to check.
+ * @returns True if value is boolean.
+ * @ignore
+ */
+export const isBoolean = <T extends boolean>(value: any): value is T => typeof value === "boolean"
+/**
+ * Checks if a value is a valid number (not NaN).
+ * @template T - The number type.
+ * @param value - The value to check.
+ * @returns True if value is a valid number.
+ * @ignore
+ */
+export const isNumber = <T extends number>(value: any): value is T => typeof value === "number" && !isNaN(value)
+/**
+ * Checks if a value is a string.
+ * @template T - The string type.
+ * @param value - The value to check.
+ * @returns True if value is a string.
+ * @ignore
+ */
+export const isString = <T extends string>(value: any): value is T => typeof value === "string"
+/**
+ * Checks if a value is a non-null object (not an array).
+ * @template T - The object type.
+ * @param value - The value to check.
+ * @returns True if value is an object.
+ * @ignore
+ */
+export const isObject = <T extends object>(value: any): value is T => value != null && !Array.isArray(value) && typeof value === "object"
+/**
+ * Checks if a value is a function.
+ * @template T - The function type.
+ * @param value - The value to check.
+ * @returns True if value is a function.
+ * @ignore
+ */
+export const isFunction = <T extends Function>(value: any): value is T => typeof value === "function"
+/**
+ * Checks if a value is a valid Date object.
+ * @template T - The Date type.
+ * @param value - The value to check.
+ * @returns True if value is a valid Date.
+ * @ignore
+ */
+export const isDate = <T extends Date>(value: any): value is T => value instanceof Date && !isNaN(value.getTime())
+/**
+ * Checks if a value is a File object.
+ * @template T - The File type.
+ * @param value - The value to check.
+ * @returns True if value is a File.
+ * @ignore
+ */
+export const isFile = <T extends File>(value: any): value is T => value instanceof File
+/**
+ * Checks if a value is a RegExp object.
+ * @param value - The value to check.
+ * @returns True if value is a RegExp.
+ * @ignore
+ */
+export const isRegExp = (value: any): value is RegExp => value instanceof RegExp
+
+/**
+ * Checks if a value is an array of strings.
+ * @template T - The string type.
+ * @param value - The value to check.
+ * @returns True if value is an array of strings.
+ * @ignore
+ */
+export const isStringArray = <T extends string>(value: any): value is Array<T> => Array.isArray(value) && value.every(isString)
+/**
+ * Checks if a value is an array of booleans.
+ * @template T - The boolean type.
+ * @param value - The value to check.
+ * @returns True if value is an array of booleans.
+ * @ignore
+ */
+export const isBooleanArray = <T extends boolean>(value: any): value is Array<T> => Array.isArray(value) && value.every(isBoolean)
+/**
+ * Checks if a value is an array of numbers.
+ * @template T - The number type.
+ * @param value - The value to check.
+ * @returns True if value is an array of numbers.
+ * @ignore
+ */
+export const isNumberArray = <T extends number>(value: any): value is Array<T> => Array.isArray(value) && value.every(isNumber)
+/**
+ * Checks if a value is an array of Date objects.
+ * @template T - The Date type.
+ * @param value - The value to check.
+ * @returns True if value is an array of Dates.
+ * @ignore
+ */
+export const isDateArray = <T extends Date>(value: any): value is Array<T> => Array.isArray(value) && value.every(isDate)
+
+/**
+ * Checks if a value is a Promise.
+ * @template T - The Promise type.
+ * @param value - The value to check.
+ * @returns True if value is a Promise.
+ * @ignore
+ */
+export const isPromise = <T>(value: any): value is Promise<T> => (
+    value != null &&
+    typeof value === "object" &&
+    "then" in value && typeof value["then"] === "function" &&
+    "catch" in value && typeof value["catch"] === "function"
+)

package/src/yop/ValidationContext.ts

@@ -0,0 +1,207 @@
+import { ConstraintMessage } from "./constraints/Constraint"
+import { joinPath, Path } from "./ObjectsUtil"
+import { ValidationForm, ValidationSettings, Yop } from "./Yop"
+
+/**
+ * Type representing the validation group or groups being currently validated. `undefined` means the default group.
+ * @category Validation Management
+ */
+export type Group = string | ((string | undefined)[])
+
+/**
+ * The types of validation status levels. "pending" and "unavailable" are only used for asynchronous validations.
+ * "pending" indicates that the asynchronous validation is in progress, while "unavailable" indicates that the validation
+ * couldn't be performed (e.g., due to an unreachable server).
+ * @see {@link ValidationStatus}
+ * @category Validation Management
+ */
+export type Level = "info" | "warning" | "error" | "pending" | "unavailable"
+
+/**
+ * Interface representing the status of a validation, including its level, path, value, kind, code, constraint, and message.
+ * This is used to track the results of validation operations and provide feedback to the user.
+ * @category Validation Management
+ */
+export type ValidationStatus = {
+
+    /**
+     * The severity level of the validation status, or the status of asynchronous validation.
+     * @see {@link Level}
+     */
+    level: Level
+
+    /**
+     * The path to the validated value, represented as a string (e.g., "users[0].address.street").
+     */
+    path: string
+
+    /**
+     * The value that was validated.
+     */
+    value: any
+
+    /**
+     * The kind of validation (e.g., "string", "number", "array"), used for message resolution.
+     */
+    kind: string
+
+    /**
+     * A code representing the specific validation type (e.g., "required", "min"), used for message resolution.
+     */
+    code: string
+
+    /**
+     * The constraint value that caused the validation error (e.g., `true` for a "required" constraint, `1` for a "min" constraint).
+     */
+    constraint: any
+
+    /**
+     * The resolved message for this validation status, which can be displayed to the user.
+     */
+    message: ConstraintMessage
+}
+
+/**
+ * Interface representing the context of a validation operation, providing access to the value being validated, its path,
+ * parent context, root context, settings, form, and a store for sharing data across validations.
+ * 
+ * @template Value - The type of the value being validated.
+ * @template Parent - The type of the parent object containing the value.
+ * @category Validation Management
+ */
+export interface ValidationContext<Value, Parent = unknown> {
+    
+    readonly kind: string
+
+    readonly value: Value
+    readonly path: Path
+
+    readonly parent: Parent
+    readonly parentContext: ValidationContext<Parent> | undefined
+
+    getRoot<T>(): T | undefined
+    readonly rootContext: ValidationContext<unknown> | undefined
+
+    readonly settings: ValidationSettings | undefined
+
+    readonly form: ValidationForm | undefined
+
+    readonly store: Map<string, any>
+}
+
+/**
+ * @ignore
+ */
+export const UndefinedParent = Object.freeze(Object.create(null))
+
+/**
+ * Internal implementation of the ValidationContext interface, used for managing validation state and providing utility methods
+ * for creating child contexts and statuses.
+ * @ignore
+ */
+export class InternalValidationContext<Value, Parent = unknown> implements ValidationContext<Value, Parent> {
+
+    readonly yop: Yop
+
+    readonly kind: string
+
+    readonly value: Value
+    readonly path: Path
+
+    readonly parentContext: InternalValidationContext<Parent> | undefined
+    readonly rootContext: InternalValidationContext<unknown> | undefined
+
+    readonly settings: ValidationSettings | undefined
+
+    readonly store: Map<string, any>
+
+    readonly statuses: Map<string, ValidationStatus>
+
+    constructor(props: {
+        yop: Yop
+        kind: string
+        value: Value
+        key?: string | number | undefined
+        parentContext?: InternalValidationContext<Parent> | undefined
+        rootContext?: InternalValidationContext<unknown> | undefined
+        userContext?: unknown | undefined
+        statuses?: Map<string, ValidationStatus>
+        settings?: ValidationSettings
+    }) {
+        if (props.parentContext != null && props.key == null)
+            throw new Error("key must be provided when parentContext is provided")
+
+        this.yop = props.yop
+        this.kind = props.kind
+        this.value = props.value
+        this.parentContext = props.parentContext
+        this.rootContext = props.rootContext
+        this.settings = props.settings
+        this.statuses = props.statuses ?? new Map()
+
+        this.store = props.yop.store
+
+        this.path = props.key == null ? [] : (props.parentContext?.path.concat(props.key) ?? [props.key])
+    }
+
+    ignored() {
+        return this.settings?.ignore?.(this.path) ?? false
+    }
+
+    get parent() {
+        return this.parentContext?.value || UndefinedParent as Parent
+    }
+
+    get groups() {
+        return this.settings?.groups
+    }
+
+    get form() {
+        return this.settings?.form
+    }
+
+    getRoot<T>() {
+        return this.rootContext?.value as T | undefined
+    }
+
+    createChildContext(props: {
+        kind: string
+        value: Value
+        key: string | number
+    }) {
+        return new InternalValidationContext({
+            yop: this.yop,
+            kind: props.kind,
+            value: props.value,
+            key: props.key,
+            parentContext: this,
+            rootContext: this.rootContext ?? this,
+            settings: this.settings,
+            statuses: this.statuses
+        })
+    }
+
+    createStatus(code: string, constraint: any, message?: ConstraintMessage, level: Level = "error"): ValidationStatus {
+        return {
+            level,
+            path: joinPath(this.path),
+            value: this.value,
+            kind: this.kind,
+            code,
+            constraint,
+            message: this.yop.messageProvider.getMessage(this, code, constraint, message, level),
+        }
+    }
+
+    setStatus(code: string, constraint: any, message?: ConstraintMessage, level: Level = "error"): ValidationStatus {
+        const status = this.createStatus(code, constraint, message, level)
+        this.statuses.set(status.path, status)
+        return status
+    }
+}
+
+/**
+ * @ignore
+ */
+export type ValuedContext<Value, Parent> = InternalValidationContext<NonNullable<Value>, Parent>
+