@thi.ng/equiv

What is @thi.ng/equiv?

@thi.ng/equiv is a lightweight JavaScript library for deep equality checks. It provides a robust and efficient way to compare complex data structures, including arrays, objects, sets, maps, and more. The library is designed to handle circular references and custom equality checks, making it a versatile tool for various use cases.

What are @thi.ng/equiv's main functionalities?

Basic Equality Check

This feature allows you to perform basic equality checks between primitive values. The function returns true if the values are equal and false otherwise.

const equiv = require('@thi.ng/equiv');

console.log(equiv(1, 1)); // true
console.log(equiv(1, '1')); // false

Deep Equality Check for Arrays

This feature allows you to perform deep equality checks on arrays. It compares the elements of the arrays recursively to determine if they are equal.

const equiv = require('@thi.ng/equiv');

const arr1 = [1, 2, 3];
const arr2 = [1, 2, 3];
const arr3 = [1, 2, 4];

console.log(equiv(arr1, arr2)); // true
console.log(equiv(arr1, arr3)); // false

Deep Equality Check for Objects

This feature allows you to perform deep equality checks on objects. It compares the properties of the objects recursively to determine if they are equal.

const equiv = require('@thi.ng/equiv');

const obj1 = { a: 1, b: { c: 2 } };
const obj2 = { a: 1, b: { c: 2 } };
const obj3 = { a: 1, b: { c: 3 } };

console.log(equiv(obj1, obj2)); // true
console.log(equiv(obj1, obj3)); // false

Handling Circular References

This feature allows you to handle circular references in objects. The library can detect and correctly compare objects with circular references.

const equiv = require('@thi.ng/equiv');

const a = {};
const b = {};
a.self = a;
b.self = b;

console.log(equiv(a, b)); // true

Custom Equality Checks

This feature allows you to define custom equality checks for your own classes or data structures. By implementing the [Symbol.for('equiv')] method, you can control how instances of your class are compared.

const equiv = require('@thi.ng/equiv');

class Custom {
  constructor(value) {
    this.value = value;
  }

  [Symbol.for('equiv')](other) {
    return other instanceof Custom && this.value === other.value;
  }
}

const obj1 = new Custom(1);
const obj2 = new Custom(1);
const obj3 = new Custom(2);

console.log(equiv(obj1, obj2)); // true
console.log(equiv(obj1, obj3)); // false

Other packages similar to @thi.ng/equiv

lodash.isequal

Lodash's `isEqual` function provides deep equality checks for JavaScript objects. It is part of the larger Lodash utility library, which offers a wide range of functions for manipulating and inspecting data. Compared to @thi.ng/equiv, lodash.isequal is more widely used and comes with the extensive support and documentation of the Lodash library.

fast-deep-equal

fast-deep-equal is a small and fast library for deep equality checks. It is optimized for performance and has a very small footprint. While it offers similar functionality to @thi.ng/equiv, it may not handle as many edge cases or provide as much flexibility for custom equality checks.

deep-equal

deep-equal is another library for deep equality checks. It is simple to use and provides a straightforward API for comparing complex data structures. Compared to @thi.ng/equiv, deep-equal is more focused on simplicity and ease of use, but may not offer the same level of customization or performance.

README

[!IMPORTANT] ‼️ Announcing the thi.ng user survey 2024 📋

Please participate in the survey here!
(open until end of February)

To achieve a better sample size, I'd highly appreciate if you could circulate the link to this survey in your own networks.

Discussion

[!NOTE] This is one of 189 standalone projects, maintained as part of the @thi.ng/umbrella monorepo and anti-framework.

🚀 Help me to work full-time on these projects by sponsoring me on GitHub. Thank you! ❤️

• About
• Status
• Installation
• Dependencies
• API
  • Implement IEquiv interface
• Authors
• License

About

Extensible deep value equivalence checking for any data types.

Supports:

• JS primitives
• Arrays
• Plain objects
• ES6 Sets / Maps
• Date
• RegExp
• Types with IEquiv implementation

Status

STABLE - used in production

Search or submit any issues for this package

Installation

yarn add @thi.ng/equiv

ES module import:

<script type="module" src="https://cdn.skypack.dev/@thi.ng/equiv"></script>

Skypack documentation

For Node.js REPL:

const equiv = await import("@thi.ng/equiv");

Package sizes (brotli'd, pre-treeshake): ESM: 436 bytes

Dependencies

None

API

Generated API docs

import { equiv } from "@thi.ng/equiv";

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

Implement IEquiv interface

This is useful & required for custom types to take part in equiv checks, by default only plain objects & array are traversed deeply.

Furthermore, by implementing this interface we can better control which internal values / criteria are required to establish equivalence. In this example we exclude the meta property and only check for same type & children equality.

import { IEquiv } from "@thi.ng/api";
import { equiv } from "@thi.ng/equiv";

class Node implements IEquiv {

    meta: any;
    children: any[];

    constructor(children: any[], meta?: any) {
        this.children = children;
        this.meta = meta;
    }

    equiv(o: any) {
        return o instanceof Node && equiv(this.children, o.children);
    }
}

equiv(new Node([1,2,3], "foo"), new Node([1,2,3], "bar"));
// true

Authors

• Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-equiv,
  title = "@thi.ng/equiv",
  author = "Karsten Schmidt",
  note = "https://thi.ng/equiv",
  year = 2016
}

License

© 2016 - 2024 Karsten Schmidt // Apache License 2.0