@helpers4/object 2.0.0-alpha.9 → 2.0.0-beta.0

package/llms.txt

@@ -0,0 +1,577 @@
+# @helpers4/object
+
+> Tree-shakable TypeScript utility functions for the `object` domain.
+> Package: `@helpers4/object` — Version: 2.0.0-beta.0
+> License: LGPL-3.0-or-later
+
+## Installation
+
+```sh
+npm install @helpers4/object
+# or
+pnpm add @helpers4/object
+```
+
+## Usage
+
+```typescript
+import { compact, deepClone, deepCompare, ... } from '@helpers4/object';
+```
+
+## Functions
+
+| Function | Description |
+|---|---|
+| `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 |
+| `get` | Gets a value from an object using a dot-notated path |
+| `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  |
+
+---
+
+## API Reference
+
+### `compact`
+
+Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`) from an object.
+
+```typescript
+import { compact } from '@helpers4/object';
+
+compact<T extends Record<string, unknown>>(obj: T): Partial<T>
+```
+
+**Parameters:**
+
+- `obj: T` — The source object
+
+**Returns:** `Partial<T>` — A new object containing only entries with truthy values
+
+```typescript
+import { compact } from '@helpers4/object';
+
+compact(obj: undefined): undefined
+```
+
+**Parameters:**
+
+- `obj: undefined` — The source object
+
+**Returns:** `undefined` — A new object containing only entries with truthy values
+
+```typescript
+import { compact } from '@helpers4/object';
+
+compact(obj: null): null
+```
+
+**Parameters:**
+
+- `obj: null` — The source object
+
+**Returns:** `null` — A new object containing only entries with truthy values
+
+**Examples:**
+
+*Remove falsy values from object*
+
+Removes all entries with falsy values (false, null, undefined, 0, "", NaN).
+
+```typescript
+compact({ a: 1, b: null, c: '', d: 0, e: 'hello' })
+// => { a: 1, e: 'hello' }
+```
+
+*Clean up API response*
+
+Useful to strip empty or missing fields before sending data.
+
+```typescript
+compact({ name: 'Alice', email: '', age: 0, role: 'admin' })
+// => { name: 'Alice', 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
+```
+
+---
+
+### `deepCompare`
+
+Deep comparison of two objects that returns detailed information about differences.
+
+```typescript
+import { deepCompare } from '@helpers4/object';
+
+deepCompare(objA: object | null | undefined, objB: object | null | undefined): boolean | DeepCompareResult
+```
+
+**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)
+
+**Returns:** `boolean | DeepCompareResult` — `true` if objects are identical, `false` if incompatible types, or a `DeepCompareResult` object detailing differences
+
+**Examples:**
+
+*Compare nested objects*
+
+Deeply compares two objects, returning true when they are structurally equal.
+
+```typescript
+deepCompare({ a: { b: 1 } }, { a: { b: 1 } })
+// => true
+```
+
+*Detect deep differences*
+
+Returns a detailed diff object when nested values differ.
+
+```typescript
+deepCompare({ a: { b: 1 } }, { a: { b: 2 } })
+// => { a: { b: false } }
+```
+
+---
+
+### `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 }
+```
+
+---
+
+### `get`
+
+Gets a value from an object using a dot-notated path
+
+```typescript
+import { get } from '@helpers4/object';
+
+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
+
+**Returns:** `T | undefined` — The value at the path or default value
+
+**Examples:**
+
+*Access a nested property*
+
+Uses a dot-notated path to retrieve a deeply nested value.
+
+```typescript
+get({ a: { b: { c: 42 } } }, 'a.b.c')
+// => 42
+```
+
+*Return default for missing path*
+
+Returns the default value when the path does not exist.
+
+```typescript
+get({ a: 1 }, 'b.c', 'default')
+// => 'default'
+```
+
+---
+
+### `omit`
+
+Creates a new object without the specified keys.
+
+```typescript
+import { omit } from '@helpers4/object';
+
+omit<T extends Record<string, unknown>, K extends string | number | symbol>(obj: T, keys: readonly K[]): Omit<T, K>
+```
+
+**Parameters:**
+
+- `obj: T` — The source object
+- `keys: readonly K[]` — The keys to omit
+
+**Returns:** `Omit<T, K>` — A new object without the omitted keys
+
+```typescript
+import { omit } from '@helpers4/object';
+
+omit(obj: undefined, keys: readonly string[]): undefined
+```
+
+**Parameters:**
+
+- `obj: undefined` — The source object
+- `keys: readonly string[]` — The keys to omit
+
+**Returns:** `undefined` — A new object without the omitted keys
+
+```typescript
+import { omit } from '@helpers4/object';
+
+omit(obj: null, keys: readonly string[]): null
+```
+
+**Parameters:**
+
+- `obj: null` — The source object
+- `keys: readonly string[]` — The keys to omit
+
+**Returns:** `null` — A new object without the omitted keys
+
+**Examples:**
+
+*Omit specific keys*
+
+Creates a new object without the specified keys.
+
+```typescript
+omit({ a: 1, b: 2, c: 3 }, ['b'])
+// => { a: 1, c: 3 }
+```
+
+*Remove sensitive fields*
+
+Useful to strip sensitive data before sending to client.
+
+```typescript
+const user = { id: 1, name: 'Alice', password: 'secret', token: 'abc123' };
+omit(user, ['password', 'token'])
+// => { id: 1, name: 'Alice' }
+```
+
+---
+
+### `pick`
+
+Creates a new object with only the specified keys.
+
+```typescript
+import { pick } from '@helpers4/object';
+
+pick<T extends Record<string, unknown>, K extends string | number | symbol>(obj: T, keys: readonly K[]): Pick<T, K>
+```
+
+**Parameters:**
+
+- `obj: T` — The source object
+- `keys: readonly K[]` — The keys to pick
+
+**Returns:** `Pick<T, K>` — A new object with only the picked keys
+
+```typescript
+import { pick } from '@helpers4/object';
+
+pick(obj: undefined, keys: readonly string[]): undefined
+```
+
+**Parameters:**
+
+- `obj: undefined` — The source object
+- `keys: readonly string[]` — The keys to pick
+
+**Returns:** `undefined` — A new object with only the picked keys
+
+```typescript
+import { pick } from '@helpers4/object';
+
+pick(obj: null, keys: readonly string[]): null
+```
+
+**Parameters:**
+
+- `obj: null` — The source object
+- `keys: readonly string[]` — The keys to pick
+
+**Returns:** `null` — A new object with only the picked keys
+
+**Examples:**
+
+*Pick specific keys*
+
+Creates a new object with only the specified keys.
+
+```typescript
+pick({ a: 1, b: 2, c: 3 }, ['a', 'c'])
+// => { a: 1, c: 3 }
+```
+
+*Extract user fields*
+
+Useful to select only the fields you need from an object.
+
+```typescript
+const user = { id: 1, name: 'Alice', email: 'alice@example.com', password: 'secret' };
+pick(user, ['id', 'name', 'email'])
+// => { id: 1, name: 'Alice', email: 'alice@example.com' }
+```
+
+---
+
+### `removeUndefinedNull`
+
+Remove null and undefined values from an object.
+
+```typescript
+import { removeUndefinedNull } from '@helpers4/object';
+
+removeUndefinedNull<T extends Record<string, string | number | boolean | null | undefined>>(obj: T): Partial<T>
+```
+
+**Parameters:**
+
+- `obj: T` — an object
+
+**Returns:** `Partial<T>` — A shallow copy of the object without null or undefined values
+
+```typescript
+import { removeUndefinedNull } from '@helpers4/object';
+
+removeUndefinedNull(obj: null): null
+```
+
+**Parameters:**
+
+- `obj: null` — a null object
+
+**Returns:** `null` — null
+
+```typescript
+import { removeUndefinedNull } from '@helpers4/object';
+
+removeUndefinedNull(obj: undefined): undefined
+```
+
+**Parameters:**
+
+- `obj: undefined` — an undefined object
+
+**Returns:** `undefined` — undefined
+
+**Examples:**
+
+*Strip null and undefined values*
+
+Returns a shallow copy of the object without null or undefined properties.
+
+```typescript
+removeUndefinedNull({ a: 1, b: null, c: undefined, d: 'ok' })
+// => { a: 1, d: 'ok' }
+```
+
+---
+
+### `safeJsonParse`
+
+Parses a JSON string, returning `null` (or a fallback) on any parse failure.
+
+Unlike `JSON.parse`, this never throws. Invalid JSON strings and other
+parsing edge-cases resolve to `null` or the provided `fallback`.
+
+```typescript
+import { safeJsonParse } from '@helpers4/object';
+
+safeJsonParse<T>(input: string): T | null
+```
+
+**Parameters:**
+
+- `input: string` — The JSON string to parse.
+
+**Returns:** `T | null` — The parsed value typed as `T`, or `fallback` on failure.
+
+```typescript
+import { safeJsonParse } from '@helpers4/object';
+
+safeJsonParse<T>(input: string, fallback: T): T
+```
+
+**Parameters:**
+
+- `input: string` — The JSON string to parse.
+- `fallback: T` — Value returned on failure. Defaults to `null` when omitted.
+
+**Returns:** `T` — The parsed value typed as `T`, or `fallback` on failure.
+
+**Examples:**
+
+*Parse valid JSON*
+
+Returns the parsed value when the input is valid JSON.
+
+```typescript
+safeJsonParse<{ a: number }>('{"a":1}')
+// => { a: 1 }
+```
+
+*Return null on invalid input*
+
+Returns null instead of throwing when JSON is malformed.
+
+```typescript
+safeJsonParse('invalid')
+// => null
+```
+
+*Use a fallback value*
+
+Returns the provided fallback when parsing fails.
+
+```typescript
+safeJsonParse('invalid', [])
+// => []
+```
+
+---
+
+### `set`
+
+Sets a value in an object using a dot-notated path
+
+```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 set value in
+- `path: string` — The dot-notated path (e.g., 'a.b.c')
+- `value: unknown` — The value to set
+
+**Returns:** `Record<string, unknown>` — The modified object
+
+**Examples:**
+
+*Set a nested property*
+
+Creates intermediate objects as needed along the dot-notated path.
+
+```typescript
+set({}, 'a.b.c', 42)
+// => { 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
+```
+
+---