@helpers4/object 2.0.0-beta.0 → 2.0.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.0-beta.0
+> Package: `@helpers4/object` — Version: 2.0.0
 > License: LGPL-3.0-or-later
 
 ## Installation
@@ -15,7 +15,7 @@ pnpm add @helpers4/object
 ## Usage
 
 ```typescript
-import { compact, deepClone, deepCompare, ... } from '@helpers4/object';
+import { compact, deepClone, deepMerge, ... } from '@helpers4/object';
 ```
 
 ## Functions
@@ -24,15 +24,19 @@ import { compact, deepClone, deepCompare, ... } from '@helpers4/object';
 |---|---|
 | `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 |
-| `deepCompare` | Deep comparison of two objects that returns detailed information about differences. |
 | `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 |
+| `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 |
+| `map` | Transforms the values and/or keys of a plain object in a single pass.  Both callbacks are optional 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 |
-| `shallowEquals` | Quick comparison of two objects using JSON.stringify. This is a fast but simple comparison that may  |
 
 ---
 
@@ -131,22 +135,94 @@ cloned.a.b = 2;
 
 ---
 
-### `deepCompare`
+### `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.
+
+Returns `true` when both inputs are deeply equal, otherwise a
+DiffResult describing the differences key by key.
 
-Deep comparison of two objects that returns detailed information about differences.
+Comparison rules:
+- Same reference \u2192 `true`.
+- Either side is `null`/`undefined` (and not both) \u2192 `false`.
+- Both `Date` \u2192 epoch comparison.
+- Both arrays \u2192 compared with `array/equalsDeep` (leaf, no diff drill-down).
+- Special objects (Map, Set, RegExp, Promise, class instances\u2026) \u2192 reference equality.
+- Plain objects \u2192 key-by-key, recursing up to `options.depth` levels.
+- Mixed types (e.g. array vs object, Date vs object) \u2192 `false`.
+
+For a boolean wrapper see equalsDeep from this category.
+For a one-level boolean check see equalsShallow from this category.
 
 ```typescript
-import { deepCompare } from '@helpers4/object';
+import { diff } from '@helpers4/object';
 
-deepCompare(objA: object | null | undefined, objB: object | null | undefined): boolean | DeepCompareResult
+diff(objA: object | null | undefined, objB: object | null | undefined, options: DiffOptions): boolean | DiffResult
 ```
 
 **Parameters:**
 
-- `objA: object | null | undefined` — First object to compare (can be object, undefined, or null)
-- `objB: object | null | undefined` — Second object to compare (can be object, undefined, or null)
+- `objA: object | null | undefined` — First value (object, `null`, or `undefined`).
+- `objB: object | null | undefined` — Second value (object, `null`, or `undefined`).
+- `options: DiffOptions` (default: `{}`) — See DiffOptions.
 
-**Returns:** `boolean | DeepCompareResult` — `true` if objects are identical, `false` if incompatible types, or a `DeepCompareResult` object detailing differences
+**Returns:** `boolean | DiffResult` — `true` when equal, otherwise a DiffResult, or `false` for incompatible types.
 
 **Examples:**
 
@@ -155,7 +231,7 @@ deepCompare(objA: object | null | undefined, objB: object | null | undefined): b
 Deeply compares two objects, returning true when they are structurally equal.
 
 ```typescript
-deepCompare({ a: { b: 1 } }, { a: { b: 1 } })
+diff({ a: { b: 1 } }, { a: { b: 1 } })
 // => true
 ```
 
@@ -164,64 +240,96 @@ deepCompare({ a: { b: 1 } }, { a: { b: 1 } })
 Returns a detailed diff object when nested values differ.
 
 ```typescript
-deepCompare({ a: { b: 1 } }, { a: { b: 2 } })
+diff({ a: { b: 1 } }, { a: { b: 2 } })
 // => { a: { b: false } }
 ```
 
 ---
 
-### `deepMerge`
+### `equalsDeep`
 
-Merges two or more objects deeply
+Recursive structural object equality.
+
+Boolean wrapper around diff \u2014 returns `true` when the two values
+are deeply equal according to the same rules. Use this when you only
+need a yes/no answer; use diff when you also need to know
+*what* differs.
+
+For a one-level boolean check use equalsShallow.
 
 ```typescript
-import { deepMerge } from '@helpers4/object';
+import { equalsDeep } from '@helpers4/object';
 
-deepMerge<T extends Record<string, unknown>>(target: T, sources: Record<string, unknown>[]): T
+equalsDeep(objA: object | null | undefined, objB: object | null | undefined): boolean
 ```
 
 **Parameters:**
 
-- `target: T` — The target object
-- `sources: Record<string, unknown>[]` — The source objects to merge
+- `objA: object | null | undefined` — First value (object, `null`, or `undefined`).
+- `objB: object | null | undefined` — Second value (object, `null`, or `undefined`).
 
-**Returns:** `T` — The merged object
+**Returns:** `boolean` — `true` if both inputs are deeply equal, `false` otherwise.
+
+**Examples:**
+
+*Compare nested objects*
+
+Recursive structural equality. Returns true when the two values are deeply equal.
 
 ```typescript
-import { deepMerge } from '@helpers4/object';
+equalsDeep({ a: { b: 1 } }, { a: { b: 1 } })
+// => true
+```
 
-deepMerge(target: undefined, sources: Record<string, unknown>[]): undefined
+*Detect deep differences*
+
+Returns false when nested values differ.
+
+```typescript
+equalsDeep({ a: { b: 1 } }, { a: { b: 2 } })
+// => false
 ```
 
-**Parameters:**
+---
 
-- `target: undefined` — The target object
-- `sources: Record<string, unknown>[]` — The source objects to merge
+### `equalsShallow`
 
-**Returns:** `undefined` — The merged object
+One-level (shallow) object equality.
+
+Two objects are equal when they share the exact same set of own
+enumerable string keys and each pair of values satisfies strict equality
+(`===`). No recursion: nested objects/arrays are compared by reference.
+
+Falls back to strict equality when either input is `null`, `undefined`
+or not an object \u2014 so primitives match if and only if they are `===`.
+Arrays are not supported; they always return `false` (unless identical
+references). Use `array/equalsShallow` instead.
+
+For recursive structural comparison use equalsDeep. For a diff
+structure use diff.
 
 ```typescript
-import { deepMerge } from '@helpers4/object';
+import { equalsShallow } from '@helpers4/object';
 
-deepMerge(target: null, sources: Record<string, unknown>[]): null
+equalsShallow(objA: unknown, objB: unknown): boolean
 ```
 
 **Parameters:**
 
-- `target: null` — The target object
-- `sources: Record<string, unknown>[]` — The source objects to merge
+- `objA: unknown` — First value to compare
+- `objB: unknown` — Second value to compare
 
-**Returns:** `null` — The merged object
+**Returns:** `boolean` — `true` if values are shallowly equal, `false` otherwise.
 
 **Examples:**
 
-*Merge two objects deeply*
+*Compare two equal objects*
 
-Recursively merges source properties into the target object.
+Uses JSON.stringify for a fast comparison.
 
 ```typescript
-deepMerge({ a: 1, b: { c: 2 } }, { b: { d: 3 }, e: 4 })
-// => { a: 1, b: { c: 2, d: 3 }, e: 4 }
+equalsShallow({ a: 1, b: 2 }, { a: 1, b: 2 })
+// => true
 ```
 
 ---
@@ -266,6 +374,156 @@ get({ a: 1 }, 'b.c', 'default')
 
 ---
 
+### `groupBy`
+
+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.
+
+```typescript
+import { groupBy } from '@helpers4/object';
+
+groupBy<T, K extends PropertyKey>(items: readonly T[], keyFn: function): Partial<Record<K, T[]>>
+```
+
+**Parameters:**
+
+- `items: readonly T[]` — 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
+
+**Examples:**
+
+*Group numbers by parity*
+
+Groups elements by the string key returned by the callback.
+
+```typescript
+groupBy([1, 2, 3, 4], n => n % 2 === 0 ? 'even' : 'odd')
+// => { odd: [1, 3], even: [2, 4] }
+```
+
+*Group objects by a property*
+
+Use a property accessor as the grouping key.
+
+```typescript
+const users = [
+  { name: 'Alice', role: 'admin' },
+  { name: 'Bob',   role: 'user'  },
+  { name: 'Carol', role: 'admin' },
+];
+groupBy(users, u => u.role)
+// => { admin: [{...Alice}, {...Carol}], user: [{...Bob}] }
+```
+
+---
+
+### `invert`
+
+Returns a new object with keys and values swapped.
+If multiple keys share the same value, the last one wins.
+
+```typescript
+import { invert } from '@helpers4/object';
+
+invert<K extends string, V extends PropertyKey>(obj: Record<K, V>): Record<V, K>
+```
+
+**Parameters:**
+
+- `obj: Record<K, V>` — 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
+
+**Examples:**
+
+*Swap keys and values*
+
+Returns a new object with keys and values swapped.
+
+```typescript
+invert({ a: 'x', b: 'y', c: 'z' })
+// => { x: 'a', y: 'b', z: 'c' }
+```
+
+*Build a reverse lookup map*
+
+Useful when you have a code-to-label map and need label-to-code.
+
+```typescript
+const STATUS_LABELS = { 200: 'OK', 404: 'Not Found', 500: 'Internal Server Error' };
+const LABEL_TO_CODE = invert(STATUS_LABELS);
+
+LABEL_TO_CODE['OK']; // => '200'
+```
+
+---
+
+### `map`
+
+Transforms the values and/or keys of a plain object in a single pass.
+
+Both callbacks are optional and default to identity (no transformation).
+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).
+
+```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>
+```
+
+**Parameters:**
+
+- `obj: TObj` — 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.
+  Defaults to identity.
+
+**Returns:** `Record<TKey, TVal>` — A new object with transformed keys and/or values
+
+**Examples:**
+
+*Transform values*
+
+Maps each value of an object through a transform function.
+
+```typescript
+map({ a: 1, b: 2 }, v => v * 10)
+// => { a: 10, b: 20 }
+```
+
+*Transform keys*
+
+Maps each key of an object through a transform function.
+
+```typescript
+map({ a: 1, b: 2 }, undefined, k => k.toUpperCase())
+// => { A: 1, B: 2 }
+```
+
+*Transform both keys and values in a single pass*
+
+Provide both a value mapper and a key mapper to rewrite the whole object.
+
+```typescript
+map(
+  { price: 100, discount: 20 },
+  v => v / 100,
+  k => `${k}Ratio`
+)
+// => { priceRatio: 1, discountRatio: 0.2 }
+```
+
+---
+
 ### `omit`
 
 Creates a new object without the specified keys.
@@ -544,34 +802,3 @@ set({}, 'a.b.c', 42)
 ```
 
 ---
-
-### `shallowEquals`
-
-Quick comparison of two objects using JSON.stringify.
-This is a fast but simple comparison that may not work for all edge cases.
-
-```typescript
-import { shallowEquals } from '@helpers4/object';
-
-shallowEquals(objA: unknown, objB: unknown): boolean
-```
-
-**Parameters:**
-
-- `objA: unknown` — First object to compare
-- `objB: unknown` — Second object to compare
-
-**Returns:** `boolean` — `true` if objects are identical according to JSON.stringify, `false` otherwise
-
-**Examples:**
-
-*Compare two equal objects*
-
-Uses JSON.stringify for a fast comparison.
-
-```typescript
-shallowEquals({ a: 1, b: 2 }, { a: 1, b: 2 })
-// => true
-```
-
----