@depup/type-fest 5.4.4-depup.0

package/source/tuple-of.d.ts

@@ -0,0 +1,80 @@
+import type {If} from './if.d.ts';
+import type {IfNotAnyOrNever} from './internal/type.d.ts';
+import type {IsNegative} from './numeric.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+
+/**
+Create a tuple type of the specified length with elements of the specified type.
+
+@example
+```
+import type {TupleOf} from 'type-fest';
+
+type RGB = TupleOf<3, number>;
+//=> [number, number, number]
+
+type Line = TupleOf<2, {x: number; y: number}>;
+//=> [{x: number; y: number}, {x: number; y: number}]
+
+type TicTacToeBoard = TupleOf<3, TupleOf<3, 'X' | 'O' | null>>;
+//=> [['X' | 'O' | null, 'X' | 'O' | null, 'X' | 'O' | null], ['X' | 'O' | null, 'X' | 'O' | null, 'X' | 'O' | null], ['X' | 'O' | null, 'X' | 'O' | null, 'X' | 'O' | null]]
+```
+
+@example
+```
+import type {TupleOf} from 'type-fest';
+
+type Range<Start extends number, End extends number> = Exclude<keyof TupleOf<End>, keyof TupleOf<Start>>;
+
+type ZeroToFour = Range<0, 5>;
+//=> '0' | '1' | '2' | '3' | '4'
+
+type ThreeToEight = Range<3, 9>;
+//=> '5' | '3' | '4' | '6' | '7' | '8'
+```
+
+Note: If the specified length is the non-literal `number` type, the result will not be a tuple but a regular array.
+
+@example
+```
+import type {TupleOf} from 'type-fest';
+
+type StringArray = TupleOf<number, string>;
+//=> string[]
+```
+
+Note: If the type for elements is not specified, it will default to `unknown`.
+
+@example
+```
+import type {TupleOf} from 'type-fest';
+
+type UnknownTriplet = TupleOf<3>;
+//=> [unknown, unknown, unknown]
+```
+
+Note: If the specified length is negative, the result will be an empty tuple.
+
+@example
+```
+import type {TupleOf} from 'type-fest';
+
+type EmptyTuple = TupleOf<-3, string>;
+//=> []
+```
+
+Note: If you need a readonly tuple, simply wrap this type with `Readonly`, for example, to create `readonly [number, number, number]` use `Readonly<TupleOf<3, number>>`.
+
+@category Array
+*/
+export type TupleOf<Length extends number, Fill = unknown> = IfNotAnyOrNever<Length,
+	_TupleOf<If<IsNegative<Length>, 0, Length>, Fill, []>,
+	Fill[], []>;
+
+type _TupleOf<L extends number, Fill, Accumulator extends UnknownArray> = number extends L
+	? Fill[]
+	: L extends Accumulator['length']
+		? Accumulator
+		: _TupleOf<L, Fill, [...Accumulator, Fill]>;
+
+export {};

package/source/tuple-to-object.d.ts

@@ -0,0 +1,47 @@
+import type {IsTuple} from './is-tuple.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+import type {IsAny} from './is-any.d.ts';
+import type {If} from './if.d.ts';
+
+/**
+Transforms a tuple into an object, mapping each tuple index to its corresponding type as a key-value pair.
+
+Note: Tuple labels are [lost in the transformation process](https://stackoverflow.com/a/70398429/11719314). For example, `TupleToObject<[x: number, y: number]>` produces `{0: number; 1: number}`, and not `{x: number; y: number}`.
+
+@example
+```
+import type {TupleToObject} from 'type-fest';
+
+type Example1 = TupleToObject<[number, string, boolean]>;
+//=> {0: number; 1: string; 2: boolean}
+
+// Tuples with optional indices
+type Example2 = TupleToObject<[number, string?, boolean?]>;
+//=> {0: number; 1?: string; 2?: boolean}
+
+// Readonly tuples
+type Example3 = TupleToObject<readonly [number, string?]>;
+//=> {readonly 0: number; readonly 1?: string}
+
+// Non-tuple arrays get transformed into index signatures
+type Example4 = TupleToObject<string[]>;
+//=> {[x: number]: string}
+
+// Tuples with rest elements
+type Example5 = TupleToObject<[number, string, ...boolean[]]>;
+//=> {[x: number]: string | number | boolean; 0: number; 1: string}
+
+// Tuple labels are not preserved
+type Example6 = TupleToObject<[x: number, y: number]>;
+//=> {0: number; 1: number}
+```
+
+@category Array
+*/
+export type TupleToObject<TArray extends UnknownArray> = If<IsAny<TArray>, any, {
+	[
+	Key in keyof TArray as Key & (`${number}` | (IsTuple<TArray> extends true ? never : number))
+	]: TArray[Key];
+}>;
+
+export {};

package/source/tuple-to-union.d.ts

@@ -0,0 +1,54 @@
+/**
+Convert a tuple/array into a union type of its elements.
+
+This can be useful when you have a fixed set of allowed values and want a type defining only the allowed values, but do not want to repeat yourself.
+
+@example
+```
+import type {TupleToUnion} from 'type-fest';
+
+const destinations = ['a', 'b', 'c'] as const;
+
+type Destination = TupleToUnion<typeof destinations>;
+//=> 'a' | 'b' | 'c'
+
+function verifyDestination(destination: unknown): destination is Destination {
+	return destinations.includes(destination as any);
+}
+
+type RequestBody = {
+	deliverTo: Destination;
+};
+
+function verifyRequestBody(body: unknown): body is RequestBody {
+	const {deliverTo} = (body as any);
+	return typeof body === 'object' && body !== null && verifyDestination(deliverTo);
+}
+```
+
+Alternatively, you may use `typeof destinations[number]`. If `destinations` is a tuple, there is no difference. However if `destinations` is a string, the resulting type will the union of the characters in the string. Other types of `destinations` may result in a compile error. In comparison, TupleToUnion will return `never` if a tuple is not provided.
+
+@example
+```
+const destinations = ['a', 'b', 'c'] as const;
+
+type Destination = typeof destinations[number];
+//=> 'a' | 'b' | 'c'
+
+const erroringType = new Set(['a', 'b', 'c']);
+
+// @ts-expect-error
+type ErroringType = typeof erroringType[number];
+// Error: Type 'Set<string>' has no matching index signature for type 'number'. ts(2537)
+
+const numberBool: {[n: number]: boolean} = {1: true};
+
+type NumberBool = typeof numberBool[number];
+//=> boolean
+```
+
+@category Array
+*/
+export type TupleToUnion<ArrayType> = ArrayType extends readonly unknown[] ? ArrayType[number] : never;
+
+export {};

package/source/typed-array.d.ts

@@ -0,0 +1,19 @@
+/**
+Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
+
+@category Array
+*/
+export type TypedArray =
+	| Int8Array
+	| Uint8Array
+	| Uint8ClampedArray
+	| Int16Array
+	| Uint16Array
+	| Int32Array
+	| Uint32Array
+	| Float32Array
+	| Float64Array
+	| BigInt64Array
+	| BigUint64Array;
+
+export {};

package/source/undefined-on-partial-deep.d.ts

@@ -0,0 +1,83 @@
+import type {BuiltIns} from './internal/index.d.ts';
+
+/**
+Create a deep version of another type where all optional keys are set to also accept `undefined`.
+
+Note: This is only needed when the [`exactOptionalPropertyTypes`](https://www.typescriptlang.org/tsconfig#exactOptionalPropertyTypes) TSConfig setting is enabled.
+
+Use-cases:
+- When `exactOptionalPropertyTypes` is enabled, an object like `{a: undefined}` is not assignable to the type `{a?: number}`. You can use `UndefinedOnPartialDeep<{a?: number}>` to make it assignable.
+
+@example
+```
+import type {UndefinedOnPartialDeep} from 'type-fest';
+
+type Settings = {
+	optionA: string;
+	optionB?: number;
+	subOption: {
+		subOptionA: boolean;
+		subOptionB?: boolean;
+	};
+};
+
+const testSettingsA: Settings = {
+	optionA: 'foo',
+	optionB: undefined, // TypeScript error if `exactOptionalPropertyTypes` is true.
+	// @ts-expect-error
+	subOption: {
+		subOptionA: true,
+		subOptionB: undefined, // TypeScript error if `exactOptionalPropertyTypes` is true
+	},
+};
+
+const testSettingsB: UndefinedOnPartialDeep<Settings> = {
+	optionA: 'foo',
+	optionB: undefined, // `optionB` can be set to `undefined` now.
+	subOption: {
+		subOptionA: true,
+		subOptionB: undefined, // `subOptionB` can be set to `undefined` now.
+	},
+};
+```
+*/
+export type UndefinedOnPartialDeep<T> =
+	// Handle built-in type and function
+	T extends BuiltIns | Function
+		? T
+		// Handle tuple and array
+		: T extends readonly unknown[]
+			? UndefinedOnPartialList<T>
+			// Handle map and readonly map
+			: T extends Map<infer K, infer V>
+				? Map<K, UndefinedOnPartialDeep<V>>
+				: T extends ReadonlyMap<infer K, infer V>
+					? ReadonlyMap<K, UndefinedOnPartialDeep<V>>
+					// Handle set and readonly set
+					: T extends Set<infer K>
+						? Set<UndefinedOnPartialDeep<K>>
+						: T extends ReadonlySet<infer K>
+							? ReadonlySet<UndefinedOnPartialDeep<K>>
+							// Handle object
+							: T extends Record<any, any>
+								? {
+									[KeyType in keyof T]: undefined extends T[KeyType]
+										? UndefinedOnPartialDeep<T[KeyType]> | undefined
+										: UndefinedOnPartialDeep<T[KeyType]>
+								}
+								: T; // If T is not builtins / function / array / map / set / object, return T
+
+// Handle tuples and arrays
+type UndefinedOnPartialList<T extends readonly unknown[]> = T extends []
+	? []
+	: T extends [infer F, ...infer R]
+		? [UndefinedOnPartialDeep<F>, ...UndefinedOnPartialDeep<R>]
+		: T extends readonly [infer F, ...infer R]
+			? readonly [UndefinedOnPartialDeep<F>, ...UndefinedOnPartialDeep<R>]
+			: T extends Array<infer F>
+				? Array<UndefinedOnPartialDeep<F>>
+				: T extends ReadonlyArray<infer F>
+					? ReadonlyArray<UndefinedOnPartialDeep<F>>
+					: never;
+
+export {};

package/source/union-to-intersection.d.ts

@@ -0,0 +1,35 @@
+/**
+Convert a union type to an intersection type using [distributive conditional types](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
+
+Inspired by [this Stack Overflow answer](https://stackoverflow.com/a/50375286/2172153).
+
+@example
+```
+import type {UnionToIntersection} from 'type-fest';
+
+type Union = {the(): void} | {great(arg: string): void} | {escape: boolean};
+
+type Intersection = UnionToIntersection<Union>;
+//=> {the(): void} & {great(arg: string): void} & {escape: boolean}
+```
+
+@category Type
+*/
+export type UnionToIntersection<Union> = (
+	// `extends unknown` is always going to be the case and is used to convert the
+	// `Union` into a [distributive conditional
+	// type](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
+	Union extends unknown
+		// The union type is used as the only argument to a function since the union
+		// of function arguments is an intersection.
+		? (distributedUnion: Union) => void
+		// This won't happen.
+		: never
+		// Infer the `Intersection` type since TypeScript represents the positional
+		// arguments of unions of functions as an intersection of the union.
+) extends ((mergedIntersection: infer Intersection) => void)
+	// The `& Union` is to ensure result of `UnionToIntersection<A | B>` is always assignable to `A | B`
+	? Intersection & Union
+	: never;
+
+export {};

package/source/union-to-tuple.d.ts

@@ -0,0 +1,58 @@
+import type {IsNever} from './is-never.d.ts';
+import type {UnionToIntersection} from './union-to-intersection.d.ts';
+
+/**
+Returns the last element of a union type.
+
+@example
+```
+type Last = LastOfUnion<1 | 2 | 3>;
+//=> 3
+```
+*/
+type LastOfUnion<T> =
+UnionToIntersection<T extends any ? () => T : never> extends () => (infer R)
+	? R
+	: never;
+
+/**
+Convert a union type into an unordered tuple type of its elements.
+
+"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.
+
+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 {UnionToTuple} from 'type-fest';
+
+type Numbers = 1 | 2 | 3;
+type NumbersTuple = UnionToTuple<Numbers>;
+//=> [1, 2, 3]
+```
+
+@example
+```
+import type {UnionToTuple} from 'type-fest';
+
+const pets = {
+	dog: '🐶',
+	cat: '🐱',
+	snake: '🐍',
+};
+
+type Pet = keyof typeof pets;
+//=> 'dog' | 'cat' | 'snake'
+
+const petList = Object.keys(pets) as UnionToTuple<Pet>;
+//=> ['dog', 'cat', 'snake']
+```
+
+@category Array
+*/
+export type UnionToTuple<T, L = LastOfUnion<T>> =
+IsNever<T> extends false
+	? [...UnionToTuple<Exclude<T, L>>, L]
+	: [];
+
+export {};

package/source/unknown-array.d.ts

@@ -0,0 +1,27 @@
+/**
+Represents an array with `unknown` value.
+
+Use case: You want a type that all arrays can be assigned to, but you don't care about the value.
+
+@example
+```
+import type {UnknownArray} from 'type-fest';
+
+type IsArray<T> = T extends UnknownArray ? true : false;
+
+type A = IsArray<['foo']>;
+//=> true
+
+type B = IsArray<readonly number[]>;
+//=> true
+
+type C = IsArray<string>;
+//=> false
+```
+
+@category Type
+@category Array
+*/
+export type UnknownArray = readonly unknown[];
+
+export {};

package/source/unknown-map.d.ts

@@ -0,0 +1,26 @@
+/**
+Represents a map with `unknown` key and value.
+
+Use case: You want a type that all maps can be assigned to, but you don't care about the value.
+
+@example
+```
+import type {UnknownMap} from 'type-fest';
+
+type IsMap<T> = T extends UnknownMap ? true : false;
+
+type A = IsMap<Map<string, number>>;
+//=> true
+
+type B = IsMap<ReadonlyMap<number, string>>;
+//=> true
+
+type C = IsMap<string>;
+//=> false
+```
+
+@category Type
+*/
+export type UnknownMap = ReadonlyMap<unknown, unknown>;
+
+export {};

package/source/unknown-record.d.ts

@@ -0,0 +1,33 @@
+/**
+Represents an object with `unknown` value. You probably want this instead of `{}`.
+
+Use case: You have an object whose keys and values are unknown to you.
+
+@example
+```
+import type {UnknownRecord} from 'type-fest';
+
+function toJson(object: UnknownRecord) {
+	return JSON.stringify(object);
+}
+
+toJson({hello: 'world'}); // Ok
+
+function isObject(value: unknown): value is UnknownRecord {
+	return typeof value === 'object' && value !== null;
+}
+
+const value: unknown = {hello: 'world'};
+
+if (isObject(value)) {
+	const v = value;
+	//=> UnknownRecord
+}
+```
+
+@category Type
+@category Object
+*/
+export type UnknownRecord = Record<PropertyKey, unknown>;
+
+export {};

package/source/unknown-set.d.ts

@@ -0,0 +1,26 @@
+/**
+Represents a set with `unknown` value.
+
+Use case: You want a type that all sets can be assigned to, but you don't care about the value.
+
+@example
+```
+import type {UnknownSet} from 'type-fest';
+
+type IsSet<T> = T extends UnknownSet ? true : false;
+
+type A = IsSet<Set<string>>;
+//=> true
+
+type B = IsSet<ReadonlySet<number>>;
+//=> true
+
+type C = IsSet<string>;
+//=> false
+```
+
+@category Type
+*/
+export type UnknownSet = ReadonlySet<unknown>;
+
+export {};

package/source/unwrap-partial.d.ts

@@ -0,0 +1,33 @@
+/**
+Revert the `Partial` modifier on an object type.
+
+Use-case: Infer the underlying type `T` when only `Partial<T>` is available or the original type may not be directly accessible.
+
+@example
+```
+import type {UnwrapPartial} from 'type-fest';
+
+type Config = Partial<{
+	port: number;
+	host: string;
+	secure?: boolean;
+}>;
+
+type InitializedConfig = UnwrapPartial<Config>;
+//=> {port: number; host: string; secure?: boolean}
+```
+
+Note: If the provided type isn’t of `Partial<T>`, `UnwrapPartial` has no effect on the original type.
+
+@category Object
+*/
+export type UnwrapPartial<PartialObjectType> =
+	PartialObjectType extends Partial<infer ObjectType>
+		? (
+			Partial<ObjectType> extends PartialObjectType
+				? ObjectType
+				: PartialObjectType
+		)
+		: PartialObjectType;
+
+export {};

package/source/value-of.d.ts

@@ -0,0 +1,24 @@
+/**
+Create a union of the given object's values, and optionally specify which keys to get the values from.
+
+Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/31438) if you want to have this type as a built-in in TypeScript.
+
+@example
+```
+import type {ValueOf} from 'type-fest';
+
+type A = ValueOf<{id: number; name: string; active: boolean}>;
+//=> string | number | boolean
+
+type B = ValueOf<{id: number; name: string; active: boolean}, 'name'>;
+//=> string
+
+type C = ValueOf<{id: number; name: string; active: boolean}, 'id' | 'name'>;
+//=> string | number
+```
+
+@category Object
+*/
+export type ValueOf<ObjectType, ValueType extends keyof ObjectType = keyof ObjectType> = ObjectType[ValueType];
+
+export {};

package/source/words.d.ts

@@ -0,0 +1,122 @@
+import type {
+	ApplyDefaultOptions,
+	IsNumeric,
+	WordSeparators,
+} from './internal/index.d.ts';
+import type {IsLowercase} from './is-lowercase.d.ts';
+import type {IsUppercase} from './is-uppercase.d.ts';
+
+type SkipEmptyWord<Word extends string> = Word extends '' ? [] : [Word];
+
+type RemoveLastCharacter<
+	Sentence extends string,
+	Character extends string,
+> = Sentence extends `${infer LeftSide}${Character}`
+	? SkipEmptyWord<LeftSide>
+	: never;
+
+/**
+Words options.
+
+@see {@link Words}
+*/
+export type WordsOptions = {
+	/**
+	Split on numeric sequence.
+
+	@default true
+
+	@example
+	```
+	import type {Words} from 'type-fest';
+
+	type Example1 = Words<'p2pNetwork', {splitOnNumbers: true}>;
+	//=> ['p', '2', 'p', 'Network']
+
+	type Example2 = Words<'p2pNetwork', {splitOnNumbers: false}>;
+	//=> ['p2p', 'Network']
+	```
+	*/
+	splitOnNumbers?: boolean;
+};
+
+export type _DefaultWordsOptions = {
+	splitOnNumbers: true;
+};
+
+/**
+Split a string (almost) like Lodash's `_.words()` function.
+
+- Split on each word that begins with a capital letter.
+- Split on each {@link WordSeparators}.
+- Split on numeric sequence.
+
+@example
+```
+import type {Words} from 'type-fest';
+
+type Words0 = Words<'helloWorld'>;
+//=> ['hello', 'World']
+
+type Words1 = Words<'helloWORLD'>;
+//=> ['hello', 'WORLD']
+
+type Words2 = Words<'hello-world'>;
+//=> ['hello', 'world']
+
+type Words3 = Words<'--hello the_world'>;
+//=> ['hello', 'the', 'world']
+
+type Words4 = Words<'lifeIs42'>;
+//=> ['life', 'Is', '42']
+
+type Words5 = Words<'p2pNetwork', {splitOnNumbers: false}>;
+//=> ['p2p', 'Network']
+```
+
+@category Change case
+@category Template literal
+*/
+export type Words<Sentence extends string, Options extends WordsOptions = {}> =
+	WordsImplementation<Sentence, ApplyDefaultOptions<WordsOptions, _DefaultWordsOptions, Options>>;
+
+type WordsImplementation<
+	Sentence extends string,
+	Options extends Required<WordsOptions>,
+	LastCharacter extends string = '',
+	CurrentWord extends string = '',
+> = Sentence extends `${infer FirstCharacter}${infer RemainingCharacters}`
+	? FirstCharacter extends WordSeparators
+		// Skip word separator
+		? [...SkipEmptyWord<CurrentWord>, ...WordsImplementation<RemainingCharacters, Options>]
+		: LastCharacter extends ''
+			// Fist char of word
+			? WordsImplementation<RemainingCharacters, Options, FirstCharacter, FirstCharacter>
+			// Case change: non-numeric to numeric
+			: [false, true] extends [IsNumeric<LastCharacter>, IsNumeric<FirstCharacter>]
+				? Options['splitOnNumbers'] extends true
+					// Split on number: push word
+					? [...SkipEmptyWord<CurrentWord>, ...WordsImplementation<RemainingCharacters, Options, FirstCharacter, FirstCharacter>]
+					// No split on number: concat word
+					: WordsImplementation<RemainingCharacters, Options, FirstCharacter, `${CurrentWord}${FirstCharacter}`>
+				// Case change: numeric to non-numeric
+				: [true, false] extends [IsNumeric<LastCharacter>, IsNumeric<FirstCharacter>]
+					? Options['splitOnNumbers'] extends true
+						// Split on number: push word
+						? [...SkipEmptyWord<CurrentWord>, ...WordsImplementation<RemainingCharacters, Options, FirstCharacter, FirstCharacter>]
+						// No split on number: concat word
+						: WordsImplementation<RemainingCharacters, Options, FirstCharacter, `${CurrentWord}${FirstCharacter}`>
+					// No case change: concat word
+					: [true, true] extends [IsNumeric<LastCharacter>, IsNumeric<FirstCharacter>]
+						? WordsImplementation<RemainingCharacters, Options, FirstCharacter, `${CurrentWord}${FirstCharacter}`>
+					// Case change: lower to upper, push word
+						: [true, true] extends [IsLowercase<LastCharacter>, IsUppercase<FirstCharacter>]
+							? [...SkipEmptyWord<CurrentWord>, ...WordsImplementation<RemainingCharacters, Options, FirstCharacter, FirstCharacter>]
+						// Case change: upper to lower, brings back the last character, push word
+							: [true, true] extends [IsUppercase<LastCharacter>, IsLowercase<FirstCharacter>]
+								? [...RemoveLastCharacter<CurrentWord, LastCharacter>, ...WordsImplementation<RemainingCharacters, Options, FirstCharacter, `${LastCharacter}${FirstCharacter}`>]
+							// No case change: concat word
+								: WordsImplementation<RemainingCharacters, Options, FirstCharacter, `${CurrentWord}${FirstCharacter}`>
+	: [...SkipEmptyWord<CurrentWord>];
+
+export {};