@helpers4/object 3.0.2 → 3.0.4

package/llms.txt

@@ -1,7 +1,7 @@
 # @helpers4/object
 
 > Tree-shakable TypeScript utility functions for the `object` domain.
-> Package: `@helpers4/object` — Version: 3.0.2
+> Package: `@helpers4/object` — Version: 3.0.4
 > License: LGPL-3.0-or-later
 
 ## Installation
@@ -15,13 +15,14 @@ pnpm add @helpers4/object
 ## Usage
 
 ```typescript
-import { clone, cloneDeep, compact, ... } from '@helpers4/object';
+import { camelCaseKeys, clone, cloneDeep, ... } from '@helpers4/object';
 ```
 
 ## Functions
 
 | Function | Description |
 |---|---|
+| `camelCaseKeys` | Recursively transforms every key of a plain object (including keys nested inside arrays and nested o |
 | `clone` | Creates a shallow copy of a value — one level deep, unlike cloneDeep.  Unlike a plain `{ ...value }` |
 | `cloneDeep` | Creates a deep copy of an object or array.  Recursively clones own enumerable string keys. `Date` in |
 | `compact` | Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`) from an objec |
@@ -34,16 +35,22 @@ import { clone, cloneDeep, compact, ... } from '@helpers4/object';
 | `invert` | Returns a new object with keys and values swapped. If multiple keys share the same value, the last o |
 | `isEmpty` | Checks if a plain object has no own enumerable string-keyed properties. `null` and `undefined` are t |
 | `isNonEmpty` | Checks if a plain object has at least one own enumerable string-keyed property. `null` and `undefine |
+| `kebabCaseKeys` | Recursively transforms every key of a plain object (including keys nested inside arrays and nested o |
 | `map` | Transforms the values and/or keys of a plain object in a single pass.  Both callbacks are optional a |
+| `mapDeep` | Recursively transforms the keys and/or values of a plain object — the deep counterpart to map, which |
 | `mergeDeep` | Merges two or more objects deeply, returning a **new** object without mutating any input.  Sources a |
 | `omit` | Creates a new object without the specified keys. |
 | `omitBy` | Creates a new object without the own enumerable entries for which `predicate` returns `true`.  Compl |
 | `parsePropertyPath` | Parses a dot/bracket-notation property path into an array of string/number key segments — the same n |
+| `pascalCaseKeys` | Recursively transforms every key of a plain object (including keys nested inside arrays and nested o |
 | `pick` | Creates a new object with only the specified keys. Keys that are prototype-polluting strings (`__pro |
 | `pickBy` | Creates a new object with only the own enumerable entries for which `predicate` returns `true`.  Com |
 | `removeUndefinedNull` | Remove null and undefined values from an object. |
 | `safeJsonParse` | Parses a JSON string, returning `null` (or a fallback) on any parse failure.  Unlike `JSON.parse`, t |
 | `set` | Sets a value in an object at the given path, creating intermediate objects as needed.  **Two path fo |
+| `snakeCaseKeys` | Recursively transforms every key of a plain object (including keys nested inside arrays and nested o |
+| `sortKeys` | Creates a new object with the same entries as the input, but with its own keys sorted. Shallow only  |
+| `titleCaseKeys` | Recursively transforms every key of a plain object (including keys nested inside arrays and nested o |
 | `unflatten` | Rebuilds a nested object from a single-level object whose keys are dot-notation paths. The inverse o |
 | `unset` | Removes the value at a dot/bracket-notation path or explicit key array, mutating the object in place |
 | `update` | Updates the value at a path by applying a function to its current value, creating intermediate objec |
@@ -52,6 +59,49 @@ import { clone, cloneDeep, compact, ... } from '@helpers4/object';
 
 ## API Reference
 
+### `camelCaseKeys`
+
+Recursively transforms every key of a plain object (including keys nested inside arrays and
+nested objects) to camelCase. Handles snake_case, kebab-case, PascalCase, and space-separated
+keys. Non-plain-object values (arrays' items aside) — `Date`, `Map`, `Set`, class instances,
+primitives — are left untouched, only their position is walked into. An entry whose
+transformed key is a prototype-polluting string (`__proto__`, `constructor`, `prototype`) is
+silently skipped, same as the rest of `@helpers4/object`.
+
+```typescript
+import { camelCaseKeys } from '@helpers4/object';
+
+camelCaseKeys<T>(value: T): T
+```
+
+**Parameters:**
+
+- `value: T` — The object (or array of objects) to transform
+
+**Returns:** `T` — A new value with every plain-object key converted to camelCase
+
+**Examples:**
+
+*Convert a snake_case API response*
+
+Recursively converts every key, including nested objects, to camelCase.
+
+```typescript
+camelCaseKeys({ user_name: 'Alice', home_address: { zip_code: '12345' } })
+// => { userName: 'Alice', homeAddress: { zipCode: '12345' } }
+```
+
+*Arrays of objects are walked too*
+
+Each object inside an array gets its keys converted.
+
+```typescript
+camelCaseKeys({ user_list: [{ first_name: 'A' }] })
+// => { userList: [{ firstName: 'A' }] }
+```
+
+---
+
 ### `clone`
 
 Creates a shallow copy of a value — one level deep, unlike cloneDeep.
@@ -675,6 +725,40 @@ function processConfig(config: Record<string, unknown>): void {
 
 ---
 
+### `kebabCaseKeys`
+
+Recursively transforms every key of a plain object (including keys nested inside arrays and
+nested objects) to kebab-case. Handles snake_case, camelCase, PascalCase, and space-separated
+keys. Non-plain-object values — `Date`, `Map`, `Set`, class instances, primitives — are left
+untouched, only their position is walked into. An entry whose transformed key is a
+prototype-polluting string (`__proto__`, `constructor`, `prototype`) is silently skipped,
+same as the rest of `@helpers4/object`.
+
+```typescript
+import { kebabCaseKeys } from '@helpers4/object';
+
+kebabCaseKeys<T>(value: T): T
+```
+
+**Parameters:**
+
+- `value: T` — The object (or array of objects) to transform
+
+**Returns:** `T` — A new value with every plain-object key converted to kebab-case
+
+**Examples:**
+
+*Convert object keys for a kebab-case config format*
+
+Recursively converts every key, including nested objects, to kebab-case.
+
+```typescript
+kebabCaseKeys({ userName: 'Alice', homeAddress: { zipCode: '12345' } })
+// => { 'user-name': 'Alice', 'home-address': { 'zip-code': '12345' } }
+```
+
+---
+
 ### `map`
 
 Transforms the values and/or keys of a plain object in a single pass.
@@ -738,6 +822,70 @@ map(
 
 ---
 
+### `mapDeep`
+
+Recursively transforms the keys and/or values of a plain object — the deep counterpart to
+map, which only transforms the top level. Descends into nested plain objects and
+arrays of them; `Date`, `Map`, `Set`, class instances, and primitives are left untouched
+(only their position is walked into, matching cloneDeep's notion of what counts
+as a plain-data node worth recursing into).
+
+Both callbacks are optional and default to identity (no transformation). `mapKey` is called
+with the *original* key and value (before any recursive value transform); `mapValue` receives
+the already-recursed value. Entries whose mapped key is a prototype-polluting string
+(`__proto__`, `constructor`, `prototype`) are silently skipped, same as map.
+
+Array elements also go through `mapValue` (with their stringified index as `key`, since
+arrays have no property keys of their own) — so values inside a plain array, not just object
+properties, get transformed too. `mapKey` is never called for array elements, since there is
+no key to rename.
+
+```typescript
+import { mapDeep } from '@helpers4/object';
+
+mapDeep<T>(obj: T, mapValue?: function, mapKey?: function): T
+```
+
+**Parameters:**
+
+- `obj: T` — The value to transform (typically an object, or an array of objects)
+- `mapValue?: function` — Callback called with `(value, key)` for each entry's (already-recursed) value.
+  For array elements, `key` is the element's index as a string. Defaults to identity.
+- `mapKey?: function` — Callback called with `(key, value)` for each object entry. Defaults to identity.
+
+**Returns:** `T` — A new value with every plain-object key/value transformed
+
+**Examples:**
+
+*Transform every key, recursively*
+
+Unlike map(), mapDeep() walks into nested objects and arrays of objects.
+
+```typescript
+mapDeep({ a: { b: 1 } }, undefined, key => key.toUpperCase())
+// => { A: { B: 1 } }
+```
+
+*Transform every value, recursively*
+
+Values are visited after their own nested content has already been transformed.
+
+```typescript
+mapDeep({ a: { b: 1, c: 2 } }, v => typeof v === 'number' ? v * 10 : v)
+// => { a: { b: 10, c: 20 } }
+```
+
+*Transform values inside arrays too*
+
+Array elements are visited by mapValue as well, keyed by their stringified index.
+
+```typescript
+mapDeep({ tags: [1, 2, 3] }, v => typeof v === 'number' ? v * 10 : v)
+// => { tags: [10, 20, 30] }
+```
+
+---
+
 ### `mergeDeep`
 
 Merges two or more objects deeply, returning a **new** object without mutating any input.
@@ -957,6 +1105,40 @@ parsePropertyPath('a[0]b')
 
 ---
 
+### `pascalCaseKeys`
+
+Recursively transforms every key of a plain object (including keys nested inside arrays and
+nested objects) to PascalCase. Handles camelCase, snake_case, kebab-case, and space-separated
+keys. Non-plain-object values — `Date`, `Map`, `Set`, class instances, primitives — are left
+untouched, only their position is walked into. An entry whose transformed key is a
+prototype-polluting string (`__proto__`, `constructor`, `prototype`) is silently skipped,
+same as the rest of `@helpers4/object`.
+
+```typescript
+import { pascalCaseKeys } from '@helpers4/object';
+
+pascalCaseKeys<T>(value: T): T
+```
+
+**Parameters:**
+
+- `value: T` — The object (or array of objects) to transform
+
+**Returns:** `T` — A new value with every plain-object key converted to PascalCase
+
+**Examples:**
+
+*Convert object keys to PascalCase (e.g. for a C#/JSON.NET consumer)*
+
+Recursively converts every key, including nested objects, to PascalCase.
+
+```typescript
+pascalCaseKeys({ user_name: 'Alice', home_address: { zip_code: '12345' } })
+// => { UserName: 'Alice', HomeAddress: { ZipCode: '12345' } }
+```
+
+---
+
 ### `pick`
 
 Creates a new object with only the specified keys.
@@ -1256,6 +1438,115 @@ set({}, ['user', id], 'alice')
 
 ---
 
+### `snakeCaseKeys`
+
+Recursively transforms every key of a plain object (including keys nested inside arrays and
+nested objects) to snake_case. Handles camelCase, PascalCase, kebab-case, and space-separated
+keys. Non-plain-object values — `Date`, `Map`, `Set`, class instances, primitives — are left
+untouched, only their position is walked into. An entry whose transformed key is a
+prototype-polluting string (`__proto__`, `constructor`, `prototype`) is silently skipped,
+same as the rest of `@helpers4/object`.
+
+```typescript
+import { snakeCaseKeys } from '@helpers4/object';
+
+snakeCaseKeys<T>(value: T): T
+```
+
+**Parameters:**
+
+- `value: T` — The object (or array of objects) to transform
+
+**Returns:** `T` — A new value with every plain-object key converted to snake_case
+
+**Examples:**
+
+*Convert a camelCase object for a snake_case API*
+
+Recursively converts every key, including nested objects, to snake_case.
+
+```typescript
+snakeCaseKeys({ userName: 'Alice', homeAddress: { zipCode: '12345' } })
+// => { user_name: 'Alice', home_address: { zip_code: '12345' } }
+```
+
+---
+
+### `sortKeys`
+
+Creates a new object with the same entries as the input, but with its own keys sorted.
+Shallow only — nested objects are copied as-is, their keys are not re-sorted.
+Key order matters for things like `JSON.stringify` diffs and snapshot stability; this does
+not change equality (`{a:1,b:2}` and `{b:2,a:1}` are already equal), just iteration/serialization order.
+Note: integer-index-like keys (`"0"`, `"1"`, `"42"`...) are always iterated first, in numeric
+order, by the JS engine itself — no object key ordering can override that language behavior.
+A prototype-polluting key (`__proto__`, `constructor`, `prototype`) is silently skipped,
+same as the rest of `@helpers4/object`.
+
+```typescript
+import { sortKeys } from '@helpers4/object';
+
+sortKeys<T extends Record<string, unknown>>(obj: T, compareFn?: function): T
+```
+
+**Parameters:**
+
+- `obj: T` — The object whose keys to sort
+- `compareFn?: function` — Optional custom comparator, passed directly to `Array.prototype.sort`
+
+**Returns:** `T` — A new object with the same entries, own keys in sorted order
+
+**Examples:**
+
+*Sort object keys alphabetically*
+
+Useful for stable JSON.stringify output or predictable snapshot tests.
+
+```typescript
+sortKeys({ b: 2, a: 1, c: 3 })
+// => { a: 1, b: 2, c: 3 }
+```
+
+---
+
+### `titleCaseKeys`
+
+Recursively transforms every key of a plain object (including keys nested inside arrays and
+nested objects) to Title Case. Handles camelCase, snake_case, kebab-case, and space-separated
+keys. Non-plain-object values — `Date`, `Map`, `Set`, class instances, primitives — are left
+untouched, only their position is walked into. An entry whose transformed key is a
+prototype-polluting string (`__proto__`, `constructor`, `prototype`) is silently skipped,
+same as the rest of `@helpers4/object`.
+
+Note: unlike the other `*CaseKeys` variants, `titleCase` joins words with spaces (e.g.
+`'User Name'`) — those keys are only usable via bracket access (`obj['User Name']`), not dot
+notation. Useful for display-facing structures (form labels, table headers), not wire formats.
+
+```typescript
+import { titleCaseKeys } from '@helpers4/object';
+
+titleCaseKeys<T>(value: T): T
+```
+
+**Parameters:**
+
+- `value: T` — The object (or array of objects) to transform
+
+**Returns:** `T` — A new value with every plain-object key converted to Title Case
+
+**Examples:**
+
+*Convert object keys into display-friendly labels*
+
+Recursively converts every key to Title Case — useful for form labels or table headers.
+
+```typescript
+titleCaseKeys({ user_name: 'Alice', home_address: { zip_code: '12345' } })
+// => { 'User Name': 'Alice', 'Home Address': { 'Zip Code': '12345' } }
+```
+
+---
+
 ### `unflatten`
 
 Rebuilds a nested object from a single-level object whose keys are