ts-order/dist/comparator/index.d.ts

Type-safe Order utility for delarative, composable, and immutable multi-key ordering logic

import { Comparator, KeyOptions } from "../types-CdxsM0-q.js";

//#region src/comparator/index.d.ts

/**
 * Convenience alias for `-1`, indicating that `a` should come before `b` inside a comparator function.
 */
declare const A_BEFORE_B = -1;
/**
 * Convenience alias for `1`, indicating that `a` should come after `b` inside a comparator function.
 */
declare const A_AFTER_B = 1;
/**
 * Convenience alias for `0` indicating that `a` is equal to `b` inside a comparator function.
 */
declare const EQUAL = 0;
/**
 * Inverts the result of a comparator so that higher values come first.
 *
 * @example
 * ```ts
 * ['c', 'a', 'b'].sort(reverse(string)); // ['c', 'b', 'a']
 * ```
 */
declare function reverse<T>(compareFn: Comparator<T>): Comparator<T>;
/**
 * Wraps a comparator so `null` and `undefined` sort before defined values.
 *
 * @example
 * ```ts
 * [null, 'b', 'a'].sort(nullsFirst(string)); // [null, 'a', 'b']
 * ```
 */
declare function nullsFirst<T>(compareFn: Comparator<T>): Comparator<T | null | undefined>;
/**
 * Wraps a comparator so `null` and `undefined` sort after defined values.
 *
 * @example
 * ```ts
 * ['b', null, 'a'].sort(nullsLast(string)); // ['a', 'b', null]
 * ```
 */
declare function nullsLast<T>(compareFn: Comparator<T>): Comparator<T | null | undefined>;
/**
 * Wraps a comparator so `NaN` numbers sort before other values.
 *
 * @example
 * ```ts
 * [NaN, 2, 1].sort(nansFirst(number)); // [NaN, 1, 2]
 * ```
 */
declare function nansFirst<T>(compareFn: Comparator<T>): Comparator<T>;
/**
 * Wraps a comparator so `NaN` numbers sort after other values.
 *
 * @example
 * ```ts
 * [2, NaN, 1].sort(nansLast(number)); // [1, 2, NaN]
 * ```
 */
declare function nansLast<T>(compareFn: Comparator<T>): Comparator<T>;
/**
 * Basic three-way comparator using JavaScript relational operators (i.e. `a < b`, `a > b`).
 *
 * @example
 * ```ts
 * ['b', 'a', 'c'].sort(compare); // ['a', 'b', 'c']
 * ```
 */
declare function compare<T>(a: T, b: T): number;
/**
 * Locale-aware string comparator using `Intl.Collator`.
 *
 * @example
 * ```ts
 * ['ä', 'a', 'z'].sort(localeString); // ['a', 'ä', 'z'] in de-DE locale
 * ```
 */
declare function localeString(a: string, b: string): number;
/**
 * Numeric comparator that places `NaN` before finite numbers.
 *
 * @example
 * ```ts
 * [3, NaN, 1].sort(number); // [NaN, 1, 3]
 * ```
 */
declare function number(a: number, b: number): number;
/**
 * Boolean comparator treating `false` as 0 and `true` as 1.
 *
 * @example
 * ```ts
 * [true, false].sort(boolean); // [false, true]
 * ```
 */
declare function boolean(a: boolean, b: boolean): number;
/**
 * Date comparator that falls back to placing invalid dates first.
 *
 * @example
 * ```ts
 * [new Date('2020'), new Date('2010')].sort(date); // [2010, 2020]
 * ```
 */
declare function date(a: Date, b: Date): number;
/**
 * Builds a comparator by projecting values through `key` before comparing.
 *
 * @example
 * ```ts
 * // sorts users by age ascending
 * users.sort(by(user => user.age));
 * ```
 */
declare function by<T, K>(key: (v: T) => K, options?: KeyOptions<K, T>): Comparator<T>;
/**
 * Chains comparators, returning the first non-zero comparison result.
 *
 * @example
 * ```ts
 * // Sort users by last name, then first name
 * users.sort(
 *   order(
 *     by((u) => u.last),
 *     by((u) => u.first),
 *   ),
 * );
 * ```
 */
declare function order<T>(...comparators: Comparator<T>[]): Comparator<T>;
/**
 * Adapts a comparator to work on mapped values.
 *
 * @example
 * ```ts
 * // Sort strings by their length
 * ['aa', 'b'].sort(map((value: string) => value.length)); // ['b', 'aa']
 * ```
 */
declare function map<T, U>(map: (value: T) => U, compareFn?: Comparator<U>): Comparator<T>;
/**
 * Runs a comparator only when both values satisfy a predicate.
 *
 * @example
 * ```ts
 * people.sort(
 *   when(
 *     (person) => person.age >= 18,
 *     by((person) => person.age),
 *   ),
 * );
 * ```
 */
declare function when<T>(predicate: (v: T) => boolean, compareFn: Comparator<T>): Comparator<T>;
//#endregion
export { A_AFTER_B, A_BEFORE_B, EQUAL, boolean, by, compare, compare as string, date, localeString, map, nansFirst, nansLast, nullsFirst, nullsLast, number, order, reverse, when };