@longlast/equals 0.5.7 → 0.5.9

package/README.md

@@ -32,4 +32,4 @@ equals(
 
 [Browse the docs on longlast.js.org][docs].
 
-[docs]: https://longlast.js.org/equals/
+[docs]: https://longlast.js.org/reference/equals/

package/dist/index.d.ts

@@ -1,7 +1,39 @@
 /**
  * @module equals
  */
-import { type Curried2 } from "@longlast/curry";
+import { type Curried2, type Curried3 } from "@longlast/curry";
+export interface EqualsOptions {
+    /**
+     * Custom logic to use in preference to the default {@link equals}
+     * comparison.
+     */
+    readonly override?: undefined | ((a: unknown, b: unknown) => boolean | undefined);
+}
+/**
+ * @function
+ * A version of {@link equals} that allows callers to override the default
+ * comparison algorithm. If the provided override function returns a boolean,
+ * it is used as the result of the comparison. If the override returns
+ * `undefined`, the behavior of `equalsWith` defaults to that of
+ * {@link equals}.
+ *
+ * `equalsWith` is curried. See {@link curry}.
+ *
+ * @example
+ * ```ts
+ * // `mathEquals` treats -0 as equal to 0.
+ * const mathEquals = equalsWith({override: trueIfBothZero});
+ *
+ * function trueIfBothZero(a: unknown, b: unknown) {
+ *     if (a === 0 && b === 0) {
+ *         return true;
+ *     }
+ * }
+ *
+ * mathEquals({x: 0}, {x: -0}); // => true
+ * ```
+ */
+export declare const equalsWith: Curried3<EqualsOptions, unknown, unknown, boolean>;
 /**
  * @function
  * Deeply compares two values, returning true if they're equal and false
@@ -21,9 +53,9 @@ import { type Curried2 } from "@longlast/curry";
  *   - Maps are equal iff they have the same set of keys, and their
  *     corresponding values are deeply equal. Note that map keys 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}.
+ *   - Partially applied functions (via {@link curry} or {@link partial-apply})
+ *     are equal iff they originate from the same function and their bound
+ *     arguments are equal according to `equals`.
  *   - 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
@@ -34,7 +66,7 @@ import { type Curried2 } from "@longlast/curry";
  * class. For example:
  *
  * ```ts
- * import {$equals} from "@longlast/symbols"
+ * import {$equals} from "@longlast/symbols";
  *
  * class HttpError extends Error {
  *     private statusCode: number;

package/dist/index.js

@@ -3,74 +3,37 @@
  */
 import { curry } from "@longlast/curry";
 import { $boundArguments, $equals, $getBoundArguments, $unapplied, } from "@longlast/symbols";
-// TODO: export an `Equatable` interface that classes with the [$equals] method
-// can implement.
 /**
  * @function
- * Deeply compares two values, returning true if they're equal and false
- * otherwise. The following criteria are used to determine equality:
+ * A version of {@link equals} that allows callers to override the default
+ * comparison algorithm. If the provided override function returns a boolean,
+ * it is used as the result of the comparison. If the override returns
+ * `undefined`, the behavior of `equalsWith` defaults to that of
+ * {@link equals}.
  *
- *   - All values are equal to themselves.
- *   - Primitives `a` and `b` are equal iff `Object.is(a, b)`. This is similar
- *     to `===` comparison, but treats `NaN` as equal to `NaN` and `0` as
- *     different from `-0`.
- *   - Dates are equal iff they have the same millisecond-precision timestamp.
- *   - RegExps are equal iff they have the same pattern and flags.
- *   - Errors are equal iff they have the same class and message.
- *   - Arrays are equal iff they have the same length and their corresponding
- *     elements are equal (according to `equals`).
- *   - Sets are equal iff they contain the same elements. Note that set
- *     elements are _not_ deeply compared.
- *   - Maps are equal iff they have the same set of keys, and their
- *     corresponding values are deeply equal. Note that map keys 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:
+ * `equalsWith` is curried. See {@link curry}.
  *
+ * @example
  * ```ts
- * import {$equals} from "@longlast/symbols"
- *
- * class HttpError extends Error {
- *     private statusCode: number;
- *     constructor(message: string, statusCode: number) {
- *         super(message);
- *         this.statusCode = statusCode;
- *     }
+ * // `mathEquals` treats -0 as equal to 0.
+ * const mathEquals = equalsWith({override: trueIfBothZero});
  *
- *     [$equals](other: unknown) {
- *         return other instanceof HttpError &&
- *             other.statusCode === this.statusCode &&
- *             other.message === this.message;
+ * function trueIfBothZero(a: unknown, b: unknown) {
+ *     if (a === 0 && b === 0) {
+ *         return true;
  *     }
  * }
- * ```
  *
- * 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.
+ * mathEquals({x: 0}, {x: -0}); // => true
+ * ```
  */
-export const equals = curry(_equals);
-function _equals(a, b) {
-    // This is an optimized implementation. There is a simpler, equivalent one
-    // in pkg/equals/alt/reference.ts.
-    if (a == null) {
+export const equalsWith = curry(_equalsWith);
+function _equalsWith(options, a, b) {
+    const override = options.override?.(a, b);
+    if (override !== undefined) {
+        return override;
+    }
+    if (a == null || b == null) {
         return a === b;
     }
     // TODO: (pre-1.0.0) decide if we should pass `equals` as the second
@@ -88,7 +51,7 @@ function _equals(a, b) {
         const bUnapplied = b[$unapplied];
         return (aUnapplied != null &&
             aUnapplied === bUnapplied &&
-            _equals(getBoundArguments(a), getBoundArguments(b)));
+            _equalsWith(options, getBoundArguments(a), getBoundArguments(b)));
     }
     // If `a` is a primitive at this point, return false, since we already know
     // it is not identical to `b`.
@@ -116,7 +79,8 @@ function _equals(a, b) {
     }
     if (Array.isArray(a)) {
         unsafeNarrow(b);
-        return a.length === b.length && a.every((_, i) => _equals(a[i], b[i]));
+        return (a.length === b.length &&
+            a.every((_, i) => _equalsWith(options, a[i], b[i])));
     }
     if (setConstructorString === aConstructorString) {
         unsafeNarrow(a);
@@ -131,7 +95,7 @@ function _equals(a, b) {
             return false;
         }
         for (const key of a.keys()) {
-            if (!b.has(key) || !_equals(a.get(key), b.get(key))) {
+            if (!b.has(key) || !_equalsWith(options, a.get(key), b.get(key))) {
                 return false;
             }
         }
@@ -151,7 +115,7 @@ function _equals(a, b) {
             if (!bKeySet.has(key)) {
                 return false;
             }
-            if (!_equals(a[key], b[key])) {
+            if (!_equalsWith(options, a[key], b[key])) {
                 return false;
             }
         }
@@ -159,6 +123,69 @@ function _equals(a, b) {
     }
     return false;
 }
+/**
+ * @function
+ * Deeply compares two values, returning true if they're equal and false
+ * otherwise. The following criteria are used to determine equality:
+ *
+ *   - All values are equal to themselves.
+ *   - Primitives `a` and `b` are equal iff `Object.is(a, b)`. This is similar
+ *     to `===` comparison, but treats `NaN` as equal to `NaN` and `0` as
+ *     different from `-0`.
+ *   - Dates are equal iff they have the same millisecond-precision timestamp.
+ *   - RegExps are equal iff they have the same pattern and flags.
+ *   - Errors are equal iff they have the same class and message.
+ *   - Arrays are equal iff they have the same length and their corresponding
+ *     elements are equal (according to `equals`).
+ *   - Sets are equal iff they contain the same elements. Note that set
+ *     elements are _not_ deeply compared.
+ *   - Maps are equal iff they have the same set of keys, and their
+ *     corresponding values are deeply equal. Note that map keys are _not_
+ *     deeply compared.
+ *   - Partially applied functions (via {@link curry} or {@link partial-apply})
+ *     are equal iff they originate from the same function and their bound
+ *     arguments are equal according to `equals`.
+ *   - 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.
+ */
+// TODO: clear function provenance on `equals`.
+export const equals = equalsWith({});
 function getBoundArguments(f) {
     // TODO: (pre-1.0.0) remove `f[$boundArguments]` fallback.
     return f[$getBoundArguments]?.() ?? f[$boundArguments];
@@ -170,9 +197,6 @@ function functionString(f) {
     return Function.prototype.toString.call(f);
 }
 function constructorOf(value) {
-    if (value == null) {
-        return null;
-    }
     return protoOf(value)?.constructor;
 }
 function unsafeNarrow(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longlast/equals",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "Deeply compares objects",
   "homepage": "https://longlast.js.org/",
   "license": "MIT",