@rxap/utilities/src/lib/deep-merge.d.ts

A collection of utility functions, types and interfaces.

import { RecursivePartial } from './helpers';
export type MergeFunction = (lVal: any, rVal: any, mergeArrayFunction: MergeArrayFunction) => any;
export type MergeArrayFunction = (lVal: any[], rVal: any[], mergeDeepFunction: MergeFunction) => any[];
/**
 * Merges two objects deeply, giving priority to the properties of the second object (`rObj`) in case of a conflict.
 *
 * @param {any} lObj - The first object to be merged. This object's properties will be overridden by `rObj`'s properties in case of a conflict.
 * @param {any} rObj - The second object to be merged. This object's properties will override `lObj`'s properties in case of a conflict.
 * @param {MergeArrayFunction} mergeArrayFunction - The function used to merge arrays
 *
 * @returns {any} A new object that is the result of a deep merge of `lObj` and `rObj`. In case of a conflict, the properties of `rObj` will take precedence.
 *
 * @example
 * // returns { a: 1, b: 2, c: 3 }
 * mergeDeepRight({ a: 1, b: 2 }, { b: 3, c: 3 });
 *
 * @function MergeDeepRight
 */
export declare function MergeDeepRight(lObj: any, rObj: any, mergeArrayFunction: MergeArrayFunction): Record<string, any>;
/**
 * Merges two objects deeply, giving priority to the properties of the first object (`lObj`) in case of a conflict.
 *
 * @param {any} lObj - The first object to be merged. This object's properties will override `rObj`'s properties in case of a conflict.
 * @param {any} rObj - The second object to be merged. This object's properties will be overridden by `lObj`'s properties in case of a conflict.
 * @param {MergeArrayFunction} mergeArrayFunction - The function used to merge arrays
 *
 * @returns {any} A new object that is the result of a deep merge of `lObj` and `rObj`. In case of a conflict, the properties of `lObj` will take precedence.
 *
 * @example
 * // returns { a: 1, b: 2, c: 3 }
 * mergeDeepLeft({ a: 1, b: 2 }, { b: 3, c: 3 });
 *
 * @function MergeDeepLeft
 */
export declare function MergeDeepLeft(lObj: any, rObj: any, mergeArrayFunction: MergeArrayFunction): Record<string, any>;
/**
 * Merges two arrays deeply by applying a custom merge function to elements at corresponding indices.
 *
 * This function creates a new array where each element is the result of a deep merge operation between
 * elements from two input arrays at the same index. The merging of elements at each index is handled by
 * a user-provided merge function. If an element exists in the second array but not in the first, the element
 * from the second array is taken as is. If an element exists in both arrays, the merge function is applied.
 *
 * @param {any[]} a - The first array to merge.
 * @param {any[]} b - The second array to merge. Elements in this array can overwrite or be merged with elements in the first array.
 * @param {MergeFunction} mergeDeepFunction - A function that defines how two elements should be merged deeply. It should take two values and return the merged result.
 * @returns {any[]} A new array containing the deeply merged elements of the two input arrays.
 *
 * @example
 * const array1 = [{ name: "Alice" }, { name: "Bob" }];
 * const array2 = [{ age: 25 }, { age: 30 }];
 * const mergedArray = MergeArrayDeep(array1, array2, (x, y) => ({ ...x, ...y }));
 * // mergedArray would be [{ name: "Alice", age: 25 }, { name: "Bob", age: 30 }]
 */
export declare function MergeArrayDeep(a: any[], b: any[], mergeDeepFunction: MergeFunction): any;
/**
 * Returns a shallow copy of the first array passed to the function.
 *
 * This function ignores the second array and the merge function provided as parameters.
 * It simply returns a new array that is a shallow copy of the first array, meaning that
 * the elements of the new array are exactly the same as the elements of the input array `a`.
 * Changes to the elements of the returned array will reflect on the corresponding elements
 * of the original array if those elements are objects.
 *
 * @param a - The array to be copied.
 * @param b - This parameter is not used in the function.
 * @param mergeDeepFunction - This parameter is not used in the function.
 * @returns A new array that is a shallow copy of array `a`.
 */
export declare function UseLeftArray(a: any[], b: any[], mergeDeepFunction: MergeFunction): any[];
/**
 * Returns a shallow copy of the second array provided.
 *
 * This function ignores the first array and the merge function provided, and simply returns a new array that is a shallow copy of the second array. This means that the new array will have the same elements as the second array, but will be a different object in memory.
 *
 * @param a - The first array, which is not used in this function.
 * @param b - The second array, from which a shallow copy is created and returned.
 * @param mergeDeepFunction - A function intended for merging, which is not utilized in this function.
 * @returns A new array that is a shallow copy of array `b`.
 */
export declare function UseRightArray(a: any[], b: any[], mergeDeepFunction: MergeFunction): any[];
/**
 * Merges two objects or arrays deeply, returning a new object or array that contains the combined contents of both.
 * If the same key exists in both objects, the value from the second object (`b`) will be used.
 * If the same index exists in both arrays, the value from the second array (`b`) will be used.
 *
 * @template T The type of the objects or arrays to be merged.
 *
 * @param {T} a The first object or array to merge. This will not be modified.
 * @param {Partial<T> | RecursivePartial<T> | T} b The second object or array to merge. This will not be modified.
 * @param {Function} mergeDeepFunction The function to use to merge nested objects or arrays.
 *
 * @returns {T} A new object or array that contains the combined contents of `a` and `b`.
 *
 * @throws {TypeError} If `a` or `b` is not an object or array.
 *
 * @example
 *
 * deepMerge({ a: 1, b: 2 }, { b: 3, c: 4 }); // Returns { a: 1, b: 3, c: 4 }
 * deepMerge([1, 2], [2, 3]); // Returns [2, 3]
 *
 * @note
 *
 * - If `a` and `b` are both arrays, the returned array will have a length equal to the longer of the two input arrays.
 * - If `a` and `b` are both objects, the returned object will contain all keys present in either `a` or `b`.
 * - If `a` is an array and `b` is an object, or vice versa, a TypeError will be thrown.
 * - This function uses recursion to merge objects and arrays deeply. Therefore, it may not be suitable for very large or deeply nested objects or arrays due to the risk of a stack overflow.
 *
 */
export declare function deepMerge<T>(a: T, b: Partial<T> | RecursivePartial<T> | T, mergeDeepFunction?: MergeFunction, mergeArrayFunction?: MergeArrayFunction): T;