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

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

import { MutableStringMappers, Configuration } from "../internal.mjs";
/**
 * Determines the behavior of a validator.
 */
declare class MutableConfiguration {
    private readonly _stringMappers;
    private _allowDiff;
    private _recordStacktrace;
    private _throwOnFailure;
    private _errorTransformer;
    /**
     * Creates a new configuration.
     *
     * @param allowDiff           - `true` if error messages may include a diff that compares actual and
     *   expected values
     * @param stringMappers     - the configuration used to map contextual values to a String
     * @param recordStacktrace - `true` if the error stack trace must be recorded when a validation failure
     *   occurs. If `false`, the error type remains the same, but the stack trace points to the invocation
     *   of `elseGetError()`. Users who only plan to
     *   {@link ValidationFailures.getMessages|list of failure messages} instead of retrieving an error
     *   may see a performance improvement if this value is set to `false`.
     * @param throwOnFailure    - `true` if an error is thrown on validation failure.
     * @param errorTransformer  - a function that transforms the validation error into a suitable runtime
     *                            error or error
     * @throws TypeError if any of the arguments are `undefined` or `null`
     */
    private constructor();
    /**
     * @param configuration - the immutable configuration
     * @returns a mutable copy of the configuration
     */
    static from(configuration: Configuration): MutableConfiguration;
    /**
     * Returns an immutable copy of this configuration.
     *
     * @returns an immutable copy of this configuration
     */
    toImmutable(): Configuration;
    /**
     * Returns `true` if error messages may include a diff that compares actual and expected values.
     *
     * @returns `true` by default
     */
    allowDiff(): boolean;
    /**
     * Specifies whether error messages may include a diff that compares actual and expected values.
     *
     * @param mayDiff - `true` if error messages may include a diff, `false` otherwise
     * @returns this
     */
    allowDiff(mayDiff: boolean): this;
    /**
     * Returns the configuration used to map contextual values to a String. Supports common types such as
     * arrays, numbers, collections, maps, paths and errors.
     *
     * @returns a function that takes an object and returns the `string` representation of the object
     */
    stringMappers(): MutableStringMappers;
    /**
     * Returns `true` if error stack traces should reference the code that triggers a validation
     * failure. When set to `false`, the error type remains unchanged, but the stack trace location is
     * undefined. Users who only plan to {@link ValidationFailures.getMessages|list of failure messages}
     * instead of errors may experience a performance improvement if this value is set to `false`.
     *
     * @returns `true` if errors must be recorded when a validation failure occurs
     */
    recordStacktrace(): boolean;
    /**
     * Specifies whether error stack traces should reference the code that triggers a validation failure.
     * When set to `false`, the error type remains unchanged, but the stack trace location is
     * undefined. Users who only plan to {@link ValidationFailures.getMessages|list of failure messages}
     * instead of errors may experience a performance improvement if this value is set to `false`.
     *
     * @param recordStacktrace - `true` if errors must be recorded when a validation failure occurs
     * @returns this
     */
    recordStacktrace(recordStacktrace: boolean): this;
    /**
     * Returns `true` if an error is thrown on validation failure.
     *
     * @returns `true` if an error is thrown on validation failure
     */
    throwOnFailure(): boolean;
    /**
     * Specifies whether an error is thrown on validation failure.
     *
     * @param throwOnFailure - `true` if an error is thrown on validation failure
     * @returns this
     */
    throwOnFailure(throwOnFailure: boolean): this;
    /**
     * Returns a function that transforms the validation error into a suitable runtime error or error.
     * The input and output of the function must be subclasses of `RuntimeError` or
     * `Error`. If the function returns `null` the input error will be thrown.
     *
     * @returns a function that transforms the validation error
     */
    errorTransformer(): (error: Error) => Error;
    /**
     * Transform the validation error into a suitable runtime error or error. If the function returns
     * `undefined` or `null` then the input error will be thrown.
     *
     * @param errorTransformer - a function that transforms the validation error
     * @throws TypeError if `errorTransformer` is `undefined` or `null`
     * @returns this
     */
    errorTransformer(errorTransformer: (error: Error) => Error): this;
    toString(): string;
}
export { MutableConfiguration };