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

simple decorator based validation engine

import { ModelErrorDefinition } from "./ModelErrorDefinition";
import type { Model } from "./Model";
import { ConditionalAsync } from "../types";
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>;
/**
 * @description Retrieves nested properties to ignore for child validation
 * @param parentProp - The property of the parent model
 * @param propsToIgnore - Properties to ignore from the parent model
 * @returns An array of properties to ignore for the child model
 */
export declare function getChildNestedPropsToIgnore(parentProp: string, ...propsToIgnore: string[]): string[];
export declare function validateDecorator<M extends Model, Async extends boolean = false>(model: M, value: any, decorator: any, 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 object of metadata 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: any, 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>;