@helpers4/object 2.0.4 → 3.0.0-alpha.1

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
@@ -39,6 +39,7 @@ A set of helpers for working with URLs.
 - [commit](../commit)
 - [date](../date)
 - [function](../function)
+- [guard](../guard)
 - [id](../id)
 - [markdown](../markdown)
 - [node](../node)
@@ -61,6 +62,7 @@ A set of helpers for working with URLs.
 | commit | [@helpers4/commit](https://www.npmjs.com/package/@helpers4/commit) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/commit) | Conventional Commits parsing and analysis |
 | date | [@helpers4/date](https://www.npmjs.com/package/@helpers4/date) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/date) | Date and time utility functions |
 | function | [@helpers4/function](https://www.npmjs.com/package/@helpers4/function) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/function) | Function utilities and type guards |
+| guard | [@helpers4/guard](https://www.npmjs.com/package/@helpers4/guard) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/guard) | Runtime type guard utilities |
 | id | [@helpers4/id](https://www.npmjs.com/package/@helpers4/id) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/id) | Unique identifier generation utilities |
 | markdown | [@helpers4/markdown](https://www.npmjs.com/package/@helpers4/markdown) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/markdown) | Markdown formatting and escaping utilities |
 | node | [@helpers4/node](https://www.npmjs.com/package/@helpers4/node) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/node) | Node.js-specific utilities |
@@ -69,7 +71,7 @@ A set of helpers for working with URLs.
 | observable | [@helpers4/observable](https://www.npmjs.com/package/@helpers4/observable) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/observable) | Observable utilities and combinators |
 | promise | [@helpers4/promise](https://www.npmjs.com/package/@helpers4/promise) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/promise) | Promise utilities and error handling |
 | string | [@helpers4/string](https://www.npmjs.com/package/@helpers4/string) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/string) | String manipulation and formatting utilities |
-| type | [@helpers4/type](https://www.npmjs.com/package/@helpers4/type) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/type) | Type checking and validation utilities |
+| type | [@helpers4/type](https://www.npmjs.com/package/@helpers4/type) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/type) | Compile-time TypeScript utility types |
 | url | [@helpers4/url](https://www.npmjs.com/package/@helpers4/url) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/url) | URL parsing and manipulation utilities |
 | version | [@helpers4/version](https://www.npmjs.com/package/@helpers4/version) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/version) | Version string manipulation utilities |
 <!-- /AUTOMATIC-CATEGORIES-TABLE -->

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,21 +36,19 @@ declare function deepClone<T>(obj: T): T;
  * SPDX-License-Identifier: LGPL-3.0-or-later
  */
 /**
- * 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
+ * Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`) from an object.
+ * Own keys that are prototype-polluting strings (`__proto__`, `constructor`, `prototype`) are
+ * silently skipped.
+ * @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<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;
+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.
@@ -168,30 +167,109 @@ declare function equalsShallow(objA: unknown, objB: unknown): boolean;
  * 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).
+ * @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.
  *
- * @internal
+ * @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;
+/**
+ * Builds a brand-new nested object type from the remaining path segments and a leaf value type.
+ * Used by `DeepSet` once a path segment no longer matches an existing key on T.
+ * @ignore
+ */
+type BuildPath<Path extends readonly PropertyKey[], V> = Path extends readonly [infer K extends PropertyKey, ...infer Rest extends readonly PropertyKey[]] ? Record<K, BuildPath<Rest, V>> : V;
 /**
  * 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.
+ * When a key in Path is not present at the corresponding level of T, that level (and
+ * everything below it) is added as a new field instead of resolving to `never` — matching
+ * the runtime behavior of `set`, which creates intermediate objects as needed.
  *
- * @internal
+ * @ignore
  * @example
  * DeepSet<{ a: { b: number } }, ['a', 'b'], string>
  * // => { a: { b: string } }
+ * DeepSet<{ a: { b: number } }, ['a', 'c'], string>
+ * // => { a: { b: number } & { c: 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 ? {
+type DeepSet<T, Path extends readonly PropertyKey[], V> = Path extends readonly [] ? V : Path extends readonly [infer K extends PropertyKey, ...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;
+} : T & Record<K, BuildPath<Rest, V>> : never;
 
 /**
  * This file is part of helpers4.
@@ -205,29 +283,36 @@ type DeepSet<T, Path extends readonly PropertyKey[], V> = Path extends readonly
  * **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.
+ *    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 or explicit `PropertyKey[]`
+ * @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
- * get({ a: [1, 2, 3] }, 'a[1]')                 // => 2
- * get({ a: { b: 0 } }, 'a.b', 99)               // => 0  (falsy values are returned as-is)
+ * 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)
+ * 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<T extends object, const Path extends readonly PropertyKey[]>(obj: T, path: Path, defaultValue?: DeepGet<T, Path>): DeepGet<T, Path> | 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.
@@ -239,6 +324,9 @@ declare function get<T extends object, const Path extends readonly PropertyKey[]
  *
  * 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
@@ -246,9 +334,11 @@ declare function get<T extends object, const Path extends readonly PropertyKey[]
  * @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.
@@ -258,6 +348,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
@@ -267,9 +360,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.
@@ -278,19 +374,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.
@@ -299,18 +398,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.
@@ -325,7 +428,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.
@@ -344,7 +448,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.
@@ -372,6 +538,8 @@ declare function omit(obj: null, keys: readonly string[]): null;
  */
 /**
  * Creates a new object with only the specified keys.
+ * Keys that are prototype-polluting strings (`__proto__`, `constructor`, `prototype`) are
+ * silently skipped.
  * @param obj - The source object
  * @param keys - The keys to pick
  * @returns A new object with only the picked keys
@@ -446,47 +614,44 @@ declare function safeJsonParse<T>(input: string, fallback: T): T;
 /**
  * Sets a value in an object at the given path, creating intermediate objects as needed.
  *
- * **Three path forms are supported:**
+ * **Two 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"`).
+ * 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. **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"`.
+ * 2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,
+ *    no parsing performed. Enables symbol-keyed access and precise return-type inference.
  *
- * 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')]`.
+ * 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 or explicit `PropertyKey[]`
+ * @param path - Dot/bracket-notation string literal or explicit `PropertyKey[]`
  * @param value - Value to assign at the path
- * @returns The mutated object (same reference)
+ * @returns The mutated object (same reference, narrowed type)
  * @example
- * // 1. Dot notation — "1" stays a string key
+ * // 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
+ * // Bracket notation — [1] becomes a number key
  * set({ layers: [{}, { name: 'old' }] }, 'layers[1].name', 'bg')
  * // => { layers: [{}, { name: 'bg' }] }
  *
- * // 3. Key array — supports symbols
+ * // 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>;
+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, diff, equalsDeep, equalsShallow, get, groupBy, invert, isEmpty, isNonEmpty, map, mergeDeep, omit, pick, removeUndefinedNull, safeJsonParse, set };
 export type { DiffOptions, DiffResult };