namespace Comp

An object providing methods to compare two values of type K.

Companion interface: Comp<K>

Functions

anyDeepComp

Returns a Comp instance that compares any value using default comparison functions. For Iterables and objects, their elements are compared recursively.

Definition

function anyDeepComp<T>(): Comp<T>;

Type parameters

Name	Description
T

note

can become slow with large nested arrays and objects, and circular structures can cause infinite loops

example

const c = Comp.anyDeepComp();
console.log(c.compare({ a: 1, b: 1 }, { b: 1, a: 1 }))
// => 0
console.log(c.compare([{ a: 1, b: 1 }], [{ b: 1, a: 1 }]))
// => 0

anyFlatComp

Returns a Comp instance that compares any value using default comparison functions, but never recursively compares Iterables or objects. In those cases, it will use the stringComp instance.

Definition

function anyFlatComp<T>(): Comp<T>;

Type parameters

Name	Description
T

example

const c = Comp.anyFlatComp();
console.log(c.compare({ a: 1, b: 1 }, { b: 1, a: 1 }) < 0)
// => true
// First object is smaller because the objects are converted to a string with and then compares the resulting string.

anyShallowComp

Returns a Comp instance that compares any value using default comparison functions. For Iterables and objects, their elements are compared only one level deep for performance and to avoid infinite recursion.

Definition

function anyShallowComp<T>(): Comp<T>;

Type parameters

Name	Description
T

example

const c = Comp.anyShallowComp();
console.log(c.compare({ a: 1, b: 1 }, { b: 1, a: 1 }))
// => 0
console.log(c.compare([{ a: 1, b: 1 }], [{ b: 1, a: 1 }]) < 0)
// => true
// First object is smaller because the objects are converted to a string and then compares the resulting string.

anyStringJSONComp

Returns a Comp instance converts values to string with JSON.stringify, and orders the resulting string naturally.

Definition

function anyStringJSONComp<T>(): Comp<T>;

Type parameters

Name	Description
T

anyToStringComp

Returns a any Comp instance that orders any according to their toString values.

Definition

function anyToStringComp(): Comp<any>;

bigIntComp

Returns a default bigint Comp instance that orders bigint numbers naturally.

Definition

function bigIntComp(): Comp<bigint>;

booleanComp

Returns a default boolean Comp instance that orders booleans according to false < true.

Definition

function booleanComp(): Comp<boolean>;

example

const c = Comp.booleanComp();
console.log(c.compare(false, true) < 0)
// => true
console.log(c.compare(true, true))
// => 0

createValueOfComp

Returns a Comp instance that orders objects with a valueOf method according to the given valueComp instance for the valueOf values.

Definition

function createValueOfComp<T extends {
    valueOf(): V;
  }, V>(cls: {
    new (): T;
  }, valueComp?: Comp<V>): Comp<T>;

Type parameters

Name	Description
T
V

Parameters

Name	Type	Description
cls	{     new (): T;   }	the constructor of the values the Comp instance can compare
valueComp	Comp<V>	(optional) the Comp instance to use on the .valueOf values

dateComp

Returns a Date Comp instance that orders Dates according to their .valueOf value.

Definition

function dateComp(): Comp<Date>;

defaultComp

Returns the default Comp instance, which is the Comp.anyDeepComp() instance.

Definition

function defaultComp(): Comp<any>;

invert

Returns a Comp instance the reverses the order of the given comp instance.

Definition

function invert<T>(comp: Comp<T>): Comp<T>;

Type parameters

Name	Description
T

Parameters

Name	Type	Description
comp	Comp<T>	the Comp instance to wrap

example

const c = Comp.invert(Comp.numberComp())
console.log(c.compare(3, 5) > 0)
// => true
console.log(c.compare(5, 5))
// => 0

iterableComp

Returns a Comp instance for Iterable objects that orders the Iterables by comparing the elements with the given itemComp Comp instance.

Definition

function iterableComp<T>(itemComp?: Comp<T>): Comp<Iterable<T>>;

Type parameters

Name	Description
T

Parameters

Name	Type	Description
itemComp	Comp<T>	(optional) the Comp instance to use to compare the Iterable's elements.

example

const c = Comp.iterableComp();
console.log(c.compare([1, 3, 2], [1, 3, 2]))
// => 0
console.log(c.compare([1, 2, 3, 4], [1, 3, 2]) < 0)
// => true

numberComp

Returns a default number Comp instance that orders numbers naturally.

Definition

function numberComp(): Comp<number>;

example

const c = Comp.numberComp();
console.log(c.compare(3, 5))
// => -2

objectComp

Returns a Comp instance for objects that orders the object keys according to the given keyComp, and then compares the corresponding values using the given valueComp. Objects are then compared as follows: starting with the smallest key of either object:

• if only one of the objects has the key, the object with the key is considered to be larger than the other
• if both objects have the key, the values are compared with valueComp. If the values are not equal, this result is returned.

if the objects have the same keys with the same values, they are considered equal

Definition

function objectComp(options?: {
    keyComp?: Comp<any>;
    valueComp?: Comp<any>;
  }): Comp<Record<any, any>>;

Parameters

Name	Type	Description
options	{     keyComp?: Comp<any>;     valueComp?: Comp<any>;   }

example

const c = Comp.objectComp();
console.log(c.compare({ a: 1 }, { a: 1 }))
// => 0
console.log(c.compare({ a: 1 }, { a: 2 }) < 0)
// => true
console.log(c.compare({ b: 5 }, { a: 2 }) < 0)
// => true
console.log(c.compare({ a: 1, b: 2 }, { b: 5 }) < 0)
// => true
console.log(c.compare({ a: 1, b: 2 }, { b: 2, a: 1 }))
// => 0

stringCaseInsensitiveComp

Returns a Comp instance that compares strings in a case-insensitive way.

Definition

function stringCaseInsensitiveComp(): Comp<string>;

stringCharCodeComp

Returns a string Comp instance that orders strings according to their indexed char codes.

Definition

function stringCharCodeComp(): Comp<string>;

stringComp

Returns a Comp instance that compares strings based on the string's localeCompare method.

Definition

function stringComp(...args: ConstructorParameters<typeof Intl.Collator>): Comp<string>;

Parameters

Name	Type	Description
args	ConstructorParameters<typeof Intl.Collator>

toEq

Returns an Eq equality instance thet will return true when the given comp comparable instance returns 0.

Definition

function toEq<T>(comp: Comp<T>): Eq<T>;

Type parameters

Name	Description
T

Parameters

Name	Type	Description
comp	Comp<T>	the Comp comparable instance to convert

example

const eq = Comp.toEq(Comp.objectComp())
console.log(eq({ a: 1, b: 2 }, { b: 2, a: 1 }))
// => true

withNull

Returns a Comp instance that extends the given comp instance with the capability to handle null values, where null is considered to be smaller than any other value, and equal to another null.

Definition

function withNull<T>(comp: Comp<T>): Comp<T | null>;

Type parameters

Name	Description
T

Parameters

Name	Type	Description
comp	Comp<T>	the Comp instance to wrap

example

const c = Comp.withNull(Comp.numberComp())
console.log(c.compare(null, 5) < 0)
// => true
console.log(c.compare(null, null))
// => 0

withUndefined

Returns a Comp instance that extends the given comp instance with the capability to handle undefined values, where undefined is considered to be smaller than any other value, and equal to another undefined.

Definition

function withUndefined<T>(comp: Comp<T>): Comp<T | undefined>;

Type parameters

Name	Description
T

Parameters

Name	Type	Description
comp	Comp<T>	the Comp instance to wrap

example

const c = Comp.withUndefined(Comp.numberComp())
console.log(c.compare(undefined, 5) < 0)
// => true
console.log(c.compare(undefined, undefined))
// => 0