@helpers4/object 2.0.3 → 2.1.0

package/README.md

@@ -12,9 +12,8 @@ A set of helpers for working with URLs.
 [https://helpers4.dev/typescript/categories/object/](https://helpers4.dev/typescript/categories/object/)
 
 <!-- AUTOMATIC-METHODS -->
+- cloneDeep
 - compact
-- deepClone
-- deepMerge
 - diff
 - equalsDeep
 - equalsShallow
@@ -24,6 +23,7 @@ A set of helpers for working with URLs.
 - isEmpty
 - isNonEmpty
 - map
+- mergeDeep
 - omit
 - pick
 - removeUndefinedNull

package/lib/index.d.ts

@@ -4,30 +4,31 @@
  * SPDX-License-Identifier: LGPL-3.0-or-later
  */
 /**
- * Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`) from an object.
- * @param obj - The source object
- * @returns A new object containing only entries with truthy values
+ * 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
- * compact({ a: 1, b: null, c: '', d: 0, e: 'hello' })
- * // => { a: 1, e: 'hello' }
- * @since 2.0.0
- */
-declare function compact<T extends Record<string, unknown>>(obj: T): Partial<T>;
-declare function compact(obj: undefined): undefined;
-declare function compact(obj: null): null;
-
-/**
- * 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
+ * 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
  */
-declare function deepClone<T>(obj: T): T;
+declare function cloneDeep<T>(obj: T): T;
 
 /**
  * This file is part of helpers4.
@@ -35,15 +36,17 @@ 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
- * @since 1.9.0
+ * Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`) from an object.
+ * @param obj - The source object
+ * @returns A new object containing only entries with truthy values
+ * @example
+ * compact({ a: 1, b: null, c: '', d: 0, e: 'hello' })
+ * // => { a: 1, e: 'hello' }
+ * @since 2.0.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 compact<T extends Record<string, unknown>>(obj: T): Partial<T>;
+declare function compact(obj: undefined): undefined;
+declare function compact(obj: null): null;
 
 /**
  * This file is part of helpers4.
@@ -163,14 +166,142 @@ 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
+ * Keys that must never be set on a plain object (prototype-pollution guard).
+ * @ignore
+ */
+declare const UNSAFE_KEY_LIST: readonly ["__proto__", "constructor", "prototype"];
+/** @ignore */
+type UnsafeKey = (typeof UNSAFE_KEY_LIST)[number];
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+
+/**
+ * Parses a `[n]` bracket index: numeric index strings become `number`, anything else stays `string`.
+ * @ignore
+ */
+type BracketKey<S extends string> = S extends `${number}` ? number : S;
+/**
+ * Parses consecutive bracket segments: `'[0][1]'` → `[0, 1]`.
+ * @ignore
+ */
+type ParseBrackets<S extends string> = S extends `[${infer Idx}]${infer Rest}` ? [BracketKey<Idx>, ...ParseBrackets<Rest>] : [];
+/**
+ * Parses a single dot-segment (no dots inside): `'arr[0]'` → `['arr', 0]`.
+ * @ignore
+ */
+type ParseSegment<S extends string> = S extends `${infer Name}[${infer Idx}]${infer Rest}` ? Name extends '' ? [BracketKey<Idx>, ...ParseBrackets<Rest>] : [Name, BracketKey<Idx>, ...ParseBrackets<Rest>] : [S];
+/**
+ * Converts a dot/bracket path string literal into a `PropertyKey` tuple.
+ *
+ * - Dot segments produce string keys: `'a.1'` → `['a', '1']`
+ * - Bracket segments produce number keys: `'a[1]'` → `['a', 1]`
+ *
+ * Limitation: edge-case paths handled specially at runtime (empty string `''`,
+ * bare `'.'`, consecutive dots `'a..b'`) are not modelled at the type level.
+ *
+ * @ignore
+ */
+type ParseStringPath<S extends string> = string extends S ? readonly PropertyKey[] : S extends `${infer Head}.${infer Tail}` ? [...ParseSegment<Head>, ...ParseStringPath<Tail>] : ParseSegment<S>;
+/**
+ * Normalises both path forms into a `PropertyKey` tuple for use with `DeepGet`/`DeepSet`.
+ * - `string` literal → parsed via `ParseStringPath`
+ * - `readonly PropertyKey[]` → used as-is
+ * @ignore
+ */
+type ParsePath<P extends string | readonly PropertyKey[]> = P extends string ? ParseStringPath<P> : P extends readonly PropertyKey[] ? P : never;
+/**
+ * Returns `true` if any key in the tuple is a prototype-polluting string.
+ * Used to make `set` return `T` unchanged (instead of a misleading `DeepSet` type)
+ * when the path is rejected by the runtime guard.
+ * @ignore
+ */
+type ContainsUnsafeStringKey<Keys extends readonly PropertyKey[]> = Keys extends readonly [infer K, ...infer Rest extends readonly PropertyKey[]] ? K extends UnsafeKey ? true : ContainsUnsafeStringKey<Rest> : false;
+/**
+ * Converts a union to an intersection: `A | B | C` → `A & B & C`.
+ * Used to derive the return type of `mergeDeep` from a tuple of source types.
+ * @ignore
+ */
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/**
+ * Return type of `mergeDeep`: intersection of all source types.
+ *
+ * @ignore
+ * @example
+ * MergeResult<[{ a: number }, { b: string }]>        // { a: number } & { b: string }
+ * MergeResult<[{ a: { b: number } }, { a: { c: string } }]>  // { a: { b: number } & { c: string } }
+ */
+type MergeResult<T extends object[]> = UnionToIntersection<T[number]>;
+/**
+ * Resolves the value type at a given path within T.
+ * Returns `unknown` when the path doesn't match the shape of T.
+ *
+ * @ignore
+ * @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.
+ *
+ * @ignore
+ * @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.
+ *    - Dot segments are always string keys: `'a.1'` → key `'1'` (string).
+ *    - Bracket segments are always number keys: `'a[1]'` → key `1` (number).
+ *    - String literal paths give **full compile-time type inference** on the return type.
+ *    - Dynamic (non-literal) strings return `unknown`.
+ *
+ * 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.
+ *
+ * Both forms support **all objects** (plain objects, arrays, class instances).
+ * Symbol keys are only reachable via the key-array form.
+ *
+ * @param obj - The object to read from
+ * @param path - Dot/bracket-notation string literal 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   (inferred: number | undefined)
+ * get({ layers: [{ name: 'bg' }] }, 'layers[0].name')  // => 'bg'  (inferred: string | undefined)
+ * get({ a: { b: 0 } }, 'a.b', 99)               // => 0  (falsy values returned as-is)
+ * get({ a: 1 }, 'b.c', 'default')               // => 'default'
+ *
+ * const id = Symbol('id')
+ * get({ [id]: 'alice' }, [id])                  // => 'alice'  (symbol key, inferred: string | undefined)
  * @since 1.9.0
  */
-declare function get<T = unknown>(obj: unknown, path: string, defaultValue?: T): T | undefined;
+declare function get<D>(obj: null | undefined, path: string | readonly PropertyKey[], defaultValue: D): D;
+declare function get(obj: null | undefined, path: string | readonly PropertyKey[]): undefined;
+declare function get<T extends object, const P extends string | readonly PropertyKey[]>(obj: T | null | undefined, path: P, defaultValue?: DeepGet<T, ParsePath<P>>): DeepGet<T, ParsePath<P>> | undefined;
 
 /**
  * This file is part of helpers4.
@@ -182,6 +313,9 @@ declare function get<T = unknown>(obj: unknown, path: string, defaultValue?: T):
  *
  * 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
@@ -189,9 +323,11 @@ declare function get<T = unknown>(obj: unknown, path: string, defaultValue?: T):
  * @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
  */
-declare function groupBy<T, K extends PropertyKey>(items: readonly T[], keyFn: (item: T) => K): Partial<Record<K, T[]>>;
+declare function groupBy<T, K extends PropertyKey>(items: readonly T[] | null | undefined, keyFn: (item: T) => K): Partial<Record<K, T[]>>;
 
 /**
  * This file is part of helpers4.
@@ -201,6 +337,9 @@ declare function groupBy<T, K extends PropertyKey>(items: readonly T[], 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
@@ -210,9 +349,12 @@ declare function groupBy<T, K extends PropertyKey>(items: readonly T[], keyFn: (
  *
  * invert({ one: 1, two: 2 })
  * // => { 1: 'one', 2: 'two' }
+ *
+ * invert(null)
+ * // => {}
  * @since 2.0.0
  */
-declare function invert<K extends string, V extends PropertyKey>(obj: Record<K, V>): Record<V, K>;
+declare function invert<K extends string, V extends PropertyKey>(obj: Record<K, V> | null | undefined): Record<V, K>;
 
 /**
  * This file is part of helpers4.
@@ -221,19 +363,22 @@ declare function invert<K extends string, V extends PropertyKey>(obj: Record<K,
  */
 /**
  * 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
  */
-declare function isEmpty(value: Record<PropertyKey, unknown>): boolean;
+declare function isEmpty(value: Record<PropertyKey, unknown> | null | undefined): boolean;
 
 /**
  * This file is part of helpers4.
@@ -242,18 +387,22 @@ declare function isEmpty(value: Record<PropertyKey, unknown>): boolean;
  */
 /**
  * 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
  */
-declare function isNonEmpty(value: Record<PropertyKey, unknown>): boolean;
+declare function isNonEmpty(value: Record<PropertyKey, unknown> | null | undefined): value is Record<PropertyKey, unknown>;
 
 /**
  * This file is part of helpers4.
@@ -268,7 +417,8 @@ declare function isNonEmpty(value: Record<PropertyKey, unknown>): boolean;
  * 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.
@@ -287,7 +437,69 @@ declare function isNonEmpty(value: Record<PropertyKey, unknown>): boolean;
  * // => { A: 10, B: 20 }
  * @since 2.0.0
  */
-declare function map<TObj extends Record<string, unknown>, TVal = TObj[keyof TObj], TKey extends PropertyKey = keyof TObj>(obj: TObj, mapValue?: (value: TObj[keyof TObj], key: keyof TObj) => TVal, mapKey?: (key: keyof TObj, value: TObj[keyof TObj]) => TKey): Record<TKey, TVal>;
+declare function map<TObj extends Record<string, unknown>, TVal = TObj[keyof TObj], TKey extends PropertyKey = keyof TObj>(obj: TObj | null | undefined, mapValue?: (value: TObj[keyof TObj], key: keyof TObj) => TVal, mapKey?: (key: keyof TObj, value: TObj[keyof TObj]) => TKey): Record<TKey, TVal>;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+
+/**
+ * Merges two or more objects deeply, returning a **new** object without mutating any input.
+ *
+ * Sources are applied left to right. For each key:
+ * - If both sides are plain objects → merged recursively into a new object.
+ * - Otherwise → **later source wins** (the earlier value is overwritten).
+ * - `undefined` in a source **never overwrites** an existing value.
+ * - `null` in a source **does overwrite** and prevents a later source from
+ *   deep-merging into that key: `mergeDeep({ a: { x: 1 } }, { a: null }, { a: { y: 2 } })`
+ *   → `{ a: { y: 2 } }` — `x: 1` is permanently lost.
+ * - Arrays, class instances, and all non-plain-object values are **replaced**, not merged.
+ *
+ * Own enumerable string and symbol keys of each source are processed at the top level;
+ * inherited and non-enumerable properties are skipped. Prototype-polluting keys
+ * (`__proto__`, `constructor`, `prototype`) are silently ignored.
+ * **Note:** symbol keys inside nested plain-object values are not preserved — they are
+ * lost when those values are deep-cloned. Only top-level symbol keys survive.
+ *
+ * **TypeScript return type — intersection semantics**
+ *
+ * The return type is `A & B & C …` (intersection of all source types). This is accurate
+ * when keys are disjoint or share the same type:
+ * ```ts
+ * mergeDeep({ a: 1 }, { b: 'x' })           // { a: number } & { b: string }  ✓
+ * mergeDeep({ a: { b: 1 } }, { a: { c: 2 } }) // { a: { b: number } & { c: number } }  ✓
+ * ```
+ * When the same key carries **incompatible types** across sources, the intersection
+ * resolves to `never` for that key — TypeScript surfaces the conflict rather than
+ * silently picking a type:
+ * ```ts
+ * mergeDeep({ a: 1 }, { a: 'x' })  // { a: never }  ← type conflict detected
+ * ```
+ * At runtime the later source always wins (`'x'`), but the `never` type signals that
+ * the caller should align their source types. If intentional, cast the result.
+ *
+ * @param sources - Two or more objects to merge (none are mutated)
+ * @returns A new object that is the deep merge of all sources
+ * @example
+ * mergeDeep({ a: 1, b: { c: 2 } }, { b: { d: 3 }, e: 4 })
+ * // => { a: 1, b: { c: 2, d: 3 }, e: 4 }
+ *
+ * // Later source wins for non-object values
+ * mergeDeep({ a: 1, arr: [1, 2] }, { a: 2, arr: [3] })
+ * // => { a: 2, arr: [3] }
+ *
+ * // undefined never overwrites
+ * mergeDeep({ a: 1 }, { a: undefined })
+ * // => { a: 1 }
+ *
+ * // Three sources, left to right
+ * mergeDeep({ x: 1 }, { y: 2 }, { x: 99, z: 3 })
+ * // => { x: 99, y: 2, z: 3 }
+ * @since 1.9.0
+ */
+declare function mergeDeep<T extends [object, ...object[]]>(...sources: [...T]): MergeResult<T>;
 
 /**
  * This file is part of helpers4.
@@ -385,15 +597,48 @@ 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.
+ *
+ * **Two path forms are supported:**
+ *
+ * 1. **String path** — dot notation and bracket notation, mixed freely.
+ *    - Dot segments are always string keys: `'layers.1.name'` → keys `['layers', '1', 'name']`.
+ *    - Bracket segments are always number keys: `'layers[1].name'` → keys `['layers', 1, 'name']`.
+ *    - String literal paths give **full compile-time type inference** on the return type.
+ *    - Dynamic (non-literal) strings return `T` (same object type).
+ *
+ * 2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,
+ *    no parsing performed. Enables symbol-keyed access and precise return-type inference.
+ *
+ * Both forms support **all objects** (plain objects, arrays, class instances).
+ * Symbol keys are only reachable via the key-array form.
+ *
+ * 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 literal or explicit `PropertyKey[]`
+ * @param value - Value to assign at the path
+ * @returns The mutated object (same reference, narrowed type)
+ * @example
+ * // Dot notation — "1" stays a string key
+ * set({}, 'a.b.c', 42)
+ * // => { a: { b: { c: 42 } } }
+ *
+ * // Bracket notation — [1] becomes a number key
+ * set({ layers: [{}, { name: 'old' }] }, 'layers[1].name', 'bg')
+ * // => { layers: [{}, { name: 'bg' }] }
+ *
+ * // 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 P extends string | readonly PropertyKey[], V extends DeepGet<T, ParsePath<P>>>(obj: T, path: P, value: V): string extends P ? T : readonly PropertyKey[] extends P ? T : ContainsUnsafeStringKey<ParsePath<P>> extends true ? T : DeepSet<T, ParsePath<P>, V>;
 
-export { compact, deepClone, deepMerge, diff, equalsDeep, equalsShallow, get, groupBy, invert, isEmpty, isNonEmpty, map, omit, pick, removeUndefinedNull, safeJsonParse, set };
+export { cloneDeep, compact, cloneDeep as deepClone, mergeDeep as deepMerge, diff, equalsDeep, equalsShallow, get, groupBy, invert, isEmpty, isNonEmpty, map, mergeDeep, omit, pick, removeUndefinedNull, safeJsonParse, set };
 export type { DiffOptions, DiffResult };