Sorting library inspired by Rust's Ordering.

Allows to easy definition of comparison abilities for your objects, especially value objects.

Community

Join our discord server

Installation

npm install @pallad/compare

Usage

Comparing two values of same type

import {compare} from '@pallad/compare';

compare(1, 2).isLess // true
compare(1, 2).isGreater // false
compare(1, 2).isEqual // false

Sorting

compare first tries to leverage compare defined by Comparable interface if that is possible. Otherwise fallbacks to regular operators (<, ==, >) comparison .

import {compare} from '@pallad/compare';

[5, 1, 10].sort(compare); // [1, 5, 10]
[5, 1, 10].sort(compare.reverse); // [10, 5, 1]

Defining custom sorting for any values

You can define your own custom comparator that is used even if values are Comparable values.

import {compare} from '@pallad/compare';

interface Option {
    type: string;
    value: string;
}

function comparator(a: Option, b: Option) {
    return a.type.localeCompare(b.type);
}


const aValue: Option = {
    type: '2',
    value: 'Option 2'
};

const bValue: Option = {
    type: '1',
    value: 'Option 1'
};
compare(aValue, bValue, comparator).isGreater // true
compare.reverse(aValue, bValue, comparator).isGreater // false

You do not need to pass comparator all the time, just create own compare function.

import {createCompareWithComparator} from '@pallad/compare';

const customCompare = createCompareWithComparator(comparator);
customCompare(aValue, bValue).isGreater // true
customCompare.reverse(aValue, bValue).isGreater // false

Defining custom sorting for value objects

import {Comparable, Equal, Less, Greater} from '@pallad/compare';

class Money implements Comparable {
    constructor(readonly value: number, readonly currency: string) {
    }

    compare(another: Money) {
        if (another.currency !== this.currency) {
            throw new Error('Cannot compare values with different currencies');
        }

        if (another.value === this.value) {
            return Equal;
        } else if (this.value < another.value) {
            return Less
        }
        return Greater;
    }
}


const amountA = new Money(100, 'BGP');
const amountB = new Money(200, 'BGP');

amountA.compare(amountB) // Less

// uses `compare` since it is defined
compare(amountA, amountB); // Less

Explanation

As in Rust's Ordering - @pallad/compare uses 3 immutable objects to describe the comparison result.

The result could be:

• Less
• Equal
• Greater

Each of them implements following shape:

interface Result {
    type: 'equal' | 'less' | 'greater',
    /**
     * Indicates that value is lower
     */
    isLess: boolean;
    /**
     * Indicates that values are equal
     */
    isEqual: boolean;
    /**
     * Indicates that values are not equal (less or greater only)
     */
    isNotEqual: boolean;
    /**
     * Indicates that value is less or equal
     */
    isLessOrEqual: boolean;
    /**
     * Indicates that value is greater or equal
     */
    isGreaterOrEqual: boolean;
    /**
     * Indicates that value is greater
     */
    isGreater: boolean;

    /**
     * Maps result to another value
     */
    map(ifLess: T1, ifEqual: T2, ifGreater: T3): T1 | T2 | T3;

    map({less: T1, equal: T2, greater: T3}): T1 | T2 | T3;

    /**
     * Returns opposite value to current one
     *
     * Less -> Greater
     * Equal -> Equal
     * Greater -> Less
     */
    reverse: Result;
    /**
     * Just numeric value you can use in `.sort` functions
     */
    sortResult: 0 | -1 | 1,
    /**
     * Just numeric value you can use in `.sort` functions to reverse sorting
     */
    sortResultReversed: 0 | -1 | 1,
}

Mapping

You can map comparison result to any other value

import {compare} from '@pallad/compare';

// using arguments for each value
const r1 = compare(1, 5).map('less', 'equal', 'greater') // 'less'
type R1 = typeof r1; // 'less' | 'equal' | 'greater'  

// using object
const r2 = compare(1, 5).map({
    less: 'less',
    equal: 'equal',
    greater: 'greater'
}) // 'less'

type R2 = typeof r2; // 'less' | 'equal' | 'greater'

Mapping to boolean

Before your try to map to booleans, think if currently available helpers are not good enough

import {compare} from '@pallad/compare';

compare(1, 10).map(false, true, false); // Too explicit ⚠️
compare(1, 10).isEqual // better 👌

compare(1, 10).map(true, true, false); // Too explicit ⚠️
compare(1, 10).isLessOrEqual // better 👌