@cowwoc/requirements/node/internal/message/diff/ContextGenerator.d.mts

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

import { Configuration, type ApplicationScope, type MessageSection } from "../../internal.mjs";
/**
 * Returns the difference between two values as an error context.
 */
declare class ContextGenerator {
    private readonly scope;
    private readonly configuration;
    private readonly diffGenerator;
    /**
     * The name of the actual value.
     */
    private readonly _actualName;
    /**
     * The actual value.
     */
    private _actualValue;
    /**
     * The name of the expected value.
     */
    private readonly _expectedName;
    /**
     * The expected value.
     */
    private _expectedValue;
    /**
     * `true` if error messages may include a diff that compares actual and expected values.
     */
    private _allowDiff;
    /**
     * `true` if the output may include an explanation of the diff format.
     */
    private _allowLegend;
    /**
     * Creates a ContextGenerator.
     *
     * @param scope         - the application configuration
     * @param configuration - the validator configuration
     * @param actualName    - the name of the actual value
     * @param expectedName  - the name of the expected value
     * @throws AssertionError if:
     *                        <ul>
     *                          <li>any of the arguments is null</li>
     *                          <li>`actualName` or `expectedName` are blank</li>
     *                          <li>`actualName` or `expectedName` contains a colon</li>
     *                        </ul>
     */
    constructor(scope: ApplicationScope, configuration: Configuration, actualName: string, expectedName: string);
    /**
     * Sets the actual value.
     *
     * @param value - the object representation of the actual value
     * @returns this
     */
    actualValue(value: unknown): this;
    /**
     * Sets the expected value.
     *
     * @param value - the object representation of the expected value
     * @returns this
     */
    expectedValue(value: unknown): this;
    /**
     * Overrides the value of {@link Configuration.allowDiff}.
     *
     * @param allowDiff - `true` if error messages may include a diff that compares actual and expected
     * values
     * @returns this
     */
    allowDiff(allowDiff: boolean): this;
    /**
     * Determines if the output may include a legend of the diff format.
     *
     * @param allowLegend - `true` if the output may include an explanation of the diff format
     * return this
     */
    allowLegend(allowLegend: boolean): this;
    /**
     * @returns the diff to append to the error message
     */
    build(): MessageSection[];
    /**
     * @param actualName    - the name of the actual value
     * @param actualValue   - the value of the actual value
     * @param diff          - the difference between the two values (empty if absent)
     * @param expectedName  - the name of the expected value
     * @param expectedValue - the value of the expected value
     * @returns the difference between the expected and actual values
     */
    private getDiffSection;
    /**
     * Generates a List-specific error context from the actual and expected values.
     *
     *  @returns the difference between the expected and actual values
     *  @throws AssertionError if the actual or expected values do not exist
     */
    private getContextOfList;
    /**
     * Returns context entries to indicate that duplicate lines were skipped.
     *
     * @returns the context entries to append
     */
    private static skipEqualLines;
    /**
     * Generates an error context from the actual and expected values.
     *
     * @returns the difference between the expected and actual values
     */
    private getContextOfObjects;
    /**
     * @param list - a list
     * @param i    - an index
     * @returns the element at the specified index, or `""` if the index is out of bounds
     */
    private static getElementOrEmptyString;
    private getContextForSingleLine;
    /**
     * @param lines - the result of comparing the actual and expected values
     * @returns `true` if the string representation of the values is equal
     */
    private stringRepresentationsAreEqual;
    /**
     * @returns the difference between the expected and actual values
     * @throws TypeError if `actualName` or `expectedName` are `undefined` or `null`
     */
    private compareTypes;
    toString(): string;
}
export { ContextGenerator };