@cowwoc/requirements/node/internal/util/ValidationTarget.d.mts

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

import { type NonUndefinable } from "../internal.mjs";
/**
 * Represents a value that is being validated.
 *
 * This class is not intended to replace `undefined` or `null` references but to record additional
 * information alongside them.
 *
 * Instead of throwing an error when an `undefined` or `null` value is accessed, the system
 * marks it as invalid and continues to record validation failures.
 *
 * @typeParam T - the type of the value
 */
declare class ValidationTarget<T> {
    private static readonly INVALID;
    private readonly valid;
    private readonly value;
    /**
     * Creates a value that may be invalid.
     *
     * @param valid - `true` if the value is valid, or `false` if invalid
     * @param value - the value
     */
    constructor(valid: boolean, value: T);
    /**
     * Returns an invalid value.
     *
     * @typeParam T - the type of the value
     * @returns an invalid value
     */
    static invalid<T>(): ValidationTarget<T>;
    /**
     * Returns a valid value.
     *
     * @typeParam T - the type of the value
     * @param value - a value
     * @returns a valid value
     */
    static valid<T>(value: T): ValidationTarget<T>;
    /**
     * Returns the valid value, or a default value if invalid. A value of `null` does not hold any
     * special significance. It does not imply that the value is invalid.
     *
     * @param defaultValue - a value
     * @returns the valid value, or `defaultValue` if the value is invalid
     */
    or(defaultValue: T): T;
    or(defaultValue: T | null): T | null;
    /**
     * Returns the valid value, or a default value if invalid. A value of `null` does not hold any
     * special significance. It does not imply that the value is invalid.
     *
     * @param defaultValue - a supplier that returns the default value
     * @returns the valid value, or `defaultValue` if the value is invalid
     */
    orGet(defaultValue: () => T): T;
    /**
     * Consumes the value if it is valid. If the value is invalid, no action is taken.
     *
     * @param consumer - consumes the value if it is valid
     */
    ifValid(consumer: (value: T) => void): void;
    /**
     * Applies a function to the value if it is valid. If the value is invalid, no action is taken.
     *
     * @typeParam U - the type of value returned by the mapper
     * @param mapper - the function to apply to the value if it is valid
     * @returns `this` if the value is invalid; otherwise, a `MaybeInvalid` instance wrapping the
     * result of applying the mapper to the value
     */
    map<U>(mapper: (value: T) => U): ValidationTarget<U>;
    /**
     * Converts an `undefined` or `null` value to an invalid value. If the value is invalid or non-`null`, no
     * action is taken.
     *
     * @returns an invalid value if the original value was `undefined` or `null`; otherwise, returns `this`
     * with `T` excluding `undefined` and `null`
     */
    undefinedOrNullToInvalid(): ValidationTarget<NonUndefinable<NonNullable<T>>>;
    /**
     * Returns the value or throws an error if invalid.
     *
     * @typeParam U - the type of error to throw
     * @param errorSupplier - returns the error to throw if the value is invalid
     * @returns the value
     * @throws U if the value is invalid
     */
    orThrow(errorSupplier: () => Error): T;
    /**
     * Checks if the value is valid.
     *
     * @returns `true` if the value is valid; `false` otherwise
     */
    isValid(): boolean;
    /**
     * Checks if the value is null.
     *
     * @returns `true` if the value is `undefined`; `false` otherwise
     */
    isUndefined(): boolean;
    /**
     * Checks if the value is null.
     *
     * @returns `true` if the value is `null`; `false` otherwise
     */
    isNull(): boolean;
    /**
     * Evaluates a condition on the value.
     *
     * @param condition - the condition to evaluate
     * @returns `true` if the value is invalid, `undefined`, `null` or if the `condition` returns `false`;
     * otherwise, returns `false`
     */
    validationFailed(condition: (value: NonUndefinable<NonNullable<T>>) => boolean): boolean;
    toString(): string;
}
export { ValidationTarget };