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

package/README.md

@@ -12,11 +12,13 @@ A set of helpers for working with URLs.
 [https://helpers4.js.org/object](https://helpers4.js.org/object)
 
 <!-- AUTOMATIC-METHODS -->
-- get
-- set
+- deepClone
+- deepCompare
 - deepMerge
+- get
+- quickCompare
 - removeUndefinedNull
-- deepClone
+- set
 <!-- /AUTOMATIC-METHODS -->
 
 ## See
@@ -25,6 +27,7 @@ A set of helpers for working with URLs.
 - [array](../array)
 - [date](../date)
 - [function](../function)
+- [math](../math)
 - [number](../number)
 - [observable](../observable)
 - [promise](../promise)
@@ -42,6 +45,7 @@ A set of helpers for working with URLs.
 | 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 |
 | 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 |
 | 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/api.json

@@ -0,0 +1,143 @@
+{
+  "category": "object",
+  "members": [
+    {
+      "name": "deepClone",
+      "kind": "function",
+      "description": "Creates a deep copy of an object or array",
+      "signature": "deepClone<T>(obj: T): T",
+      "params": [
+        {
+          "name": "obj",
+          "type": "T",
+          "description": "The object to clone"
+        }
+      ],
+      "returns": "T"
+    },
+    {
+      "name": "deepCompare",
+      "kind": "function",
+      "description": "Deep comparison of two objects that returns detailed information about differences.",
+      "signature": "deepCompare(objA: object | null | undefined, objB: object | null | undefined): boolean | DeepCompareResult",
+      "params": [
+        {
+          "name": "objA",
+          "type": "object | null | undefined",
+          "description": "First object to compare (can be object, undefined, or null)"
+        },
+        {
+          "name": "objB",
+          "type": "object | null | undefined",
+          "description": "Second object to compare (can be object, undefined, or null)"
+        }
+      ],
+      "returns": "boolean | DeepCompareResult"
+    },
+    {
+      "name": "DeepCompareResult",
+      "kind": "interface",
+      "description": "Result type for deep comparison when objects are not identical"
+    },
+    {
+      "name": "deepMerge",
+      "kind": "function",
+      "description": "Merges two or more objects deeply",
+      "signature": "deepMerge<T>(target: T, sources: Record<string, any>[]): T",
+      "params": [
+        {
+          "name": "target",
+          "type": "T",
+          "description": "The target object"
+        },
+        {
+          "name": "sources",
+          "type": "Record<string, any>[]",
+          "description": "The source objects to merge"
+        }
+      ],
+      "returns": "T"
+    },
+    {
+      "name": "get",
+      "kind": "function",
+      "description": "Gets a value from an object using a dot-notated path",
+      "signature": "get<T>(obj: any, path: string, defaultValue: T): T | undefined",
+      "params": [
+        {
+          "name": "obj",
+          "type": "any",
+          "description": "The object to get value from"
+        },
+        {
+          "name": "path",
+          "type": "string",
+          "description": "The dot-notated path (e.g., 'a.b.c')"
+        },
+        {
+          "name": "defaultValue",
+          "type": "T",
+          "description": "Default value if path doesn't exist"
+        }
+      ],
+      "returns": "T | undefined"
+    },
+    {
+      "name": "quickCompare",
+      "kind": "function",
+      "description": "Quick comparison of two objects using JSON.stringify.\nThis is a fast but simple comparison that may not work for all edge cases.",
+      "signature": "quickCompare(objA: unknown, objB: unknown): boolean",
+      "params": [
+        {
+          "name": "objA",
+          "type": "unknown",
+          "description": "First object to compare"
+        },
+        {
+          "name": "objB",
+          "type": "unknown",
+          "description": "Second object to compare"
+        }
+      ],
+      "returns": "boolean"
+    },
+    {
+      "name": "removeUndefinedNull",
+      "kind": "function",
+      "description": "Remove null and undefined values from an object.",
+      "signature": "removeUndefinedNull<T>(obj: T): Partial<T>",
+      "params": [
+        {
+          "name": "obj",
+          "type": "T",
+          "description": "an object"
+        }
+      ],
+      "returns": "Partial<T>"
+    },
+    {
+      "name": "set",
+      "kind": "function",
+      "description": "Sets a value in an object using a dot-notated path",
+      "signature": "set(obj: Record<string, any>, path: string, value: any): Record<string, any>",
+      "params": [
+        {
+          "name": "obj",
+          "type": "Record<string, any>",
+          "description": "The object to set value in"
+        },
+        {
+          "name": "path",
+          "type": "string",
+          "description": "The dot-notated path (e.g., 'a.b.c')"
+        },
+        {
+          "name": "value",
+          "type": "any",
+          "description": "The value to set"
+        }
+      ],
+      "returns": "Record<string, any>"
+    }
+  ]
+}

package/examples.json

@@ -0,0 +1,85 @@
+{
+  "category": "object",
+  "helpers": [
+    {
+      "helper": "deepClone",
+      "examples": [
+        {
+          "title": "Clone a nested object",
+          "description": "Creates a deep copy — modifying the clone does not affect the original.",
+          "code": "const original = { a: { b: 1 } };\nconst cloned = deepClone(original);\ncloned.a.b = 2;\n// original.a.b is still 1"
+        }
+      ]
+    },
+    {
+      "helper": "deepCompare",
+      "examples": [
+        {
+          "title": "Compare nested objects",
+          "description": "Deeply compares two objects, returning true when they are structurally equal.",
+          "code": "deepCompare({ a: { b: 1 } }, { a: { b: 1 } })\n// => true"
+        },
+        {
+          "title": "Detect deep differences",
+          "description": "Returns a detailed diff object when nested values differ.",
+          "code": "deepCompare({ a: { b: 1 } }, { a: { b: 2 } })\n// => { a: { b: false } }"
+        }
+      ]
+    },
+    {
+      "helper": "deepMerge",
+      "examples": [
+        {
+          "title": "Merge two objects deeply",
+          "description": "Recursively merges source properties into the target object.",
+          "code": "deepMerge({ a: 1, b: { c: 2 } }, { b: { d: 3 }, e: 4 })\n// => { a: 1, b: { c: 2, d: 3 }, e: 4 }"
+        }
+      ]
+    },
+    {
+      "helper": "get",
+      "examples": [
+        {
+          "title": "Access a nested property",
+          "description": "Uses a dot-notated path to retrieve a deeply nested value.",
+          "code": "get({ a: { b: { c: 42 } } }, 'a.b.c')\n// => 42"
+        },
+        {
+          "title": "Return default for missing path",
+          "description": "Returns the default value when the path does not exist.",
+          "code": "get({ a: 1 }, 'b.c', 'default')\n// => 'default'"
+        }
+      ]
+    },
+    {
+      "helper": "quickCompare",
+      "examples": [
+        {
+          "title": "Compare two equal objects",
+          "description": "Uses JSON.stringify for a fast comparison.",
+          "code": "quickCompare({ a: 1, b: 2 }, { a: 1, b: 2 })\n// => true"
+        }
+      ]
+    },
+    {
+      "helper": "removeUndefinedNull",
+      "examples": [
+        {
+          "title": "Strip null and undefined values",
+          "description": "Returns a shallow copy of the object without null or undefined properties.",
+          "code": "removeUndefinedNull({ a: 1, b: null, c: undefined, d: 'ok' })\n// => { a: 1, d: 'ok' }"
+        }
+      ]
+    },
+    {
+      "helper": "set",
+      "examples": [
+        {
+          "title": "Set a nested property",
+          "description": "Creates intermediate objects as needed along the dot-notated path.",
+          "code": "set({}, 'a.b.c', 42)\n// => { a: { b: { c: 42 } } }"
+        }
+      ]
+    }
+  ]
+}

package/lib/index.d.ts

@@ -1,5 +1,117 @@
-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
+ */
+/**
+ * Creates a deep copy of an object or array
+ * @param obj - The object to clone
+ * @returns Deep cloned object
+ */
+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
+ */
+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
+ */
+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
+ */
+declare function deepMerge<T extends Record<string, any>>(target: T, ...sources: Record<string, any>[]): T;
+
+/**
+ * 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
+ */
+declare function get<T = any>(obj: any, path: string, defaultValue?: T): T | undefined;
+
+/**
+ * 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
+ */
+declare function quickCompare(objA: unknown, objB: unknown): boolean;
+
+/**
+ * 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
+ */
+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
+ */
+declare function removeUndefinedNull(obj: null): null;
+/**
+ * Remove null and undefined values from an object.
+ *
+ * @param obj an undefined object
+ * @returns undefined
+ */
+declare function removeUndefinedNull(obj: undefined): undefined;
+
+/**
+ * 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
+ */
+declare function set(obj: Record<string, any>, path: string, value: any): Record<string, any>;
+
+export { deepClone, deepCompare, deepMerge, get, quickCompare, removeUndefinedNull, set };
+export type { DeepCompareResult };