@depup/type-fest 5.4.4-depup.0

package/source/is-literal.d.ts

@@ -0,0 +1,315 @@
+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 {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>;
+
+/**
+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';
+
+type A = IsLiteral<1>;
+//=> true
+
+type B = IsLiteral<number>;
+//=> false
+
+type C = IsLiteral<1n>;
+//=> true
+
+type D = IsLiteral<bigint>;
+//=> false
+
+type E = IsLiteral<'type-fest'>;
+//=> true
+
+type F = IsLiteral<string>;
+//=> false
+
+type G = IsLiteral<`on${string}`>;
+//=> false
+
+declare const symbolLiteral: unique symbol;
+type H = IsLiteral<typeof symbolLiteral>;
+//=> true
+
+type I = IsLiteral<symbol>;
+//=> false
+
+type J = IsLiteral<true>;
+//=> true
+
+type K = IsLiteral<boolean>;
+//=> false
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsLiteral<T> =
+	IsPrimitive<T> extends true
+		? IsNotFalse<IsLiteralUnion<T>>
+		: false;
+
+export {};

package/source/is-lowercase.d.ts

@@ -0,0 +1,38 @@
+import type {AllExtend} from './all-extend.d.ts';
+
+/**
+Returns a boolean for whether the given string literal is lowercase.
+
+@example
+```
+import type {IsLowercase} from 'type-fest';
+
+type A = IsLowercase<'abc'>;
+//=> true
+
+type B = IsLowercase<'Abc'>;
+//=> false
+
+type C = IsLowercase<string>;
+//=> boolean
+```
+*/
+export type IsLowercase<S extends string> = AllExtend<_IsLowercase<S>, true>;
+
+/**
+Loops through each part in the string and returns a boolean array indicating whether each part is lowercase.
+*/
+type _IsLowercase<S extends string, Accumulator extends boolean[] = []> = S extends `${infer First}${infer Rest}`
+	? _IsLowercase<Rest, [...Accumulator, IsLowercaseHelper<First>]>
+	: [...Accumulator, IsLowercaseHelper<S>];
+
+/**
+Returns a boolean for whether an individual part of the string is lowercase.
+*/
+type IsLowercaseHelper<S extends string> = S extends Lowercase<string>
+	? true
+	: S extends Uppercase<string> | Capitalize<string> | `${string}${Uppercase<string>}${string}`
+		? false
+		: boolean;
+
+export {};

package/source/is-never.d.ts

@@ -0,0 +1,56 @@
+/**
+Returns a boolean for whether the given type is `never`.
+
+@link https://github.com/microsoft/TypeScript/issues/31751#issuecomment-498526919
+@link https://stackoverflow.com/a/53984913/10292952
+@link https://www.zhenghao.io/posts/ts-never
+
+Useful in type utilities, such as checking if something does not occur.
+
+@example
+```
+import type {IsNever, And} from 'type-fest';
+
+type A = IsNever<never>;
+//=> true
+
+type B = IsNever<any>;
+//=> false
+
+type C = IsNever<unknown>;
+//=> false
+
+type D = IsNever<never[]>;
+//=> false
+
+type E = IsNever<object>;
+//=> false
+
+type F = IsNever<string>;
+//=> false
+```
+
+@example
+```
+import type {IsNever} from 'type-fest';
+
+type IsTrue<T> = T extends true ? true : false;
+
+// When a distributive conditional is instantiated with `never`, the entire conditional results in `never`.
+type A = IsTrue<never>;
+//=> never
+
+// If you don't want that behaviour, you can explicitly add an `IsNever` check before the distributive conditional.
+type IsTrueFixed<T> =
+	IsNever<T> extends true ? false : T extends true ? true : false;
+
+type B = IsTrueFixed<never>;
+//=> false
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsNever<T> = [T] extends [never] ? true : false;
+
+export {};

package/source/is-null.d.ts

@@ -0,0 +1,22 @@
+/**
+Returns a boolean for whether the given type is `null`.
+
+@example
+```
+import type {IsNull} from 'type-fest';
+
+type NonNullFallback<T, Fallback> = IsNull<T> extends true ? Fallback : T;
+
+type Example1 = NonNullFallback<null, string>;
+//=> string
+
+type Example2 = NonNullFallback<number, string>;
+//=> number
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsNull<T> = [T] extends [null] ? true : false;
+
+export {};

package/source/is-nullable.d.ts

@@ -0,0 +1,30 @@
+import type {IsAny} from './is-any.d.ts';
+
+/**
+Returns a boolean for whether the given type includes `null`.
+
+Note: The built-in `NonNullable` type removes both `null` and `undefined`, which is not accurate for the name.
+
+@example
+```ts
+import type {IsNullable} from 'type-fest';
+
+type A = IsNullable<string>;
+//=> false
+
+type B = IsNullable<string | null>;
+//=> true
+
+type C = IsNullable<string | undefined>;
+//=> false
+
+type D = IsNullable<string | null | undefined>;
+//=> true
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsNullable<T> = IsAny<T> extends true ? true : Extract<T, null> extends never ? false : true;
+
+export {};

package/source/is-optional-key-of.d.ts

@@ -0,0 +1,51 @@
+import type {IsAny} from './is-any.d.ts';
+
+/**
+Returns a boolean for whether the given key is an optional key of type.
+
+This is useful when writing utility types or schema validators that need to differentiate `optional` keys.
+
+@example
+```
+import type {IsOptionalKeyOf} from 'type-fest';
+
+type User = {
+	name: string;
+	surname: string;
+
+	luckyNumber?: number;
+};
+
+type Admin = {
+	name: string;
+	surname?: string;
+};
+
+type T1 = IsOptionalKeyOf<User, 'luckyNumber'>;
+//=> true
+
+type T2 = IsOptionalKeyOf<User, 'name'>;
+//=> false
+
+type T3 = IsOptionalKeyOf<User, 'name' | 'luckyNumber'>;
+//=> boolean
+
+type T4 = IsOptionalKeyOf<User | Admin, 'name'>;
+//=> false
+
+type T5 = IsOptionalKeyOf<User | Admin, 'surname'>;
+//=> boolean
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsOptionalKeyOf<Type extends object, Key extends keyof Type> =
+	IsAny<Type | Key> extends true ? never
+		: Key extends keyof Type
+			? Type extends Record<Key, Type[Key]>
+				? false
+				: true
+			: false;
+
+export {};

package/source/is-optional.d.ts

@@ -0,0 +1,28 @@
+import type {IsAny} from './is-any.d.ts';
+
+/**
+Returns a boolean for whether the given type includes `undefined`.
+
+@example
+```ts
+import type {IsOptional} from 'type-fest';
+
+type A = IsOptional<string>;
+//=> false
+
+type B = IsOptional<string | undefined>;
+//=> true
+
+type C = IsOptional<string | null>;
+//=> false
+
+type D = IsOptional<string | null | undefined>;
+//=> true
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsOptional<T> = IsAny<T> extends true ? true : Extract<T, undefined> extends never ? false : true;
+
+export {};

package/source/is-readonly-key-of.d.ts

@@ -0,0 +1,55 @@
+import type {IsEqual} from './is-equal.d.ts';
+import type {IsAny} from './is-any.d.ts';
+
+/**
+Returns a boolean for whether the given key is a readonly key of type.
+
+This is useful when writing utility types or schema validators that need to differentiate `readonly` keys.
+
+@example
+```
+import type {IsReadonlyKeyOf} from 'type-fest';
+
+type User = {
+	name: string;
+	surname: string;
+
+	readonly id: number;
+};
+
+type Admin = {
+	name: string;
+	id: string;
+};
+
+type T1 = IsReadonlyKeyOf<User, 'id'>;
+//=> true
+
+type T2 = IsReadonlyKeyOf<User, 'name'>;
+//=> false
+
+type T3 = IsReadonlyKeyOf<User, 'name' | 'id'>;
+//=> boolean
+
+type T4 = IsReadonlyKeyOf<User | Admin, 'name'>;
+//=> false
+
+type T5 = IsReadonlyKeyOf<User | Admin, 'id'>;
+//=> boolean
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsReadonlyKeyOf<Type extends object, Key extends keyof Type> =
+	IsAny<Type | Key> extends true ? never
+		: Key extends unknown // For distributing `Key`
+			? Type extends unknown // For distributing `Type`
+				? IsEqual<
+					{[K in Key]: Type[Key]},
+					{readonly [K in Key]: Type[Key]}
+				>
+				: never // Should never happen
+			: never; // Should never happen
+
+export {};

package/source/is-required-key-of.d.ts

@@ -0,0 +1,51 @@
+import type {IsOptionalKeyOf} from './is-optional-key-of.d.ts';
+import type {Not} from './internal/type.d.ts';
+import type {IsAny} from './is-any.d.ts';
+
+/**
+Returns a boolean for whether the given key is a required key of type.
+
+This is useful when writing utility types or schema validators that need to differentiate `required` keys.
+
+@example
+```
+import type {IsRequiredKeyOf} from 'type-fest';
+
+type User = {
+	name: string;
+	surname: string;
+
+	luckyNumber?: number;
+};
+
+type Admin = {
+	name: string;
+	surname?: string;
+};
+
+type T1 = IsRequiredKeyOf<User, 'name'>;
+//=> true
+
+type T2 = IsRequiredKeyOf<User, 'luckyNumber'>;
+//=> false
+
+type T3 = IsRequiredKeyOf<User, 'name' | 'luckyNumber'>;
+//=> boolean
+
+type T4 = IsRequiredKeyOf<User | Admin, 'name'>;
+//=> true
+
+type T5 = IsRequiredKeyOf<User | Admin, 'surname'>;
+//=> boolean
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsRequiredKeyOf<Type extends object, Key extends keyof Type> =
+	IsAny<Type | Key> extends true ? never
+		: Key extends keyof Type
+			? Not<IsOptionalKeyOf<Type, Key>>
+			: false;
+
+export {};