feat(isEqual): add isEqual function with its tests and documentation

[xvyashar]

Function Signature

function isEqual(a: unknown, b: unknown): boolean;

Motivation

isEqual performs a deep equality comparison between two values, recursively comparing nested structures instead of relying on reference equality.

It supports common JavaScript value types including primitives, functions, objects, arrays, dates, regular expressions, maps, sets, and circular references:

// Primitive types
console.log(isEqual("abc", "abc")); // true
console.log(isEqual(1, 1)); // true
console.log(isEqual(null, null)); // true

// Deep object comparison
const obj = { a: { b: { c: 1 } } };
const clonedObj = clone(obj);
console.log(isEqual(obj, clonedObj)); // true

// Deep array comparison
const array = [1, 2, [3, [4, 5, [6, 7]]]];
const clonedArray = clone(array);
console.log(isEqual(array, clonedArray)); // true

// Date comparison
const date1 = new Date("2026-01-01");
const date2 = new Date("2026-01-01");
console.log(isEqual(date1, date2)); // true

// RegExp comparison
const regex1 = new RegExp("abc", "g");
const regex2 = new RegExp("abc", "g");
console.log(isEqual(regex1, regex2)); // true

// Map comparison
const map = new Map([
  ["a", 1],
  ["b", { c: [1, 2] }],
]);
const clonedMap = clone(map);
console.log(isEqual(map, clonedMap)); // true

// Set comparison
const set = new Set([1, 2, "a"]);
const clonedSet = clone(set);
console.log(isEqual(set, clonedSet)); // true

Benefits:

• Provides reliable deep equality comparison for complex JavaScript values.
• Handles nested and circular data structures.
• Supports built-in collections such as Map and Set.

[ASafaeirad]

I don't get this part.
Why do we return true if they have already been compared?

[xvyashar]

As we can see in the next line, this function immediately adds the current comparison to the map. So, when it reaches the same comparison twice or more, it means:

• The result of this comparison was true (because this function would have already exited early if the result was false).
• Or the comparison is still in progress at the parent scope. By returning true, we skip this comparison and let the parent comparison determine the result, while avoiding a circular reference overflowing our call stack.

By the way, I agree that the naming of these functions and "comparedObjects" is kinda misleading. I can think of new names if you want!

[github-actions]

🎉 This PR is included in version 4.24.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀