es-toolkit 1.51.0-dev.2077 → 1.51.0-dev.2078

package/dist/object/merge.d.mts

@@ -1,3 +1,5 @@
+import { Merge } from "../types/Merge.mjs";
+
 //#region src/object/merge.d.ts
 /**
  * Merges the properties of the source object into the target object.
@@ -39,6 +41,6 @@
  * console.log(result);
  * // Output: { a: [1, 2, 3] }
  */
-declare function merge<T extends Record<PropertyKey, any>, S extends Record<PropertyKey, any>>(target: T, source: S): T & S;
+declare function merge<T extends Record<PropertyKey, any>, S extends Record<PropertyKey, any>>(target: T, source: S): Merge<T, S>;
 //#endregion
 export { merge };

package/dist/object/merge.d.ts

@@ -1,3 +1,5 @@
+import { Merge } from "../types/Merge.js";
+
 //#region src/object/merge.d.ts
 /**
  * Merges the properties of the source object into the target object.
@@ -39,6 +41,6 @@
  * console.log(result);
  * // Output: { a: [1, 2, 3] }
  */
-declare function merge<T extends Record<PropertyKey, any>, S extends Record<PropertyKey, any>>(target: T, source: S): T & S;
+declare function merge<T extends Record<PropertyKey, any>, S extends Record<PropertyKey, any>>(target: T, source: S): Merge<T, S>;
 //#endregion
 export { merge };

package/dist/object/merge.js

@@ -2,46 +2,6 @@ const require_isPlainObject = require("../predicate/isPlainObject.js");
 const require_isMergeableValue = require("../_internal/isMergeableValue.js");
 const require_isUnsafeProperty = require("../_internal/isUnsafeProperty.js");
 //#region src/object/merge.ts
-/**
-* Merges the properties of the source object into the target object.
-*
-* This function performs a deep merge, meaning nested objects and arrays are merged recursively.
-* 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 target - The target object into which the source object properties will be merged. This object is modified in place.
-* @param source - The source object whose properties will be merged into the target object.
-* @returns 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: { x: 1, y: 2 } };
-* const source = { b: { y: 3, z: 4 }, c: 5 };
-*
-* const result = merge(target, source);
-* console.log(result);
-* // Output: { a: 1, b: { x: 1, y: 3, z: 4 }, c: 5 }
-*
-* @example
-* const target = { a: [1, 2], b: { x: 1 } };
-* const source = { a: [3], b: { y: 2 } };
-*
-* const result = merge(target, source);
-* console.log(result);
-* // Output: { a: [3, 2], b: { x: 1, y: 2 } }
-*
-* @example
-* const target = { a: null };
-* const source = { a: [1, 2, 3] };
-*
-* const result = merge(target, source);
-* console.log(result);
-* // Output: { a: [1, 2, 3] }
-*/
 function merge(target, source) {
 	const sourceKeys = Object.keys(source);
 	for (let i = 0; i < sourceKeys.length; i++) {

package/dist/object/merge.mjs

@@ -2,46 +2,6 @@ import { isPlainObject } from "../predicate/isPlainObject.mjs";
 import { isMergeableValue } from "../_internal/isMergeableValue.mjs";
 import { isUnsafeProperty } from "../_internal/isUnsafeProperty.mjs";
 //#region src/object/merge.ts
-/**
-* Merges the properties of the source object into the target object.
-*
-* This function performs a deep merge, meaning nested objects and arrays are merged recursively.
-* 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 target - The target object into which the source object properties will be merged. This object is modified in place.
-* @param source - The source object whose properties will be merged into the target object.
-* @returns 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: { x: 1, y: 2 } };
-* const source = { b: { y: 3, z: 4 }, c: 5 };
-*
-* const result = merge(target, source);
-* console.log(result);
-* // Output: { a: 1, b: { x: 1, y: 3, z: 4 }, c: 5 }
-*
-* @example
-* const target = { a: [1, 2], b: { x: 1 } };
-* const source = { a: [3], b: { y: 2 } };
-*
-* const result = merge(target, source);
-* console.log(result);
-* // Output: { a: [3, 2], b: { x: 1, y: 2 } }
-*
-* @example
-* const target = { a: null };
-* const source = { a: [1, 2, 3] };
-*
-* const result = merge(target, source);
-* console.log(result);
-* // Output: { a: [1, 2, 3] }
-*/
 function merge(target, source) {
 	const sourceKeys = Object.keys(source);
 	for (let i = 0; i < sourceKeys.length; i++) {

package/dist/types/Merge.d.mts

@@ -0,0 +1,37 @@
+import { Simplify } from "./Simplify.mjs";
+
+//#region src/types/Merge.d.ts
+/**
+ * The result of deeply merging the source type `S` into the target type `T`,
+ * matching what `merge(target, source)` returns at runtime.
+ *
+ * Keys present on only one side are kept as-is. When both sides have a plain
+ * object at the same key, the merge recurses; tuples merge index by index, and
+ * other arrays merge into an array of both element types. If the source value
+ * can be `undefined`, the target type is kept because `merge` skips
+ * `undefined` source values. Values that are not plain objects or arrays
+ * (functions, `Date`, `RegExp`, `Map`, `Set`, etc.) are not merged into;
+ * the source value replaces the target value. When an array meets a plain
+ * object, `merge` keeps the target and assigns the source's properties onto
+ * it, so both property sets are kept (`T & S`).
+ *
+ * @template T - Type of the target object.
+ * @template S - Type of the source object.
+ *
+ * @example
+ * type Target = { a: number; b: { x: number; y: number } };
+ * type Source = { b: { y: string; z: boolean }; c: string };
+ * type Result = Merge<Target, Source>;
+ * // => { a: number; b: { x: number; y: string; z: boolean }; c: string }
+ */
+type Merge<T, S> = undefined extends S ? T | MergeDefined<T, Exclude<S, undefined>> : MergeDefined<T, S>;
+/**
+ * Values `merge` does not merge into: everything that is not a plain object
+ * or an array. The source value replaces the target value instead.
+ */
+type NonMergeable = ((...args: any[]) => unknown) | Date | RegExp | Error | Promise<unknown> | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | WeakMap<object, unknown> | WeakSet<object>;
+type MergeDefined<T, S> = S extends readonly unknown[] ? (T extends readonly unknown[] ? MergeArrays<T, S> : T extends NonMergeable ? S : T extends object ? T & S : S) : S extends NonMergeable ? S : S extends object ? (T extends readonly unknown[] ? T & S : T extends NonMergeable ? S : T extends object ? MergeRecords<T, S> : S) : S;
+type MergeArrays<T extends readonly unknown[], S extends readonly unknown[]> = T extends readonly [] ? S : S extends readonly [] ? T : T extends readonly [infer TH, ...infer TR] ? S extends readonly [infer SH, ...infer SR] ? [Merge<TH, SH>, ...MergeArrays<TR, SR>] : Array<T[number] | S[number]> : Array<T[number] | S[number]>;
+type MergeRecords<T extends object, S extends object> = Simplify<Omit<T, keyof S> & Omit<S, keyof T> & { [K in keyof T & keyof S]: Merge<T[K], S[K]> }>;
+//#endregion
+export { Merge };

package/dist/types/Merge.d.ts

@@ -0,0 +1,37 @@
+import { Simplify } from "./Simplify.js";
+
+//#region src/types/Merge.d.ts
+/**
+ * The result of deeply merging the source type `S` into the target type `T`,
+ * matching what `merge(target, source)` returns at runtime.
+ *
+ * Keys present on only one side are kept as-is. When both sides have a plain
+ * object at the same key, the merge recurses; tuples merge index by index, and
+ * other arrays merge into an array of both element types. If the source value
+ * can be `undefined`, the target type is kept because `merge` skips
+ * `undefined` source values. Values that are not plain objects or arrays
+ * (functions, `Date`, `RegExp`, `Map`, `Set`, etc.) are not merged into;
+ * the source value replaces the target value. When an array meets a plain
+ * object, `merge` keeps the target and assigns the source's properties onto
+ * it, so both property sets are kept (`T & S`).
+ *
+ * @template T - Type of the target object.
+ * @template S - Type of the source object.
+ *
+ * @example
+ * type Target = { a: number; b: { x: number; y: number } };
+ * type Source = { b: { y: string; z: boolean }; c: string };
+ * type Result = Merge<Target, Source>;
+ * // => { a: number; b: { x: number; y: string; z: boolean }; c: string }
+ */
+type Merge<T, S> = undefined extends S ? T | MergeDefined<T, Exclude<S, undefined>> : MergeDefined<T, S>;
+/**
+ * Values `merge` does not merge into: everything that is not a plain object
+ * or an array. The source value replaces the target value instead.
+ */
+type NonMergeable = ((...args: any[]) => unknown) | Date | RegExp | Error | Promise<unknown> | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | WeakMap<object, unknown> | WeakSet<object>;
+type MergeDefined<T, S> = S extends readonly unknown[] ? (T extends readonly unknown[] ? MergeArrays<T, S> : T extends NonMergeable ? S : T extends object ? T & S : S) : S extends NonMergeable ? S : S extends object ? (T extends readonly unknown[] ? T & S : T extends NonMergeable ? S : T extends object ? MergeRecords<T, S> : S) : S;
+type MergeArrays<T extends readonly unknown[], S extends readonly unknown[]> = T extends readonly [] ? S : S extends readonly [] ? T : T extends readonly [infer TH, ...infer TR] ? S extends readonly [infer SH, ...infer SR] ? [Merge<TH, SH>, ...MergeArrays<TR, SR>] : Array<T[number] | S[number]> : Array<T[number] | S[number]>;
+type MergeRecords<T extends object, S extends object> = Simplify<Omit<T, keyof S> & Omit<S, keyof T> & { [K in keyof T & keyof S]: Merge<T[K], S[K]> }>;
+//#endregion
+export { Merge };

package/dist/types/index.d.mts

@@ -1,3 +1,5 @@
+import { Simplify } from "./Simplify.mjs";
+import { Merge } from "./Merge.mjs";
 import { ObjectKeys } from "./ObjectKeys.mjs";
 import { ToCamelCaseKeys } from "./ToCamelCaseKeys.mjs";
 import { ToConstantCaseKeys } from "./ToConstantCaseKeys.mjs";
@@ -7,7 +9,6 @@ import { ToSnakeCaseKeys } from "./ToSnakeCaseKeys.mjs";
 import { DeepPartial } from "./DeepPartial.mjs";
 import { DeepReadonly } from "./DeepReadonly.mjs";
 import { NonEmptyArray } from "./NonEmptyArray.mjs";
-import { Simplify } from "./Simplify.mjs";
 import { ValueOf } from "./ValueOf.mjs";
 import { Writable } from "./Writable.mjs";
-export { type DeepPartial, type DeepReadonly, type NonEmptyArray, type ObjectKeys, type Simplify, type ToCamelCaseKeys, type ToConstantCaseKeys, type ToKebabCaseKeys, type ToPascalCaseKeys, type ToSnakeCaseKeys, type ValueOf, type Writable };
+export { type DeepPartial, type DeepReadonly, type Merge, type NonEmptyArray, type ObjectKeys, type Simplify, type ToCamelCaseKeys, type ToConstantCaseKeys, type ToKebabCaseKeys, type ToPascalCaseKeys, type ToSnakeCaseKeys, type ValueOf, type Writable };

package/dist/types/index.d.ts

@@ -1,3 +1,5 @@
+import { Simplify } from "./Simplify.js";
+import { Merge } from "./Merge.js";
 import { ObjectKeys } from "./ObjectKeys.js";
 import { ToCamelCaseKeys } from "./ToCamelCaseKeys.js";
 import { ToConstantCaseKeys } from "./ToConstantCaseKeys.js";
@@ -7,7 +9,6 @@ import { ToSnakeCaseKeys } from "./ToSnakeCaseKeys.js";
 import { DeepPartial } from "./DeepPartial.js";
 import { DeepReadonly } from "./DeepReadonly.js";
 import { NonEmptyArray } from "./NonEmptyArray.js";
-import { Simplify } from "./Simplify.js";
 import { ValueOf } from "./ValueOf.js";
 import { Writable } from "./Writable.js";
-export { type DeepPartial, type DeepReadonly, type NonEmptyArray, type ObjectKeys, type Simplify, type ToCamelCaseKeys, type ToConstantCaseKeys, type ToKebabCaseKeys, type ToPascalCaseKeys, type ToSnakeCaseKeys, type ValueOf, type Writable };
+export { type DeepPartial, type DeepReadonly, type Merge, type NonEmptyArray, type ObjectKeys, type Simplify, type ToCamelCaseKeys, type ToConstantCaseKeys, type ToKebabCaseKeys, type ToPascalCaseKeys, type ToSnakeCaseKeys, type ValueOf, type Writable };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "es-toolkit",
-  "version": "1.51.0-dev.2077+61705608",
+  "version": "1.51.0-dev.2078+a1918b04",
   "description": "A state-of-the-art, high-performance JavaScript utility library with a small bundle size and strong type annotations.",
   "homepage": "https://es-toolkit.dev",
   "bugs": "https://github.com/toss/es-toolkit/issues",