@helpers4/object 2.0.2 → 2.0.4

package/README.md

@@ -21,6 +21,8 @@ A set of helpers for working with URLs.
 - get
 - groupBy
 - invert
+- isEmpty
+- isNonEmpty
 - map
 - omit
 - pick

package/lib/index.d.ts

@@ -35,15 +35,21 @@ declare function deepClone<T>(obj: T): T;
  * SPDX-License-Identifier: LGPL-3.0-or-later
  */
 /**
- * Merges two or more objects deeply
- * @param target - The target object
- * @param sources - The source objects to merge
- * @returns The merged object
+ * Merges two or more objects deeply.
+ *
+ * Recursively merges own enumerable properties — both string and symbol keys.
+ * Plain objects are merged recursively; all other values (arrays, class instances,
+ * primitives, etc.) are replaced by the source value.
+ * `undefined` source values do not overwrite existing target values.
+ *
+ * @param target - The target object (mutated in place)
+ * @param sources - One or more source objects to merge into the target
+ * @returns The mutated target
  * @since 1.9.0
  */
-declare function deepMerge<T extends Record<string, unknown>>(target: T, ...sources: Record<string, unknown>[]): T;
-declare function deepMerge(target: undefined, ...sources: Record<string, unknown>[]): undefined;
-declare function deepMerge(target: null, ...sources: Record<string, unknown>[]): null;
+declare function deepMerge<T extends Record<PropertyKey, unknown>>(target: T, ...sources: Record<PropertyKey, unknown>[]): T;
+declare function deepMerge(target: undefined, ...sources: Record<PropertyKey, unknown>[]): undefined;
+declare function deepMerge(target: null, ...sources: Record<PropertyKey, unknown>[]): null;
 
 /**
  * This file is part of helpers4.
@@ -163,14 +169,65 @@ declare function equalsShallow(objA: unknown, objB: unknown): boolean;
  * 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
+ * Resolves the value type at a given path within T.
+ * Returns `unknown` when the path doesn't match the shape of T.
+ *
+ * @internal
+ * @example
+ * DeepGet<{ a: { b: number } }, ['a', 'b']>  // => number
+ * DeepGet<{ a: { b: number } }, ['a', 'x']>  // => unknown
+ * DeepGet<{ a: number }, []>                  // => { a: number }
+ */
+type DeepGet<T, Path extends readonly PropertyKey[]> = Path extends readonly [] ? T : Path extends readonly [infer K, ...infer Rest extends readonly PropertyKey[]] ? K extends keyof T ? DeepGet<T[K], Rest> : unknown : unknown;
+/**
+ * Produces the type of T after setting the value at Path to V.
+ * Resolves to `never` when a key in Path is not present in the corresponding level of T,
+ * surfacing invalid paths at the call site rather than silently returning T unchanged.
+ *
+ * @internal
+ * @example
+ * DeepSet<{ a: { b: number } }, ['a', 'b'], string>
+ * // => { a: { b: string } }
+ */
+type DeepSet<T, Path extends readonly PropertyKey[], V> = Path extends readonly [] ? T : Path extends readonly [infer K, ...infer Rest extends readonly PropertyKey[]] ? K extends keyof T ? {
+    [P in keyof T]: P extends K ? DeepSet<T[K], Rest, V> : T[P];
+} : never : never;
+
+/**
+ * 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/bracket-notated path or explicit key array.
+ *
+ * **Two path forms are supported:**
+ *
+ * 1. **String path** — dot notation (`'a.b.c'`) and bracket notation (`'layers[1].name'`)
+ *    are both accepted and mixed freely. Segments are traversed as string keys; `[n]`
+ *    indices become numeric keys.
+ *
+ * 2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,
+ *    no parsing performed. Enables symbol-keyed traversal and compile-time type inference:
+ *    `get(obj, ['a', 'b'] as const)` infers the return type from the path.
+ *
+ * @param obj - The object to read from
+ * @param path - Dot/bracket-notation string or explicit `PropertyKey[]`
+ * @param defaultValue - Returned when the path is absent or resolves to `undefined`
+ * @returns The value at the path, or `defaultValue`
+ * @example
+ * get({ a: { b: { c: 42 } } }, 'a.b.c')       // => 42
+ * get({ a: [1, 2, 3] }, 'a[1]')                 // => 2
+ * get({ a: { b: 0 } }, 'a.b', 99)               // => 0  (falsy values are returned as-is)
+ * get({ a: 1 }, 'b.c', 'default')               // => 'default'
+ *
+ * const id = Symbol('id')
+ * get({ [id]: 'alice' }, [id])                  // => 'alice'  (symbol key)
  * @since 1.9.0
  */
 declare function get<T = unknown>(obj: unknown, path: string, defaultValue?: T): T | undefined;
+declare function get<T extends object, const Path extends readonly PropertyKey[]>(obj: T, path: Path, defaultValue?: DeepGet<T, Path>): DeepGet<T, Path> | undefined;
 
 /**
  * This file is part of helpers4.
@@ -214,6 +271,47 @@ declare function groupBy<T, K extends PropertyKey>(items: readonly T[], keyFn: (
  */
 declare function invert<K extends string, V extends PropertyKey>(obj: Record<K, V>): Record<V, K>;
 
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Checks if a plain object has no own enumerable string-keyed properties.
+ *
+ * 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
+ * @example
+ * isEmpty({})          // => true
+ * isEmpty({ a: 1 })    // => false
+ * isEmpty({ a: undefined }) // => false  (key exists)
+ * @since 2.0.3
+ */
+declare function isEmpty(value: Record<PropertyKey, unknown>): boolean;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Checks if a plain object has at least one own enumerable string-keyed property.
+ *
+ * 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
+ * @example
+ * isNonEmpty({ a: 1 })    // => true
+ * isNonEmpty({})          // => false
+ * @since 2.0.3
+ */
+declare function isNonEmpty(value: Record<PropertyKey, unknown>): boolean;
+
 /**
  * This file is part of helpers4.
  * Copyright (C) 2025 baxyz
@@ -344,15 +442,51 @@ declare function safeJsonParse<T>(input: string, fallback: T): T;
  * Copyright (C) 2025 baxyz
  * SPDX-License-Identifier: LGPL-3.0-or-later
  */
+
 /**
- * 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
+ * Sets a value in an object at the given path, creating intermediate objects as needed.
+ *
+ * **Three path forms are supported:**
+ *
+ * 1. **Dot notation** (`string`) — segments split on `.` are kept as-is string keys.
+ *    `"layers.1.name"` → keys `["layers", "1", "name"]` (all strings, including `"1"`).
+ *
+ * 2. **Bracket notation** (`string`) — `[n]` segments are parsed as numeric keys.
+ *    `"layers[1].name"` → keys `["layers", 1, "name"]` (index `1` becomes a number).
+ *    Dot and bracket can be mixed freely: `"a[0].b[2].c"`.
+ *
+ * 3. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,
+ *    no parsing performed. Enables full key-type control, including symbols:
+ *    `["layers", 1, Symbol('id')]`.
+ *
+ * Intermediate nodes that are absent, `null`, or not an object are replaced with `{}`.
+ * Any path containing a string segment equal to `__proto__`, `constructor`, or `prototype`
+ * is rejected and the original object is returned unchanged (prototype-pollution guard).
+ *
+ * @param obj - The object to mutate
+ * @param path - Dot/bracket-notation string or explicit `PropertyKey[]`
+ * @param value - Value to assign at the path
+ * @returns The mutated object (same reference)
+ * @example
+ * // 1. Dot notation — "1" stays a string key
+ * set({}, 'a.b.c', 42)
+ * // => { a: { b: { c: 42 } } }
+ *
+ * set({}, 'layers.1.name', 'bg')
+ * // => { layers: { '1': { name: 'bg' } } }
+ *
+ * // 2. Bracket notation — [1] becomes a number key
+ * set({ layers: [{}, { name: 'old' }] }, 'layers[1].name', 'bg')
+ * // => { layers: [{}, { name: 'bg' }] }
+ *
+ * // 3. Key array — supports symbols
+ * const id = Symbol('id')
+ * set({}, ['user', id], 'alice')
+ * // => { user: { [id]: 'alice' } }
  * @since 1.9.0
  */
 declare function set(obj: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
+declare function set<T extends object, const Path extends readonly PropertyKey[], V extends DeepGet<T, Path>>(obj: T, path: Path, value: V): DeepSet<T, Path, V>;
 
-export { compact, deepClone, deepMerge, diff, equalsDeep, equalsShallow, get, groupBy, invert, map, omit, pick, removeUndefinedNull, safeJsonParse, set };
+export { compact, deepClone, deepMerge, diff, equalsDeep, equalsShallow, get, groupBy, invert, isEmpty, isNonEmpty, map, omit, pick, removeUndefinedNull, safeJsonParse, set };
 export type { DiffOptions, DiffResult };

package/lib/index.js

@@ -6,17 +6,28 @@ function compact(obj) {
 	return result;
 }
 //#endregion
-//#region helpers/object/deepClone.ts
+//#region helpers/object/_unsafeKeys.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([
+/**
+* Keys that must never be set on a plain object (prototype-pollution guard).
+* @internal
+*/
+var UNSAFE_KEYS = new Set([
 	"__proto__",
 	"constructor",
 	"prototype"
 ]);
+//#endregion
+//#region helpers/object/deepClone.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
@@ -28,7 +39,7 @@ function deepClone(obj) {
 	if (obj instanceof Date) return new Date(obj.getTime());
 	if (Array.isArray(obj)) return obj.map((item) => deepClone(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] = deepClone(obj[key]);
 	return cloned;
 }
 //#endregion
@@ -66,22 +77,26 @@ function isPlainObject(value) {
 * Copyright (C) 2025 baxyz
 * SPDX-License-Identifier: LGPL-3.0-or-later
 */
-var UNSAFE_KEYS$1 = new Set([
-	"__proto__",
-	"constructor",
-	"prototype"
-]);
+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$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;
+		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);
 }
@@ -443,22 +458,70 @@ 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'`).
+*
+* @internal
+* @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(".");
+	const keys = typeof path === "string" ? parsePath(path) : path;
 	let result = obj;
 	for (const key of keys) {
 		if (result == null || typeof result !== "object") return defaultValue;
@@ -523,6 +586,53 @@ function invert(obj) {
 	return result;
 }
 //#endregion
+//#region helpers/object/isEmpty.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Checks if a plain object has no own enumerable string-keyed properties.
+*
+* 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
+* @example
+* isEmpty({})          // => true
+* isEmpty({ a: 1 })    // => false
+* isEmpty({ a: undefined }) // => false  (key exists)
+* @since 2.0.3
+*/
+function isEmpty(value) {
+	return Object.keys(value).length === 0;
+}
+//#endregion
+//#region helpers/object/isNonEmpty.ts
+/**
+* This file is part of helpers4.
+* Copyright (C) 2025 baxyz
+* SPDX-License-Identifier: LGPL-3.0-or-later
+*/
+/**
+* Checks if a plain object has at least one own enumerable string-keyed property.
+*
+* 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
+* @example
+* isNonEmpty({ a: 1 })    // => true
+* isNonEmpty({})          // => false
+* @since 2.0.3
+*/
+function isNonEmpty(value) {
+	return Object.keys(value).length > 0;
+}
+//#endregion
 //#region helpers/object/map.ts
 /**
 * This file is part of helpers4.
@@ -641,32 +751,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, map, omit, pick, removeUndefinedNull, safeJsonParse, set };
+export { compact, deepClone, deepMerge, diff, equalsDeep, equalsShallow, get, groupBy, invert, isEmpty, isNonEmpty, map, omit, pick, removeUndefinedNull, safeJsonParse, set };
 
 //# sourceMappingURL=index.js.map