@visulima/object 1.0.9 → 1.0.10

package/dist/index.d.ts

@@ -452,6 +452,71 @@ type ShouldBeTrue = IsNegative<-1>;
 */
 type IsNegative<T extends Numeric> = T extends Negative<T> ? true : false;
 
+/**
+Returns a boolean for whether the given type is a `string` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
+
+Useful for:
+	- providing strongly-typed string manipulation functions
+	- constraining strings to be a string literal
+	- type utilities, such as when constructing parsers and ASTs
+
+The implementation of this type is inspired by the trick mentioned in this [StackOverflow answer](https://stackoverflow.com/a/68261113/420747).
+
+@example
+```
+import type {IsStringLiteral} from 'type-fest';
+
+type CapitalizedString<T extends string> = IsStringLiteral<T> extends true ? Capitalize<T> : string;
+
+// https://github.com/yankeeinlondon/native-dash/blob/master/src/capitalize.ts
+function capitalize<T extends Readonly<string>>(input: T): CapitalizedString<T> {
+	return (input.slice(0, 1).toUpperCase() + input.slice(1)) as CapitalizedString<T>;
+}
+
+const output = capitalize('hello, world!');
+//=> 'Hello, world!'
+```
+
+@example
+```
+// String types with infinite set of possible values return `false`.
+
+import type {IsStringLiteral} from 'type-fest';
+
+type AllUppercaseStrings = IsStringLiteral<Uppercase<string>>;
+//=> false
+
+type StringsStartingWithOn = IsStringLiteral<`on${string}`>;
+//=> false
+
+// This behaviour is particularly useful in string manipulation utilities, as infinite string types often require separate handling.
+
+type Length<S extends string, Counter extends never[] = []> =
+	IsStringLiteral<S> extends false
+		? number // return `number` for infinite string types
+		: S extends `${string}${infer Tail}`
+			? Length<Tail, [...Counter, never]>
+			: Counter['length'];
+
+type L1 = Length<Lowercase<string>>;
+//=> number
+
+type L2 = Length<`${number}`>;
+//=> number
+```
+
+@category Type Guard
+@category Utilities
+*/
+type IsStringLiteral<T> = IfNever<T, false,
+// If `T` is an infinite string type (e.g., `on${string}`), `Record<T, never>` produces an index signature,
+// and since `{}` extends index signatures, the result becomes `false`.
+T extends string
+	? {} extends Record<T, never>
+		? false
+		: true
+	: false>;
+
 /**
 Returns a boolean for whether two given types are both true.
 
@@ -588,32 +653,7 @@ type LessThan<A extends number, B extends number> = number extends A | B
 	? never
 	: GreaterThanOrEqual<A, B> extends true ? false : true;
 
-/**
-Infer the length of the given tuple `<T>`.
-
-Returns `never` if the given type is an non-fixed-length array like `Array<string>`.
-
-@example
-```
-type Tuple = TupleLength<[string, number, boolean]>;
-//=> 3
-
-type Array = TupleLength<string[]>;
-//=> never
-
-// Supports union types.
-type Union = TupleLength<[] | [1, 2, 3] | Array<number>>;
-//=> 1 | 3
-```
-*/
-type TupleLength<T extends UnknownArray> =
-	// `extends unknown` is used to convert `T` (if `T` is a union type) to
-	// a [distributive conditionaltype](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types))
-	T extends unknown
-		? number extends T['length']
-			? never // Return never if the given type is an non-flexed-length array like `Array<string>`
-			: T['length']
-		: never; // Should never happen
+// Should never happen
 
 /**
 Create a tuple type of the given length `<L>` and fill it with the given type `<Fill>`.
@@ -628,52 +668,6 @@ type BuildTuple<L extends number, Fill = unknown, T extends readonly unknown[] =
 		? T
 		: BuildTuple<L, Fill, [...T, Fill]>;
 
-/**
-Returns the maximum value from a tuple of integers.
-
-Note:
-- Float numbers are not supported.
-
-@example
-```
-ArrayMax<[1, 2, 5, 3]>;
-//=> 5
-
-ArrayMax<[1, 2, 5, 3, 99, -1]>;
-//=> 99
-```
-*/
-type TupleMax<A extends number[], Result extends number = NegativeInfinity> = number extends A[number]
-	? never :
-	A extends [infer F extends number, ...infer R extends number[]]
-		? GreaterThan<F, Result> extends true
-			? TupleMax<R, F>
-			: TupleMax<R, Result>
-		: Result;
-
-/**
-Returns the minimum value from a tuple of integers.
-
-Note:
-- Float numbers are not supported.
-
-@example
-```
-ArrayMin<[1, 2, 5, 3]>;
-//=> 1
-
-ArrayMin<[1, 2, 5, 3, -5]>;
-//=> -5
-```
-*/
-type TupleMin<A extends number[], Result extends number = PositiveInfinity> = number extends A[number]
-	? never
-	: A extends [infer F extends number, ...infer R extends number[]]
-		? LessThan<F, Result> extends true
-			? TupleMin<R, F>
-			: TupleMin<R, Result>
-		: Result;
-
 /**
 Return a string representation of the given string or number.
 
@@ -904,48 +898,30 @@ type IsNumberLike<N> =
 				: false;
 
 /**
-Returns the minimum number in the given union of numbers.
-
-Note: Just supports numbers from 0 to 999.
+Returns the number with reversed sign.
 
 @example
 ```
-type A = UnionMin<3 | 1 | 2>;
+ReverseSign<-1>;
 //=> 1
-```
-*/
-type UnionMin<N extends number> = InternalUnionMin<N>;
-
-/**
-The actual implementation of `UnionMin`. It's private because it has some arguments that don't need to be exposed.
-*/
-type InternalUnionMin<N extends number, T extends UnknownArray = []> =
-	T['length'] extends N
-		? T['length']
-		: InternalUnionMin<N, [...T, unknown]>;
 
-/**
-Returns the maximum number in the given union of numbers.
+ReverseSign<1>;
+//=> -1
 
-Note: Just supports numbers from 0 to 999.
+ReverseSign<NegativeInfinity>
+//=> PositiveInfinity
 
-@example
-```
-type A = UnionMax<1 | 3 | 2>;
-//=> 3
+ReverseSign<PositiveInfinity>
+//=> NegativeInfinity
 ```
 */
-type UnionMax<N extends number> = InternalUnionMax<N>;
-
-/**
-The actual implementation of `UnionMax`. It's private because it has some arguments that don't need to be exposed.
-*/
-type InternalUnionMax<N extends number, T extends UnknownArray = []> =
-	IsNever<N> extends true
-		? T['length']
-		:	T['length'] extends N
-			? InternalUnionMax<Exclude<N, T['length']>, T>
-			: InternalUnionMax<N, [...T, unknown]>;
+type ReverseSign<N extends number> =
+	// Handle edge cases
+	N extends 0 ? 0 : N extends PositiveInfinity ? NegativeInfinity : N extends NegativeInfinity ? PositiveInfinity :
+	// Handle negative numbers
+	`${N}` extends `-${infer P extends number}` ? P
+		// Handle positive numbers
+		: `-${N}` extends `${infer R extends number}` ? R : never;
 
 /**
 Matches any primitive, `void`, `Date`, or `RegExp` value.
@@ -957,6 +933,24 @@ Matches non-recursive types.
 */
 type NonRecursiveType = BuiltIns | Function | (new (...arguments_: any[]) => unknown);
 
+/**
+Returns a boolean for whether A is false.
+
+@example
+```
+Not<true>;
+//=> false
+
+Not<false>;
+//=> true
+```
+*/
+type Not<A extends boolean> = A extends true
+	? false
+	: A extends false
+		? true
+		: never;
+
 /**
 Create an object type with the given key `<Key>` and value `<Value>`.
 
@@ -1110,76 +1104,11 @@ type SimplifyDeep<Type, ExcludeType = never> =
 	object
 	>;
 
-/**
-Returns the sum of two numbers.
-
-Note:
-- A or B can only support `-999` ~ `999`.
-- A and B can only be small integers, less than 1000.
-- If the result is negative, you can only get `number`.
-
-@example
-```
-import type {Sum} from 'type-fest';
-
-Sum<111, 222>;
-//=> 333
-
-Sum<-111, 222>;
-//=> 111
-
-Sum<111, -222>;
-//=> number
-
-Sum<PositiveInfinity, -9999>;
-//=> PositiveInfinity
-
-Sum<PositiveInfinity, NegativeInfinity>;
-//=> number
-```
-
-@category Numeric
-*/
-// TODO: Support big integer and negative number.
-type Sum<A extends number, B extends number> = number extends A | B
-	? number
-	: [
-		IsEqual<A, PositiveInfinity>, IsEqual<A, NegativeInfinity>,
-		IsEqual<B, PositiveInfinity>, IsEqual<B, NegativeInfinity>,
-	] extends infer R extends [boolean, boolean, boolean, boolean]
-		? Or<
-		And<IsEqual<R[0], true>, IsEqual<R[3], false>>,
-		And<IsEqual<R[2], true>, IsEqual<R[1], false>>
-		> extends true
-			? PositiveInfinity
-			: Or<
-			And<IsEqual<R[1], true>, IsEqual<R[2], false>>,
-			And<IsEqual<R[3], true>, IsEqual<R[0], false>>
-			> extends true
-				? NegativeInfinity
-				: true extends R[number]
-					? number
-					: ([IsNegative<A>, IsNegative<B>] extends infer R
-						? [false, false] extends R
-							? [...BuildTuple<A>, ...BuildTuple<B>]['length']
-							: [true, true] extends R
-								? number
-								: TupleMax<[NumberAbsolute<A>, NumberAbsolute<B>]> extends infer Max_
-									? TupleMin<[NumberAbsolute<A>, NumberAbsolute<B>]> extends infer Min_ extends number
-										? Max_ extends A | B
-											? Subtract<Max_, Min_>
-											: number
-										: never
-									: never
-						: never) & number
-		: never;
-
 /**
 Returns the difference between two numbers.
 
 Note:
 - A or B can only support `-999` ~ `999`.
-- If the result is negative, you can only get `number`.
 
 @example
 ```
@@ -1192,7 +1121,10 @@ Subtract<111, -222>;
 //=> 333
 
 Subtract<-111, 222>;
-//=> number
+//=> -333
+
+Subtract<18, 96>;
+//=> -78
 
 Subtract<PositiveInfinity, 9999>;
 //=> PositiveInfinity
@@ -1203,38 +1135,53 @@ Subtract<PositiveInfinity, PositiveInfinity>;
 
 @category Numeric
 */
-// TODO: Support big integer and negative number.
-type Subtract<A extends number, B extends number> = number extends A | B
-	? number
-	: [
-		IsEqual<A, PositiveInfinity>, IsEqual<A, NegativeInfinity>,
-		IsEqual<B, PositiveInfinity>, IsEqual<B, NegativeInfinity>,
-	] extends infer R extends [boolean, boolean, boolean, boolean]
-		? Or<
-		And<IsEqual<R[0], true>, IsEqual<R[2], false>>,
-		And<IsEqual<R[3], true>, IsEqual<R[1], false>>
-		> extends true
-			? PositiveInfinity
-			: Or<
-			And<IsEqual<R[1], true>, IsEqual<R[3], false>>,
-			And<IsEqual<R[2], true>, IsEqual<R[0], false>>
-			> extends true
-				? NegativeInfinity
-				: true extends R[number]
-					? number
-					: [IsNegative<A>, IsNegative<B>] extends infer R
-						? [false, false] extends R
-							? BuildTuple<A> extends infer R
-								? R extends [...BuildTuple<B>, ...infer R]
-									? R['length']
-									: number
-								: never
-							: LessThan<A, B> extends true
-								? number
-								: [false, true] extends R
-									? Sum<A, NumberAbsolute<B>>
-									: Subtract<NumberAbsolute<B>, NumberAbsolute<A>>
-						: never
+// TODO: Support big integer.
+type Subtract<A extends number, B extends number> =
+	// Handle cases when A or B is the actual "number" type
+	number extends A | B ? number
+		// Handle cases when A and B are both +/- infinity
+		: A extends B & (PositiveInfinity | NegativeInfinity) ? number
+			// Handle cases when A is - infinity or B is + infinity
+			: A extends NegativeInfinity ? NegativeInfinity : B extends PositiveInfinity ? NegativeInfinity
+				// Handle cases when A is + infinity or B is - infinity
+				: A extends PositiveInfinity ? PositiveInfinity : B extends NegativeInfinity ? PositiveInfinity
+					// Handle case when numbers are equal to each other
+					: A extends B ? 0
+						// Handle cases when A or B is 0
+						: A extends 0 ? ReverseSign<B> : B extends 0 ? A
+							// Handle remaining regular cases
+							: SubtractPostChecks<A, B>;
+
+/**
+Subtracts two numbers A and B, such that they are not equal and neither of them are 0, +/- infinity or the `number` type
+*/
+type SubtractPostChecks<A extends number, B extends number, AreNegative = [IsNegative<A>, IsNegative<B>]> =
+	AreNegative extends [false, false]
+		? SubtractPositives<A, B>
+		: AreNegative extends [true, true]
+			// When both numbers are negative we subtract the absolute values and then reverse the sign
+			? ReverseSign<SubtractPositives<NumberAbsolute<A>, NumberAbsolute<B>>>
+			// When the signs are different we can add the absolute values and then reverse the sign if A < B
+			: [...BuildTuple<NumberAbsolute<A>>, ...BuildTuple<NumberAbsolute<B>>] extends infer R extends unknown[]
+				? LessThan<A, B> extends true ? ReverseSign<R['length']> : R['length']
+				: never;
+
+/**
+Subtracts two positive numbers.
+*/
+type SubtractPositives<A extends number, B extends number> =
+	LessThan<A, B> extends true
+		// When A < B we can reverse the result of B - A
+		? ReverseSign<SubtractIfAGreaterThanB<B, A>>
+		: SubtractIfAGreaterThanB<A, B>;
+
+/**
+Subtracts two positive numbers A and B such that A > B.
+*/
+type SubtractIfAGreaterThanB<A extends number, B extends number> =
+	// This is where we always want to end up and do the actual subtraction
+	BuildTuple<A> extends [...BuildTuple<B>, ...infer R]
+		? R['length']
 		: never;
 
 /**
@@ -1282,11 +1229,89 @@ type PathsOptions = {
 	```
 	*/
 	bracketNotation?: boolean;
+
+	/**
+	Only include leaf paths in the output.
+
+	@default false
+
+	@example
+	```
+	type Post = {
+		id: number;
+		author: {
+			id: number;
+			name: {
+				first: string;
+				last: string;
+			};
+		};
+	};
+
+	type AllPaths = Paths<Post, {leavesOnly: false}>;
+	//=> 'id' | 'author' | 'author.id' | 'author.name' | 'author.name.first' | 'author.name.last'
+
+	type LeafPaths = Paths<Post, {leavesOnly: true}>;
+	//=> 'id' | 'author.id' | 'author.name.first' | 'author.name.last'
+	```
+
+	@example
+	```
+	type ArrayExample = {
+		array: Array<{foo: string}>;
+		tuple: [string, {bar: string}];
+	};
+
+	type AllPaths = Paths<ArrayExample, {leavesOnly: false}>;
+	//=> 'array' | `array.${number}` | `array.${number}.foo` | 'tuple' | 'tuple.0' | 'tuple.1' | 'tuple.1.bar'
+
+	type LeafPaths = Paths<ArrayExample, {leavesOnly: true}>;
+	//=> `array.${number}.foo` | 'tuple.0' | 'tuple.1.bar'
+	```
+	*/
+	leavesOnly?: boolean;
+
+	/**
+	Only include paths at the specified depth. By default all paths up to {@link PathsOptions.maxRecursionDepth | `maxRecursionDepth`} are included.
+
+	Note: Depth starts at `0` for root properties.
+
+	@default number
+
+	@example
+	```
+	type Post = {
+		id: number;
+		author: {
+			id: number;
+			name: {
+				first: string;
+				last: string;
+			};
+		};
+	};
+
+	type DepthZero = Paths<Post, {depth: 0}>;
+	//=> 'id' | 'author'
+
+	type DepthOne = Paths<Post, {depth: 1}>;
+	//=> 'author.id' | 'author.name'
+
+	type DepthTwo = Paths<Post, {depth: 2}>;
+	//=> 'author.name.first' | 'author.name.last'
+
+	type LeavesAtDepthOne = Paths<Post, {leavesOnly: true; depth: 1}>;
+	//=> 'author.id'
+	```
+	*/
+	depth?: number;
 };
 
 type DefaultPathsOptions = {
 	maxRecursionDepth: 10;
 	bracketNotation: false;
+	leavesOnly: false;
+	depth: number;
 };
 
 /**
@@ -1335,6 +1360,10 @@ type Paths<T, Options extends PathsOptions = {}> = _Paths<T, {
 	maxRecursionDepth: Options['maxRecursionDepth'] extends number ? Options['maxRecursionDepth'] : DefaultPathsOptions['maxRecursionDepth'];
 	// Set default bracketNotation to false
 	bracketNotation: Options['bracketNotation'] extends boolean ? Options['bracketNotation'] : DefaultPathsOptions['bracketNotation'];
+	// Set default leavesOnly to false
+	leavesOnly: Options['leavesOnly'] extends boolean ? Options['leavesOnly'] : DefaultPathsOptions['leavesOnly'];
+	// Set default depth to number
+	depth: Options['depth'] extends number ? Options['depth'] : DefaultPathsOptions['depth'];
 }>;
 
 type _Paths<T, Options extends Required<PathsOptions>> =
@@ -1374,11 +1403,30 @@ type InternalPaths<T, Options extends Required<PathsOptions>> =
 						) extends infer TranformedKey extends string | number ?
 						// 1. If style is 'a[0].b' and 'Key' is a numberlike value like 3 or '3', transform 'Key' to `[${Key}]`, else to `${Key}` | Key
 						// 2. If style is 'a.0.b', transform 'Key' to `${Key}` | Key
-							| TranformedKey
+							| ((Options['leavesOnly'] extends true
+								? MaxDepth extends 0
+									? TranformedKey
+									: T[Key] extends EmptyObject | readonly [] | NonRecursiveType | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown>
+										? TranformedKey
+										: never
+								: TranformedKey
+							) extends infer _TransformedKey
+								// If `depth` is provided, the condition becomes truthy only when it reaches `0`.
+								// Otherwise, since `depth` defaults to `number`, the condition is always truthy, returning paths at all depths.
+								? 0 extends Options['depth']
+									? _TransformedKey
+									: never
+								: never)
 							| (
 								// Recursively generate paths for the current key
 								GreaterThan<MaxDepth, 0> extends true // Limit the depth to prevent infinite recursion
-									? _Paths<T[Key], {bracketNotation: Options['bracketNotation']; maxRecursionDepth: Subtract<MaxDepth, 1>}> extends infer SubPath
+									? _Paths<T[Key],
+									{
+										bracketNotation: Options['bracketNotation'];
+										maxRecursionDepth: Subtract<MaxDepth, 1>;
+										leavesOnly: Options['leavesOnly'];
+										depth: Subtract<Options['depth'], 1>;
+									}> extends infer SubPath
 										? SubPath extends string | number
 											? (
 												Options['bracketNotation'] extends true
@@ -1562,7 +1610,9 @@ The implementation of `SplitArrayByIndex` for variable length arrays.
 type SplitVariableArrayByIndex<T extends UnknownArray,
 	SplitIndex extends number,
 	T1 = Subtract<SplitIndex, StaticPartOfArray<T>['length']>,
-	T2 = T1 extends number ? BuildTuple<T1, VariablePartOfArray<T>[number]> : [],
+	T2 = T1 extends number
+		? BuildTuple<GreaterThanOrEqual<T1, 0> extends true ? T1 : number, VariablePartOfArray<T>[number]>
+		: [],
 > =
 SplitIndex extends 0
 	? [[], T]
@@ -1674,173 +1724,58 @@ type LiteralUnion<
 > = LiteralType | (BaseType & Record<never, never>);
 
 /**
-SharedUnionFieldsDeep options.
+Returns the last element of a union type.
 
-@see {@link SharedUnionFieldsDeep}
+@example
+```
+type Last = LastOfUnion<1 | 2 | 3>;
+//=> 3
+```
 */
-type SharedUnionFieldsDeepOptions = {
-	/**
-	When set to true, this option impacts each element within arrays or tuples. If all union values are arrays or tuples, it constructs an array of the shortest possible length, ensuring every element exists in the union array.
-
-	@default false
- 	*/
-	recurseIntoArrays?: boolean;
-};
+type LastOfUnion<T> =
+UnionToIntersection<T extends any ? () => T : never> extends () => (infer R)
+	? R
+	: never;
 
 /**
-Create a type with shared fields from a union of object types, deeply traversing nested structures.
+Convert a union type into an unordered tuple type of its elements.
 
-Use the {@link SharedUnionFieldsDeepOptions `Options`} to specify the behavior for arrays.
+"Unordered" means the elements of the tuple are not guaranteed to be in the same order as in the union type. The arrangement can appear random and may change at any time.
 
-Use-cases:
-- You want a safe object type where each key exists in the union object.
-- You want to focus on the common fields of the union type and don't want to have to care about the other fields.
+This can be useful when you have objects with a finite set of keys and want a type defining only the allowed keys, but do not want to repeat yourself.
 
 @example
 ```
-import type {SharedUnionFieldsDeep} from 'type-fest';
-
-type Cat = {
-	info: {
-		name: string;
-		type: 'cat';
-		catType: string;
-	};
-};
-
-type Dog = {
-	info: {
-		name: string;
-		type: 'dog';
-		dogType: string;
-	};
-};
-
-function displayPetInfo(petInfo: (Cat | Dog)['info']) {
-	// typeof petInfo =>
-	// {
-	// 	name: string;
-	// 	type: 'cat';
-	// 	catType: string; // Needn't care about this field, because it's not a common pet info field.
-	// } | {
-	// 	name: string;
-	// 	type: 'dog';
-	// 	dogType: string; // Needn't care about this field, because it's not a common pet info field.
-	// }
-
-	// petInfo type is complex and have some needless fields
-
-	console.log('name: ', petInfo.name);
-	console.log('type: ', petInfo.type);
-}
-
-function displayPetInfo(petInfo: SharedUnionFieldsDeep<Cat | Dog>['info']) {
-	// typeof petInfo =>
-	// {
-	// 	name: string;
-	// 	type: 'cat' | 'dog';
-	// }
+import type {UnionToTuple} from 'type-fest';
 
-	// petInfo type is simple and clear
+type Numbers = 1 | 2 | 3;
+type NumbersTuple = UnionToTuple<Numbers>;
+//=> [1, 2, 3]
+```
 
-	console.log('name: ', petInfo.name);
-	console.log('type: ', petInfo.type);
-}
+@example
 ```
+import type {UnionToTuple} from 'type-fest';
 
-@see SharedUnionFields
+const pets = {
+  dog: '🐶',
+  cat: '🐱',
+  snake: '🐍',
+};
 
-@category Object
-@category Union
-*/
-type SharedUnionFieldsDeep<Union, Options extends SharedUnionFieldsDeepOptions = {recurseIntoArrays: false}> =
-	// `Union extends` will convert `Union`
-	// to a [distributive conditionaltype](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
-	// But this is not what we want, so we need to wrap `Union` with `[]` to prevent it.
-	[Union] extends [NonRecursiveType | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown>]
-		? Union
-		: [Union] extends [UnknownArray]
-			? Options['recurseIntoArrays'] extends true
-				? SetArrayAccess<SharedArrayUnionFieldsDeep<Union, Options>, IsArrayReadonly<Union>>
-				: Union
-			: [Union] extends [object]
-				? SharedObjectUnionFieldsDeep<Union, Options>
-				: Union;
-
-/**
-Same as `SharedUnionFieldsDeep`, but accepts only `object`s and as inputs. Internal helper for `SharedUnionFieldsDeep`.
-*/
-type SharedObjectUnionFieldsDeep<Union, Options extends SharedUnionFieldsDeepOptions> =
-	// `keyof Union` can extract the same key in union type, if there is no same key, return never.
-	keyof Union extends infer Keys
-		? IsNever<Keys> extends false
-			? {
-				[Key in keyof Union]:
-				Union[Key] extends NonRecursiveType
-					? Union[Key]
-					// Remove `undefined` from the union to support optional
-					// fields, then recover `undefined` if union was already undefined.
-					: SharedUnionFieldsDeep<Exclude<Union[Key], undefined>, Options> | (
-						undefined extends Required<Union>[Key] ? undefined : never
-					)
-			}
-			: {}
-		: Union;
+type Pet = keyof typeof pets;
+//=> 'dog' | 'cat' | 'snake'
 
-/**
-Same as `SharedUnionFieldsDeep`, but accepts only `UnknownArray`s and as inputs. Internal helper for `SharedUnionFieldsDeep`.
-*/
-type SharedArrayUnionFieldsDeep<Union extends UnknownArray, Options extends SharedUnionFieldsDeepOptions> =
-	// Restore the readonly modifier of the array.
-	SetArrayAccess<
-	InternalSharedArrayUnionFieldsDeep<Union, Options>,
-	IsArrayReadonly<Union>
-	>;
+const petList = Object.keys(pets) as UnionToTuple<Pet>;
+//=> ['dog', 'cat', 'snake']
+```
 
-/**
-Internal helper for `SharedArrayUnionFieldsDeep`. Needn't care the `readonly` modifier of arrays.
+@category Array
 */
-type InternalSharedArrayUnionFieldsDeep<
-	Union extends UnknownArray,
-	Options extends SharedUnionFieldsDeepOptions,
-	ResultTuple extends UnknownArray = [],
-> =
-	// We should build a minimum possible length tuple where each element in the tuple exists in the union tuple.
-	IsNever<TupleLength<Union>> extends true
-		// Rule 1: If all the arrays in the union have non-fixed lengths,
-		// like `Array<string> | [number, ...string[]]`
-		// we should build a tuple that is [the_fixed_parts_of_union, ...the_rest_of_union[]].
-		// For example: `InternalSharedArrayUnionFieldsDeep<Array<string> | [number, ...string[]]>`
-		// => `[string | number, ...string[]]`.
-		? ResultTuple['length'] extends UnionMax<StaticPartOfArray<Union>['length']>
-			? [
-				// The fixed-length part of the tuple.
-				...ResultTuple,
-				// The rest of the union.
-				// Due to `ResultTuple` is the maximum possible fixed-length part of the tuple,
-				// so we can use `StaticPartOfArray` to get the rest of the union.
-				...Array<
-				SharedUnionFieldsDeep<VariablePartOfArray<Union>[number], Options>
-				>,
-			]
-			// Build the fixed-length tuple recursively.
-			: InternalSharedArrayUnionFieldsDeep<
-			Union, Options,
-			[...ResultTuple, SharedUnionFieldsDeep<Union[ResultTuple['length']], Options>]
-			>
-		// Rule 2: If at least one of the arrays in the union have fixed lengths,
-		// like `Array<string> | [number, string]`,
-		// we should build a tuple of the smallest possible length to ensure any
-		// item in the result tuple exists in the union tuple.
-		// For example: `InternalSharedArrayUnionFieldsDeep<Array<string> | [number, string]>`
-		// => `[string | number, string]`.
-		: ResultTuple['length'] extends UnionMin<TupleLength<Union>>
-			? ResultTuple
-			// As above, build tuple recursively.
-			: InternalSharedArrayUnionFieldsDeep<
-			Union, Options,
-			[...ResultTuple, SharedUnionFieldsDeep<Union[ResultTuple['length']], Options>]
-			>;
+type UnionToTuple<T, L = LastOfUnion<T>> =
+IsNever<T> extends false
+	? [...UnionToTuple<Exclude<T, L>>, L]
+	: [];
 
 /**
 Omit properties from a deeply-nested object.
@@ -1926,11 +1861,19 @@ type AddressInfo = OmitDeep<Info1, 'address.1.foo'>;
 */
 type OmitDeep<T, PathUnion extends LiteralUnion<Paths<T>, string>> =
 	SimplifyDeep<
-	SharedUnionFieldsDeep<
-	{[P in PathUnion]: OmitDeepWithOnePath<T, P>}[PathUnion]
-	>,
+	OmitDeepHelper<T, UnionToTuple<PathUnion>>,
 	UnknownArray>;
 
+/**
+Internal helper for {@link OmitDeep}.
+
+Recursively transforms `T` by applying {@link OmitDeepWithOnePath} for each path in `PathTuple`.
+*/
+type OmitDeepHelper<T, PathTuple extends UnknownArray> =
+	PathTuple extends [infer Path, ...infer RestPaths]
+		? OmitDeepHelper<OmitDeepWithOnePath<T, Path & (string | number)>, RestPaths>
+		: T;
+
 /**
 Omit one path from the given object/array.
 */
@@ -2018,6 +1961,41 @@ type StringKeysOfFoo = StringKeyOf<Foo>;
 */
 type StringKeyOf<BaseType> = `${Extract<keyof BaseType, string | number>}`;
 
+/**
+Split options.
+
+@see {@link Split}
+*/
+type SplitOptions = {
+	/**
+	When enabled, instantiations with non-literal string types (e.g., `string`, `Uppercase<string>`, `on${string}`) simply return back `string[]` without performing any splitting, as the exact structure cannot be statically determined.
+
+	Note: In the future, this option might be enabled by default, so if you currently rely on this being disabled, you should consider explicitly enabling it.
+
+	@default false
+
+	@example
+	```ts
+	type Example1 = Split<`foo.${string}.bar`, '.', {strictLiteralChecks: false}>;
+	//=> ['foo', string, 'bar']
+
+	type Example2 = Split<`foo.${string}`, '.', {strictLiteralChecks: true}>;
+	//=> string[]
+
+	type Example3 = Split<'foobarbaz', `b${string}`, {strictLiteralChecks: false}>;
+	//=> ['foo', 'r', 'z']
+
+	type Example4 = Split<'foobarbaz', `b${string}`, {strictLiteralChecks: true}>;
+	//=> string[]
+	```
+	*/
+	strictLiteralChecks?: boolean;
+};
+
+type DefaultSplitOptions = {
+	strictLiteralChecks: false;
+};
+
 /**
 Represents an array of strings split using a given character or character set.
 
@@ -2036,23 +2014,37 @@ let array: Item[];
 array = split(items, ',');
 ```
 
+@see {@link SplitOptions}
+
 @category String
 @category Template literal
 */
 type Split<
 	S extends string,
 	Delimiter extends string,
-> = SplitHelper<S, Delimiter>;
+	Options extends SplitOptions = {},
+> = SplitHelper<S, Delimiter, {
+	strictLiteralChecks: Options['strictLiteralChecks'] extends boolean ? Options['strictLiteralChecks'] : DefaultSplitOptions['strictLiteralChecks'];
+}>;
 
 type SplitHelper<
 	S extends string,
 	Delimiter extends string,
+	Options extends Required<SplitOptions>,
 	Accumulator extends string[] = [],
-> = S extends `${infer Head}${Delimiter}${infer Tail}`
-	? SplitHelper<Tail, Delimiter, [...Accumulator, Head]>
-	: Delimiter extends ''
-		? Accumulator
-		: [...Accumulator, S];
+> = S extends string // For distributing `S`
+	? Delimiter extends string // For distributing `Delimeter`
+		// If `strictLiteralChecks` is `false` OR `S` and `Delimiter` both are string literals, then perform the split
+		? Or<Not<Options['strictLiteralChecks']>, And<IsStringLiteral<S>, IsStringLiteral<Delimiter>>> extends true
+			? S extends `${infer Head}${Delimiter}${infer Tail}`
+				? SplitHelper<Tail, Delimiter, Options, [...Accumulator, Head]>
+				: Delimiter extends ''
+					? Accumulator
+					: [...Accumulator, S]
+			// Otherwise, return `string[]`
+			: string[]
+		: never // Should never happen
+	: never; // Should never happen
 
 type GetOptions = {
 	/**