1.2.2 โ€ข Published 4 months ago

simple-comparator v1.2.2

Weekly downloads
-
License
BSD-3-Clause
Repository
github
Last release
4 months ago

Simple Comparator

npm dependencies Coverage Status License

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

๐Ÿš€ Why Choose Simple Comparator?

  • Zero Dependencies - No external dependencies means smaller bundle size and no security vulnerabilities from third-party packages
  • Efficient Implementation - Direct property comparison without using slow methods like JSON.stringify() or expensive hashing functions. For simple types, the performance is identical to using native comparison operators, making it safe to use everywhere in your code without performance overhead
  • Memory Efficient - No object cloning or temporary data structures required during comparison
  • Flexible Yet Simple - Powerful features without the complexity of libraries like deep-equal (which has 17+ dependencies)
  • Browser Compatible - Unlike some alternatives (e.g., deprecated lodash.isequal), works reliably in both Node.js and browser environments

๐Ÿ› ๏ธ 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.2/mod.js";

Or from your local files:

import { compare, same, different } from "./mod.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

OptionTypeDescription
topLevelIncludestring[] \| Set<string>Only compare these properties
topLevelIgnorestring[] \| Set<string>Ignore these properties
shallowbooleanUse reference equality for nested objects
detectCircularbooleanEnable 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

BSD-3-Clause ยฉ dominikj111

This library is licensed under the BSD 3-Clause License.

Roadmap

Version 2

  • โฌœ Prototype chain comparison (see the feature proposal)
  • โฌœ Comprehesice type support (see the feature proposal)
  • โฌœ Add performance benchmarks for different comparison scenarios
  • โฌœ Provide CDN-hosted bundles in both UMD and ESM formats for direct browser usage

Version 3

  • โฌœ Add performance regression tests
  • โฌœ Enhance circular reference detection with WeakMap to store metadata (depth, path, corresponding object)
  • โฌœ Implement object signature caching using WeakMap for optimizing repeated comparisons (see the feature proposal)

Version 4

  • โฌœ Publish to JSR (Deno Registry) for better Deno integration
  • โฌœ Add input validation for comparison options
  • โฌœ Add option for partial array matching (e.g., array contains subset)
  • โฌœ Add option for fuzzy string comparison