@art-suite/art-core-ts-compare 0.0.1

package/README.md

@@ -0,0 +1,206 @@
+# @art-suite/art-core-ts-compare
+
+Deep equality, inequality, less-than and greater-than comparison - complete with custom object support.
+
+## Quick Start - Equality Functions
+
+The easiest way to use this library is with the standard equality functions:
+
+```ts
+import { eq, neq, lt, gt, lte, gte } from "@art-suite/art-core-ts-compare";
+
+// Basic equality
+eq(5, 5); // true
+eq([1, 2], [1, 2]); // true
+eq({ a: 1 }, { a: 1 }); // true
+eq(null, null); // true
+
+// Inequality
+neq(5, 10); // true
+neq([1, 2], [1, 3]); // true
+neq({ a: 1 }, { a: 2 }); // true
+
+// Less than / Greater than
+lt(5, 10); // true
+lt("a", "z"); // true
+lt([1, 2], [1, 2, 3]); // true
+lt({ a: 1 }, { a: 1, b: 2 }); // true (missing key)
+
+gt(10, 5); // true
+gt("z", "a"); // true
+gt([1, 2, 3], [1, 2]); // true
+
+// Less than or equal / Greater than or equal
+lte(5, 5); // true
+lte(5, 10); // true
+gte(10, 10); // true
+gte(10, 5); // true
+
+// Custom objects with comparison methods
+class Box {
+  constructor(public value: number) {}
+  compare(other: any) {
+    if (!(other instanceof Box)) return -1;
+    return this.value - other.value;
+  }
+}
+
+eq(new Box(5), new Box(5)); // true
+lt(new Box(2), new Box(5)); // true
+```
+
+## Power User - Deep Compare Function
+
+For advanced use cases, the `compare` function provides fine-grained control:
+
+## Deep Compare Specification
+
+This function performs a **deep comparison** between two JavaScript values and returns:
+
+- A **negative number** if the left value is less than the right.
+- A **positive number** if the left value is greater than the right.
+- `0` if the values are considered equal.
+- `NaN` if the values are not comparable (different types or incompatible comparisons).
+
+### Scope
+
+Primarily designed for comparing **JSON-style values**:
+
+- `null`, booleans, numbers, strings
+- Arrays
+- Plain objects
+
+It also supports **custom objects** that implement comparison interfaces.
+
+### Custom Comparison Methods
+
+If the **left operand** defines one of the following methods, it will be used in this priority order:
+
+1. **`.compare(right: unknown): number`** (highest priority)
+   Must return a negative number, zero, or a positive number. Used for sorting.
+
+2. **`.lt(right: unknown): boolean` and `.gt(right: unknown): boolean`**
+   Used only if `.compare` is not present. Returns `-1` if `a.lt(b)` is true, `1` if `a.gt(b)` is true, or `0` if neither is true.
+
+3. **`.eq(right: unknown): boolean`** (lowest priority)
+   Used only if `.compare` and inequality methods are not present. If `true`, returns `0`. If `false`, falls back to type-based comparison.
+
+These methods may throw. The caller is responsible for handling errors.
+
+### Comparison Rules
+
+#### Primitive Types
+
+- **Numbers**: Compared via subtraction (`a - b`) for efficiency.
+- **Strings**: Compared via `String.prototype.localeCompare()` for proper locale-aware comparison.
+- **Booleans**: Converted to numbers (`Number(a) - Number(b)`) for comparison.
+- **`null`** is treated as less than any non-`null` value.
+- **`undefined`** is treated as greater than `null` but less than any number or string.
+- **`NaN`** is not equal to anything, including itself.
+
+#### Arrays
+
+Compared element by element:
+
+- Compare each index recursively.
+- First non-zero result is returned.
+- If all elements are equal, shorter arrays sort first.
+
+#### Plain Objects
+
+- Keys are merged from both objects and sorted lexicographically.
+- For each key in sorted order:
+  - If a key is **missing in one object and present in the other**, the object missing the key is always considered less (comes first), regardless of the present value or key order.
+  - If both objects have the key, their values are compared recursively.
+- If all keys and values are equal, objects are equal.
+
+**Examples:**
+
+- `{a: 1}` vs `{a: 1, b: 2}` → first is less (missing `b`)
+- `{a: 1, b: 0}` vs `{a: 1}` → second is less (missing `b`)
+- `{}` vs `{a: undefined}` → first is less (missing `a`)
+- `{a: null}` vs `{}` → second is less (missing `a`)
+- `{x: 1}` vs `{y: 1}` → `{y: 1}` is less (missing `x`), so `compare({x: 1}, {y: 1})` returns `1`, `compare({y: 1}, {x: 1})` returns `-1`
+
+#### Incompatible Comparisons
+
+The function returns `NaN` when:
+
+- **Different types**: Comparing values of different primitive types (e.g., number vs string, boolean vs number)
+- **Incompatible objects**: Objects that are not `==` and don't implement custom comparison methods
+- **Unsupported types**: Functions, symbols, classes, or other non-JSON-like values
+
+**Note**: Arrays and plain objects are always comparable (element-by-element and key-by-key respectively), even if they contain incompatible values internally.
+
+### Error Handling
+
+This function **may throw** if:
+
+- Custom `.compare` or `.eq` methods throw.
+- Incompatible or uncoercible types are compared.
+
+Consumers (e.g., equality wrappers) are expected to catch errors and treat them as inequality or failure to compare.
+
+### TypeScript Usage Examples
+
+```ts
+deepCompare(5, 10); // -5 (using subtraction)
+deepCompare("z", "a"); // 1 (using localeCompare)
+deepCompare(null, 0); // -1
+deepCompare([1, 2], [1, 2, 3]); // -1
+deepCompare({ a: 1 }, { a: 1 }); // 0
+deepCompare({ a: 1 }, { a: 2 }); // -1
+
+deepCompare({ a: 1 }, { a: 1, b: 2 }); // -1 (missing b)
+deepCompare({ a: 1, b: 0 }, { a: 1 }); // 1 (other is missing b)
+deepCompare({}, { a: undefined }); // -1 (missing a)
+deepCompare({ a: null }, {}); // 1 (other is missing a)
+deepCompare({ x: 1 }, { y: 1 }); // 1 ({y: 1} is missing x)
+deepCompare({ y: 1 }, { x: 1 }); // -1 ({y: 1} is missing x)
+
+// Incompatible comparisons return NaN
+deepCompare(5, "hello"); // NaN
+deepCompare(true, 42); // NaN
+deepCompare(() => {}, {}); // NaN
+
+class Box {
+  constructor(public value: number) {}
+  compare(other: any) {
+    if (!(other instanceof Box)) return -1;
+    return this.value - other.value;
+  }
+}
+
+deepCompare(new Box(2), new Box(5)); // -3
+
+class Tag {
+  constructor(public name: string) {}
+  eq(other: any) {
+    return other instanceof Tag && other.name === this.name;
+  }
+}
+
+deepCompare(new Tag("a"), new Tag("a")); // 0
+deepCompare(new Tag("a"), new Tag("b")); // fallback result (non-zero)
+
+class Range {
+  constructor(public start: number, public end: number) {}
+  lt(other: any): boolean {
+    return other instanceof Range && this.end < other.start;
+  }
+  gt(other: any): boolean {
+    return other instanceof Range && this.start > other.end;
+  }
+}
+
+deepCompare(new Range(1, 3), new Range(4, 6)); // -1 (1-3 < 4-6)
+deepCompare(new Range(4, 6), new Range(1, 3)); // 1 (4-6 > 1-3)
+deepCompare(new Range(1, 3), new Range(2, 4)); // 0 (overlapping ranges)
+```
+
+### Guarantees
+
+- Returns a stable comparison result for all JSON-like structures.
+- Respects `.compare()` and `.eq()` if defined on the **left operand**.
+- Returns `NaN` for incompatible type comparisons.
+- Never swallows internal errors — follows `localeCompare`-style strictness.

package/dist/index.cjs

@@ -0,0 +1,122 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  compare: () => compare,
+  eq: () => eq,
+  gt: () => gt,
+  gte: () => gte,
+  lt: () => lt,
+  lte: () => lte,
+  neq: () => neq
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/compare.ts
+var import_art_core_ts_types = require("@art-suite/art-core-ts-types");
+var compareArrays = (a, b) => {
+  const minLength = Math.min(a.length, b.length);
+  for (let i = 0; i < minLength; i++) {
+    const result = compare(a[i], b[i]);
+    if (result !== 0) return result;
+  }
+  return a.length - b.length;
+};
+var comparePlainObjects = (a, b) => {
+  const allKeys = [.../* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)])].sort();
+  for (const key of allKeys) {
+    const aHas = key in a;
+    const bHas = key in b;
+    if (!aHas && bHas) return -1;
+    if (aHas && !bHas) return 1;
+    const result = compare(a[key], b[key]);
+    if (result !== 0) return result;
+  }
+  return 0;
+};
+var compareCustomComparableHelper = (a, b) => {
+  if (a !== null && a !== void 0 && typeof a === "object") {
+    if ((0, import_art_core_ts_types.isFunction)(a.compare)) return a.compare(b);
+    if ((0, import_art_core_ts_types.isFunction)(a.eq) && a?.eq(b)) return 0;
+    if ((0, import_art_core_ts_types.isFunction)(a.lt) && a?.lt(b)) return -1;
+    if ((0, import_art_core_ts_types.isFunction)(a.gt) && a?.gt(b)) return 1;
+    if ((0, import_art_core_ts_types.isFunction)(a.lte) && a?.lte(b)) return -1;
+    if ((0, import_art_core_ts_types.isFunction)(a.gte) && a?.gte(b)) return 1;
+  }
+  return NaN;
+};
+var compareCustomComparable = (a, b) => {
+  const customResult = compareCustomComparableHelper(a, b);
+  if (!Number.isNaN(customResult)) return customResult;
+  return -compareCustomComparableHelper(b, a);
+};
+var comparePrimitives = (a, b) => {
+  if (a === null && b === null) return 0;
+  if (a === null) return -1;
+  if (b === null) return 1;
+  if (a === void 0 && b === void 0) return 0;
+  if (a === void 0) return 1;
+  if (b === void 0) return -1;
+  if (Number.isNaN(a) && Number.isNaN(b)) return 0;
+  if (Number.isNaN(a)) return -1;
+  if (Number.isNaN(b)) return 1;
+  if (typeof a === "number" && typeof b === "number") {
+    return a - b;
+  }
+  if (typeof a === "string" && typeof b === "string") {
+    return a.localeCompare(b);
+  }
+  if (typeof a === "boolean" && typeof b === "boolean") {
+    return Number(a) - Number(b);
+  }
+  if (typeof a !== typeof b) return NaN;
+  return NaN;
+};
+var compare = (a, b) => {
+  const customResult = compareCustomComparable(a, b);
+  if (!Number.isNaN(customResult)) return customResult;
+  if ((0, import_art_core_ts_types.isArray)(a) && (0, import_art_core_ts_types.isArray)(b)) {
+    return compareArrays(a, b);
+  }
+  if ((0, import_art_core_ts_types.isPlainObject)(a) && (0, import_art_core_ts_types.isPlainObject)(b)) {
+    return comparePlainObjects(a, b);
+  }
+  return comparePrimitives(a, b);
+};
+
+// src/equality.ts
+var eq = (a, b) => compare(a, b) === 0;
+var neq = (a, b) => compare(a, b) !== 0;
+var lt = (a, b) => compare(a, b) < 0;
+var gt = (a, b) => compare(a, b) > 0;
+var lte = (a, b) => compare(a, b) <= 0;
+var gte = (a, b) => compare(a, b) >= 0;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  compare,
+  eq,
+  gt,
+  gte,
+  lt,
+  lte,
+  neq
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/compare.ts","../src/equality.ts"],"sourcesContent":["export * from './compare'\nexport * from './equality'","import { isArray, isPlainObject, isFunction } from '@art-suite/art-core-ts-types'\n\nexport interface CustomComparableInterface {\n\n  /**\n   * Compares `this` with `b`\n   * @param b - The value to compare `this` with\n   * @returns A number greater than zero if `this` is greater than `b`, less than zero if `this` is less than `b`, and zero if `this` is equal to `b`\n   */\n  compare(b: any): number\n}\n\nexport interface CustomEqualityInterface {\n  /**\n   * Checks if `this` equals `b`\n   * @param b - The value to compare `this` with\n   * @returns true if equal, false otherwise\n   */\n  eq(b: any): boolean\n}\n\nexport interface CustomInequalityInterface extends CustomEqualityInterface {\n  /**\n   * Checks if `this` is not equal to `b`\n   * @param b - The value to compare `this` with\n   * @returns true if not equal, false otherwise\n   */\n  lt(b: any): boolean\n  gt(b: any): boolean\n  lte(b: any): boolean\n  gte(b: any): boolean\n}\n\nconst compareArrays = (a: any[], b: any[]): number => {\n  const minLength = Math.min(a.length, b.length)\n\n  for (let i = 0; i < minLength; i++) {\n    const result = compare(a[i], b[i])\n    if (result !== 0) return result\n  }\n\n  return a.length - b.length\n}\n\nconst comparePlainObjects = (a: Record<string, any>, b: Record<string, any>): number => {\n  // Create a merged list of all unique keys and sort it\n  const allKeys = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort()\n\n  // Iterate through the sorted keys to find the first non-zero comparison result\n  for (const key of allKeys) {\n    const aHas = key in a\n    const bHas = key in b\n    if (!aHas && bHas) return -1 // a is missing the key, so a is less\n    if (aHas && !bHas) return 1  // b is missing the key, so b is less\n    // Both have the key, compare their values\n    const result = compare(a[key], b[key])\n    if (result !== 0) return result\n  }\n\n  return 0 // All keys and values are equal\n}\n\nconst compareCustomComparableHelper = (a: any, b: any): number => {\n  // Only check for custom methods if a is not null/undefined and is an object\n  if (a !== null && a !== undefined && typeof a === 'object') {\n    // Check if left operand supports any of the custom methods (highest priority)\n    if (isFunction(a.compare)) return a.compare(b);\n    if (isFunction(a.eq) && a?.eq(b)) return 0;\n    if (isFunction(a.lt) && a?.lt(b)) return -1;\n    if (isFunction(a.gt) && a?.gt(b)) return 1;\n    if (isFunction(a.lte) && a?.lte(b)) return -1;\n    if (isFunction(a.gte) && a?.gte(b)) return 1;\n  }\n  return NaN\n}\n\nconst compareCustomComparable = (a: any, b: any): number => {\n  const customResult = compareCustomComparableHelper(a, b)\n  if (!Number.isNaN(customResult)) return customResult\n  return -compareCustomComparableHelper(b, a)\n}\n\nconst comparePrimitives = (a: any, b: any): number => {\n  // Handle null\n  if (a === null && b === null) return 0\n  if (a === null) return -1\n  if (b === null) return 1\n\n  // Handle undefined\n  if (a === undefined && b === undefined) return 0\n  if (a === undefined) return 1\n  if (b === undefined) return -1\n\n  // Handle NaN\n  if (Number.isNaN(a) && Number.isNaN(b)) return 0\n  if (Number.isNaN(a)) return -1\n  if (Number.isNaN(b)) return 1\n\n  // Handle numbers - use subtraction for efficiency\n  if (typeof a === 'number' && typeof b === 'number') {\n    return a - b\n  }\n\n  // Handle strings - use localeCompare for proper string comparison\n  if (typeof a === 'string' && typeof b === 'string') {\n    return a.localeCompare(b)\n  }\n\n  // Handle booleans - convert to numbers for comparison\n  if (typeof a === 'boolean' && typeof b === 'boolean') {\n    return Number(a) - Number(b)\n  }\n\n  // Return NaN for different types or incompatible comparisons\n  if (typeof a !== typeof b) return NaN\n\n  // For same types that aren't numbers, strings, or booleans, return NaN\n  return NaN\n}\n\nexport const compare = (a: any, b: any): number => {\n  // Handle custom comparables first\n  const customResult = compareCustomComparable(a, b)\n  if (!Number.isNaN(customResult)) return customResult\n\n  // Handle arrays\n  if (isArray(a) && isArray(b)) {\n    return compareArrays(a, b)\n  }\n\n  // Handle plain objects\n  if (isPlainObject(a) && isPlainObject(b)) {\n    return comparePlainObjects(a, b)\n  }\n\n  // Handle primitives\n  return comparePrimitives(a, b)\n}","import { compare } from './compare'\n\nexport const eq = (a: any, b: any): boolean => compare(a, b) === 0;\nexport const neq = (a: any, b: any): boolean => compare(a, b) !== 0;\nexport const lt = (a: any, b: any): boolean => compare(a, b) < 0;\nexport const gt = (a: any, b: any): boolean => compare(a, b) > 0;\nexport const lte = (a: any, b: any): boolean => compare(a, b) <= 0;\nexport const gte = (a: any, b: any): boolean => compare(a, b) >= 0;\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,37 @@
+interface CustomComparableInterface {
+    /**
+     * Compares `this` with `b`
+     * @param b - The value to compare `this` with
+     * @returns A number greater than zero if `this` is greater than `b`, less than zero if `this` is less than `b`, and zero if `this` is equal to `b`
+     */
+    compare(b: any): number;
+}
+interface CustomEqualityInterface {
+    /**
+     * Checks if `this` equals `b`
+     * @param b - The value to compare `this` with
+     * @returns true if equal, false otherwise
+     */
+    eq(b: any): boolean;
+}
+interface CustomInequalityInterface extends CustomEqualityInterface {
+    /**
+     * Checks if `this` is not equal to `b`
+     * @param b - The value to compare `this` with
+     * @returns true if not equal, false otherwise
+     */
+    lt(b: any): boolean;
+    gt(b: any): boolean;
+    lte(b: any): boolean;
+    gte(b: any): boolean;
+}
+declare const compare: (a: any, b: any) => number;
+
+declare const eq: (a: any, b: any) => boolean;
+declare const neq: (a: any, b: any) => boolean;
+declare const lt: (a: any, b: any) => boolean;
+declare const gt: (a: any, b: any) => boolean;
+declare const lte: (a: any, b: any) => boolean;
+declare const gte: (a: any, b: any) => boolean;
+
+export { type CustomComparableInterface, type CustomEqualityInterface, type CustomInequalityInterface, compare, eq, gt, gte, lt, lte, neq };

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+interface CustomComparableInterface {
+    /**
+     * Compares `this` with `b`
+     * @param b - The value to compare `this` with
+     * @returns A number greater than zero if `this` is greater than `b`, less than zero if `this` is less than `b`, and zero if `this` is equal to `b`
+     */
+    compare(b: any): number;
+}
+interface CustomEqualityInterface {
+    /**
+     * Checks if `this` equals `b`
+     * @param b - The value to compare `this` with
+     * @returns true if equal, false otherwise
+     */
+    eq(b: any): boolean;
+}
+interface CustomInequalityInterface extends CustomEqualityInterface {
+    /**
+     * Checks if `this` is not equal to `b`
+     * @param b - The value to compare `this` with
+     * @returns true if not equal, false otherwise
+     */
+    lt(b: any): boolean;
+    gt(b: any): boolean;
+    lte(b: any): boolean;
+    gte(b: any): boolean;
+}
+declare const compare: (a: any, b: any) => number;
+
+declare const eq: (a: any, b: any) => boolean;
+declare const neq: (a: any, b: any) => boolean;
+declare const lt: (a: any, b: any) => boolean;
+declare const gt: (a: any, b: any) => boolean;
+declare const lte: (a: any, b: any) => boolean;
+declare const gte: (a: any, b: any) => boolean;
+
+export { type CustomComparableInterface, type CustomEqualityInterface, type CustomInequalityInterface, compare, eq, gt, gte, lt, lte, neq };

package/dist/index.js

@@ -0,0 +1,89 @@
+// src/compare.ts
+import { isArray, isPlainObject, isFunction } from "@art-suite/art-core-ts-types";
+var compareArrays = (a, b) => {
+  const minLength = Math.min(a.length, b.length);
+  for (let i = 0; i < minLength; i++) {
+    const result = compare(a[i], b[i]);
+    if (result !== 0) return result;
+  }
+  return a.length - b.length;
+};
+var comparePlainObjects = (a, b) => {
+  const allKeys = [.../* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)])].sort();
+  for (const key of allKeys) {
+    const aHas = key in a;
+    const bHas = key in b;
+    if (!aHas && bHas) return -1;
+    if (aHas && !bHas) return 1;
+    const result = compare(a[key], b[key]);
+    if (result !== 0) return result;
+  }
+  return 0;
+};
+var compareCustomComparableHelper = (a, b) => {
+  if (a !== null && a !== void 0 && typeof a === "object") {
+    if (isFunction(a.compare)) return a.compare(b);
+    if (isFunction(a.eq) && a?.eq(b)) return 0;
+    if (isFunction(a.lt) && a?.lt(b)) return -1;
+    if (isFunction(a.gt) && a?.gt(b)) return 1;
+    if (isFunction(a.lte) && a?.lte(b)) return -1;
+    if (isFunction(a.gte) && a?.gte(b)) return 1;
+  }
+  return NaN;
+};
+var compareCustomComparable = (a, b) => {
+  const customResult = compareCustomComparableHelper(a, b);
+  if (!Number.isNaN(customResult)) return customResult;
+  return -compareCustomComparableHelper(b, a);
+};
+var comparePrimitives = (a, b) => {
+  if (a === null && b === null) return 0;
+  if (a === null) return -1;
+  if (b === null) return 1;
+  if (a === void 0 && b === void 0) return 0;
+  if (a === void 0) return 1;
+  if (b === void 0) return -1;
+  if (Number.isNaN(a) && Number.isNaN(b)) return 0;
+  if (Number.isNaN(a)) return -1;
+  if (Number.isNaN(b)) return 1;
+  if (typeof a === "number" && typeof b === "number") {
+    return a - b;
+  }
+  if (typeof a === "string" && typeof b === "string") {
+    return a.localeCompare(b);
+  }
+  if (typeof a === "boolean" && typeof b === "boolean") {
+    return Number(a) - Number(b);
+  }
+  if (typeof a !== typeof b) return NaN;
+  return NaN;
+};
+var compare = (a, b) => {
+  const customResult = compareCustomComparable(a, b);
+  if (!Number.isNaN(customResult)) return customResult;
+  if (isArray(a) && isArray(b)) {
+    return compareArrays(a, b);
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    return comparePlainObjects(a, b);
+  }
+  return comparePrimitives(a, b);
+};
+
+// src/equality.ts
+var eq = (a, b) => compare(a, b) === 0;
+var neq = (a, b) => compare(a, b) !== 0;
+var lt = (a, b) => compare(a, b) < 0;
+var gt = (a, b) => compare(a, b) > 0;
+var lte = (a, b) => compare(a, b) <= 0;
+var gte = (a, b) => compare(a, b) >= 0;
+export {
+  compare,
+  eq,
+  gt,
+  gte,
+  lt,
+  lte,
+  neq
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/compare.ts","../src/equality.ts"],"sourcesContent":["import { isArray, isPlainObject, isFunction } from '@art-suite/art-core-ts-types'\n\nexport interface CustomComparableInterface {\n\n  /**\n   * Compares `this` with `b`\n   * @param b - The value to compare `this` with\n   * @returns A number greater than zero if `this` is greater than `b`, less than zero if `this` is less than `b`, and zero if `this` is equal to `b`\n   */\n  compare(b: any): number\n}\n\nexport interface CustomEqualityInterface {\n  /**\n   * Checks if `this` equals `b`\n   * @param b - The value to compare `this` with\n   * @returns true if equal, false otherwise\n   */\n  eq(b: any): boolean\n}\n\nexport interface CustomInequalityInterface extends CustomEqualityInterface {\n  /**\n   * Checks if `this` is not equal to `b`\n   * @param b - The value to compare `this` with\n   * @returns true if not equal, false otherwise\n   */\n  lt(b: any): boolean\n  gt(b: any): boolean\n  lte(b: any): boolean\n  gte(b: any): boolean\n}\n\nconst compareArrays = (a: any[], b: any[]): number => {\n  const minLength = Math.min(a.length, b.length)\n\n  for (let i = 0; i < minLength; i++) {\n    const result = compare(a[i], b[i])\n    if (result !== 0) return result\n  }\n\n  return a.length - b.length\n}\n\nconst comparePlainObjects = (a: Record<string, any>, b: Record<string, any>): number => {\n  // Create a merged list of all unique keys and sort it\n  const allKeys = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort()\n\n  // Iterate through the sorted keys to find the first non-zero comparison result\n  for (const key of allKeys) {\n    const aHas = key in a\n    const bHas = key in b\n    if (!aHas && bHas) return -1 // a is missing the key, so a is less\n    if (aHas && !bHas) return 1  // b is missing the key, so b is less\n    // Both have the key, compare their values\n    const result = compare(a[key], b[key])\n    if (result !== 0) return result\n  }\n\n  return 0 // All keys and values are equal\n}\n\nconst compareCustomComparableHelper = (a: any, b: any): number => {\n  // Only check for custom methods if a is not null/undefined and is an object\n  if (a !== null && a !== undefined && typeof a === 'object') {\n    // Check if left operand supports any of the custom methods (highest priority)\n    if (isFunction(a.compare)) return a.compare(b);\n    if (isFunction(a.eq) && a?.eq(b)) return 0;\n    if (isFunction(a.lt) && a?.lt(b)) return -1;\n    if (isFunction(a.gt) && a?.gt(b)) return 1;\n    if (isFunction(a.lte) && a?.lte(b)) return -1;\n    if (isFunction(a.gte) && a?.gte(b)) return 1;\n  }\n  return NaN\n}\n\nconst compareCustomComparable = (a: any, b: any): number => {\n  const customResult = compareCustomComparableHelper(a, b)\n  if (!Number.isNaN(customResult)) return customResult\n  return -compareCustomComparableHelper(b, a)\n}\n\nconst comparePrimitives = (a: any, b: any): number => {\n  // Handle null\n  if (a === null && b === null) return 0\n  if (a === null) return -1\n  if (b === null) return 1\n\n  // Handle undefined\n  if (a === undefined && b === undefined) return 0\n  if (a === undefined) return 1\n  if (b === undefined) return -1\n\n  // Handle NaN\n  if (Number.isNaN(a) && Number.isNaN(b)) return 0\n  if (Number.isNaN(a)) return -1\n  if (Number.isNaN(b)) return 1\n\n  // Handle numbers - use subtraction for efficiency\n  if (typeof a === 'number' && typeof b === 'number') {\n    return a - b\n  }\n\n  // Handle strings - use localeCompare for proper string comparison\n  if (typeof a === 'string' && typeof b === 'string') {\n    return a.localeCompare(b)\n  }\n\n  // Handle booleans - convert to numbers for comparison\n  if (typeof a === 'boolean' && typeof b === 'boolean') {\n    return Number(a) - Number(b)\n  }\n\n  // Return NaN for different types or incompatible comparisons\n  if (typeof a !== typeof b) return NaN\n\n  // For same types that aren't numbers, strings, or booleans, return NaN\n  return NaN\n}\n\nexport const compare = (a: any, b: any): number => {\n  // Handle custom comparables first\n  const customResult = compareCustomComparable(a, b)\n  if (!Number.isNaN(customResult)) return customResult\n\n  // Handle arrays\n  if (isArray(a) && isArray(b)) {\n    return compareArrays(a, b)\n  }\n\n  // Handle plain objects\n  if (isPlainObject(a) && isPlainObject(b)) {\n    return comparePlainObjects(a, b)\n  }\n\n  // Handle primitives\n  return comparePrimitives(a, b)\n}","import { compare } from './compare'\n\nexport const eq = (a: any, b: any): boolean => compare(a, b) === 0;\nexport const neq = (a: any, b: any): boolean => compare(a, b) !== 0;\nexport const lt = (a: any, b: any): boolean => compare(a, b) < 0;\nexport const gt = (a: any, b: any): boolean => compare(a, b) > 0;\nexport const lte = (a: any, b: any): boolean => compare(a, b) <= 0;\nexport const gte = (a: any, b: any): boolean => compare(a, b) >= 0;\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@art-suite/art-core-ts-compare",
+  "version": "0.0.1",
+  "description": "A TypeScript comparison utility library",
+  "keywords": [],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/art-suite/art-suite-ts"
+  },
+  "license": "MIT",
+  "author": "Shane Delamore",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prebuild": "npm run clean",
+    "build": "npx sort-package-json;tsup src/index.ts --format esm,cjs --dts --sourcemap",
+    "build:clean": "npm run clean && npm run build",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@art-suite/art-core-ts-types": "^0.3.2"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^3.1.4"
+  }
+}