@depup/type-fest 5.4.4-depup.0

package/source/internal/object.d.ts

@@ -0,0 +1,292 @@
+import type {Simplify} from '../simplify.d.ts';
+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 {FilterDefinedKeys, FilterOptionalKeys} from './keys.d.ts';
+import type {MapsSetsOrArrays, NonRecursiveType} from './type.d.ts';
+import type {StringToNumber, ToString} from './string.d.ts';
+
+/**
+Create an object type with the given key `<Key>` and value `<Value>`.
+
+It will copy the prefix and optional status of the same key from the given object `CopiedFrom` into the result.
+
+@example
+```
+type A = BuildObject<'a', string>;
+//=> {a: string}
+
+// Copy `readonly` and `?` from the key `a` of `{readonly a?: any}`
+type B = BuildObject<'a', string, {readonly a?: any}>;
+//=> {readonly a?: string}
+```
+*/
+export type BuildObject<Key extends PropertyKey, Value, CopiedFrom extends object = {}> =
+	Key extends keyof CopiedFrom
+		? Pick<{[_ in keyof CopiedFrom]: Value}, Key>
+		: Key extends `${infer NumberKey extends number}`
+			? NumberKey extends keyof CopiedFrom
+				? Pick<{[_ in keyof CopiedFrom]: Value}, NumberKey>
+				: {[_ in Key]: Value}
+			: {[_ in Key]: Value};
+
+/**
+Returns a boolean for whether the given type is a plain key-value object.
+*/
+export type IsPlainObject<T> =
+	IsNever<T> extends true
+		? false
+		: T extends NonRecursiveType | MapsSetsOrArrays
+			? false
+			: T extends object
+				? true
+				: false;
+
+/**
+Extract the object field type if T is an object and K is a key of T, return `never` otherwise.
+
+It creates a type-safe way to access the member type of `unknown` type.
+*/
+export type ObjectValue<T, K> =
+	K extends keyof T
+		? T[K]
+		: ToString<K> extends keyof T
+			? T[ToString<K>]
+			: K extends `${infer NumberK extends number}`
+				? NumberK extends keyof T
+					? T[NumberK]
+					: never
+				: never;
+
+/**
+For an object T, if it has any properties that are a union with `undefined`, make those into optional properties instead.
+
+@example
+```
+type User = {
+	firstName: string;
+	lastName: string | undefined;
+};
+
+type OptionalizedUser = UndefinedToOptional<User>;
+//=> {
+// 	firstName: string;
+// 	lastName?: string;
+// }
+```
+*/
+export type UndefinedToOptional<T extends object> = Simplify<
+	{
+	// Property is not a union with `undefined`, keep it as-is.
+		[Key in keyof Pick<T, FilterDefinedKeys<T>>]: T[Key];
+	} & {
+	// Property _is_ a union with defined value. Set as optional (via `?`) and remove `undefined` from the union.
+		[Key in keyof Pick<T, FilterOptionalKeys<T>>]?: Exclude<T[Key], undefined>;
+	}
+>;
+
+/**
+Works similar to the built-in `Pick` utility type, except for the following differences:
+- Distributes over union types and allows picking keys from any member of the union type.
+- Primitives types are returned as-is.
+- Picks all keys if `Keys` is `any`.
+- Doesn't pick `number` from a `string` index signature.
+
+@example
+```
+type ImageUpload = {
+	url: string;
+	size: number;
+	thumbnailUrl: string;
+};
+
+type VideoUpload = {
+	url: string;
+	duration: number;
+	encodingFormat: string;
+};
+
+// Distributes over union types and allows picking keys from any member of the union type
+type MediaDisplay = HomomorphicPick<ImageUpload | VideoUpload, "url" | "size" | "duration">;
+//=> {url: string; size: number} | {url: string; duration: number}
+
+// Primitive types are returned as-is
+type Primitive = HomomorphicPick<string | number, 'toUpperCase' | 'toString'>;
+//=> string | number
+
+// Picks all keys if `Keys` is `any`
+type Any = HomomorphicPick<{a: 1; b: 2} | {c: 3}, any>;
+//=> {a: 1; b: 2} | {c: 3}
+
+// Doesn't pick `number` from a `string` index signature
+type IndexSignature = HomomorphicPick<{[k: string]: unknown}, number>;
+//=> {}
+*/
+export type HomomorphicPick<T, Keys extends KeysOfUnion<T>> = {
+	[P in keyof T as Extract<P, Keys>]: T[P]
+};
+
+/**
+Extract all possible values for a given key from a union of object types.
+
+@example
+```
+type Statuses = ValueOfUnion<{id: 1; status: 'open'} | {id: 2; status: 'closed'}, 'status'>;
+//=> "open" | "closed"
+```
+*/
+export type ValueOfUnion<Union, Key extends KeysOfUnion<Union>> =
+	Union extends unknown ? Key extends keyof Union ? Union[Key] : never : never;
+
+/**
+Extract all readonly keys from a union of object types.
+
+@example
+```
+type User = {
+	readonly id: string;
+	name: string;
+};
+
+type Post = {
+	readonly id: string;
+	readonly author: string;
+	body: string;
+};
+
+type ReadonlyKeys = ReadonlyKeysOfUnion<User | Post>;
+//=> "id" | "author"
+```
+*/
+export type ReadonlyKeysOfUnion<Union> = Union extends unknown ? keyof {
+	[Key in keyof Union as IsEqual<{[K in Key]: Union[Key]}, {readonly [K in Key]: Union[Key]}> extends true ? Key : never]: never
+} : never;
+
+/**
+Merges user specified options with default options.
+
+@example
+```
+type PathsOptions = {maxRecursionDepth?: number; leavesOnly?: boolean};
+type DefaultPathsOptions = {maxRecursionDepth: 10; leavesOnly: false};
+type SpecifiedOptions = {leavesOnly: true};
+
+type Result = ApplyDefaultOptions<PathsOptions, DefaultPathsOptions, SpecifiedOptions>;
+//=> {maxRecursionDepth: 10; leavesOnly: true}
+```
+
+@example
+```
+// Complains if default values are not provided for optional options
+
+type PathsOptions = {maxRecursionDepth?: number; leavesOnly?: boolean};
+type DefaultPathsOptions = {maxRecursionDepth: 10};
+type SpecifiedOptions = {};
+
+type Result = ApplyDefaultOptions<PathsOptions, DefaultPathsOptions, SpecifiedOptions>;
+//                                              ~~~~~~~~~~~~~~~~~~~
+// Property 'leavesOnly' is missing in type 'DefaultPathsOptions' but required in type '{ maxRecursionDepth: number; leavesOnly: boolean; }'.
+```
+
+@example
+```
+// Complains if an option's default type does not conform to the expected type
+
+type PathsOptions = {maxRecursionDepth?: number; leavesOnly?: boolean};
+type DefaultPathsOptions = {maxRecursionDepth: 10; leavesOnly: 'no'};
+type SpecifiedOptions = {};
+
+type Result = ApplyDefaultOptions<PathsOptions, DefaultPathsOptions, SpecifiedOptions>;
+//                                              ~~~~~~~~~~~~~~~~~~~
+// Types of property 'leavesOnly' are incompatible. Type 'string' is not assignable to type 'boolean'.
+```
+
+@example
+```
+// Complains if an option's specified type does not conform to the expected type
+
+type PathsOptions = {maxRecursionDepth?: number; leavesOnly?: boolean};
+type DefaultPathsOptions = {maxRecursionDepth: 10; leavesOnly: false};
+type SpecifiedOptions = {leavesOnly: 'yes'};
+
+type Result = ApplyDefaultOptions<PathsOptions, DefaultPathsOptions, SpecifiedOptions>;
+//                                                                   ~~~~~~~~~~~~~~~~
+// Types of property 'leavesOnly' are incompatible. Type 'string' is not assignable to type 'boolean'.
+```
+*/
+export type ApplyDefaultOptions<
+	Options extends object,
+	Defaults extends Simplify<Omit<Required<Options>, RequiredKeysOf<Options>> & Partial<Record<RequiredKeysOf<Options>, never>>>,
+	SpecifiedOptions extends Options,
+> =
+	If<IsAny<SpecifiedOptions>, Defaults,
+		If<IsNever<SpecifiedOptions>, Defaults,
+			Simplify<Merge<Defaults, {
+				[Key in keyof SpecifiedOptions
+				as Key extends OptionalKeysOf<Options> ? undefined extends SpecifiedOptions[Key] ? never : Key : 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`.
+
+Note: This doesn't collapse literals within tagged types. For example, `CollapseLiterals<Tagged<'foo' | (string & {}), 'Tag'>>` returns `("foo" & Tag<"Tag", never>) | (string & Tag<"Tag", never>)` and not `string & Tag<"Tag", never>`.
+
+Use-case: For collapsing unions created using {@link LiteralUnion}.
+
+@example
+```
+import type {LiteralUnion} from 'type-fest';
+
+type A = CollapseLiterals<'foo' | 'bar' | (string & {})>;
+//=> string
+
+type B = CollapseLiterals<LiteralUnion<1 | 2 | 3, number>>;
+//=> number
+
+type C = CollapseLiterals<LiteralUnion<'onClick' | 'onChange', `on${string}`>>;
+//=> `on${string}`
+
+type D = CollapseLiterals<'click' | 'change' | (`on${string}` & {})>;
+//=> 'click' | 'change' | `on${string}`
+
+type E = CollapseLiterals<LiteralUnion<'foo' | 'bar', string> | null | undefined>;
+//=> string | null | undefined
+```
+*/
+export type CollapseLiterals<T> = {} extends T
+	? T
+	: T extends infer U & {}
+		? U
+		: T;
+
+/**
+Normalize keys by including string and number representations wherever applicable.
+
+@example
+```ts
+type A = NormalizedKeys<0 | '1'>;
+//=> 0 | '0' | 1 | '1'
+
+type B = NormalizedKeys<string>;
+//=> string | number
+
+type C = NormalizedKeys<number>;
+//=> number | `${number}`
+
+type D = NormalizedKeys<symbol | 'foo'>;
+//=> symbol | 'foo'
+```
+*/
+export type NormalizedKeys<Keys extends PropertyKey> =
+	| Keys
+	| (string extends Keys ? number : never)
+	| StringToNumber<Keys & string>
+	| ToString<Keys & number>;
+
+export {};

package/source/internal/string.d.ts

@@ -0,0 +1,202 @@
+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 {Whitespace} from './characters.d.ts';
+
+/**
+Return a string representation of the given string or number.
+
+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`.
+
+@example
+```
+type A = StartsWith<'abcde', 'abc'>;
+//=> true
+
+type B = StartsWith<'abcde', 'bc'>;
+//=> false
+
+type C = StartsWith<string, 'bc'>;
+//=> never
+
+type D = StartsWith<'abcde', string>;
+//=> never
+```
+
+@category String
+@category Template literal
+*/
+export type StartsWith<S extends string, SearchString extends string> = string extends S | SearchString
+	? never
+	: S extends `${SearchString}${infer T}`
+		? 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.
+*/
+export type IsWhitespace<T extends string> = T extends Whitespace
+	? true
+	: T extends `${Whitespace}${infer Rest}`
+		? IsWhitespace<Rest>
+		: false;
+
+/**
+Returns a boolean for whether the string is numeric.
+
+This type is a workaround for [Microsoft/TypeScript#46109](https://github.com/microsoft/TypeScript/issues/46109#issuecomment-930307987).
+*/
+export type IsNumeric<T extends string> = T extends `${number}`
+	? Trim<T> extends T
+		? true
+		: false
+	: false;
+
+/**
+Returns a boolean for whether `A` represents a number greater than `B`, where `A` and `B` are both numeric strings and have the same length.
+
+@example
+```
+type A = SameLengthPositiveNumericStringGt<'50', '10'>;
+//=> true
+
+type B = SameLengthPositiveNumericStringGt<'10', '10'>;
+//=> false
+```
+*/
+type SameLengthPositiveNumericStringGt<A extends string, B extends string> = A extends `${infer FirstA}${infer RestA}`
+	? B extends `${infer FirstB}${infer RestB}`
+		? FirstA extends FirstB
+			? SameLengthPositiveNumericStringGt<RestA, RestB>
+			: PositiveNumericCharacterGt<FirstA, FirstB>
+		: never
+	: false;
+
+type NumericString = '0123456789';
+
+/**
+Returns a boolean for whether `A` is greater than `B`, where `A` and `B` are both positive numeric strings.
+
+@example
+```
+type A = PositiveNumericStringGt<'500', '1'>;
+//=> true
+
+type B = PositiveNumericStringGt<'1', '1'>;
+//=> false
+
+type C = PositiveNumericStringGt<'1', '500'>;
+//=> false
+```
+*/
+export type PositiveNumericStringGt<A extends string, B extends string> = A extends B
+	? false
+	: [TupleOf<StringLength<A>, 0>, TupleOf<StringLength<B>, 0>] extends infer R extends [readonly unknown[], readonly unknown[]]
+		? R[0] extends [...R[1], ...infer Remain extends readonly unknown[]]
+			? 0 extends Remain['length']
+				? SameLengthPositiveNumericStringGt<A, B>
+				: true
+			: false
+		: never;
+
+/**
+Returns a boolean for whether `A` represents a number greater than `B`, where `A` and `B` are both positive numeric characters.
+
+@example
+```
+type A = PositiveNumericCharacterGt<'5', '1'>;
+//=> true
+
+type B = PositiveNumericCharacterGt<'1', '1'>;
+//=> false
+```
+*/
+type PositiveNumericCharacterGt<A extends string, B extends string> = NumericString extends `${infer HeadA}${A}${infer TailA}`
+	? NumericString extends `${infer HeadB}${B}${infer TailB}`
+		? HeadA extends `${HeadB}${infer _}${infer __}`
+			? true
+			: false
+		: never
+	: never;
+
+export {};

package/source/internal/tuple.d.ts

@@ -0,0 +1,79 @@
+import type {GreaterThan} from '../greater-than.d.ts';
+import type {LessThan} from '../less-than.d.ts';
+import type {NegativeInfinity, PositiveInfinity} from '../numeric.d.ts';
+import type {UnknownArray} from '../unknown-array.d.ts';
+
+/**
+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] | number[]>;
+//=> 1 | 3
+```
+*/
+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))
+	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
+
+/**
+Returns the maximum value from a tuple of integers.
+
+Note:
+- Float numbers are not supported.
+
+@example
+```
+type A = TupleMax<[1, 2, 5, 3]>;
+//=> 5
+
+type B = TupleMax<[1, 2, 5, 3, 99, -1]>;
+//=> 99
+```
+*/
+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[]]
+		? 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
+```
+type A = TupleMin<[1, 2, 5, 3]>;
+//=> 1
+
+type B = TupleMin<[1, 2, 5, 3, -5]>;
+//=> -5
+```
+*/
+export 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;
+
+export {};