@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

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.