@se-oss/deep-equal

@se-oss/deep-equal is a performant, and reliable deep equality comparison utility for JavaScript and TypeScript.

---

• Installation
• Usage
• Documentation
• Performance
• Contributing
• License

📦 Installation

npm install @se-oss/deep-equal

Install using your favorite package manager

pnpm

pnpm install @se-oss/deep-equal

yarn

yarn add @se-oss/deep-equal

📖 Usage

import { deepEqual } from '@se-oss/deep-equal';

deepEqual(1, 1); // true
deepEqual({ a: 1 }, { a: 1 }); // true
deepEqual([1, 2], [1, 2]); // true
deepEqual({ a: 1 }, { a: 2 }); // false

Loose vs strict comparison

By default, comparison is strict (===). Disable it to allow loose equality for primitives.

deepEqual(1, '1'); // false
deepEqual(1, '1', { strict: false }); // true
deepEqual(0, false, { strict: false }); // true

Ignoring object keys

Ignore specific top-level keys when comparing objects.

deepEqual({ a: 1, b: 2 }, { a: 1, b: 99 }, { ignoreKeys: ['b'] }); // true

Nested paths are not supported:

deepEqual({ a: { b: 1 } }, { a: { b: 2 } }, { ignoreKeys: ['a.b'] }); // false

Arrays, Dates, and RegExps

deepEqual([1, { a: 2 }], [1, { a: 2 }]); // true

deepEqual(new Date('2023-01-01'), new Date('2023-01-01')); // true

deepEqual(/abc/i, /abc/i); // true
deepEqual(/abc/i, /abc/g); // false

Circular references

Safely handles circular and deeply nested structures.

const a: any = {};
a.self = a;

const b: any = {};
b.self = b;

deepEqual(a, b); // true

Symbol keys

Symbol properties are compared by default and can be ignored via symbol.toString().

const sym = Symbol('id');

deepEqual({ [sym]: 1 }, { [sym]: 1 }); // true

deepEqual({ [sym]: 1 }, { [sym]: 2 }, { ignoreKeys: [sym.toString()] }); // true

📚 Documentation

For all configuration options, please see the API docs.

🚀 Performance

Library	Equal Objects (ops/sec)	Unequal Objects (ops/sec)	Circular References (Equal) (ops/sec)	Circular References (Unequal) (ops/sec)	Simple Circular References (Equal) (ops/sec)
@se-oss/deep-equal	2,527,249	895,175	3,667,331	6,392,142	3,954,003
deep-equal	8,658	1,842	5,961	8,389	6,017
lodash.isEqual	1,555,288	344,628	1,264,089	1,999,934	1,322,176

Benchmark script: bench/index.bench.ts

🤝 Contributing

Want to contribute? Awesome! To show your support is to star the project, or to raise issues on GitHub.

Thanks again for your support, it is much appreciated! 🙏

License

MIT © Shahrad Elahi and contributors.