@depup/type-fest 5.4.4-depup.0 → 5.9.0-depup.0

package/source/is-numeric-literal.d.ts

@@ -0,0 +1,50 @@
+import type {CollapseLiterals, UnwrapBrand} from './internal/object.d.ts';
+import type {IfNotAnyOrNever} from './internal/type.d.ts';
+
+/**
+Returns a boolean for whether the given type is a `number` or `bigint` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
+
+@example
+```
+import type {IsNumericLiteral} from 'type-fest';
+
+type A = IsNumericLiteral<0>;
+//=> true
+
+type B = IsNumericLiteral<number>;
+//=> false
+
+type C = IsNumericLiteral<100n>;
+//=> true
+
+type D = IsNumericLiteral<bigint>;
+//=> false
+
+type E = IsNumericLiteral<1 | 2 | 10n | 20n>;
+//=> true
+
+type F = IsNumericLiteral<number | bigint>;
+//=> false
+
+type G = IsNumericLiteral<1 | bigint>;
+//=> boolean
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsNumericLiteral<T> = IfNotAnyOrNever<T, {
+	ifNot: _IsNumericLiteral<CollapseLiterals<UnwrapBrand<T>>>;
+	ifAny: false;
+	ifNever: false;
+}>;
+
+type _IsNumericLiteral<T> = T extends number | bigint
+	? number extends T
+		? false
+		: bigint extends T
+			? false
+			: true
+	: false;
+
+export {};

package/source/is-string-literal.d.ts

@@ -0,0 +1,72 @@
+import type {CollapseLiterals, UnwrapBrand} from './internal/object.d.ts';
+import type {IfNotAnyOrNever} from './internal/type.d.ts';
+
+/**
+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).
+
+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 A = IsStringLiteral<'foo'>;
+//=> true
+
+type B = IsStringLiteral<string>;
+//=> false
+
+// String types with infinite set of possible values return `false`
+type C = IsStringLiteral<`on${string}`>;
+//=> false
+
+type D = IsStringLiteral<Uppercase<string>>;
+//=> false
+
+type E = IsStringLiteral<'foo' | 'bar' | 'baz'>;
+//=> true
+
+type F = IsStringLiteral<'sm' | 'md' | 'lg' | `${number}px`>;
+//=> boolean
+```
+
+@example
+```
+import type {IsStringLiteral} from 'type-fest';
+
+type StringLength<S extends string, Counter extends never[] = []> =
+	IsStringLiteral<S> extends true
+		? S extends `${string}${infer Tail}`
+			? StringLength<Tail, [...Counter, never]>
+			: Counter['length']
+		: number; // return `number` for non-literal string types
+
+type L1 = StringLength<'foobar'>;
+//=> 6
+
+type L2 = StringLength<Lowercase<string>>;
+//=> number
+
+type L3 = StringLength<`${number}`>;
+//=> number
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsStringLiteral<S> = IfNotAnyOrNever<S, {
+	ifNot: _IsStringLiteral<CollapseLiterals<UnwrapBrand<S>>>;
+	ifAny: false;
+	ifNever: false;
+}>;
+
+type _IsStringLiteral<S> =
+	// If `S` is an infinite string type (e.g., `on${string}`), `Record<S, never>` produces an index signature,
+	// and since `{}` extends index signatures, the result becomes `false`.
+	S extends string
+		? {} extends Record<S, never>
+			? false
+			: true
+		: false;
+
+export {};

package/source/is-symbol-literal.d.ts

@@ -0,0 +1,39 @@
+import type {CollapseLiterals, UnwrapBrand} from './internal/object.d.ts';
+import type {IfNotAnyOrNever} from './internal/type.d.ts';
+
+/**
+Returns a boolean for whether the given type is a `symbol` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
+
+@example
+```
+import type {IsSymbolLiteral} from 'type-fest';
+
+declare const symbolLiteral1: unique symbol;
+declare const symbolLiteral2: unique symbol;
+
+type A = IsSymbolLiteral<typeof symbolLiteral1>;
+//=> true
+
+type B = IsSymbolLiteral<symbol>;
+//=> false
+
+type C = IsSymbolLiteral<typeof symbolLiteral1 | typeof symbolLiteral2>;
+//=> true
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsSymbolLiteral<T> = IfNotAnyOrNever<T, {
+	ifNot: _IsSymbolLiteral<CollapseLiterals<UnwrapBrand<T>>>;
+	ifAny: false;
+	ifNever: false;
+}>;
+
+type _IsSymbolLiteral<T> = T extends symbol
+	? symbol extends T
+		? false
+		: true
+	: false;
+
+export {};

package/source/is-union.d.ts

@@ -21,20 +21,20 @@ export type IsUnion<T> = InternalIsUnion<T>;
 The actual implementation of `IsUnion`.
 */
 type InternalIsUnion<T, U = T> =
-(
-	IsNever<T> extends true
-		? false
-		: T extends any
-			? IsEqual<U, T> extends true
-				? false
-				: true
-			: never
-) extends infer Result
+	(
+		IsNever<T> extends true
+			? false
+			: T extends any
+				? IsEqual<U, T> extends true
+					? false
+					: true
+				: never
+	) extends infer Result
 	// In some cases `Result` will return `false | true` which is `boolean`,
 	// that means `T` has at least two types and it's a union type,
 	// so we will return `true` instead of `boolean`.
-	? boolean extends Result ? true
-		: Result
-	: never; // Should never happen
+		? boolean extends Result ? true
+			: Result
+		: never; // Should never happen
 
 export {};

package/source/iterable-element.d.ts

@@ -57,10 +57,10 @@ type Fruit = IterableElement<typeof fruits>;
 @category Iterable
 */
 export type IterableElement<TargetIterable> =
-	TargetIterable extends Iterable<infer ElementType> ?
-		ElementType :
-		TargetIterable extends AsyncIterable<infer ElementType> ?
-			ElementType :
-			never;
+	TargetIterable extends Iterable<infer ElementType>
+		? ElementType
+		: TargetIterable extends AsyncIterable<infer ElementType>
+			? ElementType
+			: never;
 
 export {};

package/source/jsonify.d.ts

@@ -25,15 +25,11 @@ type JsonifyList<T extends UnknownArray> = T extends readonly []
 			? JsonValue[]
 			: Array<T[number] extends NotJsonable ? null : Jsonify<UndefinedToNull<T[number]>>>;
 
-type FilterJsonableKeys<T extends object> = {
-	[Key in keyof T]: T[Key] extends NotJsonable ? never : Key;
-}[keyof T];
-
 /**
 JSON serialize objects (not including arrays) and classes.
 */
 type JsonifyObject<T extends object> = {
-	[Key in keyof Pick<T, FilterJsonableKeys<T>>]: Jsonify<T[Key]>;
+	[Key in keyof T as T[Key] extends NotJsonable ? never : Key]: Jsonify<T[Key]>;
 };
 
 /**
@@ -98,13 +94,13 @@ export type Jsonify<T> = IsAny<T> extends true
 		? null
 		: T extends JsonPrimitive
 			? T
-			: // Any object with toJSON is special case
-			T extends {toJSON(): infer J}
+			// Any object with toJSON is special case
+			: T extends {toJSON(): infer J}
 				? (() => J) extends () => JsonValue // Is J assignable to JsonValue?
 					? J // Then T is Jsonable and its Jsonable value is J
 					: Jsonify<J> // Maybe if we look a level deeper we'll find a JsonValue
-				: // Instanced primitives are objects
-				T extends Number
+				// Instanced primitives are objects
+				: T extends Number
 					? number
 					: T extends String
 						? string

package/source/kebab-case.d.ts

@@ -15,6 +15,7 @@ import type {KebabCase} from 'type-fest';
 
 const someVariable: KebabCase<'fooBar'> = 'foo-bar';
 const someVariableNoSplitOnNumbers: KebabCase<'p2pNetwork', {splitOnNumbers: false}> = 'p2p-network';
+const someVariableWithPunctuation: KebabCase<'div.card::after', {splitOnPunctuation: true}> = 'div-card-after';
 
 // Advanced
 

package/source/kebab-cased-properties-deep.d.ts

@@ -51,6 +51,13 @@ const splitOnNumbers: KebabCasedPropertiesDeep<{line1: {line2: [{line3: string}]
 		],
 	},
 };
+
+const splitOnPunctuation: KebabCasedPropertiesDeep<{'user@info': {'user::id': number; 'user::name': string}}, {splitOnPunctuation: true}> = {
+	'user-info': {
+		'user-id': 1,
+		'user-name': 'Tom',
+	},
+};
 ```
 
 @category Change case

package/source/kebab-cased-properties.d.ts

@@ -4,7 +4,7 @@ import type {ApplyDefaultOptions} from './internal/index.d.ts';
 import type {WordsOptions} from './words.d.ts';
 
 /**
-Convert object properties to kebab case but not recursively.
+Convert top-level object properties to kebab case.
 
 This can be useful when, for example, converting some API types from a different style.
 
@@ -28,6 +28,10 @@ const result: KebabCasedProperties<User> = {
 const splitOnNumbers: KebabCasedProperties<{line1: string}, {splitOnNumbers: true}> = {
 	'line-1': 'string',
 };
+
+const splitOnPunctuation: KebabCasedProperties<{'foo::bar': string}, {splitOnPunctuation: true}> = {
+	'foo-bar': 'string',
+};
 ```
 
 @category Change case

package/source/keys-of-union.d.ts

@@ -38,7 +38,7 @@ type AllKeys = KeysOfUnion<Union>;
 @category Object
 */
 export type KeysOfUnion<ObjectType> =
-  // Hack to fix https://github.com/sindresorhus/type-fest/issues/1008
-  keyof UnionToIntersection<ObjectType extends unknown ? Record<keyof ObjectType, never> : never>;
+	// Hack to fix https://github.com/sindresorhus/type-fest/issues/1008
+	keyof UnionToIntersection<ObjectType extends unknown ? Record<keyof ObjectType, never> : never>;
 
 export {};

package/source/last-array-element.d.ts

@@ -1,3 +1,8 @@
+import type {If} from './if.d.ts';
+import type {IfNotAnyOrNever, IsExactOptionalPropertyTypesEnabled} from './internal/type.d.ts';
+import type {SplitOnRestElement} from './split-on-rest-element.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+
 /**
 Extract the type of the last element of an array.
 
@@ -16,21 +21,69 @@ const last2 = lastOf([true, false, 'baz', 10]);
 //=> 10
 ```
 
+Note: When the array ends with an optional or rest element, the last element's position becomes ambiguous. In such cases, the result is a union of the types of all elements that could potentially be the last element of the array.
+
+@example
+```
+import type {LastArrayElement} from 'type-fest';
+
+type A = LastArrayElement<[string, number?, bigint?]>;
+//=> bigint | number | string
+
+type B = LastArrayElement<[string, number, bigint?, ...boolean[]]>;
+//=> boolean | bigint | number
+```
+
+Note: If empty array is a valid value for the array type, the result includes an `undefined`. This aligns with the runtime behavior of `[].at(-1)`.
+
+@example
+```
+import type {LastArrayElement} from 'type-fest';
+
+type A = LastArrayElement<[]>;
+//=> undefined
+
+// `[]` is assignable to `string[]`
+type B = LastArrayElement<string[]>;
+//=> string | undefined
+
+// `[]` is assignable to `[string?, number?]`
+type C = LastArrayElement<[string?, number?]>;
+//=> number | string | undefined
+
+// `[]` is assignable to [string?, number?, ...bigint[]]`
+type D = LastArrayElement<[string?, number?, ...bigint[]]>;
+//=> bigint | number | string | undefined
+```
+
 @category Array
 @category Template literal
 */
-export type LastArrayElement<Elements extends readonly unknown[], ElementBeforeTailingSpreadElement = never> =
-	// If the last element of an array is a spread element, the `LastArrayElement` result should be `'the type of the element before the spread element' | 'the type of the spread element'`.
-	Elements extends readonly []
-		? ElementBeforeTailingSpreadElement
-		: Elements extends readonly [...infer U, infer V]
-			? V
-			: Elements extends readonly [infer U, ...infer V]
-				// If we return `V[number] | U` directly, it would be wrong for `[[string, boolean, object, ...number[]]`.
-				// So we need to recurse type `V` and carry over the type of the element before the spread element.
-				? LastArrayElement<V, U>
-				: Elements extends ReadonlyArray<infer U>
-					? U | ElementBeforeTailingSpreadElement
-					: never;
+export type LastArrayElement<TArray extends UnknownArray> =
+	IfNotAnyOrNever<TArray, {
+		ifNot: TArray extends UnknownArray // For distributing `TArray`
+			? SplitOnRestElement<TArray> extends readonly [infer BeforeRest extends UnknownArray, infer Rest extends UnknownArray, infer AfterRest extends UnknownArray]
+				? _LastArrayElement<BeforeRest, Rest, AfterRest>
+				: never
+			: never;
+	}>;
+
+type _LastArrayElement<BeforeRest extends UnknownArray, Rest extends UnknownArray, AfterRest extends UnknownArray> =
+	AfterRest extends readonly [...any, infer Last] // Note there are no optional elements in `AfterRest`.
+		? Last // If there's a `Last` in `AfterRest`, then that's the result.
+		: Rest[number] | BeforeRestLastElement<BeforeRest>; // Otherwise, the result is union of the `Rest` element and the last element in `BeforeRest`.
+
+type BeforeRestLastElement<BeforeRest extends UnknownArray, Accumulator = never> =
+	BeforeRest extends readonly []
+		? Accumulator | undefined
+		: BeforeRest extends readonly [...any, infer Last]
+			? Last | Accumulator
+			: BeforeRest extends readonly [...infer Rest, (infer Last)?]
+				? BeforeRestLastElement<
+					Rest,
+					// Add `undefined` for optional elements, if `exactOptionalPropertyTypes` is disabled.
+					Last | Accumulator | If<IsExactOptionalPropertyTypesEnabled, never, undefined>
+				>
+				: never;
 
 export {};

package/source/less-than-or-equal.d.ts

@@ -1,7 +1,7 @@
 import type {GreaterThan} from './greater-than.d.ts';
 
 /**
- Returns a boolean for whether a given number is less than or equal to another number.
+Returns a boolean for whether a given number is less than or equal to another number.
 
 @example
 ```
@@ -16,9 +16,45 @@ type B = LessThanOrEqual<1, 1>;
 type C = LessThanOrEqual<1, 5>;
 //=> true
 ```
+
+Note: If either argument is the non-literal `number` type, the result is `boolean`.
+
+@example
+```
+import type {LessThanOrEqual} from 'type-fest';
+
+type A = LessThanOrEqual<number, 1>;
+//=> boolean
+
+type B = LessThanOrEqual<1, number>;
+//=> boolean
+
+type C = LessThanOrEqual<number, number>;
+//=> boolean
+```
+
+@example
+```
+import type {LessThanOrEqual} from 'type-fest';
+
+// Use `LessThanOrEqual` to constrain a function parameter to non-positive numbers.
+declare function setNonPositive<N extends number>(value: LessThanOrEqual<N, 0> extends true ? N : never): void;
+
+setNonPositive(0); // ✅ Allowed
+setNonPositive(-1); // ✅ Allowed
+
+// @ts-expect-error
+setNonPositive(1);
+
+// @ts-expect-error
+setNonPositive(2);
+```
 */
-export type LessThanOrEqual<A extends number, B extends number> = number extends A | B
-	? never
-	: GreaterThan<A, B> extends true ? false : true;
+export type LessThanOrEqual<A extends number, B extends number> =
+	GreaterThan<A, B> extends infer Result
+		? Result extends true
+			? false
+			: true
+		: never; // Should never happen
 
 export {};

package/source/less-than.d.ts

@@ -16,10 +16,42 @@ type B = LessThan<1, 1>;
 type C = LessThan<1, 5>;
 //=> true
 ```
+
+Note: If either argument is the non-literal `number` type, the result is `boolean`.
+
+@example
+```
+import type {LessThan} from 'type-fest';
+
+type A = LessThan<number, 1>;
+//=> boolean
+
+type B = LessThan<1, number>;
+//=> boolean
+
+type C = LessThan<number, number>;
+//=> boolean
+```
+
+@example
+```
+import type {LessThan} from 'type-fest';
+
+// Use `LessThan` to constrain a function parameter to negative numbers.
+declare function setNegative<N extends number>(value: LessThan<N, 0> extends true ? N : never): void;
+
+setNegative(-1); // ✅ Allowed
+setNegative(-2); // ✅ Allowed
+
+// @ts-expect-error
+setNegative(0);
+
+// @ts-expect-error
+setNegative(1);
+```
 */
-export type LessThan<A extends number, B extends number> = number extends A | B
-	? never
-	: GreaterThanOrEqual<A, B> extends infer Result
+export type LessThan<A extends number, B extends number> =
+	GreaterThanOrEqual<A, B> extends infer Result
 		? Result extends true
 			? false
 			: true

package/source/literal-to-primitive.d.ts

@@ -1,5 +1,5 @@
 /**
-Given a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) return the {@link Primitive | primitive type} it belongs to, or `never` if it's not a primitive.
+Given a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) return the [primitive type](https://developer.mozilla.org/en-US/docs/Glossary/Primitive) it belongs to, or `never` if it's not a primitive.
 
 Use-case: Working with generic types that may be literal types.
 

package/source/literal-union.d.ts

@@ -3,7 +3,7 @@ import type {Primitive} from './primitive.d.ts';
 export type _LiteralStringUnion<T> = LiteralUnion<T, string>;
 
 /**
-Allows creating a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
+Create a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
 
 Currently, when a union type of a primitive type is combined with literal types, TypeScript loses all information about the combined literals. Thus, when such type is used in an IDE with autocompletion, no suggestions are made for the declared literals.
 

package/source/merge-exclusive.d.ts

@@ -38,8 +38,8 @@ exclusiveOptions = {exclusive1: true, exclusive2: 'hi'};
 @category Object
 */
 export type MergeExclusive<FirstType, SecondType> =
-	(FirstType | SecondType) extends object ?
-		(Without<FirstType, SecondType> & SecondType) | (Without<SecondType, FirstType> & FirstType) :
-		FirstType | SecondType;
+	(FirstType | SecondType) extends object
+		? (Without<FirstType, SecondType> & SecondType) | (Without<SecondType, FirstType> & FirstType)
+		: FirstType | SecondType;
 
 export {};

package/source/merge.d.ts

@@ -12,6 +12,31 @@ type SimpleMerge<Destination, Source> = Simplify<{
 /**
 Merge two types into a new type. Keys of the second type overrides keys of the first type.
 
+This is different from the TypeScript `&` (intersection) operator. With `&`, conflicting property types are intersected, which often results in `never`. For example, `{a: string} & {a: number}` makes `a` become `string & number`, which resolves to `never`. With `Merge`, the second type's keys cleanly override the first, so `Merge<{a: string}, {a: number}>` gives `{a: number}` as expected. `Merge` also produces a flattened type (via `Simplify`), making it more readable in IDE tooltips compared to `A & B`.
+
+@example
+```
+import type {Merge} from 'type-fest';
+
+type Foo = {
+	a: string;
+	b: number;
+};
+
+type Bar = {
+	a: number; // Conflicts with Foo['a']
+	c: boolean;
+};
+
+// With `&`, `a` becomes `string & number` which is `never`. Not what you want.
+type WithIntersection = (Foo & Bar)['a'];
+//=> never
+
+// With `Merge`, `a` is cleanly overridden to `number`.
+type WithMerge = Merge<Foo, Bar>['a'];
+//=> number
+```
+
 @example
 ```
 import type {Merge} from 'type-fest';

package/source/multidimensional-array.d.ts

@@ -4,7 +4,7 @@ import type {IsEqual} from './is-equal.d.ts';
 type Recursive<T> = Array<Recursive<T>>;
 
 /**
-Creates a type that represents a multidimensional array of the given type and dimension.
+Create a type that represents a multidimensional array of the given type and dimension.
 
 Use-cases:
 - Return a n-dimensional array from functions.

package/source/multidimensional-readonly-array.d.ts

@@ -4,7 +4,7 @@ import type {IsEqual} from './is-equal.d.ts';
 type Recursive<T> = ReadonlyArray<Recursive<T>>;
 
 /**
-Creates a type that represents a multidimensional readonly array that of the given type and dimension.
+Create a type that represents a multidimensional readonly array of the given type and dimension.
 
 Use-cases:
 - Return a n-dimensional array from functions.