isEqual()

import { isEqual } from "@fed1/jsos";

A JSFunction that checks whether its two arguments are (structurally) equal.

The isEqual function does a deep equality check of its arguments. That means that it iterates over all the properties in objects and all the items in arrays, maps, and sets recursively.

The function is also aware of arguments objects, regular expressions, class hierarchies, and complex/struct types.

The isEqual function works with objects containing circular references, too!

Order of contained items

The isEqual function is aware of the order of sequential types, but does not care about the order of items in maps or sets:

isEqual([1, 2, 3], [1, 2, 3]); // true
isEqual([1, 2, 3], [1, 3, 2]); // false
isEqual(new Set([1, 2, 3]), [1, 2, 3]); // false
isEqual(new Set([1, 2, 3]), new Set([1, 2, 3])); // true
isEqual(new Set([1, 2, 3]), new Set([1, 3, 2])); // true

Arguments object and arrays

An array and an arguments object with the same contents are not considered equal:

function checkArgs() {
    return isEqual(arguments, [1, 2, 3])
}

checkArgs(1, 2, 3); // false!

We recommend not using the arguments object anymore. The fact that it is not an actual array is a confusing quirk of JavaScript. We suggest using spread syntax (...) instead.

Equality checks in method signatures

For performance reasons, object equality is not checked in multimethod dispatch by default. You can activate it for specific multimethods you create by supplying the scoring option and adding the RULES.EQUAL constant to it.

See: RULES

Usage

isEqual(a, b)

Parameters

#	Parameter	Required?	Type	Default
1	a	yes	TAny
2	b	yes	TAny

1. a

The value to check for whether it is equal to b.

2. b

The value to check for whether it is equal to a.

Return value

A JSBoolean that is true when arguments a and b are equal.

Version History

Feature	Since version
isEqual()	1.0

JSOS1.0