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

package/source/internal/object.d.ts

@@ -3,13 +3,14 @@ import type {IsEqual} from '../is-equal.d.ts';
 import type {KeysOfUnion} from '../keys-of-union.d.ts';
 import type {RequiredKeysOf} from '../required-keys-of.d.ts';
 import type {Merge} from '../merge.d.ts';
-import type {OptionalKeysOf} from '../optional-keys-of.d.ts';
 import type {IsAny} from '../is-any.d.ts';
 import type {If} from '../if.d.ts';
 import type {IsNever} from '../is-never.d.ts';
+import type {StringToNumber} from '../string-to-number.d.ts';
+import type {Primitive} from '../primitive.d.ts';
 import type {FilterDefinedKeys, FilterOptionalKeys} from './keys.d.ts';
-import type {MapsSetsOrArrays, NonRecursiveType} from './type.d.ts';
-import type {StringToNumber, ToString} from './string.d.ts';
+import type {IfNotAnyOrNever, MapsSetsOrArrays, NonRecursiveType} from './type.d.ts';
+import type {ToString} from './string.d.ts';
 
 /**
 Create an object type with the given key `<Key>` and value `<Value>`.
@@ -223,14 +224,23 @@ export type ApplyDefaultOptions<
 	Options extends object,
 	Defaults extends Simplify<Omit<Required<Options>, RequiredKeysOf<Options>> & Partial<Record<RequiredKeysOf<Options>, never>>>,
 	SpecifiedOptions extends Options,
+> =
+	_ApplyDefaultOptions<Options, Defaults, SpecifiedOptions> extends infer Result extends Required<Options> // `extends Required<Options>` ensures that `ApplyDefaultOptions<SomeOption, ...>` is always assignable to `Required<SomeOption>`
+		? Result
+		: never;
+
+type _ApplyDefaultOptions<
+	Options,
+	Defaults,
+	SpecifiedOptions,
 > =
 	If<IsAny<SpecifiedOptions>, Defaults,
 		If<IsNever<SpecifiedOptions>, Defaults,
-			Simplify<Merge<Defaults, {
+			Merge<Defaults, {
 				[Key in keyof SpecifiedOptions
-				as Key extends OptionalKeysOf<Options> ? undefined extends SpecifiedOptions[Key] ? never : Key : Key
+				as undefined extends Required<Options>[Key & keyof Options] ? Key : undefined extends SpecifiedOptions[Key] ? never : Key
 				]: SpecifiedOptions[Key]
-			}> & Required<Options>>>>; // `& Required<Options>` ensures that `ApplyDefaultOptions<SomeOption, ...>` is always assignable to `Required<SomeOption>`
+			}>>>;
 
 /**
 Collapses literal types in a union into their corresponding primitive types, when possible. For example, `CollapseLiterals<'foo' | 'bar' | (string & {})>` returns `string`.
@@ -265,6 +275,34 @@ export type CollapseLiterals<T> = {} extends T
 		? U
 		: T;
 
+/**
+Returns the base type of a branded type.
+
+@example
+```
+type Brand = {readonly __brand: unique symbol};
+
+type A = UnwrapBrand<string & Brand>;
+//=> string
+
+type B = UnwrapBrand<number & Brand>;
+//=> number
+
+type C = UnwrapBrand<PropertyKey & Brand>;
+//=> PropertyKey
+
+type D = UnwrapBrand<(1 | 200n | 'foo' | 'bar') & Brand>;
+//=> 1 | 200n | 'foo' | 'bar'
+```
+*/
+export type UnwrapBrand<T> = IfNotAnyOrNever<T, {ifNot: _UnwrapBrand<T, Primitive>}>;
+
+type _UnwrapBrand<T, Base> = T extends Primitive
+	? T extends infer U & Pick<T, Exclude<keyof T, KeysOfUnion<Base>>>
+		? U
+		: T
+	: T;
+
 /**
 Normalize keys by including string and number representations wherever applicable.
 

package/source/internal/string.d.ts

@@ -1,6 +1,6 @@
 import type {TupleOf} from '../tuple-of.d.ts';
-import type {NegativeInfinity, PositiveInfinity} from '../numeric.d.ts';
 import type {Trim} from '../trim.d.ts';
+import type {StringLength} from '../string-length.d.ts';
 import type {Whitespace} from './characters.d.ts';
 
 /**
@@ -10,42 +10,6 @@ Note: This type is not the return type of the `.toString()` function.
 */
 export type ToString<T> = T extends string | number ? `${T}` : never;
 
-/**
-Converts a numeric string to a number.
-
-@example
-```
-type PositiveInt = StringToNumber<'1234'>;
-//=> 1234
-
-type NegativeInt = StringToNumber<'-1234'>;
-//=> -1234
-
-type PositiveFloat = StringToNumber<'1234.56'>;
-//=> 1234.56
-
-type NegativeFloat = StringToNumber<'-1234.56'>;
-//=> -1234.56
-
-type PositiveInfinity = StringToNumber<'Infinity'>;
-//=> Infinity
-
-type NegativeInfinity = StringToNumber<'-Infinity'>;
-//=> -Infinity
-```
-
-@category String
-@category Numeric
-@category Template literal
-*/
-export type StringToNumber<S extends string> = S extends `${infer N extends number}`
-	? N
-	: S extends 'Infinity'
-		? PositiveInfinity
-		: S extends '-Infinity'
-			? NegativeInfinity
-			: never;
-
 /**
 Returns a boolean for whether the given string `S` starts with the given string `SearchString`.
 
@@ -73,45 +37,6 @@ export type StartsWith<S extends string, SearchString extends string> = string e
 		? true
 		: false;
 
-/**
-Returns an array of the characters of the string.
-
-@example
-```
-type A = StringToArray<'abcde'>;
-//=> ['a', 'b', 'c', 'd', 'e']
-
-type B = StringToArray<string>;
-//=> never
-```
-
-@category String
-*/
-export type StringToArray<S extends string, Result extends string[] = []> = string extends S
-	? never
-	: S extends `${infer F}${infer R}`
-		? StringToArray<R, [...Result, F]>
-		: Result;
-
-/**
-Returns the length of the given string.
-
-@example
-```
-type A = StringLength<'abcde'>;
-//=> 5
-
-type B = StringLength<string>;
-//=> never
-```
-
-@category String
-@category Template literal
-*/
-export type StringLength<S extends string> = string extends S
-	? never
-	: StringToArray<S>['length'];
-
 /**
 Returns a boolean for whether a string is whitespace.
 */

package/source/internal/tuple.d.ts

@@ -23,7 +23,7 @@ type Union = TupleLength<[] | [1, 2, 3] | number[]>;
 */
 export 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))
+	// a [distributive conditional type](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>`
@@ -46,8 +46,8 @@ type B = TupleMax<[1, 2, 5, 3, 99, -1]>;
 ```
 */
 export type TupleMax<A extends number[], Result extends number = NegativeInfinity> = number extends A[number]
-	? never :
-	A extends [infer F extends number, ...infer R extends number[]]
+	? never
+	: A extends [infer F extends number, ...infer R extends number[]]
 		? GreaterThan<F, Result> extends true
 			? TupleMax<R, F>
 			: TupleMax<R, Result>

package/source/internal/type.d.ts

@@ -1,4 +1,3 @@
-import type {If} from '../if.d.ts';
 import type {IsAny} from '../is-any.d.ts';
 import type {IsNever} from '../is-never.d.ts';
 import type {Primitive} from '../primitive.d.ts';
@@ -90,16 +89,16 @@ An if-else-like type that resolves depending on whether the given type is `any`
 
 @example
 ```
-// When `T` is a NOT `any` or `never` (like `string`) => Returns `IfNotAnyOrNever` branch
-type A = IfNotAnyOrNever<string, 'VALID', 'IS_ANY', 'IS_NEVER'>;
+// When `T` is neither `any` nor `never` (like `string`) => Returns `IfNot` branch
+type A = IfNotAnyOrNever<string, {ifNot: 'VALID'; ifAny: 'IS_ANY'; ifNever: 'IS_NEVER'}>;
 //=> 'VALID'
 
 // When `T` is `any` => Returns `IfAny` branch
-type B = IfNotAnyOrNever<any, 'VALID', 'IS_ANY', 'IS_NEVER'>;
+type B = IfNotAnyOrNever<any, {ifNot: 'VALID'; ifAny: 'IS_ANY'; ifNever: 'IS_NEVER'}>;
 //=> 'IS_ANY'
 
 // When `T` is `never` => Returns `IfNever` branch
-type C = IfNotAnyOrNever<never, 'VALID', 'IS_ANY', 'IS_NEVER'>;
+type C = IfNotAnyOrNever<never, {ifNot: 'VALID'; ifAny: 'IS_ANY'; ifNever: 'IS_NEVER'}>;
 //=> 'IS_NEVER'
 ```
 
@@ -112,7 +111,7 @@ import type {StringRepeat} from 'type-fest';
 type NineHundredNinetyNineSpaces = StringRepeat<' ', 999>;
 
 // The following implementation is not tail recursive
-type TrimLeft<S extends string> = IfNotAnyOrNever<S, S extends ` ${infer R}` ? TrimLeft<R> : S>;
+type TrimLeft<S extends string> = IfNotAnyOrNever<S, {ifNot: S extends ` ${infer R}` ? TrimLeft<R> : S}>;
 
 // Hence, instantiations with long strings will fail
 // @ts-expect-error
@@ -121,7 +120,7 @@ type T1 = TrimLeft<NineHundredNinetyNineSpaces>;
 // Error: Type instantiation is excessively deep and possibly infinite.
 
 // To fix this, move the recursion into a helper type
-type TrimLeftOptimised<S extends string> = IfNotAnyOrNever<S, _TrimLeftOptimised<S>>;
+type TrimLeftOptimised<S extends string> = IfNotAnyOrNever<S, {ifNot: _TrimLeftOptimised<S>}>;
 
 type _TrimLeftOptimised<S extends string> = S extends ` ${infer R}` ? _TrimLeftOptimised<R> : S;
 
@@ -129,8 +128,16 @@ type T2 = TrimLeftOptimised<NineHundredNinetyNineSpaces>;
 //=> ''
 ```
 */
-export type IfNotAnyOrNever<T, IfNotAnyOrNever, IfAny = any, IfNever = never> =
-	If<IsAny<T>, IfAny, If<IsNever<T>, IfNever, IfNotAnyOrNever>>;
+export type IfNotAnyOrNever<T, Cases extends {ifNot: unknown; ifAny?: unknown; ifNever?: unknown}> =
+	IsAny<T> extends true
+		? 'ifAny' extends keyof Cases
+			? Cases['ifAny']
+			: any
+		: IsNever<T> extends true
+			? 'ifNever' extends keyof Cases
+				? Cases['ifNever']
+				: never
+			: Cases['ifNot'];
 
 /**
 Returns a boolean for whether the given type is `any` or `never`.

package/source/is-boolean-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 `true` or `false` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
+
+@example
+```
+import type {IsBooleanLiteral} from 'type-fest';
+
+type A = IsBooleanLiteral<true>;
+//=> true
+
+type B = IsBooleanLiteral<false>;
+//=> true
+
+type C = IsBooleanLiteral<boolean>;
+//=> false
+
+type D = IsBooleanLiteral<true | false>;
+//=> false
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsBooleanLiteral<T> = IfNotAnyOrNever<T, {
+	ifNot: _IsBooleanLiteral<CollapseLiterals<UnwrapBrand<T>>>;
+	ifAny: false;
+	ifNever: false;
+}>;
+
+type _IsBooleanLiteral<T> = boolean extends T
+	? false
+	: T extends boolean
+		? true
+		: false;
+
+export {};

package/source/is-equal.d.ts

@@ -1,4 +1,3 @@
-import type {IsNever} from './is-never.d.ts';
 /**
 Returns a boolean for whether the two given types are equal.
 

package/source/is-integer.d.ts

@@ -47,14 +47,14 @@ type J = IsInteger<1e-7>;
 @category Numeric
 */
 export type IsInteger<T> =
-T extends bigint
-	? true
-	: T extends number
-		? number extends T
-			? false
-			: T extends PositiveInfinity | NegativeInfinity
+	T extends bigint
+		? true
+		: T extends number
+			? number extends T
 				? false
-				: Not<IsFloat<T>>
-		: false;
+				: T extends PositiveInfinity | NegativeInfinity
+					? false
+					: Not<IsFloat<T>>
+			: false;
 
 export {};

package/source/is-literal.d.ts

@@ -1,270 +1,14 @@
-import type {Primitive} from './primitive.d.ts';
-import type {_Numeric} from './numeric.d.ts';
-import type {CollapseLiterals, IfNotAnyOrNever, IsNotFalse, IsPrimitive} from './internal/index.d.ts';
+import type {IsStringLiteral} from './is-string-literal.d.ts';
+import type {IsNumericLiteral} from './is-numeric-literal.d.ts';
+import type {IsBooleanLiteral} from './is-boolean-literal.d.ts';
+import type {IsSymbolLiteral} from './is-symbol-literal.d.ts';
 import type {IsNever} from './is-never.d.ts';
-import type {TagContainer, UnwrapTagged} from './tagged.d.ts';
-
-/**
-Returns a boolean for whether the given type `T` is the specified `LiteralType`.
-
-@link https://stackoverflow.com/a/52806744/10292952
-
-@example
-```
-type A = LiteralCheck<1, number>;
-//=> true
-
-type B = LiteralCheck<number, number>;
-//=> false
-
-type C = LiteralCheck<1, string>;
-//=> false
-```
-*/
-type LiteralCheck<T, LiteralType extends Primitive> = (
-	IsNever<T> extends false // Must be wider than `never`
-		? [T] extends [LiteralType & infer U] // Remove any branding
-			? [U] extends [LiteralType] // Must be narrower than `LiteralType`
-				? [LiteralType] extends [U] // Cannot be wider than `LiteralType`
-					? false
-					: true
-				: false
-			: false
-		: false
-);
-
-/**
-Returns a boolean for whether the given type `T` is one of the specified literal types in `LiteralUnionType`.
-
-@example
-```
-type A = LiteralChecks<1, Numeric>;
-//=> true
-
-type B = LiteralChecks<1n, Numeric>;
-//=> true
-
-type C = LiteralChecks<bigint, Numeric>;
-//=> false
-```
-*/
-type LiteralChecks<T, LiteralUnionType> = (
-	// Conditional type to force union distribution.
-	// If `T` is none of the literal types in the union `LiteralUnionType`, then `LiteralCheck<T, LiteralType>` will evaluate to `false` for the whole union.
-	// If `T` is one of the literal types in the union, it will evaluate to `boolean` (i.e. `true | false`)
-	IsNotFalse<LiteralUnionType extends Primitive
-		? LiteralCheck<T, LiteralUnionType>
-		: never
-	>
-);
-
-/**
-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
-*/
-export type IsStringLiteral<S> = IfNotAnyOrNever<S,
-	_IsStringLiteral<CollapseLiterals<S extends TagContainer<any> ? UnwrapTagged<S> : S>>,
-	false, false>;
-
-export type _IsStringLiteral<S> =
-// 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`.
-S extends string
-	? {} extends Record<S, never>
-		? false
-		: true
-	: false;
-
-/**
-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).
-
-Useful for:
-	- providing strongly-typed functions when given literal arguments
-	- type utilities, such as when constructing parsers and ASTs
-
-@example
-```
-import type {IsNumericLiteral, IsStringLiteral} from 'type-fest';
-
-// https://github.com/inocan-group/inferred-types/blob/master/modules/types/src/boolean-logic/operators/EndsWith.ts
-type EndsWith<TValue, TEndsWith extends string> =
-	TValue extends string
-		? IsStringLiteral<TEndsWith> extends true
-			? IsStringLiteral<TValue> extends true
-				? TValue extends `${string}${TEndsWith}`
-					? true
-					: false
-				: boolean
-			: boolean
-		: TValue extends number
-			? IsNumericLiteral<TValue> extends true
-				? EndsWith<`${TValue}`, TEndsWith>
-				: false
-			: false;
-
-function endsWith<Input extends string | number, End extends string>(input: Input, end: End) {
-	return `${input}`.endsWith(end) as EndsWith<Input, End>;
-}
-
-endsWith('abc', 'c');
-//=> true
-
-endsWith(123_456, '456');
-//=> true
-
-const end = '123' as string;
-
-endsWith('abc123', end);
-//=> boolean
-```
-
-@category Type Guard
-@category Utilities
-*/
-export type IsNumericLiteral<T> = LiteralChecks<T, _Numeric>;
-
-/**
-Returns a boolean for whether the given type is a `true` or `false` [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
-
-Useful for:
-	- providing strongly-typed functions when given literal arguments
-	- type utilities, such as when constructing parsers and ASTs
-
-@example
-```
-import type {IsBooleanLiteral} from 'type-fest';
-
-const id = 123;
-
-type GetId<AsString extends boolean> =
-	IsBooleanLiteral<AsString> extends true
-		? AsString extends true
-			? `${typeof id}`
-			: typeof id
-		: number | string;
-
-function getId<AsString extends boolean = false>(options?: {asString: AsString}) {
-	return (options?.asString ? `${id}` : id) as GetId<AsString>;
-}
-
-const numberId = getId();
-//=> 123
-
-const stringId = getId({asString: true});
-//=> '123'
-
-declare const runtimeBoolean: boolean;
-const eitherId = getId({asString: runtimeBoolean});
-//=> string | number
-```
-
-@category Type Guard
-@category Utilities
-*/
-export type IsBooleanLiteral<T> = LiteralCheck<T, boolean>;
-
-/**
-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).
-
-Useful for:
-	- providing strongly-typed functions when given literal arguments
-	- type utilities, such as when constructing parsers and ASTs
-
-@example
-```
-import type {IsSymbolLiteral} from 'type-fest';
-
-type Get<Object_ extends Record<symbol, number>, Key extends keyof Object_> =
-	IsSymbolLiteral<Key> extends true
-		? Object_[Key]
-		: number;
-
-function get<Object_ extends Record<symbol, number>, Key extends keyof Object_>(o: Object_, key: Key) {
-	return o[key] as Get<Object_, Key>;
-}
-
-const symbolLiteral = Symbol('literal');
-let symbolValue = Symbol('value1');
-symbolValue = Symbol('value2');
-
-get({[symbolLiteral]: 1} as const, symbolLiteral);
-//=> 1
-
-get({[symbolValue]: 1} as const, symbolValue);
-//=> number
-```
-
-@category Type Guard
-@category Utilities
-*/
-export type IsSymbolLiteral<T> = LiteralCheck<T, symbol>;
-
-/** Helper type for `IsLiteral`. */
-type IsLiteralUnion<T> =
-	| IsStringLiteral<T>
-	| IsNumericLiteral<T>
-	| IsBooleanLiteral<T>
-	| IsSymbolLiteral<T>;
+import type {IfNotAnyOrNever} from './internal/type.d.ts';
+import type {CollapseLiterals, UnwrapBrand} from './internal/object.d.ts';
 
 /**
 Returns a boolean for whether the given type is a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types).
 
-Useful for:
-	- providing strongly-typed functions when given literal arguments
-	- type utilities, such as when constructing parsers and ASTs
-
 @example
 ```
 import type {IsLiteral} from 'type-fest';
@@ -300,16 +44,48 @@ type I = IsLiteral<symbol>;
 type J = IsLiteral<true>;
 //=> true
 
-type K = IsLiteral<boolean>;
+type K = IsLiteral<false>;
+//=> true
+
+type L = IsLiteral<boolean>;
 //=> false
+
+type M = IsLiteral<1 | 'foo' | false>;
+//=> true
+
+type N = IsLiteral<string | number | symbol>;
+//=> false
+
+type O = IsLiteral<1000n | string | true>;
+//=> boolean
 ```
 
 @category Type Guard
 @category Utilities
 */
-export type IsLiteral<T> =
-	IsPrimitive<T> extends true
-		? IsNotFalse<IsLiteralUnion<T>>
-		: false;
+export type IsLiteral<T> = IfNotAnyOrNever<T, {
+	ifNot: _IsLiteral<CollapseLiterals<UnwrapBrand<T>>>;
+	ifAny: false;
+	ifNever: false;
+}>;
+
+type _IsLiteral<T> =
+	| (Extract<T, boolean> extends infer Bools
+		// We can't instantiate `IsBooleanLiteral` with `never`,
+		// because that will add an extraneous `false` to the result if there are no booleans.
+		? IsNever<Bools> extends true
+			? never
+			: IsBooleanLiteral<Bools>
+		: never)
+	| (IsLiteralNonBools<Exclude<T, boolean>>);
+
+type IsLiteralNonBools<T> =
+	T extends number | bigint
+		? IsNumericLiteral<T>
+		: T extends string
+			? IsStringLiteral<T>
+			: T extends symbol
+				? IsSymbolLiteral<T>
+				: false;
 
 export {};