@helpers4/object 3.0.2 → 3.0.3

package/meta/api.json

@@ -1,7 +1,48 @@
 {
   "category": "object",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "functions": [
+    {
+      "name": "camelCaseKeys",
+      "kind": "function",
+      "description": "Recursively transforms every key of a plain object (including keys nested inside arrays and\nnested objects) to camelCase. Handles snake_case, kebab-case, PascalCase, and space-separated\nkeys. Non-plain-object values (arrays' items aside) — `Date`, `Map`, `Set`, class instances,\nprimitives — are left untouched, only their position is walked into. An entry whose\ntransformed key is a prototype-polluting string (`__proto__`, `constructor`, `prototype`) is\nsilently skipped, same as the rest of `@helpers4/object`.",
+      "since": "3.0.3",
+      "signatures": [
+        {
+          "signature": "camelCaseKeys<T>(value: T): T",
+          "description": "Recursively transforms every key of a plain object (including keys nested inside arrays and\nnested objects) to camelCase. Handles snake_case, kebab-case, PascalCase, and space-separated\nkeys. Non-plain-object values (arrays' items aside) — `Date`, `Map`, `Set`, class instances,\nprimitives — are left untouched, only their position is walked into. An entry whose\ntransformed key is a prototype-polluting string (`__proto__`, `constructor`, `prototype`) is\nsilently skipped, same as the rest of `@helpers4/object`.",
+          "params": [
+            {
+              "name": "value",
+              "type": "T",
+              "description": "The object (or array of objects) to transform"
+            }
+          ],
+          "returns": {
+            "type": "T",
+            "description": "A new value with every plain-object key converted to camelCase"
+          },
+          "typeParameters": [
+            {
+              "name": "T"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Convert a snake_case API response",
+          "description": "Recursively converts every key, including nested objects, to camelCase.",
+          "code": "camelCaseKeys({ user_name: 'Alice', home_address: { zip_code: '12345' } })\n// => { userName: 'Alice', homeAddress: { zipCode: '12345' } }"
+        },
+        {
+          "title": "Arrays of objects are walked too",
+          "description": "Each object inside an array gets its keys converted.",
+          "code": "camelCaseKeys({ user_list: [{ first_name: 'A' }] })\n// => { userList: [{ firstName: 'A' }] }"
+        }
+      ],
+      "sourceFile": "camelCaseKeys.ts"
+    },
     {
       "name": "clone",
       "kind": "function",
@@ -603,6 +644,42 @@
       ],
       "sourceFile": "isNonEmpty.ts"
     },
+    {
+      "name": "kebabCaseKeys",
+      "kind": "function",
+      "description": "Recursively transforms every key of a plain object (including keys nested inside arrays and\nnested objects) to kebab-case. Handles snake_case, camelCase, PascalCase, and space-separated\nkeys. Non-plain-object values — `Date`, `Map`, `Set`, class instances, primitives — are left\nuntouched, only their position is walked into. An entry whose transformed key is a\nprototype-polluting string (`__proto__`, `constructor`, `prototype`) is silently skipped,\nsame as the rest of `@helpers4/object`.",
+      "since": "3.0.3",
+      "signatures": [
+        {
+          "signature": "kebabCaseKeys<T>(value: T): T",
+          "description": "Recursively transforms every key of a plain object (including keys nested inside arrays and\nnested objects) to kebab-case. Handles snake_case, camelCase, PascalCase, and space-separated\nkeys. Non-plain-object values — `Date`, `Map`, `Set`, class instances, primitives — are left\nuntouched, only their position is walked into. An entry whose transformed key is a\nprototype-polluting string (`__proto__`, `constructor`, `prototype`) is silently skipped,\nsame as the rest of `@helpers4/object`.",
+          "params": [
+            {
+              "name": "value",
+              "type": "T",
+              "description": "The object (or array of objects) to transform"
+            }
+          ],
+          "returns": {
+            "type": "T",
+            "description": "A new value with every plain-object key converted to kebab-case"
+          },
+          "typeParameters": [
+            {
+              "name": "T"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Convert object keys for a kebab-case config format",
+          "description": "Recursively converts every key, including nested objects, to kebab-case.",
+          "code": "kebabCaseKeys({ userName: 'Alice', homeAddress: { zipCode: '12345' } })\n// => { 'user-name': 'Alice', 'home-address': { 'zip-code': '12345' } }"
+        }
+      ],
+      "sourceFile": "kebabCaseKeys.ts"
+    },
     {
       "name": "map",
       "kind": "function",
@@ -671,6 +748,64 @@
       ],
       "sourceFile": "map.ts"
     },
+    {
+      "name": "mapDeep",
+      "kind": "function",
+      "description": "Recursively transforms the keys and/or values of a plain object — the deep counterpart to\nmap, which only transforms the top level. Descends into nested plain objects and\narrays of them; `Date`, `Map`, `Set`, class instances, and primitives are left untouched\n(only their position is walked into, matching cloneDeep's notion of what counts\nas a plain-data node worth recursing into).\n\nBoth callbacks are optional and default to identity (no transformation). `mapKey` is called\nwith the *original* key and value (before any recursive value transform); `mapValue` receives\nthe already-recursed value. Entries whose mapped key is a prototype-polluting string\n(`__proto__`, `constructor`, `prototype`) are silently skipped, same as map.\n\nArray elements also go through `mapValue` (with their stringified index as `key`, since\narrays have no property keys of their own) — so values inside a plain array, not just object\nproperties, get transformed too. `mapKey` is never called for array elements, since there is\nno key to rename.",
+      "since": "3.0.3",
+      "signatures": [
+        {
+          "signature": "mapDeep<T>(obj: T, mapValue?: function, mapKey?: function): T",
+          "description": "Recursively transforms the keys and/or values of a plain object — the deep counterpart to\nmap, which only transforms the top level. Descends into nested plain objects and\narrays of them; `Date`, `Map`, `Set`, class instances, and primitives are left untouched\n(only their position is walked into, matching cloneDeep's notion of what counts\nas a plain-data node worth recursing into).\n\nBoth callbacks are optional and default to identity (no transformation). `mapKey` is called\nwith the *original* key and value (before any recursive value transform); `mapValue` receives\nthe already-recursed value. Entries whose mapped key is a prototype-polluting string\n(`__proto__`, `constructor`, `prototype`) are silently skipped, same as map.\n\nArray elements also go through `mapValue` (with their stringified index as `key`, since\narrays have no property keys of their own) — so values inside a plain array, not just object\nproperties, get transformed too. `mapKey` is never called for array elements, since there is\nno key to rename.",
+          "params": [
+            {
+              "name": "obj",
+              "type": "T",
+              "description": "The value to transform (typically an object, or an array of objects)"
+            },
+            {
+              "name": "mapValue",
+              "type": "function",
+              "description": "Callback called with `(value, key)` for each entry's (already-recursed) value.\n  For array elements, `key` is the element's index as a string. Defaults to identity.",
+              "optional": true
+            },
+            {
+              "name": "mapKey",
+              "type": "function",
+              "description": "Callback called with `(key, value)` for each object entry. Defaults to identity.",
+              "optional": true
+            }
+          ],
+          "returns": {
+            "type": "T",
+            "description": "A new value with every plain-object key/value transformed"
+          },
+          "typeParameters": [
+            {
+              "name": "T"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Transform every key, recursively",
+          "description": "Unlike map(), mapDeep() walks into nested objects and arrays of objects.",
+          "code": "mapDeep({ a: { b: 1 } }, undefined, key => key.toUpperCase())\n// => { A: { B: 1 } }"
+        },
+        {
+          "title": "Transform every value, recursively",
+          "description": "Values are visited after their own nested content has already been transformed.",
+          "code": "mapDeep({ a: { b: 1, c: 2 } }, v => typeof v === 'number' ? v * 10 : v)\n// => { a: { b: 10, c: 20 } }"
+        },
+        {
+          "title": "Transform values inside arrays too",
+          "description": "Array elements are visited by mapValue as well, keyed by their stringified index.",
+          "code": "mapDeep({ tags: [1, 2, 3] }, v => typeof v === 'number' ? v * 10 : v)\n// => { tags: [10, 20, 30] }"
+        }
+      ],
+      "sourceFile": "mapDeep.ts"
+    },
     {
       "name": "mergeDeep",
       "kind": "function",
@@ -882,6 +1017,42 @@
       ],
       "sourceFile": "parsePropertyPath.ts"
     },
+    {
+      "name": "pascalCaseKeys",
+      "kind": "function",
+      "description": "Recursively transforms every key of a plain object (including keys nested inside arrays and\nnested objects) to PascalCase. Handles camelCase, snake_case, kebab-case, and space-separated\nkeys. Non-plain-object values — `Date`, `Map`, `Set`, class instances, primitives — are left\nuntouched, only their position is walked into. An entry whose transformed key is a\nprototype-polluting string (`__proto__`, `constructor`, `prototype`) is silently skipped,\nsame as the rest of `@helpers4/object`.",
+      "since": "3.0.3",
+      "signatures": [
+        {
+          "signature": "pascalCaseKeys<T>(value: T): T",
+          "description": "Recursively transforms every key of a plain object (including keys nested inside arrays and\nnested objects) to PascalCase. Handles camelCase, snake_case, kebab-case, and space-separated\nkeys. Non-plain-object values — `Date`, `Map`, `Set`, class instances, primitives — are left\nuntouched, only their position is walked into. An entry whose transformed key is a\nprototype-polluting string (`__proto__`, `constructor`, `prototype`) is silently skipped,\nsame as the rest of `@helpers4/object`.",
+          "params": [
+            {
+              "name": "value",
+              "type": "T",
+              "description": "The object (or array of objects) to transform"
+            }
+          ],
+          "returns": {
+            "type": "T",
+            "description": "A new value with every plain-object key converted to PascalCase"
+          },
+          "typeParameters": [
+            {
+              "name": "T"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Convert object keys to PascalCase (e.g. for a C#/JSON.NET consumer)",
+          "description": "Recursively converts every key, including nested objects, to PascalCase.",
+          "code": "pascalCaseKeys({ user_name: 'Alice', home_address: { zip_code: '12345' } })\n// => { UserName: 'Alice', HomeAddress: { ZipCode: '12345' } }"
+        }
+      ],
+      "sourceFile": "pascalCaseKeys.ts"
+    },
     {
       "name": "pick",
       "kind": "function",
@@ -1223,6 +1394,121 @@
       ],
       "sourceFile": "set.ts"
     },
+    {
+      "name": "snakeCaseKeys",
+      "kind": "function",
+      "description": "Recursively transforms every key of a plain object (including keys nested inside arrays and\nnested objects) to snake_case. Handles camelCase, PascalCase, kebab-case, and space-separated\nkeys. Non-plain-object values — `Date`, `Map`, `Set`, class instances, primitives — are left\nuntouched, only their position is walked into. An entry whose transformed key is a\nprototype-polluting string (`__proto__`, `constructor`, `prototype`) is silently skipped,\nsame as the rest of `@helpers4/object`.",
+      "since": "3.0.3",
+      "signatures": [
+        {
+          "signature": "snakeCaseKeys<T>(value: T): T",
+          "description": "Recursively transforms every key of a plain object (including keys nested inside arrays and\nnested objects) to snake_case. Handles camelCase, PascalCase, kebab-case, and space-separated\nkeys. Non-plain-object values — `Date`, `Map`, `Set`, class instances, primitives — are left\nuntouched, only their position is walked into. An entry whose transformed key is a\nprototype-polluting string (`__proto__`, `constructor`, `prototype`) is silently skipped,\nsame as the rest of `@helpers4/object`.",
+          "params": [
+            {
+              "name": "value",
+              "type": "T",
+              "description": "The object (or array of objects) to transform"
+            }
+          ],
+          "returns": {
+            "type": "T",
+            "description": "A new value with every plain-object key converted to snake_case"
+          },
+          "typeParameters": [
+            {
+              "name": "T"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Convert a camelCase object for a snake_case API",
+          "description": "Recursively converts every key, including nested objects, to snake_case.",
+          "code": "snakeCaseKeys({ userName: 'Alice', homeAddress: { zipCode: '12345' } })\n// => { user_name: 'Alice', home_address: { zip_code: '12345' } }"
+        }
+      ],
+      "sourceFile": "snakeCaseKeys.ts"
+    },
+    {
+      "name": "sortKeys",
+      "kind": "function",
+      "description": "Creates a new object with the same entries as the input, but with its own keys sorted.\nShallow only — nested objects are copied as-is, their keys are not re-sorted.\nKey order matters for things like `JSON.stringify` diffs and snapshot stability; this does\nnot change equality (`{a:1,b:2}` and `{b:2,a:1}` are already equal), just iteration/serialization order.\nNote: integer-index-like keys (`\"0\"`, `\"1\"`, `\"42\"`...) are always iterated first, in numeric\norder, by the JS engine itself — no object key ordering can override that language behavior.\nA prototype-polluting key (`__proto__`, `constructor`, `prototype`) is silently skipped,\nsame as the rest of `@helpers4/object`.",
+      "since": "3.0.3",
+      "signatures": [
+        {
+          "signature": "sortKeys<T extends Record<string, unknown>>(obj: T, compareFn?: function): T",
+          "description": "Creates a new object with the same entries as the input, but with its own keys sorted.\nShallow only — nested objects are copied as-is, their keys are not re-sorted.\nKey order matters for things like `JSON.stringify` diffs and snapshot stability; this does\nnot change equality (`{a:1,b:2}` and `{b:2,a:1}` are already equal), just iteration/serialization order.\nNote: integer-index-like keys (`\"0\"`, `\"1\"`, `\"42\"`...) are always iterated first, in numeric\norder, by the JS engine itself — no object key ordering can override that language behavior.\nA prototype-polluting key (`__proto__`, `constructor`, `prototype`) is silently skipped,\nsame as the rest of `@helpers4/object`.",
+          "params": [
+            {
+              "name": "obj",
+              "type": "T",
+              "description": "The object whose keys to sort"
+            },
+            {
+              "name": "compareFn",
+              "type": "function",
+              "description": "Optional custom comparator, passed directly to `Array.prototype.sort`",
+              "optional": true
+            }
+          ],
+          "returns": {
+            "type": "T",
+            "description": "A new object with the same entries, own keys in sorted order"
+          },
+          "typeParameters": [
+            {
+              "name": "T",
+              "constraint": "Record<string, unknown>"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Sort object keys alphabetically",
+          "description": "Useful for stable JSON.stringify output or predictable snapshot tests.",
+          "code": "sortKeys({ b: 2, a: 1, c: 3 })\n// => { a: 1, b: 2, c: 3 }"
+        }
+      ],
+      "sourceFile": "sortKeys.ts"
+    },
+    {
+      "name": "titleCaseKeys",
+      "kind": "function",
+      "description": "Recursively transforms every key of a plain object (including keys nested inside arrays and\nnested objects) to Title Case. Handles camelCase, snake_case, kebab-case, and space-separated\nkeys. Non-plain-object values — `Date`, `Map`, `Set`, class instances, primitives — are left\nuntouched, only their position is walked into. An entry whose transformed key is a\nprototype-polluting string (`__proto__`, `constructor`, `prototype`) is silently skipped,\nsame as the rest of `@helpers4/object`.\n\nNote: unlike the other `*CaseKeys` variants, `titleCase` joins words with spaces (e.g.\n`'User Name'`) — those keys are only usable via bracket access (`obj['User Name']`), not dot\nnotation. Useful for display-facing structures (form labels, table headers), not wire formats.",
+      "since": "3.0.3",
+      "signatures": [
+        {
+          "signature": "titleCaseKeys<T>(value: T): T",
+          "description": "Recursively transforms every key of a plain object (including keys nested inside arrays and\nnested objects) to Title Case. Handles camelCase, snake_case, kebab-case, and space-separated\nkeys. Non-plain-object values — `Date`, `Map`, `Set`, class instances, primitives — are left\nuntouched, only their position is walked into. An entry whose transformed key is a\nprototype-polluting string (`__proto__`, `constructor`, `prototype`) is silently skipped,\nsame as the rest of `@helpers4/object`.\n\nNote: unlike the other `*CaseKeys` variants, `titleCase` joins words with spaces (e.g.\n`'User Name'`) — those keys are only usable via bracket access (`obj['User Name']`), not dot\nnotation. Useful for display-facing structures (form labels, table headers), not wire formats.",
+          "params": [
+            {
+              "name": "value",
+              "type": "T",
+              "description": "The object (or array of objects) to transform"
+            }
+          ],
+          "returns": {
+            "type": "T",
+            "description": "A new value with every plain-object key converted to Title Case"
+          },
+          "typeParameters": [
+            {
+              "name": "T"
+            }
+          ]
+        }
+      ],
+      "examples": [
+        {
+          "title": "Convert object keys into display-friendly labels",
+          "description": "Recursively converts every key to Title Case — useful for form labels or table headers.",
+          "code": "titleCaseKeys({ user_name: 'Alice', home_address: { zip_code: '12345' } })\n// => { 'User Name': 'Alice', 'Home Address': { 'Zip Code': '12345' } }"
+        }
+      ],
+      "sourceFile": "titleCaseKeys.ts"
+    },
     {
       "name": "unflatten",
       "kind": "function",

package/meta/examples.json

@@ -1,6 +1,21 @@
 {
   "category": "object",
   "functions": [
+    {
+      "name": "camelCaseKeys",
+      "examples": [
+        {
+          "title": "Convert a snake_case API response",
+          "description": "Recursively converts every key, including nested objects, to camelCase.",
+          "code": "camelCaseKeys({ user_name: 'Alice', home_address: { zip_code: '12345' } })\n// => { userName: 'Alice', homeAddress: { zipCode: '12345' } }"
+        },
+        {
+          "title": "Arrays of objects are walked too",
+          "description": "Each object inside an array gets its keys converted.",
+          "code": "camelCaseKeys({ user_list: [{ first_name: 'A' }] })\n// => { userList: [{ firstName: 'A' }] }"
+        }
+      ]
+    },
     {
       "name": "clone",
       "examples": [
@@ -176,6 +191,16 @@
         }
       ]
     },
+    {
+      "name": "kebabCaseKeys",
+      "examples": [
+        {
+          "title": "Convert object keys for a kebab-case config format",
+          "description": "Recursively converts every key, including nested objects, to kebab-case.",
+          "code": "kebabCaseKeys({ userName: 'Alice', homeAddress: { zipCode: '12345' } })\n// => { 'user-name': 'Alice', 'home-address': { 'zip-code': '12345' } }"
+        }
+      ]
+    },
     {
       "name": "map",
       "examples": [
@@ -196,6 +221,26 @@
         }
       ]
     },
+    {
+      "name": "mapDeep",
+      "examples": [
+        {
+          "title": "Transform every key, recursively",
+          "description": "Unlike map(), mapDeep() walks into nested objects and arrays of objects.",
+          "code": "mapDeep({ a: { b: 1 } }, undefined, key => key.toUpperCase())\n// => { A: { B: 1 } }"
+        },
+        {
+          "title": "Transform every value, recursively",
+          "description": "Values are visited after their own nested content has already been transformed.",
+          "code": "mapDeep({ a: { b: 1, c: 2 } }, v => typeof v === 'number' ? v * 10 : v)\n// => { a: { b: 10, c: 20 } }"
+        },
+        {
+          "title": "Transform values inside arrays too",
+          "description": "Array elements are visited by mapValue as well, keyed by their stringified index.",
+          "code": "mapDeep({ tags: [1, 2, 3] }, v => typeof v === 'number' ? v * 10 : v)\n// => { tags: [10, 20, 30] }"
+        }
+      ]
+    },
     {
       "name": "mergeDeep",
       "examples": [
@@ -251,6 +296,16 @@
         }
       ]
     },
+    {
+      "name": "pascalCaseKeys",
+      "examples": [
+        {
+          "title": "Convert object keys to PascalCase (e.g. for a C#/JSON.NET consumer)",
+          "description": "Recursively converts every key, including nested objects, to PascalCase.",
+          "code": "pascalCaseKeys({ user_name: 'Alice', home_address: { zip_code: '12345' } })\n// => { UserName: 'Alice', HomeAddress: { ZipCode: '12345' } }"
+        }
+      ]
+    },
     {
       "name": "pick",
       "examples": [
@@ -331,6 +386,36 @@
         }
       ]
     },
+    {
+      "name": "snakeCaseKeys",
+      "examples": [
+        {
+          "title": "Convert a camelCase object for a snake_case API",
+          "description": "Recursively converts every key, including nested objects, to snake_case.",
+          "code": "snakeCaseKeys({ userName: 'Alice', homeAddress: { zipCode: '12345' } })\n// => { user_name: 'Alice', home_address: { zip_code: '12345' } }"
+        }
+      ]
+    },
+    {
+      "name": "sortKeys",
+      "examples": [
+        {
+          "title": "Sort object keys alphabetically",
+          "description": "Useful for stable JSON.stringify output or predictable snapshot tests.",
+          "code": "sortKeys({ b: 2, a: 1, c: 3 })\n// => { a: 1, b: 2, c: 3 }"
+        }
+      ]
+    },
+    {
+      "name": "titleCaseKeys",
+      "examples": [
+        {
+          "title": "Convert object keys into display-friendly labels",
+          "description": "Recursively converts every key to Title Case — useful for form labels or table headers.",
+          "code": "titleCaseKeys({ user_name: 'Alice', home_address: { zip_code: '12345' } })\n// => { 'User Name': 'Alice', 'Home Address': { 'Zip Code': '12345' } }"
+        }
+      ]
+    },
     {
       "name": "unflatten",
       "examples": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpers4/object",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "A set of helpers in TS/JS, compatible with tree-shaking, for object.",
   "author": "baxyz <baxy@etik.com>",
   "license": "LGPL-3.0",
@@ -27,6 +27,7 @@
   "keywords": [
     "helpers",
     "object",
+    "camelCaseKeys",
     "clone",
     "cloneDeep",
     "compact",
@@ -39,16 +40,22 @@
     "invert",
     "isEmpty",
     "isNonEmpty",
+    "kebabCaseKeys",
     "map",
+    "mapDeep",
     "mergeDeep",
     "omit",
     "omitBy",
     "parsePropertyPath",
+    "pascalCaseKeys",
     "pick",
     "pickBy",
     "removeUndefinedNull",
     "safeJsonParse",
     "set",
+    "snakeCaseKeys",
+    "sortKeys",
+    "titleCaseKeys",
     "unflatten",
     "unset",
     "update"