compare

The compare utility is a generic comparator function that determines the relative order of two values. It returns -1 if the first value is smaller, 1 if it is larger, and 0 if they are equal.

Implementation

View Source Code

/**
 * Compares two values and returns:
 * - 0 if they are equal
 * - 1 if the first value is greater
 * - -1 if the second value is greater
 *
 * @example
 * ```ts
 * compare('a', 'b'); // -1
 * compare(1, 2); // -1
 * compare(new Date('2023-01-01'), new Date('2023-01-02')); // -1
 * compare('a', 'a'); // 0
 * compare(1, 1); // 0
 * compare(new Date('2023-01-01'), new Date('2023-01-01')); // 0
 * ```
 *
 * @param a - The first value to compare.
 * @param b - The second value to compare.
 *
 * @returns 0 if equal, 1 if the first value is greater, -1 if the second value is greater.
 */
// biome-ignore lint/suspicious/noExplicitAny: -
export const compare = (a: any, b: any): number => {
  if (a === b) return 0;
  if (a === undefined) return 1;
  if (b === undefined) return -1;
  if (a === null) return b === null ? 0 : -1;
  if (b === null) return 1;

  if (typeof a === 'string' && typeof b === 'string') {
    return a.localeCompare(b);
  }

  if (typeof a === 'number' && typeof b === 'number') {
    return a - b;
  }

  if (a instanceof Date && b instanceof Date) {
    return a.getTime() - b.getTime();
  }

  if (typeof a === 'object' && typeof b === 'object') {
    const aString = JSON.stringify(a);
    const bString = JSON.stringify(b);
    return aString.localeCompare(bString);
  }

  return String(a).localeCompare(String(b));
};

Features

• Isomorphic: Works in both Browser and Node.js.
• Versatile: Handles numbers, strings, and dates.
• Standard Interface: Compatible with native Array.prototype.sort().
• Type-safe: Properly typed for any comparable inputs.

API

function compare<T>(a: T, b: T): -1 | 0 | 1;

Parameters

• a: The first value to compare.
• b: The second value to compare.

Returns

• -1: a is less than b.
• 0: a is equal to b.
• 1: a is greater than b.

Examples

Basic Comparison

import { compare } from '@vielzeug/toolkit';

compare(10, 20); // -1
compare('z', 'a'); // 1
compare(5, 5); // 0

Using with Native Sort

import { compare } from '@vielzeug/toolkit';

const numbers = [10, 2, 33, 4, 1];
numbers.sort(compare); // [1, 2, 4, 10, 33]

Implementation Notes

• Performance-optimized for frequent use in sorting loops.
• Correctly handles null and undefined by placing them at the end (or beginning depending on direction).
• Throws nothing; safe for all basic primitive types.

See Also

• compareBy: Create a comparator for complex objects.
• sort: Functional sorting helper.
• isEqual: Check for structural identity.