@helpers4/object 2.0.3 → 2.1.0

package/lib/index.js

@@ -1,37 +1,57 @@
-//#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;
-}
+var UNSAFE_KEYS = 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
 */
-var UNSAFE_KEYS$2 = new Set([
-	"__proto__",
-	"constructor",
-	"prototype"
-]);
 /**
-* 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$2.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/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/type/isPlainObject.ts
 /**
 * This file is part of helpers4.
@@ -60,32 +80,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
-*/
-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.
@@ -443,22 +437,71 @@ function equalsShallow(objA, objB) {
 	return true;
 }
 //#endregion
-//#region helpers/object/get.ts
+//#region helpers/object/_parsePath.ts
 /**
 * This file is part of helpers4.
 * Copyright (C) 2025 baxyz
 * SPDX-License-Identifier: LGPL-3.0-or-later
 */
 /**
-* Gets a value from an object using a dot-notated path
-* @param obj - The object to get value from
-* @param path - The dot-notated path (e.g., 'a.b.c')
-* @param defaultValue - Default value if path doesn't exist
-* @returns The value at the path or default value
-* @since 1.9.0
+* Parses a string path into an array of string/number segments.
+*
+* - Dot separators (`.`) split segments; each segment becomes a string key.
+* - Bracket indices (`[n]`) become number keys.
+* - A leading `.` is treated as "current level" and stripped before parsing,
+*   so `.[0]` ≡ `[0]` and `.a.b` ≡ `a.b`.
+* - Empty string (or bare `.`) returns `['']` (addresses the `''` key on the root object).
+* - Consecutive dots (`a..b`) produce an empty-string segment: `['a', '', 'b']`.
+* - 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'`).
+*
+* @ignore
+* @example
+* parsePath('a.b.c')       // => ['a', 'b', 'c']        (all strings)
+* parsePath('layers.1.x')  // => ['layers', '1', 'x']   (all strings)
+* parsePath('layers[1].x') // => ['layers', 1, 'x']     (bracket → number)
+* parsePath('.[0]')        // => [0]                     (leading dot stripped)
+* parsePath('a..b')        // => ['a', '', 'b']          (empty segment preserved)
+* parsePath('.')           // => ['']                    (leading dot → empty-string key)
+*/
+var BRACKET = /\[(\d+)\]/g;
+var parsePathCache = /* @__PURE__ */ new Map();
+function parsePath(path) {
+	const cached = parsePathCache.get(path);
+	if (cached !== void 0) return cached;
+	const result = Object.freeze(parsePathUncached(path));
+	parsePathCache.set(path, result);
+	return result;
+}
+function parsePathUncached(path) {
+	if (path === "") return [""];
+	if (path[0] === ".") path = path.slice(1);
+	if (path === "") return [""];
+	const result = [];
+	for (const dotSegment of path.split(".")) {
+		BRACKET.lastIndex = 0;
+		let last = 0;
+		let match;
+		while ((match = BRACKET.exec(dotSegment)) !== null) {
+			if (match.index > last) result.push(dotSegment.slice(last, match.index));
+			result.push(parseInt(match[1], 10));
+			last = BRACKET.lastIndex;
+		}
+		if (last === 0) result.push(dotSegment);
+		else if (last < dotSegment.length) throw new RangeError(`parsePath: non-bracket text '${dotSegment.slice(last)}' after ']' in segment '${dotSegment}' — use 'a[0].b' instead of 'a[0]b'`);
+	}
+	return result;
+}
+//#endregion
+//#region helpers/object/get.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
 */
 function get(obj, path, defaultValue) {
-	const keys = path.split(".");
+	if (obj == null) return defaultValue;
+	const keys = typeof path === "string" ? parsePath(path) : path;
 	let result = obj;
 	for (const key of keys) {
 		if (result == null || typeof result !== "object") return defaultValue;
@@ -478,6 +521,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
@@ -485,12 +531,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);
 	}
@@ -506,6 +556,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
@@ -515,11 +568,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
@@ -531,20 +592,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
@@ -555,19 +619,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
@@ -584,7 +652,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.
@@ -605,14 +674,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;
@@ -688,32 +787,20 @@ function safeJsonParse(input, fallback) {
 * Copyright (C) 2025 baxyz
 * SPDX-License-Identifier: LGPL-3.0-or-later
 */
-var UNSAFE_KEYS = new Set([
-	"__proto__",
-	"constructor",
-	"prototype"
-]);
-/**
-* Sets a value in an object using a dot-notated path
-* @param obj - The object to set value in
-* @param path - The dot-notated path (e.g., 'a.b.c')
-* @param value - The value to set
-* @returns The modified object
-* @since 1.9.0
-*/
 function set(obj, path, value) {
-	const keys = path.split(".");
-	if (keys.some((k) => UNSAFE_KEYS.has(k))) return obj;
+	const keys = typeof path === "string" ? parsePath(path) : path;
+	if (keys.length === 0) return obj;
+	if (keys.some((k) => typeof k === "string" && UNSAFE_KEYS.has(k))) return obj;
 	let current = obj;
 	for (let i = 0; i < keys.length - 1; i++) {
 		const key = keys[i];
-		if (!(key in current) || typeof current[key] !== "object" || current[key] === null) current[key] = {};
+		if (!Object.hasOwn(current, key) || typeof current[key] !== "object" || current[key] === null) current[key] = {};
 		current = current[key];
 	}
 	current[keys[keys.length - 1]] = value;
 	return obj;
 }
 //#endregion
-export { compact, deepClone, deepMerge, diff, equalsDeep, equalsShallow, get, groupBy, invert, isEmpty, isNonEmpty, map, omit, pick, removeUndefinedNull, safeJsonParse, set };
+export { cloneDeep, cloneDeep as deepClone, compact, mergeDeep as deepMerge, mergeDeep, diff, equalsDeep, equalsShallow, get, groupBy, invert, isEmpty, isNonEmpty, map, omit, pick, removeUndefinedNull, safeJsonParse, set };
 
 //# sourceMappingURL=index.js.map