es-toolkit 1.51.0-dev.2076 → 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/object/omitBy.d.mts

@@ -1,3 +1,5 @@
+import { ObjectKeys } from "../types/ObjectKeys.mjs";
+
 //#region src/object/omitBy.d.ts
 /**
  * Creates a new object composed of the properties that do not satisfy the predicate function.
@@ -9,7 +11,7 @@
  * @param obj - The object to omit properties from.
  * @param shouldOmit - A predicate function that determines
  * whether a property should be omitted. It takes the property's key and value as arguments and returns `true`
- * if the property should be omitted, and `false` otherwise.
+ * if the property should be omitted, and `false` otherwise. Numeric keys are passed as strings.
  * @returns A new object with the properties that do not satisfy the predicate function.
  *
  * @example
@@ -18,6 +20,6 @@
  * const result = omitBy(obj, shouldOmit);
  * // result will be { a: 1, c: 3 }
  */
-declare function omitBy<T extends Record<string, any>>(obj: T, shouldOmit: (value: T[keyof T], key: keyof T) => boolean): Partial<T>;
+declare function omitBy<T extends Record<string, any>>(obj: T, shouldOmit: (value: T[keyof T], key: ObjectKeys<T>) => boolean): Partial<T>;
 //#endregion
 export { omitBy };

package/dist/object/omitBy.d.ts

@@ -1,3 +1,5 @@
+import { ObjectKeys } from "../types/ObjectKeys.js";
+
 //#region src/object/omitBy.d.ts
 /**
  * Creates a new object composed of the properties that do not satisfy the predicate function.
@@ -9,7 +11,7 @@
  * @param obj - The object to omit properties from.
  * @param shouldOmit - A predicate function that determines
  * whether a property should be omitted. It takes the property's key and value as arguments and returns `true`
- * if the property should be omitted, and `false` otherwise.
+ * if the property should be omitted, and `false` otherwise. Numeric keys are passed as strings.
  * @returns A new object with the properties that do not satisfy the predicate function.
  *
  * @example
@@ -18,6 +20,6 @@
  * const result = omitBy(obj, shouldOmit);
  * // result will be { a: 1, c: 3 }
  */
-declare function omitBy<T extends Record<string, any>>(obj: T, shouldOmit: (value: T[keyof T], key: keyof T) => boolean): Partial<T>;
+declare function omitBy<T extends Record<string, any>>(obj: T, shouldOmit: (value: T[keyof T], key: ObjectKeys<T>) => boolean): Partial<T>;
 //#endregion
 export { omitBy };

package/dist/object/omitBy.js

@@ -9,7 +9,7 @@
 * @param obj - The object to omit properties from.
 * @param shouldOmit - A predicate function that determines
 * whether a property should be omitted. It takes the property's key and value as arguments and returns `true`
-* if the property should be omitted, and `false` otherwise.
+* if the property should be omitted, and `false` otherwise. Numeric keys are passed as strings.
 * @returns A new object with the properties that do not satisfy the predicate function.
 *
 * @example
@@ -23,8 +23,9 @@ function omitBy(obj, shouldOmit) {
 	const keys = Object.keys(obj);
 	for (let i = 0; i < keys.length; i++) {
 		const key = keys[i];
-		const value = obj[key];
-		if (!shouldOmit(value, key)) result[key] = value;
+		const objectKey = key;
+		const value = obj[objectKey];
+		if (!shouldOmit(value, key)) result[objectKey] = value;
 	}
 	return result;
 }

package/dist/object/omitBy.mjs

@@ -9,7 +9,7 @@
 * @param obj - The object to omit properties from.
 * @param shouldOmit - A predicate function that determines
 * whether a property should be omitted. It takes the property's key and value as arguments and returns `true`
-* if the property should be omitted, and `false` otherwise.
+* if the property should be omitted, and `false` otherwise. Numeric keys are passed as strings.
 * @returns A new object with the properties that do not satisfy the predicate function.
 *
 * @example
@@ -23,8 +23,9 @@ function omitBy(obj, shouldOmit) {
 	const keys = Object.keys(obj);
 	for (let i = 0; i < keys.length; i++) {
 		const key = keys[i];
-		const value = obj[key];
-		if (!shouldOmit(value, key)) result[key] = value;
+		const objectKey = key;
+		const value = obj[objectKey];
+		if (!shouldOmit(value, key)) result[objectKey] = value;
 	}
 	return result;
 }

package/dist/object/pickBy.d.mts

@@ -1,3 +1,5 @@
+import { ObjectKeys } from "../types/ObjectKeys.mjs";
+
 //#region src/object/pickBy.d.ts
 /**
  * Creates a new object composed of the properties that satisfy the predicate function.
@@ -9,7 +11,7 @@
  * @param obj - The object to pick properties from.
  * @param shouldPick - A predicate function that determines
  * whether a property should be picked. It takes the property's key and value as arguments and returns `true`
- * if the property should be picked, and `false` otherwise.
+ * if the property should be picked, and `false` otherwise. Numeric keys are passed as strings.
  * @returns A new object with the properties that satisfy the predicate function.
  *
  * @example
@@ -18,6 +20,6 @@
  * const result = pickBy(obj, shouldPick);
  * // result will be { b: 'pick' }
  */
-declare function pickBy<T extends Record<string, any>>(obj: T, shouldPick: (value: T[keyof T], key: keyof T) => boolean): Partial<T>;
+declare function pickBy<T extends Record<string, any>>(obj: T, shouldPick: (value: T[keyof T], key: ObjectKeys<T>) => boolean): Partial<T>;
 //#endregion
 export { pickBy };

package/dist/object/pickBy.d.ts

@@ -1,3 +1,5 @@
+import { ObjectKeys } from "../types/ObjectKeys.js";
+
 //#region src/object/pickBy.d.ts
 /**
  * Creates a new object composed of the properties that satisfy the predicate function.
@@ -9,7 +11,7 @@
  * @param obj - The object to pick properties from.
  * @param shouldPick - A predicate function that determines
  * whether a property should be picked. It takes the property's key and value as arguments and returns `true`
- * if the property should be picked, and `false` otherwise.
+ * if the property should be picked, and `false` otherwise. Numeric keys are passed as strings.
  * @returns A new object with the properties that satisfy the predicate function.
  *
  * @example
@@ -18,6 +20,6 @@
  * const result = pickBy(obj, shouldPick);
  * // result will be { b: 'pick' }
  */
-declare function pickBy<T extends Record<string, any>>(obj: T, shouldPick: (value: T[keyof T], key: keyof T) => boolean): Partial<T>;
+declare function pickBy<T extends Record<string, any>>(obj: T, shouldPick: (value: T[keyof T], key: ObjectKeys<T>) => boolean): Partial<T>;
 //#endregion
 export { pickBy };

package/dist/object/pickBy.js

@@ -9,7 +9,7 @@
 * @param obj - The object to pick properties from.
 * @param shouldPick - A predicate function that determines
 * whether a property should be picked. It takes the property's key and value as arguments and returns `true`
-* if the property should be picked, and `false` otherwise.
+* if the property should be picked, and `false` otherwise. Numeric keys are passed as strings.
 * @returns A new object with the properties that satisfy the predicate function.
 *
 * @example
@@ -23,8 +23,9 @@ function pickBy(obj, shouldPick) {
 	const keys = Object.keys(obj);
 	for (let i = 0; i < keys.length; i++) {
 		const key = keys[i];
-		const value = obj[key];
-		if (shouldPick(value, key)) result[key] = value;
+		const objectKey = key;
+		const value = obj[objectKey];
+		if (shouldPick(value, key)) result[objectKey] = value;
 	}
 	return result;
 }

package/dist/object/pickBy.mjs

@@ -9,7 +9,7 @@
 * @param obj - The object to pick properties from.
 * @param shouldPick - A predicate function that determines
 * whether a property should be picked. It takes the property's key and value as arguments and returns `true`
-* if the property should be picked, and `false` otherwise.
+* if the property should be picked, and `false` otherwise. Numeric keys are passed as strings.
 * @returns A new object with the properties that satisfy the predicate function.
 *
 * @example
@@ -23,8 +23,9 @@ function pickBy(obj, shouldPick) {
 	const keys = Object.keys(obj);
 	for (let i = 0; i < keys.length; i++) {
 		const key = keys[i];
-		const value = obj[key];
-		if (shouldPick(value, key)) result[key] = value;
+		const objectKey = key;
+		const value = obj[objectKey];
+		if (shouldPick(value, key)) result[objectKey] = value;
 	}
 	return result;
 }

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/ObjectKeys.d.mts

@@ -0,0 +1,19 @@
+//#region src/types/ObjectKeys.d.ts
+/**
+ * Creates a union of the keys of `T` as they are returned by `Object.keys`:
+ * numeric keys are converted to strings and symbol keys are excluded. The key-side
+ * counterpart to `ValueOf`.
+ *
+ * @template T - The object type to read keys from.
+ *
+ * @example
+ * type Keys = ObjectKeys<{ a: number; 1: string }>;
+ * // => 'a' | '1'
+ *
+ * const obj = { a: 1, b: 2 };
+ * const keys = Object.keys(obj) as Array<ObjectKeys<typeof obj>>;
+ * // => Array<'a' | 'b'>
+ */
+type ObjectKeys<T> = `${Exclude<keyof T, symbol>}`;
+//#endregion
+export { ObjectKeys };

package/dist/types/ObjectKeys.d.ts

@@ -0,0 +1,19 @@
+//#region src/types/ObjectKeys.d.ts
+/**
+ * Creates a union of the keys of `T` as they are returned by `Object.keys`:
+ * numeric keys are converted to strings and symbol keys are excluded. The key-side
+ * counterpart to `ValueOf`.
+ *
+ * @template T - The object type to read keys from.
+ *
+ * @example
+ * type Keys = ObjectKeys<{ a: number; 1: string }>;
+ * // => 'a' | '1'
+ *
+ * const obj = { a: 1, b: 2 };
+ * const keys = Object.keys(obj) as Array<ObjectKeys<typeof obj>>;
+ * // => Array<'a' | 'b'>
+ */
+type ObjectKeys<T> = `${Exclude<keyof T, symbol>}`;
+//#endregion
+export { ObjectKeys };

package/dist/types/index.d.mts

@@ -1,3 +1,6 @@
+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";
 import { ToKebabCaseKeys } from "./ToKebabCaseKeys.mjs";
@@ -6,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 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,6 @@
+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";
 import { ToKebabCaseKeys } from "./ToKebabCaseKeys.js";
@@ -6,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 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.2076+893f52aa",
+  "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",