@helpers4/object 2.0.3 → 2.1.0

package/meta/api.json

@@ -1,98 +1,26 @@
 {
   "category": "object",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "functions": [
     {
-      "name": "compact",
-      "kind": "function",
-      "description": "Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `\"\"`, `NaN`) from an object.",
-      "since": "2.0.0",
-      "signatures": [
-        {
-          "signature": "compact<T extends Record<string, unknown>>(obj: T): Partial<T>",
-          "description": "Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `\"\"`, `NaN`) from an object.",
-          "params": [
-            {
-              "name": "obj",
-              "type": "T",
-              "description": "The source object"
-            }
-          ],
-          "returns": {
-            "type": "Partial<T>",
-            "description": "A new object containing only entries with truthy values"
-          },
-          "typeParameters": [
-            {
-              "name": "T",
-              "constraint": "Record<string, unknown>"
-            }
-          ]
-        },
-        {
-          "signature": "compact(obj: undefined): undefined",
-          "description": "Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `\"\"`, `NaN`) from an object.",
-          "params": [
-            {
-              "name": "obj",
-              "type": "undefined",
-              "description": "The source object"
-            }
-          ],
-          "returns": {
-            "type": "undefined",
-            "description": "A new object containing only entries with truthy values"
-          }
-        },
-        {
-          "signature": "compact(obj: null): null",
-          "description": "Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `\"\"`, `NaN`) from an object.",
-          "params": [
-            {
-              "name": "obj",
-              "type": "null",
-              "description": "The source object"
-            }
-          ],
-          "returns": {
-            "type": "null",
-            "description": "A new object containing only entries with truthy values"
-          }
-        }
-      ],
-      "examples": [
-        {
-          "title": "Remove falsy values from object",
-          "description": "Removes all entries with falsy values (false, null, undefined, 0, \"\", NaN).",
-          "code": "compact({ a: 1, b: null, c: '', d: 0, e: 'hello' })\n// => { a: 1, e: 'hello' }"
-        },
-        {
-          "title": "Clean up API response",
-          "description": "Useful to strip empty or missing fields before sending data.",
-          "code": "compact({ name: 'Alice', email: '', age: 0, role: 'admin' })\n// => { name: 'Alice', role: 'admin' }"
-        }
-      ],
-      "sourceFile": "compact.ts"
-    },
-    {
-      "name": "deepClone",
+      "name": "cloneDeep",
       "kind": "function",
-      "description": "Creates a deep copy of an object or array",
+      "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": "deepClone<T>(obj: T): T",
-          "description": "Creates a deep copy of an object or array",
+          "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 object to clone"
+              "description": "The value to clone"
             }
           ],
           "returns": {
             "type": "T",
-            "description": "Deep cloned object"
+            "description": "A deep copy of `obj`"
           },
           "typeParameters": [
             {
@@ -105,35 +33,30 @@
         {
           "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"
+          "code": "const original = { a: { b: 1 } };\nconst cloned = cloneDeep(original);\ncloned.a.b = 2;\n// original.a.b is still 1"
         }
       ],
-      "sourceFile": "deepClone.ts"
+      "sourceFile": "cloneDeep.ts"
     },
     {
-      "name": "deepMerge",
+      "name": "compact",
       "kind": "function",
-      "description": "Merges two or more objects deeply",
-      "since": "1.9.0",
+      "description": "Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `\"\"`, `NaN`) from an object.",
+      "since": "2.0.0",
       "signatures": [
         {
-          "signature": "deepMerge<T extends Record<string, unknown>>(target: T, sources: Record<string, unknown>[]): T",
-          "description": "Merges two or more objects deeply",
+          "signature": "compact<T extends Record<string, unknown>>(obj: T): Partial<T>",
+          "description": "Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `\"\"`, `NaN`) from an object.",
           "params": [
             {
-              "name": "target",
+              "name": "obj",
               "type": "T",
-              "description": "The target object"
-            },
-            {
-              "name": "sources",
-              "type": "Record<string, unknown>[]",
-              "description": "The source objects to merge"
+              "description": "The source object"
             }
           ],
           "returns": {
-            "type": "T",
-            "description": "The merged object"
+            "type": "Partial<T>",
+            "description": "A new object containing only entries with truthy values"
           },
           "typeParameters": [
             {
@@ -143,54 +66,49 @@
           ]
         },
         {
-          "signature": "deepMerge(target: undefined, sources: Record<string, unknown>[]): undefined",
-          "description": "Merges two or more objects deeply",
+          "signature": "compact(obj: undefined): undefined",
+          "description": "Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `\"\"`, `NaN`) from an object.",
           "params": [
             {
-              "name": "target",
+              "name": "obj",
               "type": "undefined",
-              "description": "The target object"
-            },
-            {
-              "name": "sources",
-              "type": "Record<string, unknown>[]",
-              "description": "The source objects to merge"
+              "description": "The source object"
             }
           ],
           "returns": {
             "type": "undefined",
-            "description": "The merged object"
+            "description": "A new object containing only entries with truthy values"
           }
         },
         {
-          "signature": "deepMerge(target: null, sources: Record<string, unknown>[]): null",
-          "description": "Merges two or more objects deeply",
+          "signature": "compact(obj: null): null",
+          "description": "Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `\"\"`, `NaN`) from an object.",
           "params": [
             {
-              "name": "target",
+              "name": "obj",
               "type": "null",
-              "description": "The target object"
-            },
-            {
-              "name": "sources",
-              "type": "Record<string, unknown>[]",
-              "description": "The source objects to merge"
+              "description": "The source object"
             }
           ],
           "returns": {
             "type": "null",
-            "description": "The merged object"
+            "description": "A new object containing only entries with truthy values"
           }
         }
       ],
       "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 }"
+          "title": "Remove falsy values from object",
+          "description": "Removes all entries with falsy values (false, null, undefined, 0, \"\", NaN).",
+          "code": "compact({ a: 1, b: null, c: '', d: 0, e: 'hello' })\n// => { a: 1, e: 'hello' }"
+        },
+        {
+          "title": "Clean up API response",
+          "description": "Useful to strip empty or missing fields before sending data.",
+          "code": "compact({ name: 'Alice', email: '', age: 0, role: 'admin' })\n// => { name: 'Alice', role: 'admin' }"
         }
       ],
-      "sourceFile": "deepMerge.ts"
+      "sourceFile": "compact.ts"
     },
     {
       "name": "diff",
@@ -331,38 +249,92 @@
     {
       "name": "get",
       "kind": "function",
-      "description": "Gets a value from an object using a dot-notated 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-notated 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",
-              "description": "The object to get value from"
+              "type": "null | undefined",
+              "description": "The object to read from"
             },
             {
               "name": "path",
-              "type": "string",
-              "description": "The dot-notated path (e.g., 'a.b.c')"
+              "type": "string | readonly PropertyKey[]",
+              "description": "Dot/bracket-notation string literal or explicit `PropertyKey[]`"
             },
             {
               "name": "defaultValue",
-              "type": "T",
-              "description": "Default value if path doesn't exist",
+              "type": "D",
+              "description": "Returned when the path is absent or resolves to `undefined`"
+            }
+          ],
+          "returns": {
+            "type": "D",
+            "description": "The value at the path, or `defaultValue`"
+          },
+          "typeParameters": [
+            {
+              "name": "D"
+            }
+          ]
+        },
+        {
+          "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": "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": "P",
+              "description": "Dot/bracket-notation string literal or explicit `PropertyKey[]`"
+            },
+            {
+              "name": "defaultValue",
+              "type": "DeepGet<T, ParsePath<P>>",
+              "description": "Returned when the path is absent or resolves to `undefined`",
               "optional": true
             }
           ],
           "returns": {
-            "type": "T | undefined",
-            "description": "The value at the path or default value"
+            "type": "DeepGet<T, ParsePath<P>> | undefined",
+            "description": "The value at the path, or `defaultValue`"
           },
           "typeParameters": [
             {
               "name": "T",
-              "default": "unknown"
+              "constraint": "object"
+            },
+            {
+              "name": "P",
+              "constraint": "string | readonly PropertyKey[]"
             }
           ]
         }
@@ -377,6 +349,11 @@
           "title": "Return default for missing path",
           "description": "Returns the default value when the path does not exist.",
           "code": "get({ a: 1 }, 'b.c', 'default')\n// => 'default'"
+        },
+        {
+          "title": "Get via key array (supports symbols)",
+          "description": "Pass an explicit PropertyKey[] to bypass parsing. Supports string, number, and symbol keys.",
+          "code": "const id = Symbol('id')\nget({ [id]: 'alice' }, [id])\n// => 'alice'"
         }
       ],
       "sourceFile": "get.ts"
@@ -384,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"
             },
             {
@@ -434,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"
             }
           ],
@@ -480,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`"
           }
         }
       ],
@@ -516,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>`."
           }
         }
       ],
@@ -552,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"
             },
             {
@@ -617,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",
@@ -940,40 +954,64 @@
     {
       "name": "set",
       "kind": "function",
-      "description": "Sets a value in an object using a dot-notated path",
+      "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 using a dot-notated path",
+          "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",
-              "type": "Record<string, unknown>",
-              "description": "The object to set value in"
+              "type": "T",
+              "description": "The object to mutate"
             },
             {
               "name": "path",
-              "type": "string",
-              "description": "The dot-notated path (e.g., 'a.b.c')"
+              "type": "P",
+              "description": "Dot/bracket-notation string literal or explicit `PropertyKey[]`"
             },
             {
               "name": "value",
-              "type": "unknown",
-              "description": "The value to set"
+              "type": "V",
+              "description": "Value to assign at the path"
             }
           ],
           "returns": {
-            "type": "Record<string, unknown>",
-            "description": "The modified object"
-          }
+            "type": "conditional",
+            "description": "The mutated object (same reference, narrowed type)"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "constraint": "object"
+            },
+            {
+              "name": "P",
+              "constraint": "string | readonly PropertyKey[]"
+            },
+            {
+              "name": "V",
+              "constraint": "unknown"
+            }
+          ]
         }
       ],
       "examples": [
         {
-          "title": "Set a nested property",
-          "description": "Creates intermediate objects as needed along the dot-notated path.",
-          "code": "set({}, 'a.b.c', 42)\n// => { a: { b: { c: 42 } } }"
+          "title": "Set a nested property (dot notation)",
+          "description": "Creates intermediate objects as needed. All segments are string keys — including numeric-looking ones like \"1\".",
+          "code": "set({}, 'a.b.c', 42)\n// => { a: { b: { c: 42 } } }\n\nset({}, 'layers.1.name', 'bg')\n// => { layers: { '1': { name: 'bg' } } }   // '1' is a string key"
+        },
+        {
+          "title": "Set via bracket notation",
+          "description": "Square-bracket indices become numeric keys. Useful when the path targets an array element.",
+          "code": "const obj = { layers: [{}, { name: 'old' }] }\nset(obj, 'layers[1].name', 'new')\n// => { layers: [{}, { name: 'new' }] }"
+        },
+        {
+          "title": "Set via key array (supports symbols)",
+          "description": "Pass an explicit PropertyKey[] to bypass parsing. Supports string, number, and symbol keys.",
+          "code": "const id = Symbol('id')\nset({}, ['user', id], 'alice')\n// => { user: { [id]: 'alice' } }"
         }
       ],
       "sourceFile": "set.ts"