@longlast/equals 0.4.3 → 0.5.0

package/README.md

@@ -27,3 +27,9 @@ equals(
     [3, 4, {openThe: "door"}],
 ); // => false
 ```
+
+## Documentation
+
+[Browse the docs on longlast.js.org][docs].
+
+[docs]: https://longlast.js.org/equals/

package/dist/index.d.ts

@@ -18,15 +18,46 @@ import { type Curried2 } from "@longlast/curry";
  *     elements are equal (according to `equals`).
  *   - Sets are equal iff they contain the same elements. Note that set
  *     elements are _not_ deeply compared.
+ *   - Partially applied curried functions are equal iff they originate from
+ *     the same curried function and their bound arguments are equal
+ *     according to `equals`. See {@link curry}.
  *   - Other objects are equal iff they have the same prototype (e.g. the same
  *     class) and the same set of enumerable string-keyed properties, and the
  *     values of their corresponding properties are equal (according to
  *     `equals`).
  *
+ * You can customize how `equals()` compares values of a specific class by
+ * using the {@link symbols.$equals $equals} symbol to define a method on that class. For
+ * example:
+ *
+ * ```ts
+ * import {$equals} from "@longlast/symbols"
+ *
+ * class HttpError extends Error {
+ *     private statusCode: number;
+ *     constructor(message: string, statusCode: number) {
+ *         super(message);
+ *         this.statusCode = statusCode;
+ *     }
+ *
+ *     [$equals](other: unknown) {
+ *         return other instanceof HttpError &&
+ *             other.statusCode === this.statusCode &&
+ *             other.message === this.message;
+ *     }
+ * }
+ * ```
+ *
+ * Note that this makes the comparison asymmetrical: `a` is considered equal to
+ * `b` iff `a[$equals](b)` returns truthy. The `$equals` method will always be
+ * called on the *first* argument to `equals()`.
+ *
+ * `equals()` is curried. See {@link curry}.
+ *
+ * ## Limitations
+ *
  * `equals()` can throw a `RangeError` if one of its arguments contains a
  * reference cycle. Avoid passing mutable objects to `equals()` unless you know
  * that they do not contain cycles.
- *
- * `equals()` is curried.
  */
 export declare const equals: Curried2<unknown, unknown, boolean>;

package/dist/index.js

@@ -2,6 +2,7 @@
  * @module equals
  */
 import { curry } from "@longlast/curry";
+import { $boundArguments, $equals, $unapplied } from "@longlast/symbols";
 /**
  * @function
  * Deeply compares two values, returning true if they're equal and false
@@ -18,16 +19,47 @@ import { curry } from "@longlast/curry";
  *     elements are equal (according to `equals`).
  *   - Sets are equal iff they contain the same elements. Note that set
  *     elements are _not_ deeply compared.
+ *   - Partially applied curried functions are equal iff they originate from
+ *     the same curried function and their bound arguments are equal
+ *     according to `equals`. See {@link curry}.
  *   - Other objects are equal iff they have the same prototype (e.g. the same
  *     class) and the same set of enumerable string-keyed properties, and the
  *     values of their corresponding properties are equal (according to
  *     `equals`).
  *
+ * You can customize how `equals()` compares values of a specific class by
+ * using the {@link symbols.$equals $equals} symbol to define a method on that class. For
+ * example:
+ *
+ * ```ts
+ * import {$equals} from "@longlast/symbols"
+ *
+ * class HttpError extends Error {
+ *     private statusCode: number;
+ *     constructor(message: string, statusCode: number) {
+ *         super(message);
+ *         this.statusCode = statusCode;
+ *     }
+ *
+ *     [$equals](other: unknown) {
+ *         return other instanceof HttpError &&
+ *             other.statusCode === this.statusCode &&
+ *             other.message === this.message;
+ *     }
+ * }
+ * ```
+ *
+ * Note that this makes the comparison asymmetrical: `a` is considered equal to
+ * `b` iff `a[$equals](b)` returns truthy. The `$equals` method will always be
+ * called on the *first* argument to `equals()`.
+ *
+ * `equals()` is curried. See {@link curry}.
+ *
+ * ## Limitations
+ *
  * `equals()` can throw a `RangeError` if one of its arguments contains a
  * reference cycle. Avoid passing mutable objects to `equals()` unless you know
  * that they do not contain cycles.
- *
- * `equals()` is curried.
  */
 export const equals = curry(_equals);
 function _equals(a, b) {
@@ -36,6 +68,9 @@ function _equals(a, b) {
     if (Object.is(a, b)) {
         return true;
     }
+    if (a != null && typeof a[$equals] === "function") {
+        return Boolean(a[$equals](b));
+    }
     if (a instanceof Date && b instanceof Date) {
         return Object.is(+a, +b);
     }
@@ -46,11 +81,20 @@ function _equals(a, b) {
         return (a.message === b.message &&
             Object.getPrototypeOf(a) === Object.getPrototypeOf(b));
     }
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((_, i) => _equals(a[i], b[i]));
+    }
     if (a instanceof Set && b instanceof Set) {
         return a.size === b.size && [...a].every((v) => b.has(v));
     }
-    if (Array.isArray(a) && Array.isArray(b)) {
-        return a.length === b.length && a.every((_, i) => equals(a[i], b[i]));
+    if (typeof a === "function" && typeof b === "function") {
+        const aArgs = a[$boundArguments];
+        const bArgs = b[$boundArguments];
+        const aUnapplied = a[$unapplied];
+        const bUnapplied = b[$unapplied];
+        return (aUnapplied != null &&
+            aUnapplied === bUnapplied &&
+            _equals(aArgs, bArgs));
     }
     if (a && b && typeof a === "object" && protoOf(a) === protoOf(b)) {
         const bKeys = new Set(Object.keys(b));
@@ -58,7 +102,7 @@ function _equals(a, b) {
             if (!bKeys.has(key)) {
                 return false;
             }
-            if (!equals(a[key], b[key])) {
+            if (!_equals(a[key], b[key])) {
                 return false;
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longlast/equals",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Deeply compares objects",
   "license": "MIT",
   "author": "Ben Christel (https://benchristel.com/)",
@@ -16,6 +16,7 @@
     "#@longlast/equals": "./src/index.ts"
   },
   "dependencies": {
-    "@longlast/curry": "^0.2.1"
+    "@longlast/curry": "^0.4.0",
+    "@longlast/symbols": "^1.0.0"
   }
 }