@helpers4/object 2.0.3 → 2.1.0

package/llms.txt

@@ -1,7 +1,7 @@
 # @helpers4/object
 
 > Tree-shakable TypeScript utility functions for the `object` domain.
-> Package: `@helpers4/object` — Version: 2.0.3
+> Package: `@helpers4/object` — Version: 2.1.0
 > License: LGPL-3.0-or-later
 
 ## Installation
@@ -15,35 +15,74 @@ pnpm add @helpers4/object
 ## Usage
 
 ```typescript
-import { compact, deepClone, deepMerge, ... } from '@helpers4/object';
+import { cloneDeep, compact, diff, ... } from '@helpers4/object';
 ```
 
 ## Functions
 
 | Function | Description |
 |---|---|
+| `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 |
-| `deepClone` | Creates a deep copy of an object or array |
-| `deepMerge` | Merges two or more objects deeply |
 | `diff` | Structural object diff.  Returns `true` when both inputs are deeply equal, otherwise a DiffResult de |
 | `equalsDeep` | Recursive structural object equality.  Boolean wrapper around diff \u2014 returns `true` when the tw |
 | `equalsShallow` | One-level (shallow) object equality.  Two objects are equal when they share the exact same set of ow |
-| `get` | Gets a value from an object using a dot-notated path |
+| `get` | Gets a value from an object using a dot/bracket-notated path or explicit key array.  **Two path form |
 | `groupBy` | Groups an array of items by a key derived from each item.  A thin, typed wrapper around `Object.grou |
 | `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.  Symbol-keyed properties are |
-| `isNonEmpty` | Checks if a plain object has at least one own enumerable string-keyed property.  Symbol-keyed proper |
+| `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 |
 | `map` | Transforms the values and/or keys of a plain object in a single pass.  Both callbacks are optional a |
+| `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. |
 | `pick` | Creates a new object with only the specified keys. |
 | `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 using a dot-notated path |
+| `set` | Sets a value in an object at the given path, creating intermediate objects as needed.  **Two path fo |
 
 ---
 
 ## API Reference
 
+### `cloneDeep`
+
+Creates a deep copy of an object or array.
+
+Recursively clones own enumerable string keys. `Date` instances are
+reconstructed with the same epoch value. Prototype-polluting keys
+(`__proto__`, `constructor`, `prototype`) are silently skipped.
+Does **not** handle circular references.
+
+**Limitation:** symbol-keyed own properties are **not** copied — only string
+keys are processed. Use `structuredClone` if symbol propagation is required.
+
+```typescript
+import { cloneDeep } from '@helpers4/object';
+
+cloneDeep<T>(obj: T): T
+```
+
+**Parameters:**
+
+- `obj: T` — The value to clone
+
+**Returns:** `T` — A deep copy of `obj`
+
+**Examples:**
+
+*Clone a nested object*
+
+Creates a deep copy — modifying the clone does not affect the original.
+
+```typescript
+const original = { a: { b: 1 } };
+const cloned = cloneDeep(original);
+cloned.a.b = 2;
+// original.a.b is still 1
+```
+
+---
+
 ### `compact`
 
 Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`) from an object.
@@ -106,93 +145,6 @@ compact({ name: 'Alice', email: '', age: 0, role: 'admin' })
 
 ---
 
-### `deepClone`
-
-Creates a deep copy of an object or array
-
-```typescript
-import { deepClone } from '@helpers4/object';
-
-deepClone<T>(obj: T): T
-```
-
-**Parameters:**
-
-- `obj: T` — The object to clone
-
-**Returns:** `T` — Deep cloned object
-
-**Examples:**
-
-*Clone a nested object*
-
-Creates a deep copy — modifying the clone does not affect the original.
-
-```typescript
-const original = { a: { b: 1 } };
-const cloned = deepClone(original);
-cloned.a.b = 2;
-// original.a.b is still 1
-```
-
----
-
-### `deepMerge`
-
-Merges two or more objects deeply
-
-```typescript
-import { deepMerge } from '@helpers4/object';
-
-deepMerge<T extends Record<string, unknown>>(target: T, sources: Record<string, unknown>[]): T
-```
-
-**Parameters:**
-
-- `target: T` — The target object
-- `sources: Record<string, unknown>[]` — The source objects to merge
-
-**Returns:** `T` — The merged object
-
-```typescript
-import { deepMerge } from '@helpers4/object';
-
-deepMerge(target: undefined, sources: Record<string, unknown>[]): undefined
-```
-
-**Parameters:**
-
-- `target: undefined` — The target object
-- `sources: Record<string, unknown>[]` — The source objects to merge
-
-**Returns:** `undefined` — The merged object
-
-```typescript
-import { deepMerge } from '@helpers4/object';
-
-deepMerge(target: null, sources: Record<string, unknown>[]): null
-```
-
-**Parameters:**
-
-- `target: null` — The target object
-- `sources: Record<string, unknown>[]` — The source objects to merge
-
-**Returns:** `null` — The merged object
-
-**Examples:**
-
-*Merge two objects deeply*
-
-Recursively merges source properties into the target object.
-
-```typescript
-deepMerge({ a: 1, b: { c: 2 } }, { b: { d: 3 }, e: 4 })
-// => { a: 1, b: { c: 2, d: 3 }, e: 4 }
-```
-
----
-
 ### `diff`
 
 Structural object diff.
@@ -338,21 +290,64 @@ equalsShallow({ a: 1, b: 2 }, { a: 1, b: 2 })
 
 ### `get`
 
-Gets a value from an object using a dot-notated path
+Gets a value from an object using a dot/bracket-notated path or explicit key array.
+
+**Two path forms are supported:**
+
+1. **String path** — dot notation (`'a.b.c'`) and bracket notation (`'layers[1].name'`)
+   are both accepted and mixed freely.
+   - Dot segments are always string keys: `'a.1'` → key `'1'` (string).
+   - Bracket segments are always number keys: `'a[1]'` → key `1` (number).
+   - String literal paths give **full compile-time type inference** on the return type.
+   - Dynamic (non-literal) strings return `unknown`.
+
+2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,
+   no parsing performed. Enables symbol-keyed traversal and compile-time type inference:
+   `get(obj, ['a', 'b'] as const)` infers the return type from the path.
+
+Both forms support **all objects** (plain objects, arrays, class instances).
+Symbol keys are only reachable via the key-array form.
 
 ```typescript
 import { get } from '@helpers4/object';
 
-get<T = unknown>(obj: unknown, path: string, defaultValue?: T): T | undefined
+get<D>(obj: null | undefined, path: string | readonly PropertyKey[], defaultValue: D): D
 ```
 
 **Parameters:**
 
-- `obj: unknown` — The object to get value from
-- `path: string` — The dot-notated path (e.g., 'a.b.c')
-- `defaultValue?: T` — Default value if path doesn't exist
+- `obj: null | undefined` — The object to read from
+- `path: string | readonly PropertyKey[]` — Dot/bracket-notation string literal or explicit `PropertyKey[]`
+- `defaultValue: D` — Returned when the path is absent or resolves to `undefined`
+
+**Returns:** `D` — The value at the path, or `defaultValue`
+
+```typescript
+import { get } from '@helpers4/object';
+
+get(obj: null | undefined, path: string | readonly PropertyKey[]): undefined
+```
+
+**Parameters:**
 
-**Returns:** `T | undefined` — The value at the path or default value
+- `obj: null | undefined` — The object to read from
+- `path: string | readonly PropertyKey[]` — Dot/bracket-notation string literal or explicit `PropertyKey[]`
+
+**Returns:** `undefined` — The value at the path, or `defaultValue`
+
+```typescript
+import { get } from '@helpers4/object';
+
+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
+```
+
+**Parameters:**
+
+- `obj: T | null | undefined` — The object to read from
+- `path: P` — Dot/bracket-notation string literal or explicit `PropertyKey[]`
+- `defaultValue?: DeepGet<T, ParsePath<P>>` — Returned when the path is absent or resolves to `undefined`
+
+**Returns:** `DeepGet<T, ParsePath<P>> | undefined` — The value at the path, or `defaultValue`
 
 **Examples:**
 
@@ -374,6 +369,16 @@ get({ a: 1 }, 'b.c', 'default')
 // => 'default'
 ```
 
+*Get via key array (supports symbols)*
+
+Pass an explicit PropertyKey[] to bypass parsing. Supports string, number, and symbol keys.
+
+```typescript
+const id = Symbol('id')
+get({ [id]: 'alice' }, [id])
+// => 'alice'
+```
+
 ---
 
 ### `groupBy`
@@ -382,16 +387,19 @@ Groups an array of items by a key derived from each item.
 
 A thin, typed wrapper around `Object.groupBy` (ES2024) that works on
 older targets and provides stricter return-type inference.
+`null` and `undefined` are treated as empty arrays and return `{}`.
+Items whose computed key is a prototype-polluting string (`__proto__`,
+`constructor`, `prototype`) are silently skipped.
 
 ```typescript
 import { groupBy } from '@helpers4/object';
 
-groupBy<T, K extends PropertyKey>(items: readonly T[], keyFn: function): Partial<Record<K, T[]>>
+groupBy<T, K extends PropertyKey>(items: readonly T[] | null | undefined, keyFn: function): Partial<Record<K, T[]>>
 ```
 
 **Parameters:**
 
-- `items: readonly T[]` — The array to group
+- `items: readonly T[] | null | undefined` — The array to group
 - `keyFn: function` — Function that returns the group key for each item
 
 **Returns:** `Partial<Record<K, T[]>>` — A record mapping each key to the array of items with that key
@@ -427,16 +435,19 @@ groupBy(users, u => u.role)
 
 Returns a new object with keys and values swapped.
 If multiple keys share the same value, the last one wins.
+`null` and `undefined` are treated as empty objects and return `{}`.
+Entries whose source key **or** value is a prototype-polluting string
+(`__proto__`, `constructor`, `prototype`) are silently skipped.
 
 ```typescript
 import { invert } from '@helpers4/object';
 
-invert<K extends string, V extends PropertyKey>(obj: Record<K, V>): Record<V, K>
+invert<K extends string, V extends PropertyKey>(obj: Record<K, V> | null | undefined): Record<V, K>
 ```
 
 **Parameters:**
 
-- `obj: Record<K, V>` — The object whose keys and values are to be swapped
+- `obj: Record<K, V> | null | undefined` — The object whose keys and values are to be swapped
 
 **Returns:** `Record<V, K>` — A new object with values as keys and original keys as values
 
@@ -467,6 +478,7 @@ LABEL_TO_CODE['OK']; // => '200'
 ### `isEmpty`
 
 Checks if a plain object has no own enumerable string-keyed properties.
+`null` and `undefined` are treated as empty objects and return `true`.
 
 Symbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`
 separately if symbol keys matter for your use case.
@@ -474,14 +486,14 @@ separately if symbol keys matter for your use case.
 ```typescript
 import { isEmpty } from '@helpers4/object';
 
-isEmpty(value: Record<PropertyKey, unknown>): boolean
+isEmpty(value: Record<PropertyKey, unknown> | null | undefined): boolean
 ```
 
 **Parameters:**
 
-- `value: Record<PropertyKey, unknown>` — The object to check
+- `value: Record<PropertyKey, unknown> | null | undefined` — The object to check
 
-**Returns:** `boolean` — `true` if the object has no own enumerable string-keyed properties
+**Returns:** `boolean` — `true` if the object has no own enumerable string-keyed properties, or if `value` is `null`/`undefined`
 
 **Examples:**
 
@@ -510,6 +522,7 @@ isEmpty(obj) // => true  (only string keys are counted)
 ### `isNonEmpty`
 
 Checks if a plain object has at least one own enumerable string-keyed property.
+`null` and `undefined` are treated as empty objects and return `false`.
 
 Symbol-keyed properties are not counted. Use `Object.getOwnPropertySymbols`
 separately if symbol keys matter for your use case.
@@ -517,14 +530,15 @@ separately if symbol keys matter for your use case.
 ```typescript
 import { isNonEmpty } from '@helpers4/object';
 
-isNonEmpty(value: Record<PropertyKey, unknown>): boolean
+isNonEmpty(value: Record<PropertyKey, unknown> | null | undefined): value is Record<PropertyKey, unknown>
 ```
 
 **Parameters:**
 
-- `value: Record<PropertyKey, unknown>` — The object to check
+- `value: Record<PropertyKey, unknown> | null | undefined` — The object to check
 
-**Returns:** `boolean` — `true` if the object has at least one own enumerable string-keyed property
+**Returns:** `value is Record<PropertyKey, unknown>` — `true` if the object has at least one own enumerable string-keyed property; `false` for empty, `null`, or `undefined`.
+Acts as a type guard: the `if` branch narrows `Record<PropertyKey, unknown> | null | undefined` to `Record<PropertyKey, unknown>`.
 
 **Examples:**
 
@@ -565,17 +579,18 @@ When `mapValue` is omitted the original values are preserved;
 when `mapKey` is omitted the original keys are preserved.
 
 Note: if two different keys map to the same output key the last one wins
-(insertion order).
+(insertion order). Entries whose mapped key is a prototype-polluting string
+(`__proto__`, `constructor`, `prototype`) are silently skipped.
 
 ```typescript
 import { map } from '@helpers4/object';
 
-map<TObj extends Record<string, unknown>, TVal = indexedAccess, TKey extends PropertyKey = keyof TObj>(obj: TObj, mapValue?: function, mapKey?: function): Record<TKey, TVal>
+map<TObj extends Record<string, unknown>, TVal = indexedAccess, TKey extends PropertyKey = keyof TObj>(obj: TObj | null | undefined, mapValue?: function, mapKey?: function): Record<TKey, TVal>
 ```
 
 **Parameters:**
 
-- `obj: TObj` — The source object
+- `obj: TObj | null | undefined` — The source object
 - `mapValue?: function` — Callback called with `(value, key)` for each entry.
   Defaults to identity.
 - `mapKey?: function` — Callback called with `(key, value)` for each entry.
@@ -618,6 +633,67 @@ map(
 
 ---
 
+### `mergeDeep`
+
+Merges two or more objects deeply, returning a **new** object without mutating any input.
+
+Sources are applied left to right. For each key:
+- If both sides are plain objects → merged recursively into a new object.
+- Otherwise → **later source wins** (the earlier value is overwritten).
+- `undefined` in a source **never overwrites** an existing value.
+- `null` in a source **does overwrite** and prevents a later source from
+  deep-merging into that key: `mergeDeep({ a: { x: 1 } }, { a: null }, { a: { y: 2 } })`
+  → `{ a: { y: 2 } }` — `x: 1` is permanently lost.
+- Arrays, class instances, and all non-plain-object values are **replaced**, not merged.
+
+Own enumerable string and symbol keys of each source are processed at the top level;
+inherited and non-enumerable properties are skipped. Prototype-polluting keys
+(`__proto__`, `constructor`, `prototype`) are silently ignored.
+**Note:** symbol keys inside nested plain-object values are not preserved — they are
+lost when those values are deep-cloned. Only top-level symbol keys survive.
+
+**TypeScript return type — intersection semantics**
+
+The return type is `A & B & C …` (intersection of all source types). This is accurate
+when keys are disjoint or share the same type:
+```ts
+mergeDeep({ a: 1 }, { b: 'x' })           // { a: number } & { b: string }  ✓
+mergeDeep({ a: { b: 1 } }, { a: { c: 2 } }) // { a: { b: number } & { c: number } }  ✓
+```
+When the same key carries **incompatible types** across sources, the intersection
+resolves to `never` for that key — TypeScript surfaces the conflict rather than
+silently picking a type:
+```ts
+mergeDeep({ a: 1 }, { a: 'x' })  // { a: never }  ← type conflict detected
+```
+At runtime the later source always wins (`'x'`), but the `never` type signals that
+the caller should align their source types. If intentional, cast the result.
+
+```typescript
+import { mergeDeep } from '@helpers4/object';
+
+mergeDeep<T extends [object, rest]>(sources: [rest]): MergeResult<T>
+```
+
+**Parameters:**
+
+- `sources: [rest]` — Two or more objects to merge (none are mutated)
+
+**Returns:** `MergeResult<T>` — A new object that is the deep merge of all sources
+
+**Examples:**
+
+*Merge two objects deeply*
+
+Returns a new object — neither input is mutated.
+
+```typescript
+mergeDeep({ a: 1, b: { c: 2 } }, { b: { d: 3 }, e: 4 })
+// => { a: 1, b: { c: 2, d: 3 }, e: 4 }
+```
+
+---
+
 ### `omit`
 
 Creates a new object without the specified keys.
@@ -868,31 +944,72 @@ safeJsonParse('invalid', [])
 
 ### `set`
 
-Sets a value in an object using a dot-notated path
+Sets a value in an object at the given path, creating intermediate objects as needed.
+
+**Two path forms are supported:**
+
+1. **String path** — dot notation and bracket notation, mixed freely.
+   - Dot segments are always string keys: `'layers.1.name'` → keys `['layers', '1', 'name']`.
+   - Bracket segments are always number keys: `'layers[1].name'` → keys `['layers', 1, 'name']`.
+   - String literal paths give **full compile-time type inference** on the return type.
+   - Dynamic (non-literal) strings return `T` (same object type).
+
+2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,
+   no parsing performed. Enables symbol-keyed access and precise return-type inference.
+
+Both forms support **all objects** (plain objects, arrays, class instances).
+Symbol keys are only reachable via the key-array form.
+
+Intermediate nodes that are absent, `null`, or not an object are replaced with `{}`.
+Any path containing a string segment equal to `__proto__`, `constructor`, or `prototype`
+is rejected and the original object is returned unchanged (prototype-pollution guard).
 
 ```typescript
 import { set } from '@helpers4/object';
 
-set(obj: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>
+set<T extends object, P extends string | readonly PropertyKey[], V extends unknown>(obj: T, path: P, value: V): conditional
 ```
 
 **Parameters:**
 
-- `obj: Record<string, unknown>` — The object to set value in
-- `path: string` — The dot-notated path (e.g., 'a.b.c')
-- `value: unknown` — The value to set
+- `obj: T` — The object to mutate
+- `path: P` — Dot/bracket-notation string literal or explicit `PropertyKey[]`
+- `value: V` — Value to assign at the path
 
-**Returns:** `Record<string, unknown>` — The modified object
+**Returns:** `conditional` — The mutated object (same reference, narrowed type)
 
 **Examples:**
 
-*Set a nested property*
+*Set a nested property (dot notation)*
 
-Creates intermediate objects as needed along the dot-notated path.
+Creates intermediate objects as needed. All segments are string keys — including numeric-looking ones like "1".
 
 ```typescript
 set({}, 'a.b.c', 42)
 // => { a: { b: { c: 42 } } }
+
+set({}, 'layers.1.name', 'bg')
+// => { layers: { '1': { name: 'bg' } } }   // '1' is a string key
+```
+
+*Set via bracket notation*
+
+Square-bracket indices become numeric keys. Useful when the path targets an array element.
+
+```typescript
+const obj = { layers: [{}, { name: 'old' }] }
+set(obj, 'layers[1].name', 'new')
+// => { layers: [{}, { name: 'new' }] }
+```
+
+*Set via key array (supports symbols)*
+
+Pass an explicit PropertyKey[] to bypass parsing. Supports string, number, and symbol keys.
+
+```typescript
+const id = Symbol('id')
+set({}, ['user', id], 'alice')
+// => { user: { [id]: 'alice' } }
 ```
 
 ---