namespace Eq

A function returning true if given v1 and v2 should be considered equal.

Companion type: Eq<T>

Functions

anyDeepEq

Returns an Eq instance that checks equality of any values. For composed values (objects and iterables) it will recursively compare the contained values.

Definition

function anyDeepEq<T = any>(): Eq<T>;

Type parameters

Name	Description
T	the value type

note

may have poor performance for deeply nested types and large arrays, and objects with circular structures may cause infinite loops

example

const eq = Eq.anyDeepEq()
console.log(eq(1, 'a'))
// => false
console.log(eq({ a: 1, b: 2 }, { b: 2, a: 1 }))
// => true
console.log(eq([{ a: 1, b: 2 }], [{ b: 2, a: 1 }]))
// => false

anyFlatEq

Returns an Eq instance that checks equality of any values. For composed values (objects and iterables) it will compare with Object.is.

Definition

function anyFlatEq<T = any>(): Eq<T>;

Type parameters

Name	Description
T	the value type

example

const eq = Eq.anyFlatEq()
console.log(eq(1, 'a'))
// => false
console.log(eq({ a: 1, b: 2 }, { b: 2, a: 1 }))
// => false

anyJsonEq

Returns an Eq instance that considers values equal their JSON.stringify values are equal.

Definition

function anyJsonEq(): Eq<any>;

example

const eq = Eq.anyJsonEq()
console.log(eq({ a: 1, b: 2 }, { a: 1, b: 2 }))
// => true
console.log(eq({ a: 1, b: 2 }, { b: 2, a: 1 }))
// => false

anyShallowEq

Returns an Eq instance that checks equality of any values. For composed values (objects and iterables) it will enter 1 level, and if again compound values are found, they are compared with Object.is.

Definition

function anyShallowEq<T = any>(): Eq<T>;

Type parameters

Name	Description
T	the value type

example

const eq = Eq.anyShallowEq()
console.log(eq(1, 'a'))
// => false
console.log(eq({ a: 1, b: 2 }, { b: 2, a: 1 }))
// => true
console.log(eq([{ a: 1, b: 2 }], [{ b: 2, a: 1 }]))
// => false

anyToStringEq

Returns an Eq instance that considers two values equal when their string representations, as returned by Eq.convertAnyToString, are equal.

Definition

function anyToStringEq(): Eq<any>;

example

const eq = Eq.anyToStringEq()
console.log(eq({ a: 1 }, { a: 1 }))
// => true
console.log(eq({ a: 1 }, { a: 2 }))
// => false

convertAnyToString

Converts any given value to a string representation that is stable for equality and ordering comparisons. For primitive values and objects with a custom toString implementation, it uses String(value). For plain objects with the default Object.prototype.toString implementation, it uses JSON.stringify(value) instead.

Definition

function convertAnyToString(value: any): string;

Parameters

Name	Type	Description
value	any	the value to convert

createStringCollatorEq

Returns an Eq instance that considers strings equal taking the given or default locale into account.

Definition

function createStringCollatorEq(...args: ConstructorParameters<typeof Intl.Collator>): Eq<string>;

Parameters

Name	Type	Description
args	ConstructorParameters<typeof Intl.Collator>

example

const eq = Eq.createStringCollatorEq()
console.log(eq('a', 'a'))
// => true
console.log(eq('abc', 'aBc'))
// => false

dateEq

Returns an Eq instance that compares Date objects according to their valueOf value.

Definition

function dateEq(): Eq<Date>;

example

const eq = Eq.dateEq()
console.log(eq(new Date(2020, 1, 1), new Date(2020, 1, 1))
// => true
console.log(eq(new Date(2020, 1, 1), new Date(2020, 2, 1))
// => false

defaultEq

Returns the default Eq instance, which is the Eq.anyDeepEq() instance.

Definition

function defaultEq(): Eq<any>;

iterableEq

Returns an Eq instance that compares Iterables by comparing their elements with the given itemEq Eq instance.

Definition

function iterableEq<T>(itemEq?: Eq<T>): Eq<Iterable<T>>;

Type parameters

Name	Description
T	the Iterable element type

Parameters

Name	Type	Description
itemEq	Eq<T>	(optional) the Eq instance to use to compare the Iterable's elements

example

const eq = Eq.iterableEq();
console.log(eq([1, 2, 3], [1, 2, 3])
// => true
console.log(eq([1, 2, 3], [1, 3, 2])
// => false

objectEq

Returns an Eq instance that checks equality of objects containing property values of type V by iteratively applying given valueEq to each of the object's property values.

Definition

function objectEq<V = any>(valueEq?: Eq<V>): Eq<Record<any, V>>;

Type parameters

Name	Description
V	the object property value type

Parameters

Name	Type	Description
valueEq	Eq<V>	(optional) the Eq instance to use to compare property values

example

const eq = Eq.objectEq()
console.log(eq({ a: 1, b: { c: 2 }}, { b: { c: 2 }, a: 1 }))
// => true
console.log(eq({ a: 1, b: { c: 2 }}, { a: 1, b: { c: 3 }}))
// => false

stringCaseInsentitiveEq

Returns an Eq instance that considers strings equal regardless of their case.

Definition

function stringCaseInsentitiveEq(): Eq<string>;

example

const eq = Eq.stringCaseInsentitiveEq()
console.log(eq('aB', 'Ab'))
// => true
console.log(eq('aBc', 'abB'))
// => false

stringCharCodeEq

Returns an Eq instance that considers strings equal when all their charcodes are equal.

Definition

function stringCharCodeEq(): Eq<string>;

example

const eq = Eq.stringCharCodeEq()
console.log(eq('a', 'a'))
// => true
console.log(eq('abc', 'aBc'))
// => false

tupleSymmetric

Returns an Eq instance for tuples that considers two tuples [A, B] and [C, D] equal if [A, B] equals [C, D], or if [A, B] equals [D, C]

Definition

function tupleSymmetric<T>(eq?: Eq<T>): Eq<readonly [T, T]>;

Type parameters

Name	Description
T

Parameters

Name	Type	Description
eq	Eq<T>	(optional) an alternative Eq instance to use for the values in the tuple

example

const eq = Eq.tupleSymmetric()
console.log(eq([1, 2], [1, 2]))
// => true
console.log(eq([1, 2], [2, 1]))
// => true
console.log(eq([1, 3], [2, 1]))
// => false

valueOfEq

Returns an Eq instance for objects that have a valueOf method. It returns true if the .valueOf values of both given objects are equal.

Definition

function valueOfEq<T extends {
    valueOf(): V;
  }, V>(): Eq<T>;

Type parameters

Name	Description
T	the object type containing a valueOf function of type V
V	the valueOf result type

example

const eq = Eq.valueOfEq()
console.log(eq(new Number(5), new Number(5)))
// => true
console.log(eq(new Number(5), new Number(3)))
// => false

Constants

Name	Description
objectIs	An Eq instance that uses Object.is to determine if two objects are equal.