@helpers4/object 3.0.0-alpha.2 → 3.0.0

package/llms.txt

@@ -1,7 +1,7 @@
 # @helpers4/object
 
 > Tree-shakable TypeScript utility functions for the `object` domain.
-> Package: `@helpers4/object` — Version: 3.0.0-alpha.2
+> Package: `@helpers4/object` — Version: 3.0.0
 > License: LGPL-3.0-or-later
 
 ## Installation
@@ -15,18 +15,20 @@ pnpm add @helpers4/object
 ## Usage
 
 ```typescript
-import { cloneDeep, compact, diff, ... } from '@helpers4/object';
+import { clone, cloneDeep, compact, ... } from '@helpers4/object';
 ```
 
 ## Functions
 
 | Function | Description |
 |---|---|
+| `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 |
 | `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 |
+| `flatten` | Flattens a nested object into a single-level object whose keys are the dot-notation path to each lea |
 | `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 |
@@ -35,15 +37,67 @@ import { cloneDeep, compact, diff, ... } from '@helpers4/object';
 | `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. |
+| `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 |
 | `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 |
+| `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 |
 
 ---
 
 ## API Reference
 
+### `clone`
+
+Creates a shallow copy of a value — one level deep, unlike cloneDeep.
+
+Unlike a plain `{ ...value }` spread, this correctly reconstructs `Date`,
+`Map`, `Set`, and arrays instead of producing an empty (or wrong-shaped)
+plain object for them. Primitives are returned as-is. Any other object
+(including class instances not listed above) has its own enumerable string
+keys shallow-copied into a plain object — the same fallback `cloneDeep`
+uses, so the two stay consistent for types neither one special-cases.
+
+```typescript
+import { clone } from '@helpers4/object';
+
+clone<T>(value: T): T
+```
+
+**Parameters:**
+
+- `value: T` — The value to shallow-clone
+
+**Returns:** `T` — A shallow copy of `value`
+
+**Examples:**
+
+*Shallow-copy a plain object*
+
+Top-level keys are copied; nested values still share references (shallow).
+
+```typescript
+const obj = { a: 1, b: { c: 2 } };
+const copy = clone(obj);
+copy.b === obj.b // => true (same nested reference)
+```
+
+*Correctly clones Date/Map/Set, unlike a spread*
+
+{ ...new Date() } produces {} — clone() doesn't have that problem.
+
+```typescript
+clone(new Map([['a', 1]]))
+// => new Map with the same entries, not {}
+```
+
+---
+
 ### `cloneDeep`
 
 Creates a deep copy of an object or array.
@@ -290,6 +344,55 @@ equalsShallow({ a: 1, b: 2 }, { a: 1, b: 2 })
 
 ---
 
+### `flatten`
+
+Flattens a nested object into a single-level object whose keys are the
+dot-notation path to each leaf value. The inverse of unflatten.
+
+Only **plain objects** are recursed into — arrays, `Date`, `Map`, `RegExp`,
+class instances, and empty plain objects `{}` are kept as opaque leaf
+values. This keeps `flatten`/`unflatten` a clean, invertible pair: arrays
+can't be losslessly told apart from plain objects once reduced to dotted
+keys, so this implementation doesn't attempt it.
+
+Caveat shared by every dotted-path flattening scheme: a key that itself
+contains a literal `.` is indistinguishable from real nesting once
+flattened (`{ 'a.b': 1 }` and `{ a: { b: 1 } }` both produce `{ 'a.b': 1 }`).
+
+```typescript
+import { flatten } from '@helpers4/object';
+
+flatten(obj: Record<string, unknown>): Record<string, unknown>
+```
+
+**Parameters:**
+
+- `obj: Record<string, unknown>` — The object to flatten
+
+**Returns:** `Record<string, unknown>` — A single-level object with dot-notation keys
+
+**Examples:**
+
+*Flatten a nested config object*
+
+Each key in the result is the full dot-notation path to a leaf value.
+
+```typescript
+flatten({ server: { host: 'localhost', port: 8080 } })
+// => { 'server.host': 'localhost', 'server.port': 8080 }
+```
+
+*Arrays and special objects are kept as leaves*
+
+Only plain objects are recursed into — arrays stay intact.
+
+```typescript
+flatten({ tags: ['a', 'b'], meta: { owner: 'x' } })
+// => { tags: ['a', 'b'], 'meta.owner': 'x' }
+```
+
+---
+
 ### `get`
 
 Gets a value from an object using a dot/bracket-notated path or explicit key array.
@@ -762,6 +865,98 @@ omit(user, ['password', 'token'])
 
 ---
 
+### `omitBy`
+
+Creates a new object without the own enumerable entries for which
+`predicate` returns `true`.
+
+Complements omit for when the keys to remove aren't known ahead of
+time — `omit` takes an explicit key list, `omitBy` takes a predicate.
+
+```typescript
+import { omitBy } from '@helpers4/object';
+
+omitBy<T extends Record<string, unknown>>(obj: T | null | undefined, predicate: function): Partial<T> | null | undefined
+```
+
+**Parameters:**
+
+- `obj: T | null | undefined` — The source object. `null`/`undefined` pass through unchanged.
+- `predicate: function` — Called with `(value, key)` for each own enumerable entry
+
+**Returns:** `Partial<T> | null | undefined` — A new object without the matching entries
+
+**Examples:**
+
+*Drop entries matching a predicate*
+
+Unlike omit(), the keys to drop don’t need to be known ahead of time.
+
+```typescript
+omitBy({ a: 1, b: undefined, c: 2 }, (value) => value === undefined)
+// => { a: 1, c: 2 }
+```
+
+*Drop entries by key name*
+
+The predicate also receives the key, so filtering by name works too.
+
+```typescript
+omitBy({ id: 1, name: 'x', _internal: true }, (_v, key) => key.startsWith('_'))
+// => { id: 1, name: 'x' }
+```
+
+---
+
+### `parsePropertyPath`
+
+Parses a dot/bracket-notation property path into an array of string/number
+key segments — the same notation accepted by get and set.
+
+- Dot separators (`.`) split segments; each segment becomes a string key.
+- Bracket indices (`[n]`) become number keys.
+- A leading `.` is treated as "current level" and stripped before parsing,
+  so `.[0]` ≡ `[0]` and `.a.b` ≡ `a.b`.
+- Empty string (or a bare `.`) returns `['']` (addresses the `''` key on the root object).
+- Consecutive dots (`a..b`) produce an empty-string segment: `['a', '', 'b']`.
+
+Results are cached (up to 500 distinct path strings, oldest evicted first)
+since real-world callers tend to reuse a small, fixed set of literal paths.
+
+```typescript
+import { parsePropertyPath } from '@helpers4/object';
+
+parsePropertyPath(path: string): readonly string | number[]
+```
+
+**Parameters:**
+
+- `path: string` — The dot/bracket-notation path string to parse
+
+**Returns:** `readonly string | number[]` — The parsed key segments
+
+**Examples:**
+
+*Parse a dot/bracket-notation path into key segments*
+
+The same notation accepted by get() and set() — bracket indices become numbers.
+
+```typescript
+parsePropertyPath('layers[1].name')
+// => ['layers', 1, 'name']
+```
+
+*Malformed paths throw instead of silently misparsing*
+
+Text trailing a closing bracket within a segment is ambiguous — use 'a[0].b' instead.
+
+```typescript
+parsePropertyPath('a[0]b')
+// => throws RangeError
+```
+
+---
+
 ### `pick`
 
 Creates a new object with only the specified keys.
@@ -830,6 +1025,49 @@ pick(user, ['id', 'name', 'email'])
 
 ---
 
+### `pickBy`
+
+Creates a new object with only the own enumerable entries for which
+`predicate` returns `true`.
+
+Complements pick for when the keys to keep aren't known ahead of
+time — `pick` takes an explicit key list, `pickBy` takes a predicate.
+
+```typescript
+import { pickBy } from '@helpers4/object';
+
+pickBy<T extends Record<string, unknown>>(obj: T | null | undefined, predicate: function): Partial<T> | null | undefined
+```
+
+**Parameters:**
+
+- `obj: T | null | undefined` — The source object. `null`/`undefined` pass through unchanged.
+- `predicate: function` — Called with `(value, key)` for each own enumerable entry
+
+**Returns:** `Partial<T> | null | undefined` — A new object with only the matching entries
+
+**Examples:**
+
+*Keep only entries matching a predicate*
+
+Unlike pick(), the keys to keep don’t need to be known ahead of time.
+
+```typescript
+pickBy({ a: 1, b: 0, c: 2 }, (value) => value > 0)
+// => { a: 1, c: 2 }
+```
+
+*Keep entries by key name*
+
+The predicate also receives the key, so filtering by name works too.
+
+```typescript
+pickBy({ _id: 1, name: 'x', _internal: true }, (_v, key) => !key.startsWith('_'))
+// => { name: 'x' }
+```
+
+---
+
 ### `removeUndefinedNull`
 
 Remove null and undefined values from an object.
@@ -1017,3 +1255,144 @@ set({}, ['user', id], 'alice')
 ```
 
 ---
+
+### `unflatten`
+
+Rebuilds a nested object from a single-level object whose keys are
+dot-notation paths. The inverse of flatten.
+
+Uses set internally, so intermediate nodes are always created as
+plain objects (never arrays — see flatten's doc for why), and any
+key segment equal to `__proto__`, `constructor`, or `prototype` is silently
+rejected (same prototype-pollution guard as `set`).
+
+```typescript
+import { unflatten } from '@helpers4/object';
+
+unflatten(obj: Record<string, unknown>): Record<string, unknown>
+```
+
+**Parameters:**
+
+- `obj: Record<string, unknown>` — A single-level object with dot-notation keys
+
+**Returns:** `Record<string, unknown>` — The rebuilt nested object
+
+**Examples:**
+
+*Rebuild a nested object from dotted keys*
+
+The inverse of flatten() — useful for parsing flat config sources (env vars, .ini files).
+
+```typescript
+unflatten({ 'server.host': 'localhost', 'server.port': 8080 })
+// => { server: { host: 'localhost', port: 8080 } }
+```
+
+*Multiple keys under the same parent are merged*
+
+Every dotted key contributes to the same nested structure.
+
+```typescript
+unflatten({ 'a.x': 1, 'a.y': 2 })
+// => { a: { x: 1, y: 2 } }
+```
+
+---
+
+### `unset`
+
+Removes the value at a dot/bracket-notation path or explicit key array,
+mutating the object in place. Uses the same path syntax as get/set.
+
+A missing intermediate segment is a no-op (nothing to remove), not an error.
+As with `set`, any path containing a string segment equal to `__proto__`,
+`constructor`, or `prototype` is rejected and the object is returned unchanged.
+
+The removed key stops appearing in `Object.keys`/`for...in` — unlike setting
+it to `undefined`, which would keep the key present.
+
+```typescript
+import { unset } from '@helpers4/object';
+
+unset<T extends object>(obj: T, path: string | readonly PropertyKey[]): T
+```
+
+**Parameters:**
+
+- `obj: T` — The object to mutate
+- `path: string | readonly PropertyKey[]` — Dot/bracket-notation string, or explicit `PropertyKey[]`
+
+**Returns:** `T` — The same object reference, with the key removed if it existed
+
+**Examples:**
+
+*Remove a nested value by path*
+
+Uses the same dot/bracket path syntax as get() and set().
+
+```typescript
+const config = { server: { host: 'localhost', debug: true } };
+unset(config, 'server.debug')
+// => { server: { host: 'localhost' } }
+```
+
+*Missing paths are a safe no-op*
+
+Unlike set(), unset() never creates intermediate objects — there is nothing to remove.
+
+```typescript
+unset({ a: 1 }, 'x.y.z')
+// => { a: 1 }  (unchanged)
+```
+
+---
+
+### `update`
+
+Updates the value at a path by applying a function to its current value,
+creating intermediate objects as needed. Equivalent to
+`set(obj, path, updater(get(obj, path)))` in a single call.
+
+Uses the same path syntax and type-inference rules as get and
+set — see those for the full behavior (string vs. `PropertyKey[]`
+paths, prototype-pollution guarding, etc.).
+
+```typescript
+import { update } from '@helpers4/object';
+
+update<T extends object, P extends string | readonly PropertyKey[], V extends unknown>(obj: T, path: P, updater: function): conditional
+```
+
+**Parameters:**
+
+- `obj: T` — The object to mutate
+- `path: P` — Dot/bracket-notation string literal or explicit `PropertyKey[]`
+- `updater: function` — Called with the current value (`undefined` if the path is
+  absent); its return value is written back at the path
+
+**Returns:** `conditional` — The mutated object (same reference, narrowed type)
+
+**Examples:**
+
+*Increment a counter in one call*
+
+Equivalent to set(obj, path, updater(get(obj, path))), without repeating the path.
+
+```typescript
+const state = { count: 1 };
+update(state, 'count', (n) => (n ?? 0) + 1)
+// => { count: 2 }
+```
+
+*Missing paths create intermediate objects, like set()*
+
+The updater receives undefined when the path does not exist yet.
+
+```typescript
+const stats: Record<string, unknown> = {};
+update(stats, 'hits.total', (n: number | undefined) => (n ?? 0) + 1)
+// => { hits: { total: 1 } }
+```
+
+---