@helpers4/object 2.0.0-beta.0 → 2.0.0

package/README.md

@@ -14,25 +14,31 @@ A set of helpers for working with URLs.
 <!-- AUTOMATIC-METHODS -->
 - compact
 - deepClone
-- deepCompare
 - deepMerge
+- diff
+- equalsDeep
+- equalsShallow
 - get
+- groupBy
+- invert
+- map
 - omit
 - pick
 - removeUndefinedNull
 - safeJsonParse
 - set
-- shallowEquals
 <!-- /AUTOMATIC-METHODS -->
 
 ## See
 
 <!-- AUTOMATIC-SIBLINGS -->
 - [array](../array)
+- [ci](../ci)
 - [commit](../commit)
 - [date](../date)
 - [function](../function)
-- [math](../math)
+- [id](../id)
+- [markdown](../markdown)
 - [number](../number)
 - [observable](../observable)
 - [promise](../promise)
@@ -48,10 +54,12 @@ 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 |
+| 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) | Mathematical utility functions and calculations |
+| 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 |

package/lib/index.d.ts

@@ -35,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.
  *
- * @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
+ * 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 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.
@@ -57,15 +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 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;
+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 equalsShallow(objA: unknown, objB: unknown): boolean;
 
 /**
  * This file is part of helpers4.
@@ -82,6 +172,82 @@ declare function deepMerge(target: null, ...sources: Record<string, unknown>[]):
  */
 declare function get<T = unknown>(obj: unknown, path: string, defaultValue?: T): T | undefined;
 
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * 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.
+ *
+ * @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 2.0.0
+ */
+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 2.0.0
+ */
+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 2.0.0
+ */
+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
@@ -168,7 +334,7 @@ declare function removeUndefinedNull(obj: undefined): undefined;
  * safeJsonParse<{ a: number }>('{"a":1}')  // => { a: 1 }
  * safeJsonParse('invalid')                 // => null
  * safeJsonParse('invalid', [])             // => []
- * @since next
+ * @since 2.0.0
  */
 declare function safeJsonParse<T>(input: string): T | null;
 declare function safeJsonParse<T>(input: string, fallback: T): T;
@@ -188,21 +354,5 @@ declare function safeJsonParse<T>(input: string, fallback: T): T;
  */
 declare function set(obj: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
 
-/**
- * This file is part of helpers4.
- * Copyright (C) 2025 baxyz
- * 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.
- *
- * @param objA - First object to compare
- * @param objB - Second object to compare
- * @returns `true` if objects are identical according to JSON.stringify, `false` otherwise
- * @since 2.0.0
- */
-declare function shallowEquals(objA: unknown, objB: unknown): boolean;
-
-export { compact, deepClone, deepCompare, deepMerge, get, omit, pick, removeUndefinedNull, safeJsonParse, set, shallowEquals };
-export type { DeepCompareResult };
+export { compact, deepClone, deepMerge, diff, equalsDeep, equalsShallow, get, groupBy, invert, map, omit, pick, removeUndefinedNull, safeJsonParse, set };
+export type { DiffOptions, DiffResult };