es-toolkit 1.14.0-dev.409 → 1.14.0-dev.410

package/dist/compat/object/mergeWith.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Merges the properties of one or more source objects into the target object.
+ *
+ * This function performs a deep merge, recursively merging nested objects and arrays.
+ * If a property in the source object is an array or object and the corresponding property in the target object is also an array or object, they will be merged.
+ * If a property in the source object is `undefined`, it will not overwrite a defined property in the target object.
+ *
+ * You can provide a custom `merge` function to control how properties are merged. The `merge` function is called for each property that is being merged and receives the following arguments:
+ *
+ * - `targetValue`: The current value of the property in the target object.
+ * - `sourceValue`: The value of the property in the source object.
+ * - `key`: The key of the property being merged.
+ * - `target`: The target object.
+ * - `source`: The source object.
+ * - `stack`: A `Map` used to keep track of objects that have already been processed to handle circular references.
+ *
+ * The `merge` function should return the value to be set in the target object. If it returns `undefined`, a default deep merge will be applied for arrays and objects.
+ *
+ * The function can handle multiple source objects and will merge them all into the target object.
+ *
+ * @param {T} target - The target object into which the source object properties will be merged. This object is modified in place.
+ * @param {S} source - The first source object whose properties will be merged into the target object.
+ * @returns {T & S} The updated target object with properties from the source object(s) merged in.
+ *
+ * @template T - Type of the target object.
+ * @template S - Type of the first source object.
+ *
+ * @example
+ * const target = { a: 1, b: 2 };
+ * const source = { b: 3, c: 4 };
+ *
+ * mergeWith(target, source, (targetValue, sourceValue) => {
+ *   if (typeof targetValue === 'number' && typeof sourceValue === 'number') {
+ *     return targetValue + sourceValue;
+ *   }
+ * });
+ * // Returns { a: 1, b: 5, c: 4 }
+ * @example
+ * const target = { a: [1], b: [2] };
+ * const source = { a: [3], b: [4] };
+ *
+ * const result = mergeWith(target, source, (objValue, srcValue) => {
+ *   if (Array.isArray(objValue)) {
+ *     return objValue.concat(srcValue);
+ *   }
+ * });
+ *
+ * expect(result).toEqual({ a: [1, 3], b: [2, 4] });
+ */
+declare function mergeWith<T, S>(target: T, source: S, merge: (targetValue: any, sourceValue: any, key: string, target: T, source: S, stack: Map<any, any>) => any): T & S;
+/**
+ * Merges the properties of one or more source objects into the target object.
+ *
+ * This function performs a deep merge, recursively merging nested objects and arrays.
+ * If a property in the source object is an array or object and the corresponding property in the target object is also an array or object, they will be merged.
+ * If a property in the source object is `undefined`, it will not overwrite a defined property in the target object.
+ *
+ * You can provide a custom `merge` function to control how properties are merged. The `merge` function is called for each property that is being merged and receives the following arguments:
+ *
+ * - `targetValue`: The current value of the property in the target object.
+ * - `sourceValue`: The value of the property in the source object.
+ * - `key`: The key of the property being merged.
+ * - `target`: The target object.
+ * - `source`: The source object.
+ * - `stack`: A `Map` used to keep track of objects that have already been processed to handle circular references.
+ *
+ * The `merge` function should return the value to be set in the target object. If it returns `undefined`, a default deep merge will be applied for arrays and objects.
+ *
+ * The function can handle multiple source objects and will merge them all into the target object.
+ *
+ * @param {O} object - The target object into which the source object properties will be merged. This object is modified in place.
+ * @param {S1} source1 - The first source object to be merged into the target object.
+ * @param {S2} source2 - The second source object to be merged into the target object.
+ * @returns {O & S1 & S2} The updated target object with properties from the source objects merged in.
+ *
+ * @template O - Type of the target object.
+ * @template S1 - Type of the first source object.
+ * @template S2 - Type of the second source object.
+ *
+ * @example
+ * const target = { a: 1, b: 2 };
+ * const source = { b: 3, c: 4 };
+ *
+ * mergeWith(target, source, (targetValue, sourceValue) => {
+ *   if (typeof targetValue === 'number' && typeof sourceValue === 'number') {
+ *     return targetValue + sourceValue;
+ *   }
+ * });
+ * // Returns { a: 1, b: 5, c: 4 }
+ * @example
+ * const target = { a: [1], b: [2] };
+ * const source = { a: [3], b: [4] };
+ *
+ * const result = mergeWith(target, source, (objValue, srcValue) => {
+ *   if (Array.isArray(objValue)) {
+ *     return objValue.concat(srcValue);
+ *   }
+ * });
+ *
+ * expect(result).toEqual({ a: [1, 3], b: [2, 4] });
+ */
+declare function mergeWith<O, S1, S2>(object: O, source1: S1, source2: S2, merge: (targetValue: any, sourceValue: any, key: string, target: any, source: any, stack: Map<any, any>) => any): O & S1 & S2;
+/**
+ * Merges the properties of one or more source objects into the target object.
+ *
+ * This function performs a deep merge, recursively merging nested objects and arrays.
+ * If a property in the source object is an array or object and the corresponding property in the target object is also an array or object, they will be merged.
+ * If a property in the source object is `undefined`, it will not overwrite a defined property in the target object.
+ *
+ * You can provide a custom `merge` function to control how properties are merged. The `merge` function is called for each property that is being merged and receives the following arguments:
+ *
+ * - `targetValue`: The current value of the property in the target object.
+ * - `sourceValue`: The value of the property in the source object.
+ * - `key`: The key of the property being merged.
+ * - `target`: The target object.
+ * - `source`: The source object.
+ * - `stack`: A `Map` used to keep track of objects that have already been processed to handle circular references.
+ *
+ * The `merge` function should return the value to be set in the target object. If it returns `undefined`, a default deep merge will be applied for arrays and objects.
+ *
+ * The function can handle multiple source objects and will merge them all into the target object.
+ *
+ * @param {O} object - The target object into which the source object properties will be merged. This object is modified in place.
+ * @param {S1} source1 - The first source object whose properties will be merged into the target object.
+ * @param {S2} source2 - The second source object whose properties will be merged into the target object.
+ * @param {S3} source3 - The third source object whose properties will be merged into the target object.
+ * @returns {O & S1 & S2 & S3} The updated target object with properties from the source object(s) merged in.
+ *
+ * @template O - Type of the target object.
+ * @template S1 - Type of the first source object.
+ * @template S2 - Type of the second source object.
+ * @template S3 - Type of the third source object.
+ *
+ * @example
+ * const target = { a: 1, b: 2 };
+ * const source = { b: 3, c: 4 };
+ *
+ * mergeWith(target, source, (targetValue, sourceValue) => {
+ *   if (typeof targetValue === 'number' && typeof sourceValue === 'number') {
+ *     return targetValue + sourceValue;
+ *   }
+ * });
+ * // Returns { a: 1, b: 5, c: 4 }
+ * @example
+ * const target = { a: [1], b: [2] };
+ * const source = { a: [3], b: [4] };
+ *
+ * const result = mergeWith(target, source, (objValue, srcValue) => {
+ *   if (Array.isArray(objValue)) {
+ *     return objValue.concat(srcValue);
+ *   }
+ * });
+ *
+ * expect(result).toEqual({ a: [1, 3], b: [2, 4] });
+ */
+declare function mergeWith<O, S1, S2, S3>(object: O, source1: S1, source2: S2, source3: S3, merge: (targetValue: any, sourceValue: any, key: string, target: any, source: any, stack: Map<any, any>) => any): O & S1 & S2 & S3;
+/**
+ * Merges the properties of one or more source objects into the target object.
+ *
+ * This function performs a deep merge, recursively merging nested objects and arrays.
+ * If a property in the source object is an array or object and the corresponding property in the target object is also an array or object, they will be merged.
+ * If a property in the source object is `undefined`, it will not overwrite a defined property in the target object.
+ *
+ * You can provide a custom `merge` function to control how properties are merged. The `merge` function is called for each property that is being merged and receives the following arguments:
+ *
+ * - `targetValue`: The current value of the property in the target object.
+ * - `sourceValue`: The value of the property in the source object.
+ * - `key`: The key of the property being merged.
+ * - `target`: The target object.
+ * - `source`: The source object.
+ * - `stack`: A `Map` used to keep track of objects that have already been processed to handle circular references.
+ *
+ * The `merge` function should return the value to be set in the target object. If it returns `undefined`, a default deep merge will be applied for arrays and objects.
+ *
+ * The function can handle multiple source objects and will merge them all into the target object.
+ *
+ * @param {O} object - The target object into which the source object properties will be merged. This object is modified in place.
+ * @param {S1} source1 - The first source object whose properties will be merged into the target object.
+ * @param {S2} source2 - The second source object whose properties will be merged into the target object.
+ * @param {S3} source3 - The third source object whose properties will be merged into the target object.
+ * @param {S4} source4 - The fourth source object whose properties will be merged into the target object.
+ * @returns {O & S1 & S2 & S3 & S4} The updated target object with properties from the source object(s) merged in.
+ *
+ * @template O - Type of the target object.
+ * @template S1 - Type of the first source object.
+ * @template S2 - Type of the second source object.
+ * @template S3 - Type of the third source object.
+ * @template S4 - Type of the fourth source object.
+ *
+ * @example
+ * const target = { a: 1, b: 2 };
+ * const source = { b: 3, c: 4 };
+ *
+ * mergeWith(target, source, (targetValue, sourceValue) => {
+ *   if (typeof targetValue === 'number' && typeof sourceValue === 'number') {
+ *     return targetValue + sourceValue;
+ *   }
+ * });
+ * // Returns { a: 1, b: 5, c: 4 }
+ * @example
+ * const target = { a: [1], b: [2] };
+ * const source = { a: [3], b: [4] };
+ *
+ * const result = mergeWith(target, source, (objValue, srcValue) => {
+ *   if (Array.isArray(objValue)) {
+ *     return objValue.concat(srcValue);
+ *   }
+ * });
+ *
+ * expect(result).toEqual({ a: [1, 3], b: [2, 4] });
+ */
+declare function mergeWith<O, S1, S2, S3, S4>(object: O, source1: S1, source2: S2, source3: S3, source4: S4, merge: (targetValue: any, sourceValue: any, key: string, target: any, source: any, stack: Map<any, any>) => any): O & S1 & S2 & S3;
+/**
+ * Merges the properties of one or more source objects into the target object.
+ *
+ * This function performs a deep merge, recursively merging nested objects and arrays.
+ * If a property in the source object is an array or object and the corresponding property in the target object is also an array or object, they will be merged.
+ * If a property in the source object is `undefined`, it will not overwrite a defined property in the target object.
+ *
+ * You can provide a custom `merge` function to control how properties are merged. The `merge` function is called for each property that is being merged and receives the following arguments:
+ *
+ * - `targetValue`: The current value of the property in the target object.
+ * - `sourceValue`: The value of the property in the source object.
+ * - `key`: The key of the property being merged.
+ * - `target`: The target object.
+ * - `source`: The source object.
+ * - `stack`: A `Map` used to keep track of objects that have already been processed to handle circular references.
+ *
+ * The `merge` function should return the value to be set in the target object. If it returns `undefined`, a default deep merge will be applied for arrays and objects.
+ *
+ * The function can handle multiple source objects and will merge them all into the target object.
+ *
+ * @param {any} any - The target object into which the source object properties will be merged. This object is modified in place.
+ * @param {any[]} sources - The source objects whose properties will be merged into the target object.
+ * @returns {any} The updated target object with properties from the source object(s) merged in.
+ *
+ * @example
+ * const target = { a: 1, b: 2 };
+ * const source = { b: 3, c: 4 };
+ *
+ * mergeWith(target, source, (targetValue, sourceValue) => {
+ *   if (typeof targetValue === 'number' && typeof sourceValue === 'number') {
+ *     return targetValue + sourceValue;
+ *   }
+ * });
+ * // Returns { a: 1, b: 5, c: 4 }
+ * @example
+ * const target = { a: [1], b: [2] };
+ * const source = { a: [3], b: [4] };
+ *
+ * const result = mergeWith(target, source, (objValue, srcValue) => {
+ *   if (Array.isArray(objValue)) {
+ *     return objValue.concat(srcValue);
+ *   }
+ * });
+ *
+ * expect(result).toEqual({ a: [1, 3], b: [2, 4] });
+ */
+declare function mergeWith(object: any, ...otherArgs: any[]): any;
+
+export { mergeWith };

package/dist/compat/object/mergeWith.mjs

@@ -0,0 +1,75 @@
+import { clone } from '../../object/clone.mjs';
+import { isArguments } from '../predicate/isArguments.mjs';
+import { isObjectLike } from '../predicate/isObjectLike.mjs';
+import { isPlainObject } from '../predicate/isPlainObject.mjs';
+import { isTypedArray } from '../predicate/isTypedArray.mjs';
+import { cloneDeep } from './cloneDeep.mjs';
+
+function mergeWith(object, ...otherArgs) {
+    const sources = otherArgs.slice(0, -1);
+    const merge = otherArgs[otherArgs.length - 1];
+    let result = object;
+    for (let i = 0; i < sources.length; i++) {
+        const source = sources[i];
+        result = mergeWithDeep(object, source, merge, new Map());
+    }
+    return result;
+}
+function mergeWithDeep(target, source, merge, stack) {
+    if (source == null || typeof source !== 'object') {
+        return target;
+    }
+    if (stack.has(source)) {
+        return clone(stack.get(source));
+    }
+    stack.set(source, target);
+    if (Array.isArray(source)) {
+        source = source.slice();
+        for (let i = 0; i < source.length; i++) {
+            source[i] = source[i] ?? undefined;
+        }
+    }
+    const sourceKeys = Object.keys(source);
+    for (let i = 0; i < sourceKeys.length; i++) {
+        const key = sourceKeys[i];
+        let sourceValue = source[key];
+        let targetValue = target[key];
+        if (isArguments(sourceValue)) {
+            sourceValue = { ...sourceValue };
+        }
+        if (isArguments(targetValue)) {
+            targetValue = { ...targetValue };
+        }
+        if (typeof Buffer !== 'undefined' && Buffer.isBuffer(sourceValue)) {
+            sourceValue = cloneDeep(sourceValue);
+        }
+        if (Array.isArray(sourceValue)) {
+            targetValue = typeof targetValue === 'object' ? Array.from(targetValue ?? []) : [];
+        }
+        const merged = merge(targetValue, sourceValue, key, target, source, stack);
+        if (merged != null) {
+            target[key] = merged;
+        }
+        else if (Array.isArray(sourceValue)) {
+            target[key] = mergeWithDeep(targetValue, sourceValue, merge, stack);
+        }
+        else if (isObjectLike(targetValue) && isObjectLike(sourceValue)) {
+            target[key] = mergeWithDeep(targetValue, sourceValue, merge, stack);
+        }
+        else if (targetValue == null && Array.isArray(sourceValue)) {
+            target[key] = mergeWithDeep([], sourceValue, merge, stack);
+        }
+        else if (targetValue == null && isPlainObject(sourceValue)) {
+            target[key] = mergeWithDeep({}, sourceValue, merge, stack);
+        }
+        else if (targetValue == null && isTypedArray(sourceValue)) {
+            target[key] = cloneDeep(sourceValue);
+        }
+        else if (targetValue === undefined || sourceValue !== undefined) {
+            target[key] = sourceValue;
+        }
+    }
+    return target;
+}
+
+export { mergeWith };

package/dist/index.d.mts

@@ -82,6 +82,7 @@ export { mapKeys } from './object/mapKeys.mjs';
 export { mapValues } from './object/mapValues.mjs';
 export { cloneDeep } from './object/cloneDeep.mjs';
 export { merge } from './object/merge.mjs';
+export { mergeWith } from './object/mergeWith.mjs';
 export { isEqual } from './predicate/isEqual.mjs';
 export { isNil } from './predicate/isNil.mjs';
 export { isNotNil } from './predicate/isNotNil.mjs';

package/dist/index.d.ts

@@ -82,6 +82,7 @@ export { mapKeys } from './object/mapKeys.js';
 export { mapValues } from './object/mapValues.js';
 export { cloneDeep } from './object/cloneDeep.js';
 export { merge } from './object/merge.js';
+export { mergeWith } from './object/mergeWith.js';
 export { isEqual } from './predicate/isEqual.js';
 export { isNil } from './predicate/isNil.js';
 export { isNotNil } from './predicate/isNotNil.js';

package/dist/index.js

@@ -103,6 +103,7 @@ exports.omitBy = isObjectLike.omitBy;
 exports.pick = isObjectLike.pick;
 exports.pickBy = isObjectLike.pickBy;
 exports.merge = object_index.merge;
+exports.mergeWith = object_index.mergeWith;
 exports.isEqual = isSymbol.isEqual;
 exports.isFunction = isSymbol.isFunction;
 exports.isLength = isSymbol.isLength;

package/dist/index.mjs

@@ -82,6 +82,7 @@ export { mapKeys } from './object/mapKeys.mjs';
 export { mapValues } from './object/mapValues.mjs';
 export { cloneDeep } from './object/cloneDeep.mjs';
 export { merge } from './object/merge.mjs';
+export { mergeWith } from './object/mergeWith.mjs';
 export { isEqual } from './predicate/isEqual.mjs';
 export { isNil } from './predicate/isNil.mjs';
 export { isNotNil } from './predicate/isNotNil.mjs';

package/dist/object/index.d.mts

@@ -9,3 +9,4 @@ export { mapKeys } from './mapKeys.mjs';
 export { mapValues } from './mapValues.mjs';
 export { cloneDeep } from './cloneDeep.mjs';
 export { merge } from './merge.mjs';
+export { mergeWith } from './mergeWith.mjs';

package/dist/object/index.d.ts

@@ -9,3 +9,4 @@ export { mapKeys } from './mapKeys.js';
 export { mapValues } from './mapValues.js';
 export { cloneDeep } from './cloneDeep.js';
 export { merge } from './merge.js';
+export { mergeWith } from './mergeWith.js';

package/dist/object/index.js

@@ -23,6 +23,29 @@ function merge(target, source) {
     return target;
 }
 
+function mergeWith(target, source, merge) {
+    const sourceKeys = Object.keys(source);
+    for (let i = 0; i < sourceKeys.length; i++) {
+        const key = sourceKeys[i];
+        const sourceValue = source[key];
+        const targetValue = target[key];
+        const merged = merge(targetValue, sourceValue, key, target, source);
+        if (merged != null) {
+            target[key] = merged;
+        }
+        else if (Array.isArray(sourceValue)) {
+            target[key] = mergeWith(targetValue ?? [], sourceValue, merge);
+        }
+        else if (isObjectLike.isObjectLike(targetValue) && isObjectLike.isObjectLike(sourceValue)) {
+            target[key] = mergeWith(targetValue ?? {}, sourceValue, merge);
+        }
+        else if (targetValue === undefined || sourceValue !== undefined) {
+            target[key] = sourceValue;
+        }
+    }
+    return target;
+}
+
 exports.clone = isObjectLike.clone;
 exports.cloneDeep = isObjectLike.cloneDeep;
 exports.flattenObject = isObjectLike.flattenObject;
@@ -34,3 +57,4 @@ exports.omitBy = isObjectLike.omitBy;
 exports.pick = isObjectLike.pick;
 exports.pickBy = isObjectLike.pickBy;
 exports.merge = merge;
+exports.mergeWith = mergeWith;

package/dist/object/index.mjs

@@ -9,3 +9,4 @@ export { mapKeys } from './mapKeys.mjs';
 export { mapValues } from './mapValues.mjs';
 export { cloneDeep } from './cloneDeep.mjs';
 export { merge } from './merge.mjs';
+export { mergeWith } from './mergeWith.mjs';

package/dist/object/merge.d.mts

@@ -5,6 +5,8 @@
  * If a property in the source object is an array or an object and the corresponding property in the target object is also an array or object, they will be merged.
  * If a property in the source object is undefined, it will not overwrite a defined property in the target object.
  *
+ * Note that this function mutates the target object.
+ *
  * @param {T} target - The target object into which the source object properties will be merged. This object is modified in place.
  * @param {S} source - The source object whose properties will be merged into the target object.
  * @returns {T & S} The updated target object with properties from the source object merged in.

package/dist/object/merge.d.ts

@@ -5,6 +5,8 @@
  * If a property in the source object is an array or an object and the corresponding property in the target object is also an array or object, they will be merged.
  * If a property in the source object is undefined, it will not overwrite a defined property in the target object.
  *
+ * Note that this function mutates the target object.
+ *
  * @param {T} target - The target object into which the source object properties will be merged. This object is modified in place.
  * @param {S} source - The source object whose properties will be merged into the target object.
  * @returns {T & S} The updated target object with properties from the source object merged in.

package/dist/object/mergeWith.d.mts

@@ -0,0 +1,57 @@
+/**
+ * Merges the properties of the source object into the target object.
+ *
+ * You can provide a custom `merge` function to control how properties are merged. The `merge` function is called for each property that is being merged and receives the following arguments:
+ *
+ * - `targetValue`: The current value of the property in the target object.
+ * - `sourceValue`: The value of the property in the source object.
+ * - `key`: The key of the property being merged.
+ * - `target`: The target object.
+ * - `source`: The source object.
+ *
+ * The `merge` function should return the value to be set in the target object. If it returns `undefined`, a default deep merge will be applied for arrays and objects:
+ *
+ * - If a property in the source object is an array or an object and the corresponding property in the target object is also an array or object, they will be merged.
+ * - If a property in the source object is undefined, it will not overwrite a defined property in the target object.
+ *
+ * Note that this function mutates the target object.
+ *
+ * @param {T} target - The target object into which the source object properties will be merged. This object is modified in place.
+ * @param {S} source - The source object whose properties will be merged into the target object.
+ * @param {(targetValue: any, sourceValue: any, key: string, target: T, source: S) => any} merge - A custom merge function that defines how properties should be combined. It receives the following arguments:
+ *   - `targetValue`: The current value of the property in the target object.
+ *   - `sourceValue`: The value of the property in the source object.
+ *   - `key`: The key of the property being merged.
+ *   - `target`: The target object.
+ *   - `source`: The source object.
+ *
+ * @returns {T & S} The updated target object with properties from the source object merged in.
+ *
+ * @template T - Type of the target object.
+ * @template S - Type of the source object.
+ *
+ * @example
+ * const target = { a: 1, b: 2 };
+ * const source = { b: 3, c: 4 };
+ *
+ * mergeWith(target, source, (targetValue, sourceValue) => {
+ *   if (typeof targetValue === 'number' && typeof sourceValue === 'number') {
+ *     return targetValue + sourceValue;
+ *   }
+ * });
+ * // Returns { a: 1, b: 5, c: 4 }
+ * @example
+ * const target = { a: [1], b: [2] };
+ * const source = { a: [3], b: [4] };
+ *
+ * const result = mergeWith(target, source, (objValue, srcValue) => {
+ *   if (Array.isArray(objValue)) {
+ *     return objValue.concat(srcValue);
+ *   }
+ * });
+ *
+ * expect(result).toEqual({ a: [1, 3], b: [2, 4] });
+ */
+declare function mergeWith<T, S>(target: T, source: S, merge: (targetValue: any, sourceValue: any, key: string, target: T, source: S) => any): T & S;
+
+export { mergeWith };

package/dist/object/mergeWith.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Merges the properties of the source object into the target object.
+ *
+ * You can provide a custom `merge` function to control how properties are merged. The `merge` function is called for each property that is being merged and receives the following arguments:
+ *
+ * - `targetValue`: The current value of the property in the target object.
+ * - `sourceValue`: The value of the property in the source object.
+ * - `key`: The key of the property being merged.
+ * - `target`: The target object.
+ * - `source`: The source object.
+ *
+ * The `merge` function should return the value to be set in the target object. If it returns `undefined`, a default deep merge will be applied for arrays and objects:
+ *
+ * - If a property in the source object is an array or an object and the corresponding property in the target object is also an array or object, they will be merged.
+ * - If a property in the source object is undefined, it will not overwrite a defined property in the target object.
+ *
+ * Note that this function mutates the target object.
+ *
+ * @param {T} target - The target object into which the source object properties will be merged. This object is modified in place.
+ * @param {S} source - The source object whose properties will be merged into the target object.
+ * @param {(targetValue: any, sourceValue: any, key: string, target: T, source: S) => any} merge - A custom merge function that defines how properties should be combined. It receives the following arguments:
+ *   - `targetValue`: The current value of the property in the target object.
+ *   - `sourceValue`: The value of the property in the source object.
+ *   - `key`: The key of the property being merged.
+ *   - `target`: The target object.
+ *   - `source`: The source object.
+ *
+ * @returns {T & S} The updated target object with properties from the source object merged in.
+ *
+ * @template T - Type of the target object.
+ * @template S - Type of the source object.
+ *
+ * @example
+ * const target = { a: 1, b: 2 };
+ * const source = { b: 3, c: 4 };
+ *
+ * mergeWith(target, source, (targetValue, sourceValue) => {
+ *   if (typeof targetValue === 'number' && typeof sourceValue === 'number') {
+ *     return targetValue + sourceValue;
+ *   }
+ * });
+ * // Returns { a: 1, b: 5, c: 4 }
+ * @example
+ * const target = { a: [1], b: [2] };
+ * const source = { a: [3], b: [4] };
+ *
+ * const result = mergeWith(target, source, (objValue, srcValue) => {
+ *   if (Array.isArray(objValue)) {
+ *     return objValue.concat(srcValue);
+ *   }
+ * });
+ *
+ * expect(result).toEqual({ a: [1, 3], b: [2, 4] });
+ */
+declare function mergeWith<T, S>(target: T, source: S, merge: (targetValue: any, sourceValue: any, key: string, target: T, source: S) => any): T & S;
+
+export { mergeWith };

package/dist/object/mergeWith.mjs

@@ -0,0 +1,26 @@
+import { isObjectLike } from '../compat/predicate/isObjectLike.mjs';
+
+function mergeWith(target, source, merge) {
+    const sourceKeys = Object.keys(source);
+    for (let i = 0; i < sourceKeys.length; i++) {
+        const key = sourceKeys[i];
+        const sourceValue = source[key];
+        const targetValue = target[key];
+        const merged = merge(targetValue, sourceValue, key, target, source);
+        if (merged != null) {
+            target[key] = merged;
+        }
+        else if (Array.isArray(sourceValue)) {
+            target[key] = mergeWith(targetValue ?? [], sourceValue, merge);
+        }
+        else if (isObjectLike(targetValue) && isObjectLike(sourceValue)) {
+            target[key] = mergeWith(targetValue ?? {}, sourceValue, merge);
+        }
+        else if (targetValue === undefined || sourceValue !== undefined) {
+            target[key] = sourceValue;
+        }
+    }
+    return target;
+}
+
+export { mergeWith };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "es-toolkit",
   "description": "A state-of-the-art, high-performance JavaScript utility library with a small bundle size and strong type annotations.",
-  "version": "1.14.0-dev.409+bb94b88e",
+  "version": "1.14.0-dev.410+cc3a4674",
   "homepage": "https://es-toolkit.slash.page",
   "bugs": "https://github.com/toss/es-toolkit/issues",
   "repository": {