@cowwoc/requirements/node/internal/validator/AbstractValidator.d.mts

A fluent API for enforcing design contracts with automatic message generation.

import { type ValidationFailure, Configuration, type ApplicationScope, type ValidatorComponent, JavascriptValidatorsImpl, type ErrorBuilder, Type, ValidationTarget, IllegalStateError, ValidationFailures, type UnknownValidator, type ClassConstructor, type NonUndefinable } from "../internal.mjs";
/**
 * Validates the state of a value, recording failures without throwing an error.
 *
 * @typeParam T - the type of the value
 */
declare abstract class AbstractValidator<T> implements ValidatorComponent<T> {
    protected static readonly VALUE_IS_UNDEFINED: () => IllegalStateError;
    private static readonly CONTAINS_WHITESPACE;
    /**
     * The application configuration.
     */
    protected readonly scope: ApplicationScope;
    /**
     * The validator configuration.
     */
    protected readonly _configuration: Configuration;
    /**
     * The name of the value.
     */
    protected readonly name: string;
    /**
     * The value being validated.
     */
    readonly value: ValidationTarget<T>;
    /**
     * The contextual information of this validator.
     */
    protected readonly context: Map<string, unknown>;
    /**
     * The list of validation failures.
     */
    protected readonly failures: ValidationFailure[];
    /**
     * @param scope - the application configuration
     * @param configuration - the validator configuration
     * @param name - the name of the value
     * @param value - the value being validated
     * @param context - the contextual information set by a parent validator or the user
     * @param failures - the list of validation failures
     * @throws TypeError if `name` is `undefined` or `null`
     * @throws RangeError if `name` contains whitespace, or is empty
     * @throws AssertionError if `scope`, `configuration`, `value`, `context` or `failures` are null
     */
    protected constructor(scope: ApplicationScope, configuration: Configuration, name: string, value: ValidationTarget<T>, context: Map<string, unknown>, failures: ValidationFailure[]);
    /**
     * @returns the application configuration
     */
    getScope(): ApplicationScope;
    getName(): string;
    validationFailed(): boolean;
    getValue(): T;
    getValueOrDefault(defaultValue: T): T;
    getValueOrDefault(defaultValue: T | null): T | null;
    and(validation: (validator: this) => void): this;
    /**
     * Adds a validation failure and throws an error if the validator is configured to throw an error on
     * failure.
     *
     * @param message - a message that explains what went wrong
     * @param errorBuilder - creates the error associated with this failure
     */
    addFailure(message: string, errorBuilder: ErrorBuilder): void;
    /**
     * Adds a `TypeError` validation failure and throws an error if the validator is
     * configured to throw an error on failure.
     *
     * @param message - a message that explains what went wrong
     */
    addTypeError(message: string): void;
    /**
     * Adds a `RangeError` validation failure and throws an error if the validator is configured
     * to throw an error on failure.
     *
     * @param message - a message that explains what went wrong
     */
    protected addRangeError(message: string): void;
    configuration(): Configuration;
    elseGetFailures(): ValidationFailures;
    elseThrow(): boolean;
    elseGetError(): Error | null;
    getContext(): Map<string, unknown>;
    withContext(value: unknown, name: string): this;
    getContextAsString(): string;
    /**
     * Ensures that a name does not conflict with other variable names already in use by the validator.
     *
     * @param name - the name of the parameter
     * @param checkContext - `false` to allow the name to be used even if it conflicts with an
     * existing name in the validator context
     * @returns the internal validator of the name
     * @throws RangeError if `name` is `undefined` or `null`
     * @throws RangeError if `name`:
     *                    <ul>
     *                      <li>contains whitespace</li>
     *                      <li>is empty</li>
     *                      <li>is already in use by the value being validated or the validator context</li>
     *                    </ul>
     */
    protected requireThatNameIsUnique(name: string, checkContext?: boolean): JavascriptValidatorsImpl;
    isUndefined(): UnknownValidator<undefined>;
    isNotUndefined(): UnknownValidator<NonUndefinable<T>>;
    isNull(): UnknownValidator<null>;
    isNotNull(): UnknownValidator<NonNullable<T>>;
    /**
     * @param otherType - another type
     * @param mustBeEqual  - `true` if the value must match the other type, `false` if it must not match the
     *   other type
     * @throws TypeError if the value does not match the expected type and the validator is configured to throw
     * an error on failure
     * @returns true if the value does not match the expected type
     */
    private validateType;
    isType(expected: Type): this;
    isInstanceOf<U extends object>(expected: ClassConstructor<U>): UnknownValidator<U>;
    isNotInstanceOf<U extends object>(expected: ClassConstructor<U>): this;
    isEqualTo(expected: unknown): this;
    isNotEqualTo(unwanted: unknown): this;
    /**
     * @param name - the name of the value
     * @param namePrefix - the string to prepend to the name if the name is null
     * @param value - a value
     * @param valuePrefix - the string to prepend to the value if the name is null
     * @returns the prefixed name if it is defined; otherwise, the prefixed string representation of the value
     */
    getNameOrValue(namePrefix: string, name: string | null, valuePrefix: string, value: unknown): string;
    /**
     * Fails the validation if the value is `undefined` or `null`.
     */
    protected failOnUndefinedOrNull(): void;
}
export { AbstractValidator };