@helpers4/object 2.0.4 → 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.4
+> 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.  Recursively merges own enumerable properties — both string and s |
 | `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/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 at the given path, creating intermediate objects as needed.  **Three 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,98 +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.
-
-Recursively merges own enumerable properties — both string and symbol keys.
-Plain objects are merged recursively; all other values (arrays, class instances,
-primitives, etc.) are replaced by the source value.
-`undefined` source values do not overwrite existing target values.
-
-```typescript
-import { deepMerge } from '@helpers4/object';
-
-deepMerge<T extends Record<PropertyKey, unknown>>(target: T, sources: Record<PropertyKey, unknown>[]): T
-```
-
-**Parameters:**
-
-- `target: T` — The target object (mutated in place)
-- `sources: Record<PropertyKey, unknown>[]` — One or more source objects to merge into the target
-
-**Returns:** `T` — The mutated target
-
-```typescript
-import { deepMerge } from '@helpers4/object';
-
-deepMerge(target: undefined, sources: Record<PropertyKey, unknown>[]): undefined
-```
-
-**Parameters:**
-
-- `target: undefined` — The target object (mutated in place)
-- `sources: Record<PropertyKey, unknown>[]` — One or more source objects to merge into the target
-
-**Returns:** `undefined` — The mutated target
-
-```typescript
-import { deepMerge } from '@helpers4/object';
-
-deepMerge(target: null, sources: Record<PropertyKey, unknown>[]): null
-```
-
-**Parameters:**
-
-- `target: null` — The target object (mutated in place)
-- `sources: Record<PropertyKey, unknown>[]` — One or more source objects to merge into the target
-
-**Returns:** `null` — The mutated target
-
-**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.
@@ -348,40 +295,59 @@ Gets a value from an object using a dot/bracket-notated path or explicit key arr
 **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. Segments are traversed as string keys; `[n]`
-   indices become numeric keys.
+   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 read from
-- `path: string` — Dot/bracket-notation string or explicit `PropertyKey[]`
-- `defaultValue?: T` — Returned when the path is absent or resolves to `undefined`
+- `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:** `T | undefined` — The value at the path, or `defaultValue`
+**Returns:** `D` — The value at the path, or `defaultValue`
 
 ```typescript
 import { get } from '@helpers4/object';
 
-get<T extends object, Path extends readonly PropertyKey[]>(obj: T, path: Path, defaultValue?: DeepGet<T, Path>): DeepGet<T, Path> | undefined
+get(obj: null | undefined, path: string | readonly PropertyKey[]): undefined
 ```
 
 **Parameters:**
 
-- `obj: T` — The object to read from
-- `path: Path` — Dot/bracket-notation string or explicit `PropertyKey[]`
-- `defaultValue?: DeepGet<T, Path>` — Returned when the path is absent or resolves to `undefined`
+- `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`
 
-**Returns:** `DeepGet<T, Path> | 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:**
 
@@ -421,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
@@ -466,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
 
@@ -506,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.
@@ -513,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:**
 
@@ -549,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.
@@ -556,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:**
 
@@ -604,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.
@@ -657,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.
@@ -909,18 +946,19 @@ safeJsonParse('invalid', [])
 
 Sets a value in an object at the given path, creating intermediate objects as needed.
 
-**Three path forms are supported:**
+**Two path forms are supported:**
 
-1. **Dot notation** (`string`) — segments split on `.` are kept as-is string keys.
-   `"layers.1.name"` → keys `["layers", "1", "name"]` (all strings, including `"1"`).
+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. **Bracket notation** (`string`) — `[n]` segments are parsed as numeric keys.
-   `"layers[1].name"` → keys `["layers", 1, "name"]` (index `1` becomes a number).
-   Dot and bracket can be mixed freely: `"a[0].b[2].c"`.
+2. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,
+   no parsing performed. Enables symbol-keyed access and precise return-type inference.
 
-3. **Key array** (`PropertyKey[]`) — explicit array of `string | number | symbol` keys,
-   no parsing performed. Enables full key-type control, including symbols:
-   `["layers", 1, Symbol('id')]`.
+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`
@@ -929,30 +967,16 @@ is rejected and the original object is returned unchanged (prototype-pollution g
 ```typescript
 import { set } from '@helpers4/object';
 
-set(obj: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>
-```
-
-**Parameters:**
-
-- `obj: Record<string, unknown>` — The object to mutate
-- `path: string` — Dot/bracket-notation string or explicit `PropertyKey[]`
-- `value: unknown` — Value to assign at the path
-
-**Returns:** `Record<string, unknown>` — The mutated object (same reference)
-
-```typescript
-import { set } from '@helpers4/object';
-
-set<T extends object, Path extends readonly PropertyKey[], V extends unknown>(obj: T, path: Path, value: V): DeepSet<T, Path, V>
+set<T extends object, P extends string | readonly PropertyKey[], V extends unknown>(obj: T, path: P, value: V): conditional
 ```
 
 **Parameters:**
 
 - `obj: T` — The object to mutate
-- `path: Path` — Dot/bracket-notation string or explicit `PropertyKey[]`
+- `path: P` — Dot/bracket-notation string literal or explicit `PropertyKey[]`
 - `value: V` — Value to assign at the path
 
-**Returns:** `DeepSet<T, Path, V>` — The mutated object (same reference)
+**Returns:** `conditional` — The mutated object (same reference, narrowed type)
 
 **Examples:**