@helpers4/object 2.0.0-beta.0 → 2.0.0

package/lib/index.js

@@ -32,27 +32,109 @@ function deepClone(obj) {
 	return cloned;
 }
 //#endregion
-//#region helpers/array/shallowEquals.ts
+//#region helpers/type/isPlainObject.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Checks if a value is a plain object.
+*
+* A plain object is created by `{}`, `new Object()`, or `Object.create(null)`.
+* Returns `false` for arrays, Date, Map, Set, RegExp, class instances, etc.
+*
+* @param value - The value to check
+* @returns True if value is a plain object
+* @example
+* isPlainObject({})           // => true
+* isPlainObject({ a: 1 })    // => true
+* isPlainObject(new Date())  // => false
+* isPlainObject([])          // => false
+* isPlainObject(null)        // => false
+* @since 2.0.0
+*/
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object") return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+//#endregion
+//#region helpers/object/deepMerge.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+var UNSAFE_KEYS$1 = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+function deepMerge(target, ...sources) {
+	if (target === void 0 || target === null) return target;
+	if (!sources.length) return target;
+	const source = sources.shift();
+	if (!source) return deepMerge(target, ...sources);
+	for (const key in source) {
+		if (!Object.hasOwn(source, key) || UNSAFE_KEYS$1.has(key)) continue;
+		const targetValue = target[key];
+		const sourceValue = source[key];
+		if (isPlainObject(targetValue) && isPlainObject(sourceValue)) target[key] = deepMerge(targetValue, sourceValue);
+		else if (sourceValue !== void 0) target[key] = sourceValue;
+	}
+	return deepMerge(target, ...sources);
+}
+//#endregion
+//#region helpers/array/equalsDeep.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
 * SPDX-License-Identifier: LGPL-3.0-or-later
 */
 /**
-* Quick comparison of two arrays using JSON.stringify.
-* This is a fast but simple comparison that may not work for all edge cases.
+* Recursive structural array equality.
+*
+* Two arrays are equal when they have the same length and each pair of
+* elements at the same index is structurally equal:
+* - Arrays recurse with `equalsDeep`.
+* - Plain objects recurse key-by-key with structural comparison.
+* - `Date` instances are compared by their epoch value.
+* - All other values use strict equality (`===`), which means `NaN !== NaN`
+*   and special objects (Map, Set, RegExp, Promise, class instances\u2026) are
+*   compared by reference.
+*
+* For positional one-level comparison use {@link equalsShallow}. For
+* order-independent comparison use {@link equalsUnordered}.
 *
 * @param arrA - First array to compare
 * @param arrB - Second array to compare
-* @returns `true` if arrays are identical according to JSON.stringify, `false` otherwise
+* @returns `true` if arrays are deeply equal, `false` otherwise.
 * @since 2.0.0
 */
-function shallowEquals$1(arrA, arrB) {
-	try {
-		return JSON.stringify(arrA) === JSON.stringify(arrB);
-	} catch {
-		return arrA === arrB;
+function equalsDeep$1(arrA, arrB) {
+	if (arrA === arrB) return true;
+	if (!Array.isArray(arrA) || !Array.isArray(arrB)) return false;
+	if (arrA.length !== arrB.length) return false;
+	for (let i = 0; i < arrA.length; i++) if (!valuesEqual(arrA[i], arrB[i])) return false;
+	return true;
+}
+function valuesEqual(a, b) {
+	if (a === b) return true;
+	if (Array.isArray(a) && Array.isArray(b)) return equalsDeep$1(a, b);
+	if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+	if (isPlainObject(a) && isPlainObject(b)) {
+		const ao = a;
+		const bo = b;
+		const keysA = Object.keys(ao);
+		if (keysA.length !== Object.keys(bo).length) return false;
+		for (const key of keysA) {
+			if (!Object.prototype.hasOwnProperty.call(bo, key)) return false;
+			if (!valuesEqual(ao[key], bo[key])) return false;
+		}
+		return true;
 	}
+	return false;
 }
 //#endregion
 //#region helpers/date/timestamp.ts
@@ -207,104 +289,158 @@ function isSpecialObject(value) {
 	return false;
 }
 //#endregion
-//#region helpers/object/deepCompare.ts
+//#region helpers/object/diff.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
 * SPDX-License-Identifier: LGPL-3.0-or-later
 */
 /**
-* Deep comparison of two objects that returns detailed information about differences.
+* Structural object diff.
+*
+* Returns `true` when both inputs are deeply equal, otherwise a
+* {@link DiffResult} describing the differences key by key.
+*
+* Comparison rules:
+* - Same reference \u2192 `true`.
+* - Either side is `null`/`undefined` (and not both) \u2192 `false`.
+* - Both `Date` \u2192 epoch comparison.
+* - Both arrays \u2192 compared with `array/equalsDeep` (leaf, no diff drill-down).
+* - Special objects (Map, Set, RegExp, Promise, class instances\u2026) \u2192 reference equality.
+* - Plain objects \u2192 key-by-key, recursing up to `options.depth` levels.
+* - Mixed types (e.g. array vs object, Date vs object) \u2192 `false`.
+*
+* For a boolean wrapper see {@link equalsDeep} from this category.
+* For a one-level boolean check see {@link equalsShallow} from this category.
 *
-* @param objA - First object to compare (can be object, undefined, or null)
-* @param objB - Second object to compare (can be object, undefined, or null)
-* @returns `true` if objects are identical, `false` if incompatible types, or a `DeepCompareResult` object detailing differences
+* @param objA - First value (object, `null`, or `undefined`).
+* @param objB - Second value (object, `null`, or `undefined`).
+* @param options - See {@link DiffOptions}.
+* @returns `true` when equal, otherwise a {@link DiffResult}, or `false` for incompatible types.
 * @since 2.0.0
 */
-function deepCompare(objA, objB) {
+function diff(objA, objB, options = {}) {
+	const depth = options.depth ?? Infinity;
 	if (objA === objB) return true;
 	if (objA == null || objB == null) return false;
 	if (objA instanceof Date && objB instanceof Date) return compare(objA, objB);
-	if (Array.isArray(objA) && Array.isArray(objB)) return shallowEquals$1(objA, objB);
+	if (Array.isArray(objA) && Array.isArray(objB)) return equalsDeep$1(objA, objB);
 	if (Array.isArray(objA) || Array.isArray(objB)) return false;
 	if (isSpecialObject(objA) || isSpecialObject(objB)) return objA === objB;
+	return diffPlainObjects(objA, objB, depth);
+}
+function diffPlainObjects(objA, objB, depth) {
 	const keys = Array.from(new Set([...Object.keys(objA), ...Object.keys(objB)]));
-	const differences = {};
+	const differences = Object.create(null);
 	for (const key of keys) {
-		const hasA = key in objA;
-		const hasB = key in objB;
-		if (!hasA && hasB) differences[key] = "onlyB";
-		else if (hasA && !hasB) differences[key] = "onlyA";
-		else {
-			const valueA = objA[key];
-			const valueB = objB[key];
-			if (Array.isArray(valueA) && Array.isArray(valueB)) {
-				if (!shallowEquals$1(valueA, valueB)) differences[key] = false;
-			} else if (valueA instanceof Date && valueB instanceof Date) {
-				if (!compare(valueA, valueB)) differences[key] = false;
-			} else if (isSpecialObject(valueA) || isSpecialObject(valueB)) {
-				if (valueA !== valueB) differences[key] = false;
-			} else if (valueA !== null && valueB !== null && valueA !== void 0 && valueB !== void 0 && typeof valueA === "object" && typeof valueB === "object" && !isSpecialObject(valueA) && !isSpecialObject(valueB)) {
-				const nestedResult = deepCompare(valueA, valueB);
-				if (nestedResult !== true) differences[key] = nestedResult === false ? false : nestedResult;
-			} else if (valueA !== valueB) differences[key] = false;
+		const hasA = Object.prototype.hasOwnProperty.call(objA, key);
+		const hasB = Object.prototype.hasOwnProperty.call(objB, key);
+		if (!hasA && hasB) {
+			differences[key] = "onlyB";
+			continue;
+		}
+		if (hasA && !hasB) {
+			differences[key] = "onlyA";
+			continue;
+		}
+		const valueA = objA[key];
+		const valueB = objB[key];
+		if (valueA === valueB) continue;
+		if (Array.isArray(valueA) && Array.isArray(valueB)) {
+			if (!equalsDeep$1(valueA, valueB)) differences[key] = false;
+			continue;
+		}
+		if (Array.isArray(valueA) || Array.isArray(valueB)) {
+			differences[key] = false;
+			continue;
+		}
+		if (valueA instanceof Date && valueB instanceof Date) {
+			if (!compare(valueA, valueB)) differences[key] = false;
+			continue;
 		}
+		if (valueA instanceof Date || valueB instanceof Date) {
+			differences[key] = false;
+			continue;
+		}
+		if (isSpecialObject(valueA) || isSpecialObject(valueB)) {
+			differences[key] = false;
+			continue;
+		}
+		if (!(valueA !== null && valueB !== null && typeof valueA === "object" && typeof valueB === "object")) {
+			differences[key] = false;
+			continue;
+		}
+		if (depth <= 0) {
+			differences[key] = false;
+			continue;
+		}
+		const nested = diffPlainObjects(valueA, valueB, depth - 1);
+		if (nested !== true) differences[key] = nested;
 	}
 	return Object.keys(differences).length > 0 ? differences : true;
 }
 //#endregion
-//#region helpers/type/isPlainObject.ts
+//#region helpers/object/equalsDeep.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
 * SPDX-License-Identifier: LGPL-3.0-or-later
 */
 /**
-* Checks if a value is a plain object.
+* Recursive structural object equality.
 *
-* A plain object is created by `{}`, `new Object()`, or `Object.create(null)`.
-* Returns `false` for arrays, Date, Map, Set, RegExp, class instances, etc.
+* Boolean wrapper around {@link diff} \u2014 returns `true` when the two values
+* are deeply equal according to the same rules. Use this when you only
+* need a yes/no answer; use {@link diff} when you also need to know
+* *what* differs.
 *
-* @param value - The value to check
-* @returns True if value is a plain object
-* @example
-* isPlainObject({})           // => true
-* isPlainObject({ a: 1 })    // => true
-* isPlainObject(new Date())  // => false
-* isPlainObject([])          // => false
-* isPlainObject(null)        // => false
+* For a one-level boolean check use {@link equalsShallow}.
+*
+* @param objA - First value (object, `null`, or `undefined`).
+* @param objB - Second value (object, `null`, or `undefined`).
+* @returns `true` if both inputs are deeply equal, `false` otherwise.
 * @since 2.0.0
 */
-function isPlainObject(value) {
-	if (value === null || typeof value !== "object") return false;
-	const proto = Object.getPrototypeOf(value);
-	return proto === Object.prototype || proto === null;
+function equalsDeep(objA, objB) {
+	return diff(objA, objB) === true;
 }
 //#endregion
-//#region helpers/object/deepMerge.ts
+//#region helpers/object/equalsShallow.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
 * SPDX-License-Identifier: LGPL-3.0-or-later
 */
-var UNSAFE_KEYS$1 = new Set([
-	"__proto__",
-	"constructor",
-	"prototype"
-]);
-function deepMerge(target, ...sources) {
-	if (target === void 0 || target === null) return target;
-	if (!sources.length) return target;
-	const source = sources.shift();
-	if (!source) return deepMerge(target, ...sources);
-	for (const key in source) {
-		if (!Object.hasOwn(source, key) || UNSAFE_KEYS$1.has(key)) continue;
-		const targetValue = target[key];
-		const sourceValue = source[key];
-		if (isPlainObject(targetValue) && isPlainObject(sourceValue)) target[key] = deepMerge(targetValue, sourceValue);
-		else if (sourceValue !== void 0) target[key] = sourceValue;
-	}
-	return deepMerge(target, ...sources);
+/**
+* One-level (shallow) object equality.
+*
+* Two objects are equal when they share the exact same set of own
+* enumerable string keys and each pair of values satisfies strict equality
+* (`===`). No recursion: nested objects/arrays are compared by reference.
+*
+* Falls back to strict equality when either input is `null`, `undefined`
+* or not an object \u2014 so primitives match if and only if they are `===`.
+* Arrays are not supported; they always return `false` (unless identical
+* references). Use `array/equalsShallow` instead.
+*
+* For recursive structural comparison use {@link equalsDeep}. For a diff
+* structure use {@link diff}.
+*
+* @param objA - First value to compare
+* @param objB - Second value to compare
+* @returns `true` if values are shallowly equal, `false` otherwise.
+* @since 2.0.0
+*/
+function equalsShallow(objA, objB) {
+	if (objA === objB) return true;
+	if (objA === null || objB === null || typeof objA !== "object" || typeof objB !== "object") return false;
+	const a = objA;
+	const b = objB;
+	if (Array.isArray(objA) || Array.isArray(objB)) return false;
+	const keysA = Object.keys(a);
+	if (keysA.length !== Object.keys(b).length) return false;
+	for (const key of keysA) if (!Object.prototype.hasOwnProperty.call(b, key) || a[key] !== b[key]) return false;
+	return true;
 }
 //#endregion
 //#region helpers/object/get.ts
@@ -331,6 +467,105 @@ function get(obj, path, defaultValue) {
 	return result !== void 0 ? result : defaultValue;
 }
 //#endregion
+//#region helpers/object/groupBy.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Groups an array of items by a key derived from each item.
+*
+* A thin, typed wrapper around `Object.groupBy` (ES2024) that works on
+* older targets and provides stricter return-type inference.
+*
+* @param items - The array to group
+* @param keyFn - Function that returns the group key for each item
+* @returns A record mapping each key to the array of items with that key
+* @example
+* groupBy([1, 2, 3, 4], n => n % 2 === 0 ? 'even' : 'odd')
+* // => { odd: [1, 3], even: [2, 4] }
+* @since 2.0.0
+*/
+function groupBy(items, keyFn) {
+	const result = {};
+	for (const item of items) {
+		const key = keyFn(item);
+		if (result[key] === void 0) result[key] = [];
+		result[key].push(item);
+	}
+	return result;
+}
+//#endregion
+//#region helpers/object/invert.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Returns a new object with keys and values swapped.
+* If multiple keys share the same value, the last one wins.
+*
+* @param obj - The object whose keys and values are to be swapped
+* @returns A new object with values as keys and original keys as values
+* @example
+* invert({ a: 'x', b: 'y', c: 'z' })
+* // => { x: 'a', y: 'b', z: 'c' }
+*
+* invert({ one: 1, two: 2 })
+* // => { 1: 'one', 2: 'two' }
+* @since 2.0.0
+*/
+function invert(obj) {
+	const result = {};
+	for (const key in obj) if (Object.prototype.hasOwnProperty.call(obj, key)) result[obj[key]] = key;
+	return result;
+}
+//#endregion
+//#region helpers/object/map.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Transforms the values and/or keys of a plain object in a single pass.
+*
+* Both callbacks are optional and default to identity (no transformation).
+* When `mapValue` is omitted the original values are preserved;
+* when `mapKey` is omitted the original keys are preserved.
+*
+* Note: if two different keys map to the same output key the last one wins
+* (insertion order).
+*
+* @param obj - The source object
+* @param mapValue - Callback called with `(value, key)` for each entry.
+*   Defaults to identity.
+* @param mapKey - Callback called with `(key, value)` for each entry.
+*   Defaults to identity.
+* @returns A new object with transformed keys and/or values
+* @example
+* map({ a: 1, b: 2 }, v => v * 10)
+* // => { a: 10, b: 20 }
+*
+* map({ a: 1, b: 2 }, undefined, k => k.toUpperCase())
+* // => { A: 1, B: 2 }
+*
+* map({ a: 1, b: 2 }, v => v * 10, k => k.toUpperCase())
+* // => { A: 10, B: 20 }
+* @since 2.0.0
+*/
+function map(obj, mapValue, mapKey) {
+	const result = {};
+	for (const key of Object.keys(obj)) {
+		const value = obj[key];
+		const newKey = mapKey ? mapKey(key, value) : key;
+		result[newKey] = mapValue ? mapValue(value, key) : value;
+	}
+	return result;
+}
+//#endregion
 //#region helpers/object/omit.ts
 function omit(obj, keys) {
 	if (obj === void 0 || obj === null) return obj;
@@ -432,31 +667,6 @@ function set(obj, path, value) {
 	return obj;
 }
 //#endregion
-//#region helpers/object/shallowEquals.ts
-/**
-* This file is part of helpers4.
-* Copyright (C) 2025 baxyz
-* SPDX-License-Identifier: LGPL-3.0-or-later
-*/
-/**
-* Quick comparison of two objects using JSON.stringify.
-* This is a fast but simple comparison that may not work for all edge cases.
-*
-* @param objA - First object to compare
-* @param objB - Second object to compare
-* @returns `true` if objects are identical according to JSON.stringify, `false` otherwise
-* @since 2.0.0
-*/
-function shallowEquals(objA, objB) {
-	if (objA === objB) return true;
-	if (typeof objA === "function" || typeof objB === "function") return objA === objB;
-	try {
-		return JSON.stringify(objA) === JSON.stringify(objB);
-	} catch {
-		return objA === objB;
-	}
-}
-//#endregion
-export { compact, deepClone, deepCompare, deepMerge, get, omit, pick, removeUndefinedNull, safeJsonParse, set, shallowEquals };
+export { compact, deepClone, deepMerge, diff, equalsDeep, equalsShallow, get, groupBy, invert, map, omit, pick, removeUndefinedNull, safeJsonParse, set };
 
 //# sourceMappingURL=index.js.map