assert-json-object/dist/index.d.mts

🧪 Fluent, chainable assertions for JSON structures with dot-path access.

/**
 * Supported primitive types for type assertions.
 */
type PrimitiveType = "string" | "number" | "boolean" | "object" | "array" | "undefined" | "null";
/**
 * Options for soft assertion mode.
 */
type SoftOptions = {
    soft?: boolean;
    maxErrors?: number;
};
/**
 * Fluent assertion class for JSON objects.
 * Supports dot-path access, negation, and soft assertion mode.
 */
declare class JsonAssertion {
    private target;
    private negated;
    private soft;
    private errors;
    private maxErrors?;
    /**
     * @param target The JSON object to assert on.
     * @param opts Optional options. If `soft` is true, enables soft assertion mode.
     * @param sharedErrors Internal: shared error array for soft mode chaining.
     * @param sharedMaxErrors Internal: shared maxErrors for soft mode chaining.
     */
    constructor(target: Record<string, any>, opts?: SoftOptions, sharedErrors?: Error[], sharedMaxErrors?: number);
    /**
     * Negates the next assertion.
     * @returns A new JsonAssertion instance with negation toggled.
     */
    get not(): JsonAssertion;
    /**
     * Returns true if soft assertion mode is enabled.
     */
    get isSoft(): boolean;
    /**
     * Returns an array of collected errors (only in soft mode).
     */
    getErrors(): Error[];
    private canCollectError;
    private handleError;
    /**
     * Asserts that the given dot-path exists in the JSON object.
     * @param path Dot-path string (e.g. "foo.bar[0].baz")
     * .toHaveKey(path): Asserts key exists at given path
     * .not.toHaveKey(path): Asserts key does NOT exist
     */
    toHaveKey(path: string): this;
    /**
     * Asserts that the value at the given path is of the specified primitive type.
     * @param path Dot-path string
     * @param type Expected primitive type: "string", "number", "boolean", "object", "array", "null", "undefined"
     */
    toBeType(path: string, type: PrimitiveType): this;
    /**
     * Asserts that the value at the given path is defined (not undefined).
     * @param path Dot-path string
     */
    toBeDefined(path: string): this;
    /**
     * Asserts that the value at the given path is null.
     * @param path Dot-path string
     */
    toBeNull(path: string): this;
    /**
     * Asserts that the value at the given path is truthy.
     * @param path Dot-path string
     */
    toBeTruthy(path: string): this;
    /**
     * Asserts that the value at the given path is falsy.
     * @param path Dot-path string
     */
    toBeFalsy(path: string): this;
    /**
     * Asserts that the value at the given path equals the expected value (deep equality).
     * @param path Dot-path string
     * @param expected Expected value
     * .toMatchValue(path, value): Asserts value is exactly equal (deep)
     */
    toMatchValue(path: string, expected: unknown): this;
    /**
     * Asserts that the value at the given path contains the expected value (for arrays or strings).
     * @param path Dot-path string
     * @param expected Expected value to be contained
     * .toContainValue(path, value): Works for arrays or strings
     */
    toContainValue(path: string, expected: unknown): this;
    /**
     * Asserts that the value at the given path is greater than the given number.
     * @param path Dot-path string
     * @param num Number to compare
     * .toBeGreaterThan(path, number): Only for numeric values
     */
    toBeGreaterThan(path: string, num: number): this;
    /**
     * Asserts that the value at the given path is less than the given number.
     * @param path Dot-path string
     * @param num Number to compare
     * .toBeLessThan(path, number): Only for numeric values
     */
    toBeLessThan(path: string, num: number): this;
    /**
     * Asserts that the value at the given path matches any value in the provided list.
     * @param path Dot-path string
     * @param values Array of allowed values
     * .toBeOneOf(path, [values]): Assert that value matches any in a list
     */
    toBeOneOf(path: string, values: unknown[]): this;
    /**
     * Asserts that the value at the given path satisfies the provided predicate function.
     * @param path Dot-path string
     * @param predicate Predicate function to test the value
     * .toSatisfy(path, fn): Apply any custom predicate on a value
     */
    toSatisfy<T = unknown>(path: string, predicate: (val: T) => boolean): this;
}

export { JsonAssertion };