@helpers4/object 2.0.4 → 3.0.0-alpha.1

package/lib/index.js

@@ -1,49 +1,66 @@
-//#region helpers/object/compact.ts
-function compact(obj) {
-	if (obj === void 0 || obj === null) return obj;
-	const result = {};
-	for (const key of Object.keys(obj)) if (obj[key]) result[key] = obj[key];
-	return result;
-}
-//#endregion
-//#region helpers/object/_unsafeKeys.ts
-/**
-* This file is part of helpers4.
-* Copyright (C) 2025 baxyz
-* SPDX-License-Identifier: LGPL-3.0-or-later
-*/
-/**
-* Keys that must never be set on a plain object (prototype-pollution guard).
-* @internal
-*/
-var UNSAFE_KEYS = new Set([
+var UNSAFE_KEYS = /* @__PURE__ */ new Set([
 	"__proto__",
 	"constructor",
 	"prototype"
 ]);
 //#endregion
-//#region helpers/object/deepClone.ts
+//#region helpers/object/cloneDeep.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
 * SPDX-License-Identifier: LGPL-3.0-or-later
 */
 /**
-* Creates a deep copy of an object or array
-* @param obj - The object to clone
-* @returns Deep cloned object
+* Creates a deep copy of an object or array.
+*
+* Recursively clones own enumerable string keys. `Date` instances are
+* reconstructed with the same epoch value. Prototype-polluting keys
+* (`__proto__`, `constructor`, `prototype`) are silently skipped.
+* Does **not** handle circular references.
+*
+* **Limitation:** symbol-keyed own properties are **not** copied — only string
+* keys are processed. Use `structuredClone` if symbol propagation is required.
+*
+* @param obj - The value to clone
+* @returns A deep copy of `obj`
+* @example
+* cloneDeep({ a: { b: [1, 2] } })
+* // => { a: { b: [1, 2] } }  — fully independent copy
+*
+* cloneDeep(new Date('2024-01-01'))
+* // => Date with the same timestamp
+*
+* // Primitives pass through unchanged
+* cloneDeep(42)   // => 42
+* cloneDeep(null) // => null
 * @since 1.9.0
 */
-function deepClone(obj) {
+function cloneDeep(obj) {
 	if (obj === null || typeof obj !== "object") return obj;
 	if (obj instanceof Date) return new Date(obj.getTime());
-	if (Array.isArray(obj)) return obj.map((item) => deepClone(item));
+	if (Array.isArray(obj)) return obj.map((item) => cloneDeep(item));
 	const cloned = {};
-	for (const key in obj) if (Object.prototype.hasOwnProperty.call(obj, key) && !UNSAFE_KEYS.has(key)) cloned[key] = deepClone(obj[key]);
+	for (const key in obj) if (Object.prototype.hasOwnProperty.call(obj, key) && !UNSAFE_KEYS.has(key)) cloned[key] = cloneDeep(obj[key]);
 	return cloned;
 }
 //#endregion
-//#region helpers/type/isPlainObject.ts
+//#region helpers/object/compact.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+function compact(obj) {
+	if (obj === void 0 || obj === null) return obj;
+	const result = {};
+	for (const key of Object.keys(obj)) {
+		if (UNSAFE_KEYS.has(key)) continue;
+		if (obj[key]) result[key] = obj[key];
+	}
+	return result;
+}
+//#endregion
+//#region helpers/guard/isPlainObject.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
@@ -71,36 +88,6 @@ function isPlainObject(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
-*/
-function mergeKey(target, source, key) {
-	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;
-}
-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);
-	const t = target;
-	const s = source;
-	for (const key in source) {
-		if (!Object.hasOwn(source, key) || UNSAFE_KEYS.has(key)) continue;
-		mergeKey(t, s, key);
-	}
-	for (const sym of Object.getOwnPropertySymbols(source)) {
-		if (!Object.prototype.propertyIsEnumerable.call(source, sym)) continue;
-		mergeKey(t, s, sym);
-	}
-	return deepMerge(target, ...sources);
-}
-//#endregion
 //#region helpers/array/equalsDeep.ts
 /**
 * This file is part of helpers4.
@@ -265,7 +252,7 @@ function compare(dateA, dateB, options = {}) {
 	}
 }
 //#endregion
-//#region helpers/type/isSpecialObject.ts
+//#region helpers/guard/isSpecialObject.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
@@ -345,7 +332,7 @@ function diff(objA, objB, options = {}) {
 	return diffPlainObjects(objA, objB, depth);
 }
 function diffPlainObjects(objA, objB, depth) {
-	const keys = Array.from(new Set([...Object.keys(objA), ...Object.keys(objB)]));
+	const keys = Array.from(/* @__PURE__ */ new Set([...Object.keys(objA), ...Object.keys(objB)]));
 	const differences = Object.create(null);
 	for (const key of keys) {
 		const hasA = Object.prototype.hasOwnProperty.call(objA, key);
@@ -476,7 +463,7 @@ function equalsShallow(objA, objB) {
 * - Non-bracket text trailing a `]` within the same dot-segment throws a RangeError;
 *   use a dot separator instead (`'a[0].b'` not `'a[0]b'`).
 *
-* @internal
+* @ignore
 * @example
 * parsePath('a.b.c')       // => ['a', 'b', 'c']        (all strings)
 * parsePath('layers.1.x')  // => ['layers', '1', 'x']   (all strings)
@@ -521,6 +508,7 @@ function parsePathUncached(path) {
 * SPDX-License-Identifier: LGPL-3.0-or-later
 */
 function get(obj, path, defaultValue) {
+	if (obj == null) return defaultValue;
 	const keys = typeof path === "string" ? parsePath(path) : path;
 	let result = obj;
 	for (const key of keys) {
@@ -541,6 +529,9 @@ function get(obj, path, defaultValue) {
 *
 * A thin, typed wrapper around `Object.groupBy` (ES2024) that works on
 * older targets and provides stricter return-type inference.
+* `null` and `undefined` are treated as empty arrays and return `{}`.
+* Items whose computed key is a prototype-polluting string (`__proto__`,
+* `constructor`, `prototype`) are silently skipped.
 *
 * @param items - The array to group
 * @param keyFn - Function that returns the group key for each item
@@ -548,12 +539,16 @@ function get(obj, path, defaultValue) {
 * @example
 * groupBy([1, 2, 3, 4], n => n % 2 === 0 ? 'even' : 'odd')
 * // => { odd: [1, 3], even: [2, 4] }
+* groupBy(null, n => n % 2 === 0 ? 'even' : 'odd')
+* // => {}
 * @since 2.0.0
 */
 function groupBy(items, keyFn) {
 	const result = {};
+	if (items == null) return result;
 	for (const item of items) {
 		const key = keyFn(item);
+		if (typeof key === "string" && UNSAFE_KEYS.has(key)) continue;
 		if (result[key] === void 0) result[key] = [];
 		result[key].push(item);
 	}
@@ -569,6 +564,9 @@ function groupBy(items, keyFn) {
 /**
 * Returns a new object with keys and values swapped.
 * If multiple keys share the same value, the last one wins.
+* `null` and `undefined` are treated as empty objects and return `{}`.
+* Entries whose source key **or** value is a prototype-polluting string
+* (`__proto__`, `constructor`, `prototype`) are silently skipped.
 *
 * @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
@@ -578,11 +576,19 @@ function groupBy(items, keyFn) {
 *
 * invert({ one: 1, two: 2 })
 * // => { 1: 'one', 2: 'two' }
+*
+* invert(null)
+* // => {}
 * @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;
+	if (obj == null) return result;
+	for (const key in obj) if (Object.prototype.hasOwnProperty.call(obj, key) && !UNSAFE_KEYS.has(key)) {
+		const val = obj[key];
+		if (typeof val === "string" && UNSAFE_KEYS.has(val)) continue;
+		result[val] = key;
+	}
 	return result;
 }
 //#endregion
@@ -594,20 +600,23 @@ function invert(obj) {
 */
 /**
 * Checks if a plain object has no own enumerable string-keyed properties.
+* `null` and `undefined` are treated as empty objects and return `true`.
 *
 * Symbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`
 * separately if symbol keys matter for your use case.
 *
 * @param value - The object to check
-* @returns `true` if the object has no own enumerable string-keyed properties
+* @returns `true` if the object has no own enumerable string-keyed properties, or if `value` is `null`/`undefined`
 * @example
 * isEmpty({})          // => true
+* isEmpty(null)        // => true
+* isEmpty(undefined)   // => true
 * isEmpty({ a: 1 })    // => false
 * isEmpty({ a: undefined }) // => false  (key exists)
 * @since 2.0.3
 */
 function isEmpty(value) {
-	return Object.keys(value).length === 0;
+	return value == null || Object.keys(value).length === 0;
 }
 //#endregion
 //#region helpers/object/isNonEmpty.ts
@@ -618,19 +627,23 @@ function isEmpty(value) {
 */
 /**
 * Checks if a plain object has at least one own enumerable string-keyed property.
+* `null` and `undefined` are treated as empty objects and return `false`.
 *
 * Symbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`
 * separately if symbol keys matter for your use case.
 *
 * @param value - The object to check
-* @returns `true` if the object has at least one own enumerable string-keyed property
+* @returns `true` if the object has at least one own enumerable string-keyed property; `false` for empty, `null`, or `undefined`.
+* Acts as a type guard: the `if` branch narrows `Record<PropertyKey, unknown> | null | undefined` to `Record<PropertyKey, unknown>`.
 * @example
 * isNonEmpty({ a: 1 })    // => true
 * isNonEmpty({})          // => false
+* isNonEmpty(null)        // => false
+* isNonEmpty(undefined)   // => false
 * @since 2.0.3
 */
 function isNonEmpty(value) {
-	return Object.keys(value).length > 0;
+	return value != null && Object.keys(value).length > 0;
 }
 //#endregion
 //#region helpers/object/map.ts
@@ -647,7 +660,8 @@ function isNonEmpty(value) {
 * 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).
+* (insertion order). Entries whose mapped key is a prototype-polluting string
+* (`__proto__`, `constructor`, `prototype`) are silently skipped.
 *
 * @param obj - The source object
 * @param mapValue - Callback called with `(value, key)` for each entry.
@@ -668,14 +682,44 @@ function isNonEmpty(value) {
 */
 function map(obj, mapValue, mapKey) {
 	const result = {};
+	if (obj == null) return result;
 	for (const key of Object.keys(obj)) {
 		const value = obj[key];
 		const newKey = mapKey ? mapKey(key, value) : key;
+		if (typeof newKey === "string" && UNSAFE_KEYS.has(newKey)) continue;
 		result[newKey] = mapValue ? mapValue(value, key) : value;
 	}
 	return result;
 }
 //#endregion
+//#region helpers/object/mergeDeep.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+function applyKey(result, source, key) {
+	const resultValue = result[key];
+	const sourceValue = source[key];
+	if (isPlainObject(resultValue) && isPlainObject(sourceValue)) result[key] = mergeDeep(resultValue, sourceValue);
+	else if (sourceValue !== void 0) result[key] = isPlainObject(sourceValue) || Array.isArray(sourceValue) ? cloneDeep(sourceValue) : sourceValue;
+}
+function applySource(result, source) {
+	for (const key in source) {
+		if (!Object.hasOwn(source, key) || UNSAFE_KEYS.has(key)) continue;
+		applyKey(result, source, key);
+	}
+	for (const sym of Object.getOwnPropertySymbols(source)) {
+		if (!Object.prototype.propertyIsEnumerable.call(source, sym)) continue;
+		applyKey(result, source, sym);
+	}
+}
+function mergeDeep(...sources) {
+	const result = {};
+	for (const source of sources) if (source !== null && source !== void 0) applySource(result, source);
+	return result;
+}
+//#endregion
 //#region helpers/object/omit.ts
 function omit(obj, keys) {
 	if (obj === void 0 || obj === null) return obj;
@@ -685,14 +729,22 @@ function omit(obj, keys) {
 }
 //#endregion
 //#region helpers/object/pick.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
 function pick(obj, keys) {
 	if (obj === void 0 || obj === null) return obj;
 	const result = {};
-	for (const key of keys) if (Object.prototype.hasOwnProperty.call(obj, key)) result[key] = obj[key];
+	for (const key of keys) {
+		if (typeof key === "string" && UNSAFE_KEYS.has(key)) continue;
+		if (Object.prototype.hasOwnProperty.call(obj, key)) result[key] = obj[key];
+	}
 	return result;
 }
 //#endregion
-//#region helpers/type/isNullish.ts
+//#region helpers/guard/isNullish.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
@@ -765,6 +817,6 @@ function set(obj, path, value) {
 	return obj;
 }
 //#endregion
-export { compact, deepClone, deepMerge, diff, equalsDeep, equalsShallow, get, groupBy, invert, isEmpty, isNonEmpty, map, omit, pick, removeUndefinedNull, safeJsonParse, set };
+export { cloneDeep, compact, diff, equalsDeep, equalsShallow, get, groupBy, invert, isEmpty, isNonEmpty, map, mergeDeep, omit, pick, removeUndefinedNull, safeJsonParse, set };
 
 //# sourceMappingURL=index.js.map