@tanstack/db/dist/esm/utils/comparison.d.ts

A reactive client store for building super fast apps on sync

import { CompareOptions } from '../query/builder/types.js';
/**
 * Whether a value has no IEEE-754 natural order: `NaN`, or an invalid Date
 * (whose timestamp is `NaN`). The query engine follows PostgreSQL float
 * semantics for these values — they are all equal to one another and greater
 * than every other (non-null) value — so the comparator and the WHERE
 * evaluator treat them explicitly instead of letting `NaN` compare unequal to
 * everything (which has no consistent order and cannot be indexed or sorted).
 */
export declare function isUnorderable(value: any): boolean;
/**
 * Universal comparison function for all data types
 * Handles null/undefined, strings, arrays, dates, objects, and primitives
 * Always sorts null/undefined values first
 */
export declare const ascComparator: (a: any, b: any, opts: CompareOptions) => number;
/**
 * Descending comparator function for ordering values
 * Handles null/undefined as largest values (opposite of ascending)
 */
export declare const descComparator: (a: unknown, b: unknown, opts: CompareOptions) => number;
export declare function makeComparator(opts: CompareOptions): (a: any, b: any) => number;
/** Default comparator orders values in ascending order with nulls first and locale string comparison. */
export declare const defaultComparator: (a: any, b: any) => number;
/**
 * Sentinel value representing undefined in normalized form.
 * This allows distinguishing between "start from beginning" (undefined parameter)
 * and "start from the key undefined" (actual undefined value in the tree).
 */
export declare const UNDEFINED_SENTINEL = "__TS_DB_BTREE_UNDEFINED_VALUE__";
/**
 * Normalize a value for comparison and Map key usage
 * Converts values that can't be directly compared or used as Map keys
 * into comparable primitive representations
 *
 * Note: This does NOT convert undefined to a sentinel. Use normalizeForBTree
 * for BTree index operations that need to distinguish undefined values.
 */
export declare function normalizeValue(value: any): any;
/**
 * Normalize a value for BTree index usage.
 * Extends normalizeValue to also convert undefined to a sentinel value.
 * This is needed because the BTree does not properly support `undefined` as a key
 * (it interprets undefined as "start from beginning" in nextHigherPair/nextLowerPair).
 */
export declare function normalizeForBTree(value: any): any;
/**
 * Compare values using the equality semantics used by Map keys.
 */
export declare function areSameValueZeroEqual(a: unknown, b: unknown): boolean;
/**
 * Converts the `UNDEFINED_SENTINEL` back to `undefined`.
 * Needed such that the sentinel is converted back to `undefined` before comparison.
 */
export declare function denormalizeUndefined(value: any): any;
/**
 * Compare two Temporal values of the same type, returning -1, 0, or 1.
 *
 * Dispatch is keyed on `Symbol.toStringTag` (the brand already checked by
 * `isTemporal`) rather than `a.constructor`, making it robust across realms
 * and resistant to a shadowed `constructor` property. Types without a static
 * `.compare` (e.g. `PlainMonthDay`) throw rather than fall back to string
 * comparison, matching Temporal's design intent.
 *
 * Callers must ensure both arguments are Temporal objects; mixed types throw.
 */
export declare function compareTemporalValues(a: unknown, b: unknown): number;
/**
 * Order two non-null values, returning -1, 0, or 1.
 *
 * Temporal types intentionally throw from `valueOf` to prevent silent
 * miscomparison via the native relational operators — delegate to
 * `compareTemporalValues` for them. For everything else (numbers, strings,
 * Dates via `valueOf`, etc.) the native operators do the right thing.
 *
 * Callers must handle null/undefined themselves — this helper assumes both
 * arguments are non-null.
 */
export declare function compareValues(a: unknown, b: unknown): number;
/**
 * Compare two values for equality, with special handling for Uint8Arrays and Buffers
 */
export declare function areValuesEqual(a: any, b: any): boolean;