@helpers4/object 2.0.4 → 2.1.0

package/meta/api.json

@@ -1,7 +1,43 @@
 {
   "category": "object",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "functions": [
+    {
+      "name": "cloneDeep",
+      "kind": "function",
+      "description": "Creates a deep copy of an object or array.\n\nRecursively clones own enumerable string keys. `Date` instances are\nreconstructed with the same epoch value. Prototype-polluting keys\n(`__proto__`, `constructor`, `prototype`) are silently skipped.\nDoes **not** handle circular references.\n\n**Limitation:** symbol-keyed own properties are **not** copied — only string\nkeys are processed. Use `structuredClone` if symbol propagation is required.",
+      "since": "1.9.0",
+      "signatures": [
+        {
+          "signature": "cloneDeep<T>(obj: T): T",
+          "description": "Creates a deep copy of an object or array.\n\nRecursively clones own enumerable string keys. `Date` instances are\nreconstructed with the same epoch value. Prototype-polluting keys\n(`__proto__`, `constructor`, `prototype`) are silently skipped.\nDoes **not** handle circular references.\n\n**Limitation:** symbol-keyed own properties are **not** copied — only string\nkeys are processed. Use `structuredClone` if symbol propagation is required.",
+          "params": [
+            {
+              "name": "obj",
+              "type": "T",
+              "description": "The value to clone"
+            }
+          ],
+          "returns": {
+            "type": "T",
+            "description": "A deep copy of `obj`"
+          },
+          "typeParameters": [
+            {
+              "name": "T"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Clone a nested object",
+          "description": "Creates a deep copy — modifying the clone does not affect the original.",
+          "code": "const original = { a: { b: 1 } };\nconst cloned = cloneDeep(original);\ncloned.a.b = 2;\n// original.a.b is still 1"
+        }
+      ],
+      "sourceFile": "cloneDeep.ts"
+    },
     {
       "name": "compact",
       "kind": "function",
@@ -74,124 +110,6 @@
       ],
       "sourceFile": "compact.ts"
     },
-    {
-      "name": "deepClone",
-      "kind": "function",
-      "description": "Creates a deep copy of an object or array",
-      "since": "1.9.0",
-      "signatures": [
-        {
-          "signature": "deepClone<T>(obj: T): T",
-          "description": "Creates a deep copy of an object or array",
-          "params": [
-            {
-              "name": "obj",
-              "type": "T",
-              "description": "The object to clone"
-            }
-          ],
-          "returns": {
-            "type": "T",
-            "description": "Deep cloned object"
-          },
-          "typeParameters": [
-            {
-              "name": "T"
-            }
-          ]
-        }
-      ],
-      "examples": [
-        {
-          "title": "Clone a nested object",
-          "description": "Creates a deep copy — modifying the clone does not affect the original.",
-          "code": "const original = { a: { b: 1 } };\nconst cloned = deepClone(original);\ncloned.a.b = 2;\n// original.a.b is still 1"
-        }
-      ],
-      "sourceFile": "deepClone.ts"
-    },
-    {
-      "name": "deepMerge",
-      "kind": "function",
-      "description": "Merges two or more objects deeply.\n\nRecursively merges own enumerable properties — both string and symbol keys.\nPlain objects are merged recursively; all other values (arrays, class instances,\nprimitives, etc.) are replaced by the source value.\n`undefined` source values do not overwrite existing target values.",
-      "since": "1.9.0",
-      "signatures": [
-        {
-          "signature": "deepMerge<T extends Record<PropertyKey, unknown>>(target: T, sources: Record<PropertyKey, unknown>[]): T",
-          "description": "Merges two or more objects deeply.\n\nRecursively merges own enumerable properties — both string and symbol keys.\nPlain objects are merged recursively; all other values (arrays, class instances,\nprimitives, etc.) are replaced by the source value.\n`undefined` source values do not overwrite existing target values.",
-          "params": [
-            {
-              "name": "target",
-              "type": "T",
-              "description": "The target object (mutated in place)"
-            },
-            {
-              "name": "sources",
-              "type": "Record<PropertyKey, unknown>[]",
-              "description": "One or more source objects to merge into the target"
-            }
-          ],
-          "returns": {
-            "type": "T",
-            "description": "The mutated target"
-          },
-          "typeParameters": [
-            {
-              "name": "T",
-              "constraint": "Record<PropertyKey, unknown>"
-            }
-          ]
-        },
-        {
-          "signature": "deepMerge(target: undefined, sources: Record<PropertyKey, unknown>[]): undefined",
-          "description": "Merges two or more objects deeply.\n\nRecursively merges own enumerable properties — both string and symbol keys.\nPlain objects are merged recursively; all other values (arrays, class instances,\nprimitives, etc.) are replaced by the source value.\n`undefined` source values do not overwrite existing target values.",
-          "params": [
-            {
-              "name": "target",
-              "type": "undefined",
-              "description": "The target object (mutated in place)"
-            },
-            {
-              "name": "sources",
-              "type": "Record<PropertyKey, unknown>[]",
-              "description": "One or more source objects to merge into the target"
-            }
-          ],
-          "returns": {
-            "type": "undefined",
-            "description": "The mutated target"
-          }
-        },
-        {
-          "signature": "deepMerge(target: null, sources: Record<PropertyKey, unknown>[]): null",
-          "description": "Merges two or more objects deeply.\n\nRecursively merges own enumerable properties — both string and symbol keys.\nPlain objects are merged recursively; all other values (arrays, class instances,\nprimitives, etc.) are replaced by the source value.\n`undefined` source values do not overwrite existing target values.",
-          "params": [
-            {
-              "name": "target",
-              "type": "null",
-              "description": "The target object (mutated in place)"
-            },
-            {
-              "name": "sources",
-              "type": "Record<PropertyKey, unknown>[]",
-              "description": "One or more source objects to merge into the target"
-            }
-          ],
-          "returns": {
-            "type": "null",
-            "description": "The mutated target"
-          }
-        }
-      ],
-      "examples": [
-        {
-          "title": "Merge two objects deeply",
-          "description": "Recursively merges source properties into the target object.",
-          "code": "deepMerge({ a: 1, b: { c: 2 } }, { b: { d: 3 }, e: 4 })\n// => { a: 1, b: { c: 2, d: 3 }, e: 4 }"
-        }
-      ],
-      "sourceFile": "deepMerge.ts"
-    },
     {
       "name": "diff",
       "kind": "function",
@@ -331,64 +249,82 @@
     {
       "name": "get",
       "kind": "function",
-      "description": "Gets a value from an object using a dot/bracket-notated path or explicit key array.\n\n**Two path forms are supported:**\n\n1. **String path** — dot notation (`'a.b.c'`) and bracket notation (`'layers[1].name'`)\n   are both accepted and mixed freely. Segments are traversed as string keys; `[n]`\n   indices become numeric keys.\n\n2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables symbol-keyed traversal and compile-time type inference:\n   `get(obj, ['a', 'b'] as const)` infers the return type from the path.",
+      "description": "Gets a value from an object using a dot/bracket-notated path or explicit key array.\n\n**Two path forms are supported:**\n\n1. **String path** — dot notation (`'a.b.c'`) and bracket notation (`'layers[1].name'`)\n   are both accepted and mixed freely.\n   - Dot segments are always string keys: `'a.1'` → key `'1'` (string).\n   - Bracket segments are always number keys: `'a[1]'` → key `1` (number).\n   - String literal paths give **full compile-time type inference** on the return type.\n   - Dynamic (non-literal) strings return `unknown`.\n\n2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables symbol-keyed traversal and compile-time type inference:\n   `get(obj, ['a', 'b'] as const)` infers the return type from the path.\n\nBoth forms support **all objects** (plain objects, arrays, class instances).\nSymbol keys are only reachable via the key-array form.",
       "since": "1.9.0",
       "signatures": [
         {
-          "signature": "get<T = unknown>(obj: unknown, path: string, defaultValue?: T): T | undefined",
-          "description": "Gets a value from an object using a dot/bracket-notated path or explicit key array.\n\n**Two path forms are supported:**\n\n1. **String path** — dot notation (`'a.b.c'`) and bracket notation (`'layers[1].name'`)\n   are both accepted and mixed freely. Segments are traversed as string keys; `[n]`\n   indices become numeric keys.\n\n2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables symbol-keyed traversal and compile-time type inference:\n   `get(obj, ['a', 'b'] as const)` infers the return type from the path.",
+          "signature": "get<D>(obj: null | undefined, path: string | readonly PropertyKey[], defaultValue: D): D",
+          "description": "Gets a value from an object using a dot/bracket-notated path or explicit key array.\n\n**Two path forms are supported:**\n\n1. **String path** — dot notation (`'a.b.c'`) and bracket notation (`'layers[1].name'`)\n   are both accepted and mixed freely.\n   - Dot segments are always string keys: `'a.1'` → key `'1'` (string).\n   - Bracket segments are always number keys: `'a[1]'` → key `1` (number).\n   - String literal paths give **full compile-time type inference** on the return type.\n   - Dynamic (non-literal) strings return `unknown`.\n\n2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables symbol-keyed traversal and compile-time type inference:\n   `get(obj, ['a', 'b'] as const)` infers the return type from the path.\n\nBoth forms support **all objects** (plain objects, arrays, class instances).\nSymbol keys are only reachable via the key-array form.",
           "params": [
             {
               "name": "obj",
-              "type": "unknown",
+              "type": "null | undefined",
               "description": "The object to read from"
             },
             {
               "name": "path",
-              "type": "string",
-              "description": "Dot/bracket-notation string or explicit `PropertyKey[]`"
+              "type": "string | readonly PropertyKey[]",
+              "description": "Dot/bracket-notation string literal or explicit `PropertyKey[]`"
             },
             {
               "name": "defaultValue",
-              "type": "T",
-              "description": "Returned when the path is absent or resolves to `undefined`",
-              "optional": true
+              "type": "D",
+              "description": "Returned when the path is absent or resolves to `undefined`"
             }
           ],
           "returns": {
-            "type": "T | undefined",
+            "type": "D",
             "description": "The value at the path, or `defaultValue`"
           },
           "typeParameters": [
             {
-              "name": "T",
-              "default": "unknown"
+              "name": "D"
             }
           ]
         },
         {
-          "signature": "get<T extends object, Path extends readonly PropertyKey[]>(obj: T, path: Path, defaultValue?: DeepGet<T, Path>): DeepGet<T, Path> | undefined",
-          "description": "Gets a value from an object using a dot/bracket-notated path or explicit key array.\n\n**Two path forms are supported:**\n\n1. **String path** — dot notation (`'a.b.c'`) and bracket notation (`'layers[1].name'`)\n   are both accepted and mixed freely. Segments are traversed as string keys; `[n]`\n   indices become numeric keys.\n\n2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables symbol-keyed traversal and compile-time type inference:\n   `get(obj, ['a', 'b'] as const)` infers the return type from the path.",
+          "signature": "get(obj: null | undefined, path: string | readonly PropertyKey[]): undefined",
+          "description": "Gets a value from an object using a dot/bracket-notated path or explicit key array.\n\n**Two path forms are supported:**\n\n1. **String path** — dot notation (`'a.b.c'`) and bracket notation (`'layers[1].name'`)\n   are both accepted and mixed freely.\n   - Dot segments are always string keys: `'a.1'` → key `'1'` (string).\n   - Bracket segments are always number keys: `'a[1]'` → key `1` (number).\n   - String literal paths give **full compile-time type inference** on the return type.\n   - Dynamic (non-literal) strings return `unknown`.\n\n2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables symbol-keyed traversal and compile-time type inference:\n   `get(obj, ['a', 'b'] as const)` infers the return type from the path.\n\nBoth forms support **all objects** (plain objects, arrays, class instances).\nSymbol keys are only reachable via the key-array form.",
           "params": [
             {
               "name": "obj",
-              "type": "T",
+              "type": "null | undefined",
+              "description": "The object to read from"
+            },
+            {
+              "name": "path",
+              "type": "string | readonly PropertyKey[]",
+              "description": "Dot/bracket-notation string literal or explicit `PropertyKey[]`"
+            }
+          ],
+          "returns": {
+            "type": "undefined",
+            "description": "The value at the path, or `defaultValue`"
+          }
+        },
+        {
+          "signature": "get<T extends object, P extends string | readonly PropertyKey[]>(obj: T | null | undefined, path: P, defaultValue?: DeepGet<T, ParsePath<P>>): DeepGet<T, ParsePath<P>> | undefined",
+          "description": "Gets a value from an object using a dot/bracket-notated path or explicit key array.\n\n**Two path forms are supported:**\n\n1. **String path** — dot notation (`'a.b.c'`) and bracket notation (`'layers[1].name'`)\n   are both accepted and mixed freely.\n   - Dot segments are always string keys: `'a.1'` → key `'1'` (string).\n   - Bracket segments are always number keys: `'a[1]'` → key `1` (number).\n   - String literal paths give **full compile-time type inference** on the return type.\n   - Dynamic (non-literal) strings return `unknown`.\n\n2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables symbol-keyed traversal and compile-time type inference:\n   `get(obj, ['a', 'b'] as const)` infers the return type from the path.\n\nBoth forms support **all objects** (plain objects, arrays, class instances).\nSymbol keys are only reachable via the key-array form.",
+          "params": [
+            {
+              "name": "obj",
+              "type": "T | null | undefined",
               "description": "The object to read from"
             },
             {
               "name": "path",
-              "type": "Path",
-              "description": "Dot/bracket-notation string or explicit `PropertyKey[]`"
+              "type": "P",
+              "description": "Dot/bracket-notation string literal or explicit `PropertyKey[]`"
             },
             {
               "name": "defaultValue",
-              "type": "DeepGet<T, Path>",
+              "type": "DeepGet<T, ParsePath<P>>",
               "description": "Returned when the path is absent or resolves to `undefined`",
               "optional": true
             }
           ],
           "returns": {
-            "type": "DeepGet<T, Path> | undefined",
+            "type": "DeepGet<T, ParsePath<P>> | undefined",
             "description": "The value at the path, or `defaultValue`"
           },
           "typeParameters": [
@@ -397,8 +333,8 @@
               "constraint": "object"
             },
             {
-              "name": "Path",
-              "constraint": "readonly PropertyKey[]"
+              "name": "P",
+              "constraint": "string | readonly PropertyKey[]"
             }
           ]
         }
@@ -425,16 +361,16 @@
     {
       "name": "groupBy",
       "kind": "function",
-      "description": "Groups an array of items by a key derived from each item.\n\nA thin, typed wrapper around `Object.groupBy` (ES2024) that works on\nolder targets and provides stricter return-type inference.",
+      "description": "Groups an array of items by a key derived from each item.\n\nA thin, typed wrapper around `Object.groupBy` (ES2024) that works on\nolder targets and provides stricter return-type inference.\n`null` and `undefined` are treated as empty arrays and return `{}`.\nItems whose computed key is a prototype-polluting string (`__proto__`,\n`constructor`, `prototype`) are silently skipped.",
       "since": "2.0.0",
       "signatures": [
         {
-          "signature": "groupBy<T, K extends PropertyKey>(items: readonly T[], keyFn: function): Partial<Record<K, T[]>>",
-          "description": "Groups an array of items by a key derived from each item.\n\nA thin, typed wrapper around `Object.groupBy` (ES2024) that works on\nolder targets and provides stricter return-type inference.",
+          "signature": "groupBy<T, K extends PropertyKey>(items: readonly T[] | null | undefined, keyFn: function): Partial<Record<K, T[]>>",
+          "description": "Groups an array of items by a key derived from each item.\n\nA thin, typed wrapper around `Object.groupBy` (ES2024) that works on\nolder targets and provides stricter return-type inference.\n`null` and `undefined` are treated as empty arrays and return `{}`.\nItems whose computed key is a prototype-polluting string (`__proto__`,\n`constructor`, `prototype`) are silently skipped.",
           "params": [
             {
               "name": "items",
-              "type": "readonly T[]",
+              "type": "readonly T[] | null | undefined",
               "description": "The array to group"
             },
             {
@@ -475,16 +411,16 @@
     {
       "name": "invert",
       "kind": "function",
-      "description": "Returns a new object with keys and values swapped.\nIf multiple keys share the same value, the last one wins.",
+      "description": "Returns a new object with keys and values swapped.\nIf multiple keys share the same value, the last one wins.\n`null` and `undefined` are treated as empty objects and return `{}`.\nEntries whose source key **or** value is a prototype-polluting string\n(`__proto__`, `constructor`, `prototype`) are silently skipped.",
       "since": "2.0.0",
       "signatures": [
         {
-          "signature": "invert<K extends string, V extends PropertyKey>(obj: Record<K, V>): Record<V, K>",
-          "description": "Returns a new object with keys and values swapped.\nIf multiple keys share the same value, the last one wins.",
+          "signature": "invert<K extends string, V extends PropertyKey>(obj: Record<K, V> | null | undefined): Record<V, K>",
+          "description": "Returns a new object with keys and values swapped.\nIf multiple keys share the same value, the last one wins.\n`null` and `undefined` are treated as empty objects and return `{}`.\nEntries whose source key **or** value is a prototype-polluting string\n(`__proto__`, `constructor`, `prototype`) are silently skipped.",
           "params": [
             {
               "name": "obj",
-              "type": "Record<K, V>",
+              "type": "Record<K, V> | null | undefined",
               "description": "The object whose keys and values are to be swapped"
             }
           ],
@@ -521,22 +457,22 @@
     {
       "name": "isEmpty",
       "kind": "function",
-      "description": "Checks if a plain object has no own enumerable string-keyed properties.\n\nSymbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`\nseparately if symbol keys matter for your use case.",
+      "description": "Checks if a plain object has no own enumerable string-keyed properties.\n`null` and `undefined` are treated as empty objects and return `true`.\n\nSymbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`\nseparately if symbol keys matter for your use case.",
       "since": "2.0.3",
       "signatures": [
         {
-          "signature": "isEmpty(value: Record<PropertyKey, unknown>): boolean",
-          "description": "Checks if a plain object has no own enumerable string-keyed properties.\n\nSymbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`\nseparately if symbol keys matter for your use case.",
+          "signature": "isEmpty(value: Record<PropertyKey, unknown> | null | undefined): boolean",
+          "description": "Checks if a plain object has no own enumerable string-keyed properties.\n`null` and `undefined` are treated as empty objects and return `true`.\n\nSymbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`\nseparately if symbol keys matter for your use case.",
           "params": [
             {
               "name": "value",
-              "type": "Record<PropertyKey, unknown>",
+              "type": "Record<PropertyKey, unknown> | null | undefined",
               "description": "The object to check"
             }
           ],
           "returns": {
             "type": "boolean",
-            "description": "`true` if the object has no own enumerable string-keyed properties"
+            "description": "`true` if the object has no own enumerable string-keyed properties, or if `value` is `null`/`undefined`"
           }
         }
       ],
@@ -557,22 +493,22 @@
     {
       "name": "isNonEmpty",
       "kind": "function",
-      "description": "Checks if a plain object has at least one own enumerable string-keyed property.\n\nSymbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`\nseparately if symbol keys matter for your use case.",
+      "description": "Checks if a plain object has at least one own enumerable string-keyed property.\n`null` and `undefined` are treated as empty objects and return `false`.\n\nSymbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`\nseparately if symbol keys matter for your use case.",
       "since": "2.0.3",
       "signatures": [
         {
-          "signature": "isNonEmpty(value: Record<PropertyKey, unknown>): boolean",
-          "description": "Checks if a plain object has at least one own enumerable string-keyed property.\n\nSymbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`\nseparately if symbol keys matter for your use case.",
+          "signature": "isNonEmpty(value: Record<PropertyKey, unknown> | null | undefined): value is Record<PropertyKey, unknown>",
+          "description": "Checks if a plain object has at least one own enumerable string-keyed property.\n`null` and `undefined` are treated as empty objects and return `false`.\n\nSymbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`\nseparately if symbol keys matter for your use case.",
           "params": [
             {
               "name": "value",
-              "type": "Record<PropertyKey, unknown>",
+              "type": "Record<PropertyKey, unknown> | null | undefined",
               "description": "The object to check"
             }
           ],
           "returns": {
-            "type": "boolean",
-            "description": "`true` if the object has at least one own enumerable string-keyed property"
+            "type": "value is Record<PropertyKey, unknown>",
+            "description": "`true` if the object has at least one own enumerable string-keyed property; `false` for empty, `null`, or `undefined`.\nActs as a type guard: the `if` branch narrows `Record<PropertyKey, unknown> | null | undefined` to `Record<PropertyKey, unknown>`."
           }
         }
       ],
@@ -593,16 +529,16 @@
     {
       "name": "map",
       "kind": "function",
-      "description": "Transforms the values and/or keys of a plain object in a single pass.\n\nBoth callbacks are optional and default to identity (no transformation).\nWhen `mapValue` is omitted the original values are preserved;\nwhen `mapKey` is omitted the original keys are preserved.\n\nNote: if two different keys map to the same output key the last one wins\n(insertion order).",
+      "description": "Transforms the values and/or keys of a plain object in a single pass.\n\nBoth callbacks are optional and default to identity (no transformation).\nWhen `mapValue` is omitted the original values are preserved;\nwhen `mapKey` is omitted the original keys are preserved.\n\nNote: if two different keys map to the same output key the last one wins\n(insertion order). Entries whose mapped key is a prototype-polluting string\n(`__proto__`, `constructor`, `prototype`) are silently skipped.",
       "since": "2.0.0",
       "signatures": [
         {
-          "signature": "map<TObj extends Record<string, unknown>, TVal = indexedAccess, TKey extends PropertyKey = keyof TObj>(obj: TObj, mapValue?: function, mapKey?: function): Record<TKey, TVal>",
-          "description": "Transforms the values and/or keys of a plain object in a single pass.\n\nBoth callbacks are optional and default to identity (no transformation).\nWhen `mapValue` is omitted the original values are preserved;\nwhen `mapKey` is omitted the original keys are preserved.\n\nNote: if two different keys map to the same output key the last one wins\n(insertion order).",
+          "signature": "map<TObj extends Record<string, unknown>, TVal = indexedAccess, TKey extends PropertyKey = keyof TObj>(obj: TObj | null | undefined, mapValue?: function, mapKey?: function): Record<TKey, TVal>",
+          "description": "Transforms the values and/or keys of a plain object in a single pass.\n\nBoth callbacks are optional and default to identity (no transformation).\nWhen `mapValue` is omitted the original values are preserved;\nwhen `mapKey` is omitted the original keys are preserved.\n\nNote: if two different keys map to the same output key the last one wins\n(insertion order). Entries whose mapped key is a prototype-polluting string\n(`__proto__`, `constructor`, `prototype`) are silently skipped.",
           "params": [
             {
               "name": "obj",
-              "type": "TObj",
+              "type": "TObj | null | undefined",
               "description": "The source object"
             },
             {
@@ -658,6 +594,43 @@
       ],
       "sourceFile": "map.ts"
     },
+    {
+      "name": "mergeDeep",
+      "kind": "function",
+      "description": "Merges two or more objects deeply, returning a **new** object without mutating any input.\n\nSources are applied left to right. For each key:\n- If both sides are plain objects → merged recursively into a new object.\n- Otherwise → **later source wins** (the earlier value is overwritten).\n- `undefined` in a source **never overwrites** an existing value.\n- `null` in a source **does overwrite** and prevents a later source from\n  deep-merging into that key: `mergeDeep({ a: { x: 1 } }, { a: null }, { a: { y: 2 } })`\n  → `{ a: { y: 2 } }` — `x: 1` is permanently lost.\n- Arrays, class instances, and all non-plain-object values are **replaced**, not merged.\n\nOwn enumerable string and symbol keys of each source are processed at the top level;\ninherited and non-enumerable properties are skipped. Prototype-polluting keys\n(`__proto__`, `constructor`, `prototype`) are silently ignored.\n**Note:** symbol keys inside nested plain-object values are not preserved — they are\nlost when those values are deep-cloned. Only top-level symbol keys survive.\n\n**TypeScript return type — intersection semantics**\n\nThe return type is `A & B & C …` (intersection of all source types). This is accurate\nwhen keys are disjoint or share the same type:\n```ts\nmergeDeep({ a: 1 }, { b: 'x' })           // { a: number } & { b: string }  ✓\nmergeDeep({ a: { b: 1 } }, { a: { c: 2 } }) // { a: { b: number } & { c: number } }  ✓\n```\nWhen the same key carries **incompatible types** across sources, the intersection\nresolves to `never` for that key — TypeScript surfaces the conflict rather than\nsilently picking a type:\n```ts\nmergeDeep({ a: 1 }, { a: 'x' })  // { a: never }  ← type conflict detected\n```\nAt runtime the later source always wins (`'x'`), but the `never` type signals that\nthe caller should align their source types. If intentional, cast the result.",
+      "since": "1.9.0",
+      "signatures": [
+        {
+          "signature": "mergeDeep<T extends [object, rest]>(sources: [rest]): MergeResult<T>",
+          "description": "Merges two or more objects deeply, returning a **new** object without mutating any input.\n\nSources are applied left to right. For each key:\n- If both sides are plain objects → merged recursively into a new object.\n- Otherwise → **later source wins** (the earlier value is overwritten).\n- `undefined` in a source **never overwrites** an existing value.\n- `null` in a source **does overwrite** and prevents a later source from\n  deep-merging into that key: `mergeDeep({ a: { x: 1 } }, { a: null }, { a: { y: 2 } })`\n  → `{ a: { y: 2 } }` — `x: 1` is permanently lost.\n- Arrays, class instances, and all non-plain-object values are **replaced**, not merged.\n\nOwn enumerable string and symbol keys of each source are processed at the top level;\ninherited and non-enumerable properties are skipped. Prototype-polluting keys\n(`__proto__`, `constructor`, `prototype`) are silently ignored.\n**Note:** symbol keys inside nested plain-object values are not preserved — they are\nlost when those values are deep-cloned. Only top-level symbol keys survive.\n\n**TypeScript return type — intersection semantics**\n\nThe return type is `A & B & C …` (intersection of all source types). This is accurate\nwhen keys are disjoint or share the same type:\n```ts\nmergeDeep({ a: 1 }, { b: 'x' })           // { a: number } & { b: string }  ✓\nmergeDeep({ a: { b: 1 } }, { a: { c: 2 } }) // { a: { b: number } & { c: number } }  ✓\n```\nWhen the same key carries **incompatible types** across sources, the intersection\nresolves to `never` for that key — TypeScript surfaces the conflict rather than\nsilently picking a type:\n```ts\nmergeDeep({ a: 1 }, { a: 'x' })  // { a: never }  ← type conflict detected\n```\nAt runtime the later source always wins (`'x'`), but the `never` type signals that\nthe caller should align their source types. If intentional, cast the result.",
+          "params": [
+            {
+              "name": "sources",
+              "type": "[rest]",
+              "description": "Two or more objects to merge (none are mutated)"
+            }
+          ],
+          "returns": {
+            "type": "MergeResult<T>",
+            "description": "A new object that is the deep merge of all sources"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "constraint": "[object, rest]"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Merge two objects deeply",
+          "description": "Returns a new object — neither input is mutated.",
+          "code": "mergeDeep({ a: 1, b: { c: 2 } }, { b: { d: 3 }, e: 4 })\n// => { a: 1, b: { c: 2, d: 3 }, e: 4 }"
+        }
+      ],
+      "sourceFile": "mergeDeep.ts"
+    },
     {
       "name": "omit",
       "kind": "function",
@@ -981,37 +954,12 @@
     {
       "name": "set",
       "kind": "function",
-      "description": "Sets a value in an object at the given path, creating intermediate objects as needed.\n\n**Three path forms are supported:**\n\n1. **Dot notation** (`string`) — segments split on `.` are kept as-is string keys.\n   `\"layers.1.name\"` → keys `[\"layers\", \"1\", \"name\"]` (all strings, including `\"1\"`).\n\n2. **Bracket notation** (`string`) — `[n]` segments are parsed as numeric keys.\n   `\"layers[1].name\"` → keys `[\"layers\", 1, \"name\"]` (index `1` becomes a number).\n   Dot and bracket can be mixed freely: `\"a[0].b[2].c\"`.\n\n3. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables full key-type control, including symbols:\n   `[\"layers\", 1, Symbol('id')]`.\n\nIntermediate nodes that are absent, `null`, or not an object are replaced with `{}`.\nAny path containing a string segment equal to `__proto__`, `constructor`, or `prototype`\nis rejected and the original object is returned unchanged (prototype-pollution guard).",
+      "description": "Sets a value in an object at the given path, creating intermediate objects as needed.\n\n**Two path forms are supported:**\n\n1. **String path** — dot notation and bracket notation, mixed freely.\n   - Dot segments are always string keys: `'layers.1.name'` → keys `['layers', '1', 'name']`.\n   - Bracket segments are always number keys: `'layers[1].name'` → keys `['layers', 1, 'name']`.\n   - String literal paths give **full compile-time type inference** on the return type.\n   - Dynamic (non-literal) strings return `T` (same object type).\n\n2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables symbol-keyed access and precise return-type inference.\n\nBoth forms support **all objects** (plain objects, arrays, class instances).\nSymbol keys are only reachable via the key-array form.\n\nIntermediate nodes that are absent, `null`, or not an object are replaced with `{}`.\nAny path containing a string segment equal to `__proto__`, `constructor`, or `prototype`\nis rejected and the original object is returned unchanged (prototype-pollution guard).",
       "since": "1.9.0",
       "signatures": [
         {
-          "signature": "set(obj: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>",
-          "description": "Sets a value in an object at the given path, creating intermediate objects as needed.\n\n**Three path forms are supported:**\n\n1. **Dot notation** (`string`) — segments split on `.` are kept as-is string keys.\n   `\"layers.1.name\"` → keys `[\"layers\", \"1\", \"name\"]` (all strings, including `\"1\"`).\n\n2. **Bracket notation** (`string`) — `[n]` segments are parsed as numeric keys.\n   `\"layers[1].name\"` → keys `[\"layers\", 1, \"name\"]` (index `1` becomes a number).\n   Dot and bracket can be mixed freely: `\"a[0].b[2].c\"`.\n\n3. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables full key-type control, including symbols:\n   `[\"layers\", 1, Symbol('id')]`.\n\nIntermediate nodes that are absent, `null`, or not an object are replaced with `{}`.\nAny path containing a string segment equal to `__proto__`, `constructor`, or `prototype`\nis rejected and the original object is returned unchanged (prototype-pollution guard).",
-          "params": [
-            {
-              "name": "obj",
-              "type": "Record<string, unknown>",
-              "description": "The object to mutate"
-            },
-            {
-              "name": "path",
-              "type": "string",
-              "description": "Dot/bracket-notation string or explicit `PropertyKey[]`"
-            },
-            {
-              "name": "value",
-              "type": "unknown",
-              "description": "Value to assign at the path"
-            }
-          ],
-          "returns": {
-            "type": "Record<string, unknown>",
-            "description": "The mutated object (same reference)"
-          }
-        },
-        {
-          "signature": "set<T extends object, Path extends readonly PropertyKey[], V extends unknown>(obj: T, path: Path, value: V): DeepSet<T, Path, V>",
-          "description": "Sets a value in an object at the given path, creating intermediate objects as needed.\n\n**Three path forms are supported:**\n\n1. **Dot notation** (`string`) — segments split on `.` are kept as-is string keys.\n   `\"layers.1.name\"` → keys `[\"layers\", \"1\", \"name\"]` (all strings, including `\"1\"`).\n\n2. **Bracket notation** (`string`) — `[n]` segments are parsed as numeric keys.\n   `\"layers[1].name\"` → keys `[\"layers\", 1, \"name\"]` (index `1` becomes a number).\n   Dot and bracket can be mixed freely: `\"a[0].b[2].c\"`.\n\n3. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables full key-type control, including symbols:\n   `[\"layers\", 1, Symbol('id')]`.\n\nIntermediate nodes that are absent, `null`, or not an object are replaced with `{}`.\nAny path containing a string segment equal to `__proto__`, `constructor`, or `prototype`\nis rejected and the original object is returned unchanged (prototype-pollution guard).",
+          "signature": "set<T extends object, P extends string | readonly PropertyKey[], V extends unknown>(obj: T, path: P, value: V): conditional",
+          "description": "Sets a value in an object at the given path, creating intermediate objects as needed.\n\n**Two path forms are supported:**\n\n1. **String path** — dot notation and bracket notation, mixed freely.\n   - Dot segments are always string keys: `'layers.1.name'` → keys `['layers', '1', 'name']`.\n   - Bracket segments are always number keys: `'layers[1].name'` → keys `['layers', 1, 'name']`.\n   - String literal paths give **full compile-time type inference** on the return type.\n   - Dynamic (non-literal) strings return `T` (same object type).\n\n2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,\n   no parsing performed. Enables symbol-keyed access and precise return-type inference.\n\nBoth forms support **all objects** (plain objects, arrays, class instances).\nSymbol keys are only reachable via the key-array form.\n\nIntermediate nodes that are absent, `null`, or not an object are replaced with `{}`.\nAny path containing a string segment equal to `__proto__`, `constructor`, or `prototype`\nis rejected and the original object is returned unchanged (prototype-pollution guard).",
           "params": [
             {
               "name": "obj",
@@ -1020,8 +968,8 @@
             },
             {
               "name": "path",
-              "type": "Path",
-              "description": "Dot/bracket-notation string or explicit `PropertyKey[]`"
+              "type": "P",
+              "description": "Dot/bracket-notation string literal or explicit `PropertyKey[]`"
             },
             {
               "name": "value",
@@ -1030,8 +978,8 @@
             }
           ],
           "returns": {
-            "type": "DeepSet<T, Path, V>",
-            "description": "The mutated object (same reference)"
+            "type": "conditional",
+            "description": "The mutated object (same reference, narrowed type)"
           },
           "typeParameters": [
             {
@@ -1039,8 +987,8 @@
               "constraint": "object"
             },
             {
-              "name": "Path",
-              "constraint": "readonly PropertyKey[]"
+              "name": "P",
+              "constraint": "string | readonly PropertyKey[]"
             },
             {
               "name": "V",

package/meta/examples.json

@@ -1,6 +1,16 @@
 {
   "category": "object",
   "functions": [
+    {
+      "name": "cloneDeep",
+      "examples": [
+        {
+          "title": "Clone a nested object",
+          "description": "Creates a deep copy — modifying the clone does not affect the original.",
+          "code": "const original = { a: { b: 1 } };\nconst cloned = cloneDeep(original);\ncloned.a.b = 2;\n// original.a.b is still 1"
+        }
+      ]
+    },
     {
       "name": "compact",
       "examples": [
@@ -16,26 +26,6 @@
         }
       ]
     },
-    {
-      "name": "deepClone",
-      "examples": [
-        {
-          "title": "Clone a nested object",
-          "description": "Creates a deep copy — modifying the clone does not affect the original.",
-          "code": "const original = { a: { b: 1 } };\nconst cloned = deepClone(original);\ncloned.a.b = 2;\n// original.a.b is still 1"
-        }
-      ]
-    },
-    {
-      "name": "deepMerge",
-      "examples": [
-        {
-          "title": "Merge two objects deeply",
-          "description": "Recursively merges source properties into the target object.",
-          "code": "deepMerge({ a: 1, b: { c: 2 } }, { b: { d: 3 }, e: 4 })\n// => { a: 1, b: { c: 2, d: 3 }, e: 4 }"
-        }
-      ]
-    },
     {
       "name": "diff",
       "examples": [
@@ -176,6 +166,16 @@
         }
       ]
     },
+    {
+      "name": "mergeDeep",
+      "examples": [
+        {
+          "title": "Merge two objects deeply",
+          "description": "Returns a new object — neither input is mutated.",
+          "code": "mergeDeep({ a: 1, b: { c: 2 } }, { b: { d: 3 }, e: 4 })\n// => { a: 1, b: { c: 2, d: 3 }, e: 4 }"
+        }
+      ]
+    },
     {
       "name": "omit",
       "examples": [

package/meta/native-alternatives.json

@@ -44,7 +44,7 @@
       "native": "{ ...a, ...b } or Object.assign({}, a, b)",
       "since": "ES2015",
       "example": "const merged = { ...defaults, ...options }",
-      "notes": "For deep merge, use deepMerge from helpers4"
+      "notes": "For deep merge, use mergeDeep from helpers4"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpers4/object",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "A set of helpers in TS/JS, compatible with tree-shaking, for object.",
   "author": "baxyz <baxy@etik.com>",
   "license": "LGPL-3.0",
@@ -27,9 +27,8 @@
   "keywords": [
     "helpers",
     "object",
+    "cloneDeep",
     "compact",
-    "deepClone",
-    "deepMerge",
     "diff",
     "equalsDeep",
     "equalsShallow",
@@ -39,6 +38,7 @@
     "isEmpty",
     "isNonEmpty",
     "map",
+    "mergeDeep",
     "omit",
     "pick",
     "removeUndefinedNull",