@helpers4/all 2.0.3 → 2.0.4

package/llms.txt

@@ -1,7 +1,7 @@
 # @helpers4/all
 
 > Complete collection of tree-shakable TypeScript utility functions.
-> Version: 2.0.3 — License: LGPL-3.0-or-later
+> Version: 2.0.4 — License: LGPL-3.0-or-later
 
 ## About
 
@@ -54,6 +54,7 @@ pnpm add @helpers4/version
 | `@helpers4/array` | `isEmpty` | Checks if an array is empty (has no elements). |
 | `@helpers4/array` | `isNonEmpty` | Checks if an array is non-empty (has at least one element). |
 | `@helpers4/array` | `max` | Returns the maximum value in an array using a loop instead of spread, avoiding the call stack overfl |
+| `@helpers4/array` | `mean` | Calculates the arithmetic mean (average) of an array of numbers. Returns `NaN` for an empty array.   |
 | `@helpers4/array` | `min` | Returns the minimum value in an array using a loop instead of spread, avoiding the call stack overfl |
 | `@helpers4/array` | `partition` | Splits an array into two groups based on a predicate function. The first group contains elements for |
 | `@helpers4/array` | `range` | Generates an array of sequential numbers from start to end (exclusive). If only one argument is prov |
@@ -66,9 +67,10 @@ pnpm add @helpers4/version
 | `@helpers4/array` | `sortStringAscInsensitiveFn` | Sort strings in ascending order (case insensitive) |
 | `@helpers4/array` | `sortStringDescFn` | Sort strings in descending order |
 | `@helpers4/array` | `sortStringNaturalAscFn` | Sort strings in ascending order using natural (human-friendly) ordering. Numbers embedded in strings |
-| `@helpers4/array` | `sortStringNaturalAscInsensitiveFn` | Sort strings in ascending natural order (case insensitive). |
+| `@helpers4/array` | `sortStringNaturalAscInsensitiveFn` | Sort strings in ascending natural order, ignoring case **and diacritics** (`Intl.Collator { sensitiv |
 | `@helpers4/array` | `sortStringNaturalDescFn` | Sort strings in descending order using natural (human-friendly) ordering. Numbers embedded in string |
-| `@helpers4/array` | `sortStringNaturalDescInsensitiveFn` | Sort strings in descending natural order (case insensitive). Numbers embedded in strings are compare |
+| `@helpers4/array` | `sortStringNaturalDescInsensitiveFn` | Sort strings in descending natural order, ignoring case **and diacritics** (`Intl.Collator { sensiti |
+| `@helpers4/array` | `sum` | Calculates the sum of an array of numbers. |
 | `@helpers4/array` | `unique` | Removes duplicate values from an array |
 | `@helpers4/array` | `unzip` | Splits an array of tuples into separate arrays, one per position.  The inverse of zip. |
 | `@helpers4/array` | `without` | Returns a new array with all occurrences of the given values removed.  Unlike `difference`, which op |
@@ -125,7 +127,7 @@ pnpm add @helpers4/version
 | `@helpers4/function` | `debounce` | Creates a debounced function that delays invoking func until after delay milliseconds have elapsed s |
 | `@helpers4/function` | `flip` | Creates a function that invokes `fn` with the first two arguments swapped.  Useful when adapting a f |
 | `@helpers4/function` | `identity` | Returns the given value unchanged  Useful as a default transform, in function composition, or as a p |
-| `@helpers4/function` | `memoize` | Returns a memoized version of the function that caches results |
+| `@helpers4/function` | `memoize` | Returns a memoized version of the function that caches results.  Cache keys are derived via `JSON.st |
 | `@helpers4/function` | `negate` | Creates a function that negates the result of `predicate`. |
 | `@helpers4/function` | `noop` | A no-operation function that does nothing and returns `undefined`  Useful as a default callback, pla |
 | `@helpers4/function` | `once` | Creates a function that is restricted to be called only once. Subsequent calls return the cached res |
@@ -149,18 +151,16 @@ pnpm add @helpers4/version
 | `@helpers4/number` | `isOdd` | Checks if a value is an odd integer.  Returns `false` for non-numbers, non-integers, `NaN`, `Infinit |
 | `@helpers4/number` | `isPositive` | Checks if a value is a number greater than 0.  Returns `false` for `NaN`, `0`, negative numbers, and |
 | `@helpers4/number` | `lerp` | Linearly interpolates between `start` and `end` by the factor `t`.  - `t = 0` returns `start`. - `t  |
-| `@helpers4/number` | `mean` | Calculates the arithmetic mean (average) of an array of numbers. Returns `NaN` for an empty array.   |
 | `@helpers4/number` | `randomBetween` | Generates a random number between min and max (inclusive) |
 | `@helpers4/number` | `randomIntBetween` | Generates a random integer between min and max (inclusive) |
 | `@helpers4/number` | `roundTo` | Rounds a number to specified decimal places |
-| `@helpers4/number` | `sum` | Calculates the sum of an array of numbers. |
 | `@helpers4/object` | `compact` | Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`) from an objec |
 | `@helpers4/object` | `deepClone` | Creates a deep copy of an object or array |
-| `@helpers4/object` | `deepMerge` | Merges two or more objects deeply |
+| `@helpers4/object` | `deepMerge` | Merges two or more objects deeply.  Recursively merges own enumerable properties — both string and s |
 | `@helpers4/object` | `diff` | Structural object diff.  Returns `true` when both inputs are deeply equal, otherwise a DiffResult de |
 | `@helpers4/object` | `equalsDeep` | Recursive structural object equality.  Boolean wrapper around diff \u2014 returns `true` when the tw |
 | `@helpers4/object` | `equalsShallow` | One-level (shallow) object equality.  Two objects are equal when they share the exact same set of ow |
-| `@helpers4/object` | `get` | Gets a value from an object using a dot-notated path |
+| `@helpers4/object` | `get` | Gets a value from an object using a dot/bracket-notated path or explicit key array.  **Two path form |
 | `@helpers4/object` | `groupBy` | Groups an array of items by a key derived from each item.  A thin, typed wrapper around `Object.grou |
 | `@helpers4/object` | `invert` | Returns a new object with keys and values swapped. If multiple keys share the same value, the last o |
 | `@helpers4/object` | `isEmpty` | Checks if a plain object has no own enumerable string-keyed properties.  Symbol-keyed properties are |
@@ -170,7 +170,7 @@ pnpm add @helpers4/version
 | `@helpers4/object` | `pick` | Creates a new object with only the specified keys. |
 | `@helpers4/object` | `removeUndefinedNull` | Remove null and undefined values from an object. |
 | `@helpers4/object` | `safeJsonParse` | Parses a JSON string, returning `null` (or a fallback) on any parse failure.  Unlike `JSON.parse`, t |
-| `@helpers4/object` | `set` | Sets a value in an object using a dot-notated path |
+| `@helpers4/object` | `set` | Sets a value in an object at the given path, creating intermediate objects as needed.  **Three path  |
 | `@helpers4/observable` | `combine` | Combine two observables with a map function and an optional pre-treatment.  Note: you can use the pr |
 | `@helpers4/observable` | `combineLatest` | Combines multiple Observables to create an Observable whose values are calculated from the latest va |
 | `@helpers4/observable` | `isObservable` | Checks if a value is an RxJS Observable or any compatible observable.  Uses duck-typing: returns `tr |
@@ -463,10 +463,30 @@ createSortByDateFn<T extends Record<string, unknown>>(property?: keyof T): SortF
 
 **Parameters:**
 
-- `property?: keyof T` — The property to sort by (defaults to 'date')
+- `property?: keyof T` — The property to sort by (defaults to `'date'`).
+  Accepted value types: `Date` (including cross-realm instances), `string`, or
+  `number` (Unix milliseconds). Any object with a `getTime(): number` method is
+  also accepted (duck-typed, so cross-realm `Date` objects work correctly).
+  `null`, `undefined`, and unparseable strings produce `NaN` and sort last,
+  distinct from a genuine Unix-epoch date (`new Date(0)`).
 
 **Returns:** `SortFn<T>` — Sort function
 
+**Examples:**
+
+*createSortByDateFn*
+
+```typescript
+```ts
+const events = [
+  { date: new Date('2023-01-01') },
+  { date: new Date('2021-06-15') },
+];
+events.sort(createSortByDateFn('date'))
+// => sorted oldest first
+```
+```
+
 ---
 
 ### `createSortByNaturalFn`
@@ -488,11 +508,23 @@ createSortByNaturalFn<T extends Record<string, unknown>>(property?: keyof T | re
   Defaults to trying 'value', 'label', 'title', 'description' in that order.
 - `caseInsensitive: boolean` (default: `false`) — Whether to ignore case **and diacritics** (default: false).
   Uses `Intl.Collator { sensitivity: 'base' }`, which treats é, E, and e as equal.
-  This differs from `createSortByStringFn(key, true)`, which only folds case via
-  `toLowerCase` and still distinguishes accented characters.
+  This differs from `createSortByStringFn(key, true)`, which only folds case and
+  still distinguishes accented characters (é ≠ e).
 
 **Returns:** `SortFn<T>` — Sort function
 
+**Examples:**
+
+*createSortByNaturalFn*
+
+```typescript
+```ts
+const items = [{ label: 'W11' }, { label: 'W2' }, { label: 'W20' }];
+items.sort(createSortByNaturalFn('label'))
+// => [{ label: 'W2' }, { label: 'W11' }, { label: 'W20' }]
+```
+```
+
 ---
 
 ### `createSortByNumberFn`
@@ -507,10 +539,27 @@ createSortByNumberFn<T extends Record<string, unknown>>(property?: keyof T): Sor
 
 **Parameters:**
 
-- `property?: keyof T` — The property to sort by (defaults to 'value')
+- `property?: keyof T` — The property to sort by (defaults to `'value'`). Always pass an
+  explicit key when T does not have a `'value'` property — omitting it on such types
+  produces a no-op comparator (all elements compare equal).
+  `null` and `undefined` sort last (treated as `+Infinity`). Non-numeric values
+  (including booleans — `Number(true) === 1`, `Number(false) === 0`) and `NaN` also
+  sort last.
 
 **Returns:** `SortFn<T>` — Sort function
 
+**Examples:**
+
+*createSortByNumberFn*
+
+```typescript
+```ts
+const items = [{ count: 3 }, { count: 1 }, { count: 2 }];
+items.sort(createSortByNumberFn('count'))
+// => [{ count: 1 }, { count: 2 }, { count: 3 }]
+```
+```
+
 ---
 
 ### `createSortByStringFn`
@@ -519,6 +568,10 @@ Creates a sort function for objects by one or more string properties.
 When multiple properties are given the array is sorted by the first key;
 ties are broken by the second key, then the third, and so on.
 
+Property values are coerced to strings via `String()` before comparison:
+numbers sort as `'0'`, `'1'`, `'42'`, etc. (lexicographic, not numeric);
+use `createSortByNumberFn` for numeric properties.
+
 ```typescript
 import { createSortByStringFn } from '@helpers4/array';
 
@@ -529,7 +582,12 @@ createSortByStringFn<T extends Record<string, unknown>>(property?: keyof T | rea
 
 - `property?: keyof T | readonly keyof T[]` — The property (or ordered list of properties) to sort by.
   Defaults to trying 'value', 'label', 'title', 'description' in that order.
-- `caseInsensitive: boolean` (default: `false`) — Whether to ignore case (default: false)
+  Pass `undefined` explicitly to use auto-detect; an empty array `[]` produces a
+  stable no-op comparator (does **not** fall back to auto-detect).
+- `caseInsensitive: boolean` (default: `false`) — Whether to ignore case (default: false).
+  Uses `Intl.Collator { sensitivity: 'accent' }`, which folds case but still
+  distinguishes accented characters (é ≠ e). This differs from
+  `createSortByNaturalFn(key, true)`, which also collapses diacritics.
 
 **Returns:** `SortFn<T>` — Sort function
 
@@ -1012,6 +1070,39 @@ max(Array.from({ length: 1_000_000 }, (_, i) => i))
 
 ---
 
+### `mean`
+
+Calculates the arithmetic mean (average) of an array of numbers.
+Returns `NaN` for an empty array.
+
+Pairs with sum for aggregate operations.
+
+```typescript
+import { mean } from '@helpers4/array';
+
+mean(array: readonly number[]): number
+```
+
+**Parameters:**
+
+- `array: readonly number[]` — The array of numbers to average
+
+**Returns:** `number` — The arithmetic mean, or `NaN` if the array is empty
+
+**Examples:**
+
+*Average a list of numbers*
+
+Returns the arithmetic mean of the array; NaN for empty arrays.
+
+```typescript
+mean([1, 2, 3, 4])  // => 2.5
+mean([10, 20, 30])  // => 20
+mean([])            // => NaN
+```
+
+---
+
 ### `min`
 
 Returns the minimum value in an array using a loop instead of spread,
@@ -1394,7 +1485,19 @@ items.sort(createSortByNaturalFn('code'))
 
 ### `sortStringNaturalAscInsensitiveFn`
 
-Sort strings in ascending natural order (case insensitive).
+Sort strings in ascending natural order, ignoring case **and diacritics**
+(`Intl.Collator { sensitivity: 'base' }` — treats é, E, and e as equal).
+Numbers embedded in strings are compared numerically: "W2" < "W11" < "W20".
+
+**Examples:**
+
+*sortStringNaturalAscInsensitiveFn*
+
+```typescript
+```ts
+['W11', 'W2', 'W20'].sort(sortStringNaturalAscInsensitiveFn) // => ['W2', 'W11', 'W20']
+```
+```
 
 ---
 
@@ -1403,13 +1506,72 @@ Sort strings in ascending natural order (case insensitive).
 Sort strings in descending order using natural (human-friendly) ordering.
 Numbers embedded in strings are compared numerically: "W20" > "W11" > "W2".
 
+**Examples:**
+
+*sortStringNaturalDescFn*
+
+```typescript
+```ts
+['W11', 'W2', 'W20'].sort(sortStringNaturalDescFn) // => ['W20', 'W11', 'W2']
+```
+```
+
 ---
 
 ### `sortStringNaturalDescInsensitiveFn`
 
-Sort strings in descending natural order (case insensitive).
+Sort strings in descending natural order, ignoring case **and diacritics**
+(`Intl.Collator { sensitivity: 'base' }` — treats é, E, and e as equal).
 Numbers embedded in strings are compared numerically: "W20" > "W11" > "W2".
 
+**Examples:**
+
+*sortStringNaturalDescInsensitiveFn*
+
+```typescript
+```ts
+['W11', 'W2', 'W20'].sort(sortStringNaturalDescInsensitiveFn) // => ['W20', 'W11', 'W2']
+```
+```
+
+---
+
+### `sum`
+
+Calculates the sum of an array of numbers.
+
+```typescript
+import { sum } from '@helpers4/array';
+
+sum(array: readonly number[]): number
+```
+
+**Parameters:**
+
+- `array: readonly number[]` — The array of numbers to sum
+
+**Returns:** `number` — The sum of all values, or `0` for an empty array
+
+**Examples:**
+
+*Sum numbers*
+
+Calculates the sum of an array of numbers.
+
+```typescript
+sum([1, 2, 3, 4])
+// => 10
+```
+
+*Sum with negative numbers*
+
+Handles negative numbers correctly.
+
+```typescript
+sum([10, -3, 5, -2])
+// => 10
+```
+
 ---
 
 ### `unique`
@@ -3700,17 +3862,23 @@ Pass identity where a transform function is required but no transformation is ne
 
 ### `memoize`
 
-Returns a memoized version of the function that caches results
+Returns a memoized version of the function that caches results.
+
+Cache keys are derived via `JSON.stringify`; `undefined` arguments are
+correctly distinguished from `null`. Arguments that are not JSON-serializable
+(functions, symbols, class instances, circular references) produce a
+`null`-equivalent key and are not supported.
 
 ```typescript
 import { memoize } from '@helpers4/function';
 
-memoize<A extends unknown[], R>(func: function): function
+memoize<A extends unknown[], R>(func: function, options?: MemoizeOptions): function
 ```
 
 **Parameters:**
 
 - `func: function` — The function to memoize
+- `options?: MemoizeOptions` — Optional settings (e.g. `maxSize` to cap memory usage)
 
 **Returns:** `function` — The memoized function
 
@@ -4515,6 +4683,10 @@ Note: for values whose integer part already consumes 14 or more digits
 digits and will silently truncate them. Increase `precision` if you
 need to correct drift in very large numbers.
 
+Note: IEEE-754 doubles carry at most ~17 significant decimal digits.
+Precision values above 17 pad with digits that reflect the underlying
+binary representation rather than correcting drift.
+
 ```typescript
 import { correctFloat } from '@helpers4/number';
 
@@ -4524,7 +4696,9 @@ correctFloat(value: number, precision: number): number
 **Parameters:**
 
 - `value: number` — The floating-point value to correct
-- `precision: number` (default: `14`) — Integer number of significant digits (default: 14)
+- `precision: number` (default: `14`) — Integer number of significant digits between 1 and 100
+  (default: 14). Values above 17 are valid but expose binary noise beyond
+  IEEE-754's meaningful range.
 
 **Returns:** `number` — The corrected value
 
@@ -4581,9 +4755,12 @@ extractNumber(value: unknown, options: ExtractNumberOptions): number | undefined
 ```typescript
 ```ts
 extractNumber('16.5px')        // => 16.5
+extractNumber('.5rem')         // => 0.5   (leading-dot decimal)
+extractNumber('-.5')           // => -0.5  (leading-dot with sign)
 extractNumber('Wafer 10')      // => 10
 extractNumber('xxx-111')       // => 111   ('-' glued to text → separator)
 extractNumber('xxx -111')      // => -111  ('-' preceded by a space → sign)
+extractNumber('x-.5')          // => 0.5   ('-' glued to 'x' → separator; leading-dot decimal follows)
 extractNumber('-111')          // => -111  ('-' at the start of the string → sign)
 extractNumber('1e5 mol')       // => 100000
 extractNumber('1e5kg')         // => 1     ('e5' glued to text → mantissa only)
@@ -4917,39 +5094,6 @@ lerp(0, 10, 2)    // => 20  (extrapolation)
 
 ---
 
-### `mean`
-
-Calculates the arithmetic mean (average) of an array of numbers.
-Returns `NaN` for an empty array.
-
-Pairs with sum for aggregate operations.
-
-```typescript
-import { mean } from '@helpers4/number';
-
-mean(array: readonly number[]): number
-```
-
-**Parameters:**
-
-- `array: readonly number[]` — The array of numbers to average
-
-**Returns:** `number` — The arithmetic mean, or `NaN` if the array is empty
-
-**Examples:**
-
-*Average a list of numbers*
-
-Returns the arithmetic mean of the array; NaN for empty arrays.
-
-```typescript
-mean([1, 2, 3, 4])  // => 2.5
-mean([10, 20, 30])  // => 20
-mean([])            // => NaN
-```
-
----
-
 ### `randomBetween`
 
 Generates a random number between min and max (inclusive)
@@ -5047,44 +5191,6 @@ roundTo(3.7, 0)
 
 ---
 
-### `sum`
-
-Calculates the sum of an array of numbers.
-
-```typescript
-import { sum } from '@helpers4/number';
-
-sum(array: readonly number[]): number
-```
-
-**Parameters:**
-
-- `array: readonly number[]` — The array of numbers to sum
-
-**Returns:** `number` — The sum of all values
-
-**Examples:**
-
-*Sum numbers*
-
-Calculates the sum of an array of numbers.
-
-```typescript
-sum([1, 2, 3, 4])
-// => 10
-```
-
-*Sum with negative numbers*
-
-Handles negative numbers correctly.
-
-```typescript
-sum([10, -3, 5, -2])
-// => 10
-```
-
----
-
 ## object
 
 Package: `@helpers4/object`
@@ -5184,46 +5290,51 @@ cloned.a.b = 2;
 
 ### `deepMerge`
 
-Merges two or more objects deeply
+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<string, unknown>>(target: T, sources: Record<string, unknown>[]): T
+deepMerge<T extends Record<PropertyKey, unknown>>(target: T, sources: Record<PropertyKey, unknown>[]): T
 ```
 
 **Parameters:**
 
-- `target: T` — The target object
-- `sources: Record<string, unknown>[]` — The source objects to merge
+- `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 merged object
+**Returns:** `T` — The mutated target
 
 ```typescript
 import { deepMerge } from '@helpers4/object';
 
-deepMerge(target: undefined, sources: Record<string, unknown>[]): undefined
+deepMerge(target: undefined, sources: Record<PropertyKey, unknown>[]): undefined
 ```
 
 **Parameters:**
 
-- `target: undefined` — The target object
-- `sources: Record<string, unknown>[]` — The source objects to merge
+- `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 merged object
+**Returns:** `undefined` — The mutated target
 
 ```typescript
 import { deepMerge } from '@helpers4/object';
 
-deepMerge(target: null, sources: Record<string, unknown>[]): null
+deepMerge(target: null, sources: Record<PropertyKey, unknown>[]): null
 ```
 
 **Parameters:**
 
-- `target: null` — The target object
-- `sources: Record<string, unknown>[]` — The source objects to merge
+- `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 merged object
+**Returns:** `null` — The mutated target
 
 **Examples:**
 
@@ -5383,7 +5494,17 @@ 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. Segments are traversed as string keys; `[n]`
+   indices become numeric keys.
+
+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.
 
 ```typescript
 import { get } from '@helpers4/object';
@@ -5393,11 +5514,25 @@ get<T = unknown>(obj: unknown, path: string, defaultValue?: T): T | undefined
 
 **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: 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`
+
+**Returns:** `T | undefined` — 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
+```
+
+**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`
 
-**Returns:** `T | undefined` — The value at the path or default value
+**Returns:** `DeepGet<T, Path> | undefined` — The value at the path, or `defaultValue`
 
 **Examples:**
 
@@ -5419,6 +5554,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`
@@ -5913,7 +6058,24 @@ 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.
+
+**Three 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"`).
+
+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"`.
+
+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')]`.
+
+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';
@@ -5923,21 +6085,58 @@ set(obj: Record<string, unknown>, path: string, value: unknown): Record<string,
 
 **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: 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 modified object
+**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>
+```
+
+**Parameters:**
+
+- `obj: T` — The object to mutate
+- `path: Path` — Dot/bracket-notation string or explicit `PropertyKey[]`
+- `value: V` — Value to assign at the path
+
+**Returns:** `DeepSet<T, Path, V>` — The mutated object (same reference)
 
 **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' } }
 ```
 
 ---
@@ -7747,6 +7946,10 @@ type MutableConfig = DeepWritable<Config>;
 type Point = readonly [x: number, y: number];
 type MutablePoint = DeepWritable<Point>;
 // => [x: number, y: number]
+
+Note: `Date`, `Map`, `Set`, `Promise`, and `RegExp` are treated as opaque and passed
+through unchanged. In particular, `DeepWritable<Map<K, V>>` does **not** strip `readonly`
+from the value type `V` — use a manual mapped type if you need that.
 ```
 ```
 

package/meta/build.json

@@ -1,7 +1,7 @@
 {
-  "buildDate": "2026-06-16T21:13:06.456Z",
-  "version": "2.0.3",
-  "mutationDashboardUrl": "https://dashboard.stryker-mutator.io/reports/github.com/helpers4/typescript/v2.0.3",
+  "buildDate": "2026-06-21T11:57:07.644Z",
+  "version": "2.0.4",
+  "mutationDashboardUrl": "https://dashboard.stryker-mutator.io/reports/github.com/helpers4/typescript/v2.0.4",
   "runtimes": {
     "node": ">=20.0.0",
     "deno": "compatible",

package/meta/packages.json

@@ -1,19 +1,19 @@
 {
-  "@helpers4/all": "2.0.3",
-  "@helpers4/array": "2.0.3",
-  "@helpers4/ci": "2.0.3",
-  "@helpers4/commit": "2.0.3",
-  "@helpers4/date": "2.0.3",
-  "@helpers4/function": "2.0.3",
-  "@helpers4/id": "2.0.3",
-  "@helpers4/markdown": "2.0.3",
-  "@helpers4/node": "2.0.3",
-  "@helpers4/number": "2.0.3",
-  "@helpers4/object": "2.0.3",
-  "@helpers4/observable": "2.0.3",
-  "@helpers4/promise": "2.0.3",
-  "@helpers4/string": "2.0.3",
-  "@helpers4/type": "2.0.3",
-  "@helpers4/url": "2.0.3",
-  "@helpers4/version": "2.0.3"
+  "@helpers4/all": "2.0.4",
+  "@helpers4/array": "2.0.4",
+  "@helpers4/ci": "2.0.4",
+  "@helpers4/commit": "2.0.4",
+  "@helpers4/date": "2.0.4",
+  "@helpers4/function": "2.0.4",
+  "@helpers4/id": "2.0.4",
+  "@helpers4/markdown": "2.0.4",
+  "@helpers4/node": "2.0.4",
+  "@helpers4/number": "2.0.4",
+  "@helpers4/object": "2.0.4",
+  "@helpers4/observable": "2.0.4",
+  "@helpers4/promise": "2.0.4",
+  "@helpers4/string": "2.0.4",
+  "@helpers4/type": "2.0.4",
+  "@helpers4/url": "2.0.4",
+  "@helpers4/version": "2.0.4"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helpers4/all",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Complete collection of helpers4 utilities - all categories in one convenient package.",
   "author": "baxyz <baxy@etik.com>",
   "license": "LGPL-3.0",
@@ -27,21 +27,21 @@
     "llms.txt"
   ],
   "peerDependencies": {
-    "@helpers4/array": "2.0.3",
-    "@helpers4/ci": "2.0.3",
-    "@helpers4/commit": "2.0.3",
-    "@helpers4/date": "2.0.3",
-    "@helpers4/function": "2.0.3",
-    "@helpers4/id": "2.0.3",
-    "@helpers4/markdown": "2.0.3",
-    "@helpers4/node": "2.0.3",
-    "@helpers4/number": "2.0.3",
-    "@helpers4/object": "2.0.3",
-    "@helpers4/observable": "2.0.3",
-    "@helpers4/promise": "2.0.3",
-    "@helpers4/string": "2.0.3",
-    "@helpers4/type": "2.0.3",
-    "@helpers4/url": "2.0.3",
-    "@helpers4/version": "2.0.3"
+    "@helpers4/array": "2.0.4",
+    "@helpers4/ci": "2.0.4",
+    "@helpers4/commit": "2.0.4",
+    "@helpers4/date": "2.0.4",
+    "@helpers4/function": "2.0.4",
+    "@helpers4/id": "2.0.4",
+    "@helpers4/markdown": "2.0.4",
+    "@helpers4/node": "2.0.4",
+    "@helpers4/number": "2.0.4",
+    "@helpers4/object": "2.0.4",
+    "@helpers4/observable": "2.0.4",
+    "@helpers4/promise": "2.0.4",
+    "@helpers4/string": "2.0.4",
+    "@helpers4/type": "2.0.4",
+    "@helpers4/url": "2.0.4",
+    "@helpers4/version": "2.0.4"
   }
 }