@decaf-ts/decorator-validation/lib/esm/model/validation.d.ts

simple decorator based validation engine

import { ModelErrorDefinition } from "./ModelErrorDefinition";
import { Model } from "./Model";
import { ValidationPropertyDecoratorDefinition } from "../validation";
import { ConditionalAsync, DecoratorMetadataAsync } from "../types";
/**
 * Retrieves the validation metadata decorators associated with a specific property of a model,
 * using the reflective metadata key.
 *
 * @param model - The model instance or class containing the decorated property.
 * @param {string} prop - The name of the property whose decorators should be retrieved.
 * @param {string} reflectKey - The metadata key used to retrieve the decorators.
 *                     Defaults to `ValidationKeys.REFLECT`.
 *
 * @returns The validation decorators applied to the property
 */
export declare function getValidationDecorators(model: Record<string, any>, prop: string, reflectKey?: string): ValidationPropertyDecoratorDefinition;
/**
 * @description
 * Retrieves all validatable property decorators from a given model, excluding specified properties.
 *
 * @summary
 * Iterates through the own enumerable properties of a model instance, filtering out any properties
 * listed in the `propsToIgnore` array. For each remaining property, it checks whether validation
 * decorators are present using `getValidationDecorators`, and if so, collects them in the result array.
 *
 * @template M - A generic parameter extending the `Model` class, representing the model type being inspected.
 *
 * @param {M} model - An instance of a class extending `Model` from which validatable properties will be extracted.
 * @param {string[]} propsToIgnore - An array of property names that should be excluded from validation inspection.
 *
 * @return {ValidationPropertyDecoratorDefinition[]} An array of validation decorator definitions
 * associated with the model's properties, excluding those listed in `propsToIgnore`.
 *
 * @function getValidatableProperties
 */
export declare function getValidatableProperties<M extends Model>(model: M, propsToIgnore: string[]): ValidationPropertyDecoratorDefinition[];
export declare function validateChildValue<M extends Model>(prop: string, childValue: any, parentModel: M, allowedTypes: string[], async: boolean, ...propsToIgnore: string[]): string | undefined | ModelErrorDefinition | Promise<string | undefined | ModelErrorDefinition>;
export declare function validateDecorator<M extends Model, Async extends boolean = false>(model: M, value: any, decorator: DecoratorMetadataAsync, async?: Async): ConditionalAsync<Async, string | undefined>;
/**
 * @description
 * Executes validation logic for a set of decorators applied to a model's property, handling both
 * synchronous and asynchronous validations, including support for nested validations and lists.
 *
 * @summary
 * Iterates over an array of decorator metadata objects and applies each validation rule to the
 * provided value. For list decorators (`ValidationKeys.LIST`), it performs element-wise validation,
 * supporting nested model validation and type checks. If the `async` flag is set, asynchronous
 * validation is supported using `Promise.all`. The result is a record mapping validation keys to
 * error messages, or `undefined` if no errors are found.
 *
 * @template M - A type parameter extending `Model`, representing the model type being validated.
 * @template Async - A boolean indicating whether validation should be performed asynchronously.
 *
 * @param {M} model - The model instance that the validation is associated with.
 * @param {string} prop - The model field name
 * @param {any} value - The value to be validated against the provided decorators.
 * @param {DecoratorMetadataAsync[]} decorators - An array of metadata objects representing validation decorators.
 * @param {Async} [async] - Optional flag indicating whether validation should be performed asynchronously.
 *
 * @return {ConditionalAsync<Async, Record<string, string>> | undefined}
 * Returns either a record of validation errors (keyed by the decorator key) or `undefined` if no errors are found.
 * If `async` is true, the return value is a Promise resolving to the same structure.
 *
 * @function validateDecorators
 */
export declare function validateDecorators<M extends Model, Async extends boolean = false>(model: M, prop: string, value: any, decorators: DecoratorMetadataAsync[], async?: Async, ...propsToIgnore: string[]): ConditionalAsync<Async, Record<string, string> | undefined>;
/**
 * @function validate
 * @template M
 * @template Async
 * @memberOf module:decorator-validation
 * @category Model
 *
 * @description
 * Validates the properties of a {@link Model} instance using registered decorators.
 * Supports both synchronous and asynchronous validation flows, depending on the `async` flag.
 *
 * @summary
 * This function inspects a given model object, identifies decorated properties that require validation,
 * and applies the corresponding validation rules. It also supports nested model validation and gracefully
 * merges any validation errors. For collections (Array/Set), it enforces the presence of the `@list` decorator
 * and checks the type of elements. If a property is a nested model, it will call `hasErrors` on it and flatten
 * the nested error keys using dot notation.
 *
 * @param {M} model - The model instance to be validated. Must extend from {@link Model}.
 * @param {Async} [async] - A flag indicating whether validation should be asynchronous.
 * @param {...string} propsToIgnore - A variadic list of property names that should be skipped during validation.
 *
 * @returns {ConditionalAsync<Async, ModelErrorDefinition | undefined>}
 * Returns either a {@link ModelErrorDefinition} containing validation errors,
 * or `undefined` if no errors are found. When `async` is `true`, returns a Promise.
 *
 * @see {@link Model}
 * @see {@link ModelErrorDefinition}
 * @see {@link validateDecorators}
 * @see {@link getValidatableProperties}
 *
 * @mermaid
 * sequenceDiagram
 *     participant Caller
 *     participant validate
 *     participant getValidatableProperties
 *     participant validateDecorators
 *     participant ModelInstance
 *     Caller->>validate: call with obj, async, propsToIgnore
 *     validate->>getValidatableProperties: retrieve decorated props
 *     loop for each property
 *         validate->>validateDecorators: validate using decorators
 *         alt is nested model
 *             validate->>ModelInstance: call hasErrors()
 *         end
 *     end
 *     alt async
 *         validate->>validate: Promise.allSettled for errors
 *     end
 *     validate-->>Caller: return ModelErrorDefinition | undefined
 */
export declare function validate<M extends Model<boolean>, Async extends boolean = false>(model: M, async: Async, ...propsToIgnore: string[]): ConditionalAsync<Async, ModelErrorDefinition | undefined>;