Simple Comparator

A powerful, flexible deep equality comparison production ready library for JavaScript and TypeScript, inspired by Jest's toEqual(). Works seamlessly in both Deno and Node.js environments.

🚀 Features

🔍 Deep Equality Comparison - Compare nested objects and arrays with ease
🎯 Selective Property Comparison - Include or ignore specific properties
🔄 Circular Reference Detection - Optional detection of circular references
🎨 Custom Equality Logic - Define your own comparison rules with the Comparable interface
🔋 Cross-Runtime Support - Works in both Deno and Node.js
💡 Type-Safe - Written in TypeScript with full type definitions
⚡ Performance Focused - Optional features like circular reference detection

📦 Installation

Node.js

npm install simple-comparator

Deno

Import directly from GitHub:

import {
    compare,
    same,
    different,
} from "https://raw.githubusercontent.com/dominikj111/simple-comparator/refs/tags/v1.2.1/index-deno.js";

Or from your local files:

import { compare, same, different } from "./index-deno.js";

🎮 Quick Start

import { compare, same, different } from "simple-comparator";

// Basic comparison
compare({ a: 1, b: 2 }, { a: 1, b: 2 }); // true

// Natural syntax
if (same(user1, user2)) {
    console.log("Users are equal");
}

if (different(oldState, newState)) {
    console.log("State has changed");
}

🛠️ Advanced Features

1. Selective Property Comparison

compare(
    { id: 1, name: "John", timestamp: Date.now() },
    { id: 2, name: "John", timestamp: Date.now() - 1000 },
    { topLevelIgnore: ["id", "timestamp"] },
); // true

2. Custom Equality Logic

class Point implements Comparable<Point> {
    constructor(
        public x: number,
        public y: number,
    ) {}

    equals(other: Point): boolean {
        return this.x === other.x && this.y === other.y;
    }
}

compare(new Point(1, 2), new Point(1, 2)); // true
compare(new Point(1, 2), { x: 1, y: 2 }); // true (falls back to property comparison)

3. Circular Reference Detection

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

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

compare(obj1, obj2, { detectCircular: true }); // true

4. Shallow Comparison

const obj1 = { nested: { value: 1 } };
const obj2 = { nested: { value: 1 } };

compare(obj1, obj2, { shallow: true }); // false (different object references)
compare(obj1, obj2); // true (deep comparison)

🔧 Configuration Options

Option	Type	Description
`topLevelInclude`	`string[] \| Set<string>`	Only compare these properties
`topLevelIgnore`	`string[] \| Set<string>`	Ignore these properties
`shallow`	`boolean`	Use reference equality for nested objects
`detectCircular`	`boolean`	Enable circular reference detection

🧪 Testing

The project includes comprehensive test suites for different JavaScript environments. When running npm test -s or yarn test:

ESLint checks are performed
Jest tests are run for both CommonJS and ES modules
Deno tests are executed if Deno is installed (skipped with a notification if Deno is not available)

This will execute:

Node.js tests using Jest
Deno tests using Deno's test runner with custom TypeScript configuration

📄 License

This library is licensed under the Apache License, Version 2.0. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

TODO List

Testing & CI

✅ Check/test other runtimes and environments
✅ Improve Continuous Integration (automatic build, linting and testing)
⬜ Add test cases for comparing objects with prototype chain

Performance

⬜ Add performance regression tests

⬜ Add performance benchmarks for different comparison scenarios
⬜ Document performance implications of different options

Distribution

⬜ Add bundling to import from CDN (vanilla js) -> umd, esm
⬜ Add Changelog
⬜ Publish to JSR (Deno Registry) for better Deno integration

Features & Improvements

✅ Optimize circular reference detection by making it optional
⬜ Add input validation for comparison options
⬜ Add option for partial array matching (e.g., array contains subset)
⬜ Add option for fuzzy string comparison
⬜ Support complex types (Regex, Map, Set, functions)

Future (v2)

⬜ Enhance circular reference detection with WeakMap to store metadata (depth, path, corresponding object)