@helpers4/object 2.0.0-alpha.2 → 2.0.0-alpha.22

package/README.md

@@ -9,22 +9,30 @@ A set of helpers for working with URLs.
 
 ## Documentation
 
-[https://helpers4.js.org/object](https://helpers4.js.org/object)
+[https://helpers4.dev/typescript/categories/object/](https://helpers4.dev/typescript/categories/object/)
 
 <!-- AUTOMATIC-METHODS -->
-- get
-- set
+- compact
+- deepClone
+- deepCompare
 - deepMerge
+- get
+- omit
+- pick
 - removeUndefinedNull
-- deepClone
+- safeJsonParse
+- set
+- shallowEquals
 <!-- /AUTOMATIC-METHODS -->
 
 ## See
 
 <!-- AUTOMATIC-SIBLINGS -->
 - [array](../array)
+- [commit](../commit)
 - [date](../date)
 - [function](../function)
+- [math](../math)
 - [number](../number)
 - [observable](../observable)
 - [promise](../promise)
@@ -40,14 +48,16 @@ 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 |
+| 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 |
-| number | [@helpers4/number](https://www.npmjs.com/package/@helpers4/number) | [Source](https://github.com/helpers4/helpers4/tree/main/helpers/number) | number utilities |
+| 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 |
+| 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,5 +1,208 @@
-export declare function get<T = any>(obj: any, path: string, defaultValue?: T): T | undefined;
-export declare function set(obj: Record<string, any>, path: string, value: any): Record<string, any>;
-export declare function deepMerge<T extends Record<string, any>>(target: T, ...sources: Record<string, any>[]): T;
-export declare function removeUndefinedNull<T extends Record<string, string | boolean | number>>(obj: T): T;  /** * Remove null and undefined values from an object. * * @param obj a null object * @returns null */ export function removeUndefinedNull<T extends Record<string, string | boolean | number>>(obj: null): null;  /** * Remove null and undefined values from an object. * * @param obj an undefined object * @returns undefined */ export function removeUndefinedNull<T extends Record<string, string | boolean | number>>(obj: undefined): undefined;  /** * Remove null and undefined values from an object. * * @param obj an object * @returns A shallow copy of the object without null or undefined values */ export function removeUndefinedNull<T extends Record<string, string | boolean | number>>(obj: T | null | undefined): T | null | undefined;
-export declare function deepClone<T>(obj: T): T;
+/**
+ * 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
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Creates a deep copy of an object or array
+ * @param obj - The object to clone
+ * @returns Deep cloned object
+ * @since 1.9.0
+ */
+declare function deepClone<T>(obj: T): T;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Result type for deep comparison when objects are not identical
+ * @since 2.0.0
+ */
+interface DeepCompareResult {
+    [key: string]: "onlyA" | "onlyB" | false | DeepCompareResult;
+}
+/**
+ * Deep comparison of two objects that returns detailed information about differences.
+ *
+ * @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
+ * @since 2.0.0
+ */
+declare function deepCompare(objA: object | undefined | null, objB: object | undefined | null): true | false | DeepCompareResult;
+
+/**
+ * This file is part of helpers4.
+ * Copyright (C) 2025 baxyz
+ * 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
+ */
+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
+ */
+/**
+ * Gets a value from an object using a dot-notated path
+ * @param obj - The object to get value from
+ * @param path - The dot-notated path (e.g., 'a.b.c')
+ * @param defaultValue - Default value if path doesn't exist
+ * @returns The value at the path or default value
+ * @since 1.9.0
+ */
+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
+ */
+/**
+ * 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 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.
+ * Copyright (C) 2025 baxyz
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Remove null and undefined values from an object.
+ *
+ * @param obj an object
+ * @returns A shallow copy of the object without null or undefined values
+ * @since 1.0.0
+ */
+declare function removeUndefinedNull<T extends Record<string, string | number | boolean | null | undefined>>(obj: T): Partial<T>;
+/**
+ * Remove null and undefined values from an object.
+ *
+ * @param obj a null object
+ * @returns null
+ * @since 1.0.0
+ */
+declare function removeUndefinedNull(obj: null): null;
+/**
+ * Remove null and undefined values from an object.
+ *
+ * @param obj an undefined object
+ * @returns undefined
+ * @since 1.0.0
+ */
+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
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ */
+/**
+ * Sets a value in an object using a dot-notated path
+ * @param obj - The object to set value in
+ * @param path - The dot-notated path (e.g., 'a.b.c')
+ * @param value - The value to set
+ * @returns The modified object
+ * @since 1.9.0
+ */
+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 };