fast-is-equal 1.0.0

package/README.md

@@ -0,0 +1,181 @@
+# fast-is-equal
+
+Blazing-fast equality checks, minus the baggage. A lean, standalone alternative to Lodash’s `isEqual`—because speed matters.
+
+## Installation
+
+Using yarn:
+
+```bash
+yarn add fast-is-equal
+```
+
+Using npm:
+
+```bash
+npm install fast-is-equal
+```
+
+## Usage
+```typescript
+import { fastIsEqual } from 'fast-is-equal';
+
+console.log(fastIsEqual(1, 1)); // true
+console.log(fastIsEqual({ a: 1 }, { a: 1 })); // true
+console.log(fastIsEqual([1, 2], [1, 3])); // false
+```
+
+## Features
+- Lightweight and dependency-free.
+- Handles primitives, objects, arrays, Maps, Sets, circular references, and more.
+- Optimized for performance (see benchmarks).
+
+## Benchmarks
+`fast-is-equal` outperforms Lodash’s `isEqual` in most cases. Run `npm run benchmark` locally to compare:
+```bash
+Performance Comparison: fastIsEqual vs Lodash isEqual
+Iterations per test case: 1000000
+----------------------------------------
+Test Case 1: Numbers
+  fastIsEqual: 0.000003 ms
+  Lodash isEqual: 0.000006 ms
+  Difference (fastIsEqual - Lodash): -0.000002 ms
+  fastIsEqual is 1.62x faster than Lodash
+----------------------------------------
+Test Case 2: Strings
+  fastIsEqual: 0.000005 ms
+  Lodash isEqual: 0.000005 ms
+  Difference (fastIsEqual - Lodash): -0.000000 ms
+  fastIsEqual is 1.08x faster than Lodash
+----------------------------------------
+Test Case 3: Booleans
+  fastIsEqual: 0.000005 ms
+  Lodash isEqual: 0.000005 ms
+  Difference (fastIsEqual - Lodash): -0.000000 ms
+  fastIsEqual is 1.06x faster than Lodash
+----------------------------------------
+Test Case 4: NaN
+  fastIsEqual: 0.000006 ms
+  Lodash isEqual: 0.000012 ms
+  Difference (fastIsEqual - Lodash): -0.000006 ms
+  fastIsEqual is 1.98x faster than Lodash
+----------------------------------------
+Test Case 5: Simple Object (equal)
+  fastIsEqual: 0.000097 ms
+  Lodash isEqual: 0.000271 ms
+  Difference (fastIsEqual - Lodash): -0.000174 ms
+  fastIsEqual is 2.80x faster than Lodash
+----------------------------------------
+Test Case 6: Simple Object (unequal)
+  fastIsEqual: 0.000105 ms
+  Lodash isEqual: 0.000271 ms
+  Difference (fastIsEqual - Lodash): -0.000165 ms
+  fastIsEqual is 2.57x faster than Lodash
+----------------------------------------
+Test Case 7: Nested Object (equal)
+  fastIsEqual: 0.000184 ms
+  Lodash isEqual: 0.000835 ms
+  Difference (fastIsEqual - Lodash): -0.000651 ms
+  fastIsEqual is 4.53x faster than Lodash
+----------------------------------------
+Test Case 8: Nested Object (unequal)
+  fastIsEqual: 0.000197 ms
+  Lodash isEqual: 0.000850 ms
+  Difference (fastIsEqual - Lodash): -0.000653 ms
+  fastIsEqual is 4.31x faster than Lodash
+----------------------------------------
+Test Case 9: Array of Primitives (equal)
+  fastIsEqual: 0.000017 ms
+  Lodash isEqual: 0.000102 ms
+  Difference (fastIsEqual - Lodash): -0.000085 ms
+  fastIsEqual is 5.95x faster than Lodash
+----------------------------------------
+Test Case 10: Array of Primitives (unequal)
+  fastIsEqual: 0.000015 ms
+  Lodash isEqual: 0.000103 ms
+  Difference (fastIsEqual - Lodash): -0.000088 ms
+  fastIsEqual is 6.79x faster than Lodash
+----------------------------------------
+Test Case 11: Array of Objects (equal)
+  fastIsEqual: 0.000078 ms
+  Lodash isEqual: 0.000638 ms
+  Difference (fastIsEqual - Lodash): -0.000560 ms
+  fastIsEqual is 8.15x faster than Lodash
+----------------------------------------
+Test Case 12: Circular Reference
+  fastIsEqual: 0.000095 ms
+  Lodash isEqual: 0.000493 ms
+  Difference (fastIsEqual - Lodash): -0.000399 ms
+  fastIsEqual is 5.22x faster than Lodash
+----------------------------------------
+Test Case 13: Map (equal)
+  fastIsEqual: 0.000074 ms
+  Lodash isEqual: 0.001383 ms
+  Difference (fastIsEqual - Lodash): -0.001309 ms
+  fastIsEqual is 18.67x faster than Lodash
+----------------------------------------
+Test Case 14: Map (unequal)
+  fastIsEqual: 0.000076 ms
+  Lodash isEqual: 0.001330 ms
+  Difference (fastIsEqual - Lodash): -0.001255 ms
+  fastIsEqual is 17.59x faster than Lodash
+----------------------------------------
+Test Case 15: Set (equal)
+  fastIsEqual: 0.000073 ms
+  Lodash isEqual: 0.000949 ms
+  Difference (fastIsEqual - Lodash): -0.000876 ms
+  fastIsEqual is 13.07x faster than Lodash
+----------------------------------------
+Test Case 16: Set (unequal)
+  fastIsEqual: 0.000070 ms
+  Lodash isEqual: 0.000930 ms
+  Difference (fastIsEqual - Lodash): -0.000860 ms
+  fastIsEqual is 13.22x faster than Lodash
+----------------------------------------
+Test Case 17: Empty Object vs Array
+  fastIsEqual: 0.000009 ms
+  Lodash isEqual: 0.000043 ms
+  Difference (fastIsEqual - Lodash): -0.000034 ms
+  fastIsEqual is 4.74x faster than Lodash
+----------------------------------------
+Test Case 18: Map vs Set
+  fastIsEqual: 0.000018 ms
+  Lodash isEqual: 0.000469 ms
+  Difference (fastIsEqual - Lodash): -0.000452 ms
+  fastIsEqual is 26.55x faster than Lodash
+----------------------------------------
+Average Performance:
+  fastIsEqual: 0.000063 ms
+  Lodash isEqual: 0.000483 ms
+  fastIsEqual is on average 7.71x faster than Lodash
+```
+
+## License
+MIT
+```
+
+#### 1.3 Add a License File
+Create a `LICENSE` file with the MIT license (or your preferred license):
+```plaintext
+MIT License
+
+Copyright (c) 2025 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/dist/__tests__/fastIsEqual.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/fastIsEqual.test.js

@@ -0,0 +1,180 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../index");
+describe('isEqual', () => {
+    // **Primitives**
+    it('should return true for identical primitives', () => {
+        expect((0, index_1.fastIsEqual)(1, 1)).toBe(true);
+        expect((0, index_1.fastIsEqual)('a', 'a')).toBe(true);
+        expect((0, index_1.fastIsEqual)(true, true)).toBe(true);
+    });
+    it('should return false for different primitives', () => {
+        expect((0, index_1.fastIsEqual)(1, 2)).toBe(false);
+        expect((0, index_1.fastIsEqual)('a', 'b')).toBe(false);
+        expect((0, index_1.fastIsEqual)(true, false)).toBe(false);
+    });
+    // **NaN**
+    it('should return true for NaN and NaN', () => {
+        expect((0, index_1.fastIsEqual)(NaN, NaN)).toBe(true);
+    });
+    // **Null and Undefined**
+    it('should return true for null and null', () => {
+        expect((0, index_1.fastIsEqual)(null, null)).toBe(true);
+    });
+    it('should return true for undefined and undefined', () => {
+        expect((0, index_1.fastIsEqual)(undefined, undefined)).toBe(true);
+    });
+    it('should return false for null and undefined', () => {
+        expect((0, index_1.fastIsEqual)(null, undefined)).toBe(false);
+    });
+    // **Objects**
+    it('should return true for identical objects', () => {
+        const obj = { a: 1, b: { c: 2 } };
+        expect((0, index_1.fastIsEqual)(obj, obj)).toBe(true);
+    });
+    it('should return true for deeply equal objects', () => {
+        const obj1 = { a: 1, b: { c: 2 } };
+        const obj2 = { a: 1, b: { c: 2 } };
+        expect((0, index_1.fastIsEqual)(obj1, obj2)).toBe(true);
+    });
+    it('should return false for objects with different keys', () => {
+        const obj1 = { a: 1 };
+        const obj2 = { b: 1 };
+        expect((0, index_1.fastIsEqual)(obj1, obj2)).toBe(false);
+    });
+    it('should return false for objects with different values', () => {
+        const obj1 = { a: 1 };
+        const obj2 = { a: 2 };
+        expect((0, index_1.fastIsEqual)(obj1, obj2)).toBe(false);
+    });
+    // **Arrays**
+    it('should return true for identical arrays', () => {
+        const arr = [1, 2, 3];
+        expect((0, index_1.fastIsEqual)(arr, arr)).toBe(true);
+    });
+    it('should return true for deeply equal arrays', () => {
+        const arr1 = [1, [2, 3]];
+        const arr2 = [1, [2, 3]];
+        expect((0, index_1.fastIsEqual)(arr1, arr2)).toBe(true);
+    });
+    it('should return false for arrays with different lengths', () => {
+        const arr1 = [1, 2];
+        const arr2 = [1, 2, 3];
+        expect((0, index_1.fastIsEqual)(arr1, arr2)).toBe(false);
+    });
+    it('should return false for arrays with different elements', () => {
+        const arr1 = [1, 2];
+        const arr2 = [1, 3];
+        expect((0, index_1.fastIsEqual)(arr1, arr2)).toBe(false);
+    });
+    // **Dates**
+    it('should return true for identical dates', () => {
+        const date = new Date();
+        expect((0, index_1.fastIsEqual)(date, date)).toBe(true);
+    });
+    it('should return true for dates with the same timestamp', () => {
+        const date1 = new Date('2023-01-01');
+        const date2 = new Date('2023-01-01');
+        expect((0, index_1.fastIsEqual)(date1, date2)).toBe(true);
+    });
+    it('should return false for dates with different timestamps', () => {
+        const date1 = new Date('2023-01-01');
+        const date2 = new Date('2023-01-02');
+        expect((0, index_1.fastIsEqual)(date1, date2)).toBe(false);
+    });
+    // **Regular Expressions**
+    it('should return true for identical regexes', () => {
+        const regex = /a/g;
+        expect((0, index_1.fastIsEqual)(regex, regex)).toBe(true);
+    });
+    it('should return true for regexes with the same pattern and flags', () => {
+        const regex1 = /a/g;
+        const regex2 = /a/g;
+        expect((0, index_1.fastIsEqual)(regex1, regex2)).toBe(true);
+    });
+    it('should return false for regexes with different patterns', () => {
+        const regex1 = /a/g;
+        const regex2 = /b/g;
+        expect((0, index_1.fastIsEqual)(regex1, regex2)).toBe(false);
+    });
+    it('should return false for regexes with different flags', () => {
+        const regex1 = /a/g;
+        const regex2 = /a/i;
+        expect((0, index_1.fastIsEqual)(regex1, regex2)).toBe(false);
+    });
+    // **Maps**
+    it('should return true for identical maps', () => {
+        const map = new Map([['a', 1]]);
+        expect((0, index_1.fastIsEqual)(map, map)).toBe(true);
+    });
+    it('should return true for maps with the same key-value pairs', () => {
+        const map1 = new Map([['a', 1]]);
+        const map2 = new Map([['a', 1]]);
+        expect((0, index_1.fastIsEqual)(map1, map2)).toBe(true);
+    });
+    it('should return false for maps with different key-value pairs', () => {
+        const map1 = new Map([['a', 1]]);
+        const map2 = new Map([['a', 2]]);
+        expect((0, index_1.fastIsEqual)(map1, map2)).toBe(false);
+    });
+    it('should return false for maps with different sizes', () => {
+        const map1 = new Map([['a', 1]]);
+        const map2 = new Map([['a', 1], ['b', 2]]);
+        expect((0, index_1.fastIsEqual)(map1, map2)).toBe(false);
+    });
+    // **Sets**
+    it('should return true for identical sets', () => {
+        const set = new Set([1, 2]);
+        expect((0, index_1.fastIsEqual)(set, set)).toBe(true);
+    });
+    it('should return true for sets with the same elements', () => {
+        const set1 = new Set([1, 2]);
+        const set2 = new Set([1, 2]);
+        expect((0, index_1.fastIsEqual)(set1, set2)).toBe(true);
+    });
+    it('should return false for sets with different elements', () => {
+        const set1 = new Set([1, 2]);
+        const set2 = new Set([1, 3]);
+        expect((0, index_1.fastIsEqual)(set1, set2)).toBe(false);
+    });
+    it('should return false for sets with different sizes', () => {
+        const set1 = new Set([1, 2]);
+        const set2 = new Set([1]);
+        expect((0, index_1.fastIsEqual)(set1, set2)).toBe(false);
+    });
+    // **Circular References**
+    it('should return true for circular references', () => {
+        const obj1 = {};
+        obj1.self = obj1;
+        const obj2 = {};
+        obj2.self = obj2;
+        expect((0, index_1.fastIsEqual)(obj1, obj2)).toBe(true);
+    });
+    it('should return false for different circular references', () => {
+        const obj1 = {};
+        obj1.self = obj1;
+        const obj2 = { self: {} };
+        expect((0, index_1.fastIsEqual)(obj1, obj2)).toBe(false);
+    });
+    // **Other Types (Functions, Promises)**
+    it('should return true for the same function reference', () => {
+        const func = () => { };
+        expect((0, index_1.fastIsEqual)(func, func)).toBe(true);
+    });
+    it('should return false for different functions', () => {
+        const func1 = () => { };
+        const func2 = () => { };
+        expect((0, index_1.fastIsEqual)(func1, func2)).toBe(false);
+    });
+    it('should return false for different promises', () => {
+        const p1 = Promise.resolve(1);
+        const p2 = Promise.resolve(1);
+        expect((0, index_1.fastIsEqual)(p1, p2)).toBe(false);
+    });
+    // **Mixed Types**
+    it('should return false for different types', () => {
+        expect((0, index_1.fastIsEqual)(1, '1')).toBe(false);
+        expect((0, index_1.fastIsEqual)({}, [])).toBe(false);
+        expect((0, index_1.fastIsEqual)(new Map(), new Set())).toBe(false);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1 @@
+export declare function fastIsEqual(a: any, b: any): boolean;

package/dist/index.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fastIsEqual = fastIsEqual;
+function fastIsEqual(a, b) {
+    // Fast path for strict equality
+    if (a === b)
+        return true;
+    // Handle NaN
+    if (Number.isNaN(a) && Number.isNaN(b))
+        return true;
+    // Early exit for null/undefined or type mismatch
+    if (a == null || b == null || typeof a !== typeof b)
+        return a === b;
+    // Check if both are arrays or both are not arrays
+    const aIsArray = Array.isArray(a);
+    const bIsArray = Array.isArray(b);
+    if (aIsArray !== bIsArray)
+        return false;
+    // Check if both are the same type of object (e.g., both Map, both Set, etc.)
+    if (a.constructor !== b.constructor)
+        return false;
+    // Fast path for arrays
+    if (aIsArray && bIsArray) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            const elemA = a[i];
+            const elemB = b[i];
+            if (elemA === elemB)
+                continue;
+            if (Number.isNaN(elemA) && Number.isNaN(elemB))
+                continue;
+            if (typeof elemA === 'object' || typeof elemB === 'object' ||
+                typeof elemA === 'function' || typeof elemB === 'function') {
+                return deepEqual(elemA, elemB, new Map());
+            }
+            if (elemA !== elemB)
+                return false;
+        }
+        return true;
+    }
+    // For other non-primitive types, use deepEqual with a visited Map
+    return deepEqual(a, b, new Map());
+}
+function deepEqual(valA, valB, visited) {
+    // Strict equality and NaN checks
+    if (valA === valB)
+        return true;
+    if (Number.isNaN(valA) && Number.isNaN(valB))
+        return true;
+    if (valA == null || valB == null)
+        return valA === valB;
+    if (typeof valA !== typeof valB)
+        return false;
+    // Handle Dates
+    if (valA instanceof Date && valB instanceof Date) {
+        return valA.getTime() === valB.getTime();
+    }
+    // Handle Regular Expressions
+    if (valA instanceof RegExp && valB instanceof RegExp) {
+        return valA.toString() === valB.toString();
+    }
+    // Handle Promises (reference equality)
+    if (valA instanceof Promise && valB instanceof Promise) {
+        return valA === valB;
+    }
+    // Handle Arrays
+    if (Array.isArray(valA) && Array.isArray(valB)) {
+        if (valA.length !== valB.length)
+            return false;
+        for (let i = 0; i < valA.length; i++) {
+            const elemA = valA[i];
+            const elemB = valB[i];
+            if (elemA === elemB)
+                continue;
+            if (Number.isNaN(elemA) && Number.isNaN(elemB))
+                continue;
+            if (typeof elemA === 'object' || typeof elemB === 'object' ||
+                typeof elemA === 'function' || typeof elemB === 'function') {
+                if (!deepEqual(elemA, elemB, visited))
+                    return false;
+            }
+            else if (elemA !== elemB) {
+                return false;
+            }
+        }
+        return true;
+    }
+    // Handle Maps
+    if (valA instanceof Map && valB instanceof Map) {
+        if (valA.size !== valB.size)
+            return false;
+        for (const [key, value] of valA) {
+            if (!valB.has(key) || !deepEqual(value, valB.get(key), visited))
+                return false;
+        }
+        return true;
+    }
+    // Handle Sets
+    if (valA instanceof Set && valB instanceof Set) {
+        if (valA.size !== valB.size)
+            return false;
+        for (const value of valA) {
+            if (!valB.has(value))
+                return false;
+        }
+        return true;
+    }
+    // Handle Objects with circular reference tracking
+    if (typeof valA === 'object' && typeof valB === 'object') {
+        if (visited.has(valA) && visited.get(valA) === valB)
+            return true;
+        visited.set(valA, valB);
+        const keysA = Object.keys(valA);
+        const keysB = Object.keys(valB);
+        if (keysA.length !== keysB.length)
+            return false;
+        for (const key of keysA) {
+            if (!Object.prototype.hasOwnProperty.call(valB, key) ||
+                !deepEqual(valA[key], valB[key], visited)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    // Default to strict equality
+    return valA === valB;
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "fast-is-equal",
+  "version": "1.0.0",
+  "description": "Blazing-fast equality checks, minus the baggage. A lean, standalone alternative to Lodash's isEqual—because speed matters.",
+  "keywords": [
+    "lodash",
+    "isEqual",
+    "typescript",
+    "react",
+    "react-native"
+  ],
+  "homepage": "https://github.com/JairajJangle/fast-is-equal#readme",
+  "bugs": {
+    "url": "https://github.com/JairajJangle/fast-is-equal/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JairajJangle/fast-is-equal.git"
+  },
+  "license": "MIT",
+  "author": "Jairaj Jangle <reachout.jairaj.jangle@gmail.com> (https://github.com/JairajJangle)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "test": "jest",
+    "build": "rimraf dist && tsc",
+    "prepublishOnly": "npm run build",
+    "benchmark": "ts-node benchmarks/fastIsEqual.benchmark.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/jest": "^29.5.3",
+    "@types/lodash": "^4.17.16",
+    "jest": "^29.7.0",
+    "lodash": "^4.17.21",
+    "rimraf": "^6.0.1",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.2",
+    "tslib": "^2.8.1",
+    "typescript": "^5.8.2"
+  }
+}