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

package/README.md

@@ -12,12 +12,20 @@ A set of helpers for working with URLs.
 [https://helpers4.dev/typescript/categories/object/](https://helpers4.dev/typescript/categories/object/)
 
 <!-- AUTOMATIC-METHODS -->
+- compact
 - deepClone
-- deepCompare
 - deepMerge
+- diff
+- equalsDeep
+- equalsShallow
 - get
-- quickCompare
+- groupBy
+- invert
+- map
+- omit
+- pick
 - removeUndefinedNull
+- safeJsonParse
 - set
 <!-- /AUTOMATIC-METHODS -->
 
@@ -25,9 +33,12 @@ A set of helpers for working with URLs.
 
 <!-- AUTOMATIC-SIBLINGS -->
 - [array](../array)
+- [ci](../ci)
+- [commit](../commit)
 - [date](../date)
 - [function](../function)
-- [math](../math)
+- [id](../id)
+- [markdown](../markdown)
 - [number](../number)
 - [observable](../observable)
 - [promise](../promise)
@@ -43,15 +54,18 @@ A set of helpers for working with URLs.
 | Name | Package | Source Code | Description |
 |------|---------|-------------|-------------|
 | array | [@helpers4/array](https://www.npmjs.com/package/@helpers4/array) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/array) | Array manipulation utilities |
-| date | [@helpers4/date](https://www.npmjs.com/package/@helpers4/date) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/date) | date utilities |
+| ci | [@helpers4/ci](https://www.npmjs.com/package/@helpers4/ci) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/ci) | CI/CD workflow status utilities |
+| commit | [@helpers4/commit](https://www.npmjs.com/package/@helpers4/commit) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/commit) | Conventional Commits parsing and analysis |
+| date | [@helpers4/date](https://www.npmjs.com/package/@helpers4/date) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/date) | Date and time utility functions |
 | function | [@helpers4/function](https://www.npmjs.com/package/@helpers4/function) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/function) | Function utilities and type guards |
-| math | [@helpers4/math](https://www.npmjs.com/package/@helpers4/math) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/math) | math utilities |
-| number | [@helpers4/number](https://www.npmjs.com/package/@helpers4/number) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/number) | number utilities |
+| id | [@helpers4/id](https://www.npmjs.com/package/@helpers4/id) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/id) | Unique identifier generation utilities |
+| markdown | [@helpers4/markdown](https://www.npmjs.com/package/@helpers4/markdown) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/markdown) | Markdown formatting and escaping utilities |
+| number | [@helpers4/number](https://www.npmjs.com/package/@helpers4/number) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/number) | Number utility functions and validation |
 | object | [@helpers4/object](https://www.npmjs.com/package/@helpers4/object) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/object) | Object manipulation utilities |
 | observable | [@helpers4/observable](https://www.npmjs.com/package/@helpers4/observable) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/observable) | Observable utilities and combinators |
 | promise | [@helpers4/promise](https://www.npmjs.com/package/@helpers4/promise) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/promise) | Promise utilities and error handling |
 | string | [@helpers4/string](https://www.npmjs.com/package/@helpers4/string) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/string) | String manipulation and formatting utilities |
-| type | [@helpers4/type](https://www.npmjs.com/package/@helpers4/type) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/type) | type utilities |
+| type | [@helpers4/type](https://www.npmjs.com/package/@helpers4/type) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/type) | Type checking and validation utilities |
 | url | [@helpers4/url](https://www.npmjs.com/package/@helpers4/url) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/url) | URL parsing and manipulation utilities |
 | version | [@helpers4/version](https://www.npmjs.com/package/@helpers4/version) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/version) | Version string manipulation utilities |
 <!-- /AUTOMATIC-CATEGORIES-TABLE -->

package/lib/index.d.ts

@@ -1,3 +1,21 @@
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Removes all entries with falsy values (`false`, `null`, `undefined`, `0`, `""`, `NaN`) from an object.
+ * @param obj - The source object
+ * @returns A new object containing only entries with truthy values
+ * @example
+ * compact({ a: 1, b: null, c: '', d: 0, e: 'hello' })
+ * // => { a: 1, e: 'hello' }
+ * @since 2.0.0
+ */
+declare function compact<T extends Record<string, unknown>>(obj: T): Partial<T>;
+declare function compact(obj: undefined): undefined;
+declare function compact(obj: null): null;
+
 /**
  * This file is part of helpers4.
  * Copyright (C) 2025 baxyz
@@ -17,21 +35,78 @@ declare function deepClone<T>(obj: T): T;
  * SPDX-License-Identifier: LGPL-3.0-or-later
  */
 /**
- * Result type for deep comparison when objects are not identical
+ * Merges two or more objects deeply
+ * @param target - The target object
+ * @param sources - The source objects to merge
+ * @returns The merged object
+ * @since 1.9.0
+ */
+declare function deepMerge<T extends Record<string, unknown>>(target: T, ...sources: Record<string, unknown>[]): T;
+declare function deepMerge(target: undefined, ...sources: Record<string, unknown>[]): undefined;
+declare function deepMerge(target: null, ...sources: Record<string, unknown>[]): null;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Per-key diff result. Each entry tells what differs between the two
+ * objects:
+ * - `"onlyA"` \u2014 the key exists only on the first input.
+ * - `"onlyB"` \u2014 the key exists only on the second input.
+ * - `false`  \u2014 both inputs have the key but the values differ.
+ * - nested `DiffResult` \u2014 plain-object values that differ deeper.
+ *
+ * @since 2.0.0
+ */
+interface DiffResult {
+    [key: string]: 'onlyA' | 'onlyB' | false | DiffResult;
+}
+/**
+ * Options for {@link diff}.
  * @since 2.0.0
  */
-interface DeepCompareResult {
-    [key: string]: "onlyA" | "onlyB" | false | DeepCompareResult;
+interface DiffOptions {
+    /**
+     * Maximum recursion depth for nested plain objects. Defaults to
+     * `Infinity` (full structural diff).
+     *
+     * - `0` compares values at the top-level only with strict equality.
+     * - `1` compares the first level of nested objects with strict equality.
+     * - `Infinity` recurses through every plain-object level.
+     *
+     * Arrays, `Date` and special objects (Map, Set, RegExp\u2026) are always
+     * leaf-compared (via {@link arrayDeepEquals}, epoch comparison, or
+     * reference equality respectively) regardless of `depth`.
+     */
+    depth?: number;
 }
 /**
- * Deep comparison of two objects that returns detailed information about differences.
+ * Structural object diff.
+ *
+ * Returns `true` when both inputs are deeply equal, otherwise a
+ * {@link DiffResult} describing the differences key by key.
+ *
+ * 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 {@link equalsDeep} from this category.
+ * For a one-level boolean check see {@link equalsShallow} from this category.
  *
- * @param objA - First object to compare (can be object, undefined, or null)
- * @param objB - Second object to compare (can be object, undefined, or null)
- * @returns `true` if objects are identical, `false` if incompatible types, or a `DeepCompareResult` object detailing differences
+ * @param objA - First value (object, `null`, or `undefined`).
+ * @param objB - Second value (object, `null`, or `undefined`).
+ * @param options - See {@link DiffOptions}.
+ * @returns `true` when equal, otherwise a {@link DiffResult}, or `false` for incompatible types.
  * @since 2.0.0
  */
-declare function deepCompare(objA: object | undefined | null, objB: object | undefined | null): true | false | DeepCompareResult;
+declare function diff(objA: object | undefined | null, objB: object | undefined | null, options?: DiffOptions): true | false | DiffResult;
 
 /**
  * This file is part of helpers4.
@@ -39,13 +114,48 @@ declare function deepCompare(objA: object | undefined | null, objB: object | und
  * SPDX-License-Identifier: LGPL-3.0-or-later
  */
 /**
- * Merges two or more objects deeply
- * @param target - The target object
- * @param sources - The source objects to merge
- * @returns The merged object
- * @since 1.9.0
+ * Recursive structural object equality.
+ *
+ * Boolean wrapper around {@link 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 {@link diff} when you also need to know
+ * *what* differs.
+ *
+ * For a one-level boolean check use {@link equalsShallow}.
+ *
+ * @param objA - First value (object, `null`, or `undefined`).
+ * @param objB - Second value (object, `null`, or `undefined`).
+ * @returns `true` if both inputs are deeply equal, `false` otherwise.
+ * @since 2.0.0
+ */
+declare function equalsDeep(objA: object | undefined | null, objB: object | undefined | null): boolean;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * 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 {@link equalsDeep}. For a diff
+ * structure use {@link diff}.
+ *
+ * @param objA - First value to compare
+ * @param objB - Second value to compare
+ * @returns `true` if values are shallowly equal, `false` otherwise.
+ * @since 2.0.0
  */
-declare function deepMerge<T extends Record<string, any>>(target: T, ...sources: Record<string, any>[]): T;
+declare function equalsShallow(objA: unknown, objB: unknown): boolean;
 
 /**
  * This file is part of helpers4.
@@ -60,7 +170,7 @@ declare function deepMerge<T extends Record<string, any>>(target: T, ...sources:
  * @returns The value at the path or default value
  * @since 1.9.0
  */
-declare function get<T = any>(obj: any, path: string, defaultValue?: T): T | undefined;
+declare function get<T = unknown>(obj: unknown, path: string, defaultValue?: T): T | undefined;
 
 /**
  * This file is part of helpers4.
@@ -68,15 +178,113 @@ declare function get<T = any>(obj: any, path: string, defaultValue?: T): T | und
  * SPDX-License-Identifier: LGPL-3.0-or-later
  */
 /**
- * Quick comparison of two objects using JSON.stringify.
- * This is a fast but simple comparison that may not work for all edge cases.
+ * Groups an array of items by a key derived from each item.
  *
- * @param objA - First object to compare
- * @param objB - Second object to compare
- * @returns `true` if objects are identical according to JSON.stringify, `false` otherwise
+ * A thin, typed wrapper around `Object.groupBy` (ES2024) that works on
+ * older targets and provides stricter return-type inference.
+ *
+ * @param items - The array to group
+ * @param keyFn - Function that returns the group key for each item
+ * @returns A record mapping each key to the array of items with that key
+ * @example
+ * groupBy([1, 2, 3, 4], n => n % 2 === 0 ? 'even' : 'odd')
+ * // => { odd: [1, 3], even: [2, 4] }
+ * @since next
+ */
+declare function groupBy<T, K extends PropertyKey>(items: readonly T[], keyFn: (item: T) => K): Partial<Record<K, T[]>>;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Returns a new object with keys and values swapped.
+ * If multiple keys share the same value, the last one wins.
+ *
+ * @param obj - The object whose keys and values are to be swapped
+ * @returns A new object with values as keys and original keys as values
+ * @example
+ * invert({ a: 'x', b: 'y', c: 'z' })
+ * // => { x: 'a', y: 'b', z: 'c' }
+ *
+ * invert({ one: 1, two: 2 })
+ * // => { 1: 'one', 2: 'two' }
+ * @since next
+ */
+declare function invert<K extends string, V extends PropertyKey>(obj: Record<K, V>): Record<V, K>;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * 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).
+ *
+ * @param obj - The source object
+ * @param mapValue - Callback called with `(value, key)` for each entry.
+ *   Defaults to identity.
+ * @param mapKey - Callback called with `(key, value)` for each entry.
+ *   Defaults to identity.
+ * @returns A new object with transformed keys and/or values
+ * @example
+ * map({ a: 1, b: 2 }, v => v * 10)
+ * // => { a: 10, b: 20 }
+ *
+ * map({ a: 1, b: 2 }, undefined, k => k.toUpperCase())
+ * // => { A: 1, B: 2 }
+ *
+ * map({ a: 1, b: 2 }, v => v * 10, k => k.toUpperCase())
+ * // => { A: 10, B: 20 }
+ * @since next
+ */
+declare function map<TObj extends Record<string, unknown>, TVal = TObj[keyof TObj], TKey extends PropertyKey = keyof TObj>(obj: TObj, mapValue?: (value: TObj[keyof TObj], key: keyof TObj) => TVal, mapKey?: (key: keyof TObj, value: TObj[keyof TObj]) => TKey): Record<TKey, TVal>;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Creates a new object without the specified keys.
+ * @param obj - The source object
+ * @param keys - The keys to omit
+ * @returns A new object without the omitted keys
+ * @example
+ * omit({ a: 1, b: 2, c: 3 }, ['b'])
+ * // => { a: 1, c: 3 }
  * @since 2.0.0
  */
-declare function quickCompare(objA: unknown, objB: unknown): boolean;
+declare function omit<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: readonly K[]): Omit<T, K>;
+declare function omit(obj: undefined, keys: readonly string[]): undefined;
+declare function omit(obj: null, keys: readonly string[]): null;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Creates a new object with only the specified keys.
+ * @param obj - The source object
+ * @param keys - The keys to pick
+ * @returns A new object with only the picked keys
+ * @example
+ * pick({ a: 1, b: 2, c: 3 }, ['a', 'c'])
+ * // => { a: 1, c: 3 }
+ * @since 2.0.0
+ */
+declare function pick<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: readonly K[]): Pick<T, K>;
+declare function pick(obj: undefined, keys: readonly string[]): undefined;
+declare function pick(obj: null, keys: readonly string[]): null;
 
 /**
  * This file is part of helpers4.
@@ -108,6 +316,29 @@ declare function removeUndefinedNull(obj: null): null;
  */
 declare function removeUndefinedNull(obj: undefined): undefined;
 
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * 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`.
+ *
+ * @param input - The JSON string to parse.
+ * @param fallback - Value returned on failure. Defaults to `null` when omitted.
+ * @returns The parsed value typed as `T`, or `fallback` on failure.
+ * @example
+ * safeJsonParse<{ a: number }>('{"a":1}')  // => { a: 1 }
+ * safeJsonParse('invalid')                 // => null
+ * safeJsonParse('invalid', [])             // => []
+ * @since next
+ */
+declare function safeJsonParse<T>(input: string): T | null;
+declare function safeJsonParse<T>(input: string, fallback: T): T;
+
 /**
  * This file is part of helpers4.
  * Copyright (C) 2025 baxyz
@@ -121,7 +352,7 @@ declare function removeUndefinedNull(obj: undefined): undefined;
  * @returns The modified object
  * @since 1.9.0
  */
-declare function set(obj: Record<string, any>, path: string, value: any): Record<string, any>;
+declare function set(obj: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
 
-export { deepClone, deepCompare, deepMerge, get, quickCompare, removeUndefinedNull, set };
-export type { DeepCompareResult };
+export { compact, deepClone, deepMerge, diff, equalsDeep, equalsShallow, get, groupBy, invert, map, omit, pick, removeUndefinedNull, safeJsonParse, set };
+export type { DiffOptions, DiffResult };