es-toolkit 1.52.0-dev.2135 → 1.52.0-dev.2137

package/dist/types/IsAny.d.mts

@@ -0,0 +1,18 @@
+//#region src/types/IsAny.d.ts
+/**
+ * Resolves to `true` when `T` is `any`, `false` otherwise.
+ *
+ * `any` is the only type that `1 & T` can turn into something `0` is
+ * assignable to, which is what makes it possible to tell `any` apart from
+ * `unknown` and from every other type.
+ *
+ * @template T - The type to check.
+ *
+ * @example
+ * type A = IsAny<any>;     // true
+ * type B = IsAny<unknown>; // false
+ * type C = IsAny<never>;   // false
+ */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+//#endregion
+export { IsAny };

package/dist/types/IsAny.d.ts

@@ -0,0 +1,18 @@
+//#region src/types/IsAny.d.ts
+/**
+ * Resolves to `true` when `T` is `any`, `false` otherwise.
+ *
+ * `any` is the only type that `1 & T` can turn into something `0` is
+ * assignable to, which is what makes it possible to tell `any` apart from
+ * `unknown` and from every other type.
+ *
+ * @template T - The type to check.
+ *
+ * @example
+ * type A = IsAny<any>;     // true
+ * type B = IsAny<unknown>; // false
+ * type C = IsAny<never>;   // false
+ */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+//#endregion
+export { IsAny };

package/dist/types/IsUnknown.d.mts

@@ -0,0 +1,20 @@
+import { IsAny } from "./IsAny.mjs";
+
+//#region src/types/IsUnknown.d.ts
+/**
+ * Resolves to `true` when `T` is `unknown`, `false` otherwise.
+ *
+ * A plain `unknown extends T` check is also `true` for `any`, so this type
+ * rules `any` out first. Useful when a type-level helper should treat an
+ * `unknown` input differently from a concrete type.
+ *
+ * @template T - The type to check.
+ *
+ * @example
+ * type A = IsUnknown<unknown>; // true
+ * type B = IsUnknown<any>;     // false
+ * type C = IsUnknown<string>;  // false
+ */
+type IsUnknown<T> = IsAny<T> extends true ? false : unknown extends T ? true : false;
+//#endregion
+export { IsUnknown };

package/dist/types/IsUnknown.d.ts

@@ -0,0 +1,20 @@
+import { IsAny } from "./IsAny.js";
+
+//#region src/types/IsUnknown.d.ts
+/**
+ * Resolves to `true` when `T` is `unknown`, `false` otherwise.
+ *
+ * A plain `unknown extends T` check is also `true` for `any`, so this type
+ * rules `any` out first. Useful when a type-level helper should treat an
+ * `unknown` input differently from a concrete type.
+ *
+ * @template T - The type to check.
+ *
+ * @example
+ * type A = IsUnknown<unknown>; // true
+ * type B = IsUnknown<any>;     // false
+ * type C = IsUnknown<string>;  // false
+ */
+type IsUnknown<T> = IsAny<T> extends true ? false : unknown extends T ? true : false;
+//#endregion
+export { IsUnknown };

package/dist/types/Merge.d.mts

@@ -1,3 +1,7 @@
+import { IsAny } from "./IsAny.mjs";
+import { IsEqual } from "./IsEqual.mjs";
+import { IsUnknown } from "./IsUnknown.mjs";
+import { Primitive } from "./Primitive.mjs";
 import { Simplify } from "./Simplify.mjs";
 
 //#region src/types/Merge.d.ts
@@ -5,15 +9,29 @@ import { Simplify } from "./Simplify.mjs";
  * 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`).
+ * Merging a type with itself gives back the same type, so a union such as
+ * `string | string[] | string[][]` stays intact instead of expanding into a
+ * merge of every pair of its members.
+ *
+ * Plain objects are merged key by key: keys present on only one side are
+ * kept, and keys present on both sides are merged the same way. A key that
+ * exists only on the source is kept even when the source is a subtype of
+ * the target.
+ *
+ * A source value that is not a plain object or an array (primitives, `Date`,
+ * `RegExp`, `Map`, `Set`, functions, ...) replaces the target value, so the
+ * source type is used.
+ *
+ * When a source array fits the target's array type, the target type is kept:
+ * overriding `string[] | string[][]` with `string[]` stays
+ * `string[] | string[][]`. If instead the target fits the source type, the
+ * source type is kept. Otherwise, tuples merge index by index and other
+ * arrays merge into an array of both element types.
+ *
+ * A source value that can be `undefined` keeps the target
+ * type as well, because `merge` skips `undefined` source values. 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.
@@ -23,6 +41,15 @@ import { Simplify } from "./Simplify.mjs";
  * 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 }
+ *
+ * @example
+ * type Options = { color: string | string[] | string[][] };
+ * type Same = Merge<Options, Options>;
+ * // => Options
+ * type Override = Merge<Options, { color: string[] }>;
+ * // => Options
+ * type Extra = Merge<{ a: number }, { a: number; b: string }>;
+ * // => { a: number; b: string }
  */
 type Merge<T, S> = undefined extends S ? T | MergeDefined<T, Exclude<S, undefined>> : MergeDefined<T, S>;
 /**
@@ -30,8 +57,17 @@ type Merge<T, S> = undefined extends S ? T | MergeDefined<T, Exclude<S, undefine
  * 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;
+/**
+ * `true` when every member of `T` is a plain object type that `merge`
+ * recurses into. Primitives are excluded explicitly because an intersection
+ * like `string & {}` satisfies `extends object` even though it is a string at
+ * runtime.
+ */
+type IsPlainRecord<T> = T extends Primitive ? false : T extends readonly unknown[] ? false : T extends NonMergeable ? false : T extends object ? true : false;
+type MergeDefined<T, S> = IsEqual<T, S> extends true ? T : IsAny<T> extends true ? any : IsAny<S> extends true ? any : IsUnknown<T> extends true ? S : [T] extends [never] ? S : [S] extends [never] ? T : IsPlainRecord<T> extends true ? (IsPlainRecord<S> extends true ? MergeRecords<T, S> : MergeAssignable<T, S>) : MergeAssignable<T, S>;
+type MergeAssignable<T, S> = [S] extends [Primitive | NonMergeable] ? S : [S] extends [T] ? T : [T] extends [S] ? S : MergeFallback<T, S>;
+type MergeFallback<T, S> = S extends Primitive ? S : S extends readonly unknown[] ? (T extends readonly unknown[] ? MergeArrays<T, S> : T extends Primitive | NonMergeable ? S : T extends object ? T & S : S) : S extends NonMergeable ? S : S extends object ? (T extends readonly unknown[] ? T & S : T extends Primitive | 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]> }>;
+type MergeRecords<T, S> = 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

@@ -1,3 +1,7 @@
+import { IsAny } from "./IsAny.js";
+import { IsEqual } from "./IsEqual.js";
+import { IsUnknown } from "./IsUnknown.js";
+import { Primitive } from "./Primitive.js";
 import { Simplify } from "./Simplify.js";
 
 //#region src/types/Merge.d.ts
@@ -5,15 +9,29 @@ import { Simplify } from "./Simplify.js";
  * 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`).
+ * Merging a type with itself gives back the same type, so a union such as
+ * `string | string[] | string[][]` stays intact instead of expanding into a
+ * merge of every pair of its members.
+ *
+ * Plain objects are merged key by key: keys present on only one side are
+ * kept, and keys present on both sides are merged the same way. A key that
+ * exists only on the source is kept even when the source is a subtype of
+ * the target.
+ *
+ * A source value that is not a plain object or an array (primitives, `Date`,
+ * `RegExp`, `Map`, `Set`, functions, ...) replaces the target value, so the
+ * source type is used.
+ *
+ * When a source array fits the target's array type, the target type is kept:
+ * overriding `string[] | string[][]` with `string[]` stays
+ * `string[] | string[][]`. If instead the target fits the source type, the
+ * source type is kept. Otherwise, tuples merge index by index and other
+ * arrays merge into an array of both element types.
+ *
+ * A source value that can be `undefined` keeps the target
+ * type as well, because `merge` skips `undefined` source values. 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.
@@ -23,6 +41,15 @@ import { Simplify } from "./Simplify.js";
  * 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 }
+ *
+ * @example
+ * type Options = { color: string | string[] | string[][] };
+ * type Same = Merge<Options, Options>;
+ * // => Options
+ * type Override = Merge<Options, { color: string[] }>;
+ * // => Options
+ * type Extra = Merge<{ a: number }, { a: number; b: string }>;
+ * // => { a: number; b: string }
  */
 type Merge<T, S> = undefined extends S ? T | MergeDefined<T, Exclude<S, undefined>> : MergeDefined<T, S>;
 /**
@@ -30,8 +57,17 @@ type Merge<T, S> = undefined extends S ? T | MergeDefined<T, Exclude<S, undefine
  * 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;
+/**
+ * `true` when every member of `T` is a plain object type that `merge`
+ * recurses into. Primitives are excluded explicitly because an intersection
+ * like `string & {}` satisfies `extends object` even though it is a string at
+ * runtime.
+ */
+type IsPlainRecord<T> = T extends Primitive ? false : T extends readonly unknown[] ? false : T extends NonMergeable ? false : T extends object ? true : false;
+type MergeDefined<T, S> = IsEqual<T, S> extends true ? T : IsAny<T> extends true ? any : IsAny<S> extends true ? any : IsUnknown<T> extends true ? S : [T] extends [never] ? S : [S] extends [never] ? T : IsPlainRecord<T> extends true ? (IsPlainRecord<S> extends true ? MergeRecords<T, S> : MergeAssignable<T, S>) : MergeAssignable<T, S>;
+type MergeAssignable<T, S> = [S] extends [Primitive | NonMergeable] ? S : [S] extends [T] ? T : [T] extends [S] ? S : MergeFallback<T, S>;
+type MergeFallback<T, S> = S extends Primitive ? S : S extends readonly unknown[] ? (T extends readonly unknown[] ? MergeArrays<T, S> : T extends Primitive | NonMergeable ? S : T extends object ? T & S : S) : S extends NonMergeable ? S : S extends object ? (T extends readonly unknown[] ? T & S : T extends Primitive | 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]> }>;
+type MergeRecords<T, S> = 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,4 +1,8 @@
 import { ObjectKeys } from "./ObjectKeys.mjs";
+import { IsAny } from "./IsAny.mjs";
+import { IsEqual } from "./IsEqual.mjs";
+import { IsUnknown } from "./IsUnknown.mjs";
+import { Primitive } from "./Primitive.mjs";
 import { Simplify } from "./Simplify.mjs";
 import { Merge } from "./Merge.mjs";
 import { ToCamelCaseKeys } from "./ToCamelCaseKeys.mjs";
@@ -6,12 +10,10 @@ import { ToConstantCaseKeys } from "./ToConstantCaseKeys.mjs";
 import { ToKebabCaseKeys } from "./ToKebabCaseKeys.mjs";
 import { ToPascalCaseKeys } from "./ToPascalCaseKeys.mjs";
 import { ToSnakeCaseKeys } from "./ToSnakeCaseKeys.mjs";
-import { Primitive } from "./Primitive.mjs";
 import { DeepPartial } from "./DeepPartial.mjs";
 import { DeepReadonly } from "./DeepReadonly.mjs";
 import { DistributiveOmit } from "./DistributiveOmit.mjs";
 import { EmptyObject } from "./EmptyObject.mjs";
-import { IsEqual } from "./IsEqual.mjs";
 import { JSONValue } from "./JSONValue.mjs";
 import { NonEmptyArray } from "./NonEmptyArray.mjs";
 import { SetOptional } from "./SetOptional.mjs";
@@ -19,4 +21,4 @@ import { SetRequired } from "./SetRequired.mjs";
 import { UnknownRecord } from "./UnknownRecord.mjs";
 import { ValueOf } from "./ValueOf.mjs";
 import { Writable } from "./Writable.mjs";
-export { type DeepPartial, type DeepReadonly, type DistributiveOmit, type EmptyObject, type IsEqual, type JSONValue, type Merge, type NonEmptyArray, type ObjectKeys, type Primitive, type SetOptional, type SetRequired, type Simplify, type ToCamelCaseKeys, type ToConstantCaseKeys, type ToKebabCaseKeys, type ToPascalCaseKeys, type ToSnakeCaseKeys, type UnknownRecord, type ValueOf, type Writable };
+export { type DeepPartial, type DeepReadonly, type DistributiveOmit, type EmptyObject, type IsAny, type IsEqual, type IsUnknown, type JSONValue, type Merge, type NonEmptyArray, type ObjectKeys, type Primitive, type SetOptional, type SetRequired, type Simplify, type ToCamelCaseKeys, type ToConstantCaseKeys, type ToKebabCaseKeys, type ToPascalCaseKeys, type ToSnakeCaseKeys, type UnknownRecord, type ValueOf, type Writable };

package/dist/types/index.d.ts

@@ -1,4 +1,8 @@
 import { ObjectKeys } from "./ObjectKeys.js";
+import { IsAny } from "./IsAny.js";
+import { IsEqual } from "./IsEqual.js";
+import { IsUnknown } from "./IsUnknown.js";
+import { Primitive } from "./Primitive.js";
 import { Simplify } from "./Simplify.js";
 import { Merge } from "./Merge.js";
 import { ToCamelCaseKeys } from "./ToCamelCaseKeys.js";
@@ -6,12 +10,10 @@ import { ToConstantCaseKeys } from "./ToConstantCaseKeys.js";
 import { ToKebabCaseKeys } from "./ToKebabCaseKeys.js";
 import { ToPascalCaseKeys } from "./ToPascalCaseKeys.js";
 import { ToSnakeCaseKeys } from "./ToSnakeCaseKeys.js";
-import { Primitive } from "./Primitive.js";
 import { DeepPartial } from "./DeepPartial.js";
 import { DeepReadonly } from "./DeepReadonly.js";
 import { DistributiveOmit } from "./DistributiveOmit.js";
 import { EmptyObject } from "./EmptyObject.js";
-import { IsEqual } from "./IsEqual.js";
 import { JSONValue } from "./JSONValue.js";
 import { NonEmptyArray } from "./NonEmptyArray.js";
 import { SetOptional } from "./SetOptional.js";
@@ -19,4 +21,4 @@ import { SetRequired } from "./SetRequired.js";
 import { UnknownRecord } from "./UnknownRecord.js";
 import { ValueOf } from "./ValueOf.js";
 import { Writable } from "./Writable.js";
-export { type DeepPartial, type DeepReadonly, type DistributiveOmit, type EmptyObject, type IsEqual, type JSONValue, type Merge, type NonEmptyArray, type ObjectKeys, type Primitive, type SetOptional, type SetRequired, type Simplify, type ToCamelCaseKeys, type ToConstantCaseKeys, type ToKebabCaseKeys, type ToPascalCaseKeys, type ToSnakeCaseKeys, type UnknownRecord, type ValueOf, type Writable };
+export { type DeepPartial, type DeepReadonly, type DistributiveOmit, type EmptyObject, type IsAny, type IsEqual, type IsUnknown, type JSONValue, type Merge, type NonEmptyArray, type ObjectKeys, type Primitive, type SetOptional, type SetRequired, type Simplify, type ToCamelCaseKeys, type ToConstantCaseKeys, type ToKebabCaseKeys, type ToPascalCaseKeys, type ToSnakeCaseKeys, type UnknownRecord, type ValueOf, type Writable };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "es-toolkit",
-  "version": "1.52.0-dev.2135+aaeb0753",
+  "version": "1.52.0-dev.2137+e472583b",
   "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",