shelving/util/sort.d.ts

Toolkit for using data in JavaScript.

import type { ImmutableArray } from "./array.js";
import type { Arguments } from "./function.js";
/** Function that can compare two values for sorting. */
export type Compare<T, A extends Arguments = []> = (left: T, right: T, ...args: A) => number;
/**
 * Compare two unknown values in ascending order.
 * - Allows values of different types to be ranked for sorting.
 *
 * 1. Numbers and dates (ascending order: -Infinity, negative, zero, positive, Infinity, NaN)
 * 2. Strings (locale-aware order)
 * 3. `true`
 * 4. `false`
 * 5. `null`
 * 6. Unsorted values (objects that can't be converted to number or string, symbols, NaN, etc)
 * 7. `undefined`
 *
 * @param x The first value to rank.
 * @param y The second value to rank.
 *
 * @returns Number below zero if `a` is higher, number above zero if `b` is higher, or `0` if they're equally sorted.
 */
export declare function compareAscending(left: unknown, right: unknown): number;
/** Compare two unknown values in descending order. */
export declare function compareDescending(left: unknown, right: unknown): number;
/** Sort an iterable set of items using a ranker (defaults to sorting in ascending order). */
export declare function sortArray<T, A extends Arguments = []>(input: ImmutableArray<T> | Iterable<T>, compare?: Compare<T, A>, ...args: A): ImmutableArray<T>;