typia/lib/compare.d.ts

Superfast runtime validators with only one line

import { Atomic } from "@typia/interface";
export type Cover<T> = T extends Atomic.Type | null | undefined ? T : T extends (...args: any[]) => any ? T : T extends readonly (infer U)[] ? Cover<U>[] : T extends object ? {
    [K in keyof T]?: Cover<T[K]>;
} : T;
/**
 * Compares two values of type `T`.
 *
 * Performs a type-directed deep equality comparison. Object properties are
 * compared by the declared structure of `T`; extra runtime properties are not
 * part of the comparison. When `T` (or a nested object type) declares an
 * `equals(y: T): boolean` method, that method is used instead of the structural
 * comparison.
 *
 * @template T Type of values to compare
 * @param x Left value
 * @param y Right value
 * @returns Whether both values are equal by structure
 */
export declare function equals<T>(x: T, y: T): boolean;
/**
 * Compares whether `x` covers the defined structure of `y`.
 *
 * Object properties whose value is `undefined` in `y` are ignored. Arrays and
 * tuples still require identical lengths and compare element-by-element.
 *
 * @template T Type of value to compare
 * @param x Full value
 * @param y Partial value to match
 * @returns Whether `x` covers `y`
 */
export declare function cover<T>(x: T, y: Cover<T>): boolean;
/**
 * Tests whether `x` precedes `y`.
 *
 * Performs a type-directed lexicographic comparison: the properties of `T` are
 * walked in declaration order, depth-first, and the scalar leaves (`number` /
 * `boolean` / `string` / `bigint`) are compared one by one. The result is
 * decided by the first leaf where `x` and `y` differ; if every leaf is equal,
 * the result is `false` (equal is not "less"). When `T` (or a nested object
 * type) declares a `less(y: T): boolean` method, that method is used instead of
 * the structural comparison.
 *
 * The ordering is total and deterministic, so it composes into an
 * `Array.prototype.sort` comparator:
 *
 * ```ts
 * const cmp = (a: T, b: T): number =>
 *   typia.compare.less(a, b) ? -1 : typia.compare.less(b, a) ? 1 : 0;
 * ```
 *
 * @template T Type of values to compare
 * @param x Left value
 * @param y Right value
 * @returns Whether `x` precedes `y`
 */
export declare function less<T>(x: T, y: T): boolean;
/**
 * Creates reusable {@link equals} function.
 *
 * @danger You must configure the generic argument `T`
 */
export declare function createEquals(): never;
/**
 * Creates reusable {@link equals} function.
 *
 * @template T Type of values to compare
 * @returns Reusable equality function
 */
export declare function createEquals<T>(): (x: T, y: T) => boolean;
/**
 * Creates reusable {@link cover} function.
 *
 * @danger You must configure the generic argument `T`
 */
export declare function createCover(): never;
/**
 * Creates reusable {@link cover} function.
 *
 * @template T Type of value to compare
 * @returns Reusable cover function
 */
export declare function createCover<T>(): (x: T, y: Cover<T>) => boolean;
/**
 * Creates reusable {@link less} function.
 *
 * @danger You must configure the generic argument `T`
 */
export declare function createLess(): never;
/**
 * Creates reusable {@link less} function.
 *
 * @template T Type of values to compare
 * @returns Reusable ordering function
 */
export declare function createLess<T>(): (x: T, y: T) => boolean;