@depup/type-fest 5.4.4-depup.0

package/source/all-extend.d.ts

@@ -0,0 +1,120 @@
+import type {If} from './if.d.ts';
+import type {CollapseRestElement} from './internal/array.d.ts';
+import type {ApplyDefaultOptions} from './internal/object.d.ts';
+import type {IfNotAnyOrNever, Not} from './internal/type.d.ts';
+import type {IsAny} from './is-any.d.ts';
+import type {IsNever} from './is-never.d.ts';
+import type {Or} from './or.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+
+/**
+@see {@link AllExtend}
+*/
+export type AllExtendOptions = {
+	/**
+	Consider `never` elements to match the target type only if the target type itself is `never` (or `any`).
+
+	- When set to `true` (default), `never` is _not_ treated as a bottom type, instead, it is treated as a type that matches only itself (or `any`).
+	- When set to `false`, `never` is treated as a bottom type, and behaves as it normally would.
+
+	@default true
+
+	@example
+	```
+	import type {AllExtend} from 'type-fest';
+
+	type A = AllExtend<[1, 2, never], number, {strictNever: true}>;
+	//=> false
+
+	type B = AllExtend<[1, 2, never], number, {strictNever: false}>;
+	//=> true
+
+	type C = AllExtend<[never, never], never, {strictNever: true}>;
+	//=> true
+
+	type D = AllExtend<[never, never], never, {strictNever: false}>;
+	//=> true
+
+	type E = AllExtend<['a', 'b', never], any, {strictNever: true}>;
+	//=> true
+
+	type F = AllExtend<['a', 'b', never], any, {strictNever: false}>;
+	//=> true
+
+	type G = AllExtend<[never, 1], never, {strictNever: true}>;
+	//=> false
+
+	type H = AllExtend<[never, 1], never, {strictNever: false}>;
+	//=> false
+	```
+	*/
+	strictNever?: boolean;
+};
+
+type DefaultAllExtendOptions = {
+	strictNever: true;
+};
+
+/**
+Returns a boolean for whether every element in an array type extends another type.
+
+@example
+```
+import type {AllExtend} from 'type-fest';
+
+type A = AllExtend<[1, 2, 3], number>;
+//=> true
+
+type B = AllExtend<[1, 2, '3'], number>;
+//=> false
+
+type C = AllExtend<[number, number | string], number>;
+//=> boolean
+
+type D = AllExtend<[true, boolean, true], true>;
+//=> boolean
+```
+
+Note: Behaviour of optional elements depend on the `exactOptionalPropertyTypes` compiler option. When the option is disabled, the target type must include `undefined` for a successful match.
+
+```
+// @exactOptionalPropertyTypes: true
+import type {AllExtend} from 'type-fest';
+
+type A = AllExtend<[1?, 2?, 3?], number>;
+//=> true
+```
+
+```
+// @exactOptionalPropertyTypes: false
+import type {AllExtend} from 'type-fest';
+
+type A = AllExtend<[1?, 2?, 3?], number>;
+//=> boolean
+
+type B = AllExtend<[1?, 2?, 3?], number | undefined>;
+//=> true
+```
+
+@see {@link AllExtendOptions}
+
+@category Utilities
+@category Array
+*/
+export type AllExtend<TArray extends UnknownArray, Type, Options extends AllExtendOptions = {}> =
+	_AllExtend<CollapseRestElement<TArray>, Type, ApplyDefaultOptions<AllExtendOptions, DefaultAllExtendOptions, Options>>;
+
+type _AllExtend<TArray extends UnknownArray, Type, Options extends Required<AllExtendOptions>> = IfNotAnyOrNever<TArray, If<IsAny<Type>, true,
+	TArray extends readonly [infer First, ...infer Rest]
+		? IsNever<First> extends true
+			? Or<IsNever<Type>, Not<Options['strictNever']>> extends true
+				// If target `Type` is also `never` OR `strictNever` is disabled, recurse further.
+				? _AllExtend<Rest, Type, Options>
+				: false
+			: First extends Type
+				? _AllExtend<Rest, Type, Options>
+				: false
+		: true
+>, false, false>;
+
+export {};

package/source/all-union-fields.d.ts

@@ -0,0 +1,91 @@
+import type {NonRecursiveType, ReadonlyKeysOfUnion, ValueOfUnion} from './internal/index.d.ts';
+import type {KeysOfUnion} from './keys-of-union.d.ts';
+import type {SharedUnionFields} from './shared-union-fields.d.ts';
+import type {Simplify} from './simplify.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+
+/**
+Create a type with all fields from a union of object types.
+
+Use-cases:
+- You want a safe object type where each key exists in the union object.
+
+@example
+```
+import type {AllUnionFields} from 'type-fest';
+
+type Cat = {
+	name: string;
+	type: 'cat';
+	catType: string;
+};
+
+type Dog = {
+	name: string;
+	type: 'dog';
+	dogType: string;
+};
+
+function displayPetInfo(petInfo: Cat | Dog) {
+	// typeof petInfo =>
+	// {
+	// 	name: string;
+	// 	type: 'cat';
+	// 	catType: string;
+	// } | {
+	// 	name: string;
+	// 	type: 'dog';
+	// 	dogType: string;
+	// }
+
+	console.log('name:', petInfo.name);
+	console.log('type:', petInfo.type);
+
+	// TypeScript complains about `catType` and `dogType` not existing on type `Cat | Dog`.
+	// @ts-expect-error
+	console.log('animal type:', petInfo.catType ?? petInfo.dogType);
+}
+
+function displayPetInfoWithAllUnionFields(petInfo: AllUnionFields<Cat | Dog>) {
+	// typeof petInfo =>
+	// {
+	// 	name: string;
+	// 	type: 'cat' | 'dog';
+	// 	catType?: string;
+	// 	dogType?: string;
+	// }
+
+	console.log('name:', petInfo.name);
+	console.log('type:', petInfo.type);
+
+	// No TypeScript error.
+	console.log('animal type:', petInfo.catType ?? petInfo.dogType);
+}
+```
+
+@see {@link SharedUnionFields}
+
+@category Object
+@category Union
+*/
+export type AllUnionFields<Union> =
+Extract<Union, NonRecursiveType | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | UnknownArray> extends infer SkippedMembers
+	? Exclude<Union, SkippedMembers> extends infer RelevantMembers
+		?
+		| SkippedMembers
+		| Simplify<
+		// Include fields that are common in all union members
+			SharedUnionFields<RelevantMembers> &
+		// Include readonly fields present in any union member
+			{
+				readonly [P in ReadonlyKeysOfUnion<RelevantMembers>]?: ValueOfUnion<RelevantMembers, P & KeysOfUnion<RelevantMembers>>
+			} &
+		// Include remaining fields that are neither common nor readonly
+			{
+				[P in Exclude<KeysOfUnion<RelevantMembers>, ReadonlyKeysOfUnion<RelevantMembers> | keyof RelevantMembers>]?: ValueOfUnion<RelevantMembers, P>
+			}
+		>
+		: never
+	: never;
+
+export {};

package/source/and.d.ts

@@ -0,0 +1,81 @@
+import type {AllExtend} from './all-extend.d.ts';
+
+/**
+Returns a boolean for whether two given types are both true.
+
+Use-case: Constructing complex conditional types where multiple conditions must be satisfied.
+
+@example
+```
+import type {And} from 'type-fest';
+
+type TT = And<true, true>;
+//=> true
+
+type TF = And<true, false>;
+//=> false
+
+type FT = And<false, true>;
+//=> false
+
+type FF = And<false, false>;
+//=> false
+```
+
+Note: When `boolean` is passed as an argument, it is distributed into separate cases, and the final result is a union of those cases.
+For example, `And<true, boolean>` expands to `And<true, true> | And<true, false>`, which simplifies to `true | false` (i.e., `boolean`).
+
+@example
+```
+import type {And} from 'type-fest';
+
+type A = And<true, boolean>;
+//=> boolean
+
+type B = And<boolean, true>;
+//=> boolean
+
+type C = And<false, boolean>;
+//=> false
+
+type D = And<boolean, false>;
+//=> false
+
+type E = And<boolean, boolean>;
+//=> boolean
+```
+
+Note: If either of the types is `never`, the result becomes `false`.
+
+@example
+```
+import type {And} from 'type-fest';
+
+type A = And<true, never>;
+//=> false
+
+type B = And<never, true>;
+//=> false
+
+type C = And<false, never>;
+//=> false
+
+type D = And<never, false>;
+//=> false
+
+type E = And<boolean, never>;
+//=> false
+
+type F = And<never, boolean>;
+//=> false
+
+type G = And<never, never>;
+//=> false
+```
+
+@see {@link Or}
+@see {@link Xor}
+*/
+export type And<A extends boolean, B extends boolean> = AllExtend<[A, B], true>;
+
+export {};

package/source/array-element.d.ts

@@ -0,0 +1,46 @@
+import type {UnknownArray} from './unknown-array.d.ts';
+
+/**
+Extracts the element type of an array or tuple.
+
+Use-cases:
+- When you need type-safe element extraction that returns `never` for non-arrays.
+- When extracting element types from generic array parameters in function signatures.
+- For better readability and explicit intent over using `T[number]` directly.
+
+Note: Returns `never` if the type is not an array.
+
+@example
+```
+import type {ArrayElement} from 'type-fest';
+
+// Arrays
+type StringArray = ArrayElement<string[]>;
+//=> string
+
+// Tuples
+type Tuple = ArrayElement<[1, 2, 3]>;
+//=> 1 | 2 | 3
+
+// Type-safe
+type NotArray = ArrayElement<{a: string}>;
+//=> never
+
+// Practical example
+declare function getRandomElement<T extends readonly unknown[]>(array: T): ArrayElement<T>;
+
+getRandomElement(['foo', 'bar', 'baz'] as const);
+//=> 'foo' | 'bar' | 'baz'
+```
+
+@see {@link ArrayValues} - For directly extracting values from a constant array type.
+@see {@link IterableElement} - For iterables like `Set`, `Map`, and generators (not suitable for all use cases due to different inference behavior).
+
+@category Array
+*/
+export type ArrayElement<T> =
+	T extends UnknownArray
+		? T[number]
+		: never;
+
+export {};

package/source/array-indices.d.ts

@@ -0,0 +1,25 @@
+/**
+Provides valid indices for a constant array or tuple.
+
+Use-case: This type is useful when working with constant arrays or tuples and you want to enforce type-safety for accessing elements by their indices.
+
+@example
+```
+import type {ArrayIndices, ArrayValues} from 'type-fest';
+
+const weekdays = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'] as const;
+
+type Weekday = ArrayIndices<typeof weekdays>;
+type WeekdayName = ArrayValues<typeof weekdays>;
+
+const getWeekdayName = (day: Weekday): WeekdayName => weekdays[day];
+```
+
+@see {@link ArrayValues}
+
+@category Array
+*/
+export type ArrayIndices<Element extends readonly unknown[]> =
+	Exclude<Partial<Element>['length'], Element['length']>;
+
+export {};

package/source/array-reverse.d.ts

@@ -0,0 +1,84 @@
+import type {If} from './if.d.ts';
+import type {IsArrayReadonly} from './internal/array.d.ts';
+import type {IfNotAnyOrNever, IsExactOptionalPropertyTypesEnabled} from './internal/type.d.ts';
+import type {IsOptionalKeyOf} from './is-optional-key-of.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+
+/**
+Reverse the order of elements in a tuple type.
+
+@example
+```ts
+import type {ArrayReverse} from 'type-fest';
+
+type A = ArrayReverse<[string, number, boolean]>;
+//=> [boolean, number, string]
+
+type B = ArrayReverse<readonly [string, number, ...boolean[]]>;
+//=> readonly [...boolean[], number, string]
+
+type C = ArrayReverse<['foo', 'bar'] | readonly [1, 2, 3]>;
+//=> ['bar', 'foo'] | readonly [3, 2, 1]
+
+type D = ArrayReverse<string[]>;
+//=> string[]
+
+type E = ArrayReverse<[]>;
+//=> []
+```
+
+Note: If the tuple contains optional elements, the result will be a union of tuples, refer to the examples below:
+
+@example
+```ts
+import type {ArrayReverse} from 'type-fest';
+
+type A = ArrayReverse<[string, number, boolean?]>;
+//=> [number, string] | [boolean, number, string]
+
+type B = ArrayReverse<[string, number?, boolean?]>;
+//=> [string] | [number, string] | [boolean, number, string]
+
+type C = ArrayReverse<[string?, number?, boolean?]>;
+//=> [] | [string] | [number, string] | [boolean, number, string]
+
+type D = ArrayReverse<[string, number?, ...boolean[]]>;
+//=> [string] | [...boolean[], number, string]
+
+type E = ArrayReverse<[string?, number?, ...boolean[]]>;
+//=> [] | [string] | [...boolean[], number, string]
+```
+
+@category Array
+*/
+export type ArrayReverse<TArray extends UnknownArray> = IfNotAnyOrNever<TArray,
+	TArray extends unknown // For distributing `TArray`
+		? _ArrayReverse<TArray> extends infer Result
+			? If<IsArrayReadonly<TArray>, Readonly<Result>, Result>
+			: never // Should never happen
+		: never>; // Should never happen
+
+type _ArrayReverse<
+	TArray extends UnknownArray,
+	BeforeRestAcc extends UnknownArray = [],
+	AfterRestAcc extends UnknownArray = [],
+	Result extends UnknownArray = never,
+> =
+	keyof TArray & `${number}` extends never
+		// Enters this branch, if `TArray` is empty (e.g., `[]`),
+		// or `TArray` contains no non-rest elements preceding the rest element (e.g., `[...string[]]` or `[...string[], string]`).
+		? TArray extends readonly [...infer Rest, infer Last]
+			? _ArrayReverse<Rest, BeforeRestAcc, [...AfterRestAcc, Last], Result> // Accumulate elements that are present after the rest element in reverse order.
+			: Result | [...AfterRestAcc, ...TArray, ...BeforeRestAcc] // Add the rest element between the accumulated elements.
+		: TArray extends readonly [(infer First)?, ...infer Rest]
+			? IsOptionalKeyOf<TArray, '0'> extends true
+				? _ArrayReverse<
+					Rest,
+					[First | (If<IsExactOptionalPropertyTypesEnabled, never, undefined>), ...BeforeRestAcc], // Add `| undefined` for optional elements, if `exactOptionalPropertyTypes` is disabled.
+					AfterRestAcc,
+					Result | BeforeRestAcc
+				>
+				: _ArrayReverse<Rest, [First, ...BeforeRestAcc], AfterRestAcc, Result>
+			: never; // Should never happen, since `readonly [(infer First)?, ...infer Rest]` is a top-type for arrays.
+
+export {};

package/source/array-slice.d.ts

@@ -0,0 +1,132 @@
+import type {Sum} from './sum.d.ts';
+import type {LessThanOrEqual} from './less-than-or-equal.d.ts';
+import type {GreaterThanOrEqual} from './greater-than-or-equal.d.ts';
+import type {GreaterThan} from './greater-than.d.ts';
+import type {IsNegative} from './numeric.d.ts';
+import type {Not, TupleMin} from './internal/index.d.ts';
+import type {IsEqual} from './is-equal.d.ts';
+import type {And} from './and.d.ts';
+import type {ArraySplice} from './array-splice.d.ts';
+import type {IsNever} from './is-never.d.ts';
+
+/**
+Returns an array slice of a given range, just like `Array#slice()`.
+
+@example
+```
+import type {ArraySlice} from 'type-fest';
+
+type T0 = ArraySlice<[0, 1, 2, 3, 4]>;
+//=> [0, 1, 2, 3, 4]
+
+type T1 = ArraySlice<[0, 1, 2, 3, 4], 0, -1>;
+//=> [0, 1, 2, 3]
+
+type T2 = ArraySlice<[0, 1, 2, 3, 4], 1, -2>;
+//=> [1, 2]
+
+type T3 = ArraySlice<[0, 1, 2, 3, 4], -2, 4>;
+//=> [3]
+
+type T4 = ArraySlice<[0, 1, 2, 3, 4], -2, -1>;
+//=> [3]
+
+type T5 = ArraySlice<[0, 1, 2, 3, 4], 0, -999>;
+//=> []
+
+function arraySlice<
+	const Array_ extends readonly unknown[],
+	Start extends number = 0,
+	End extends number = Array_['length'],
+>(array: Array_, start?: Start, end?: End) {
+	return array.slice(start, end) as ArraySlice<Array_, Start, End>;
+}
+
+const slice = arraySlice([1, '2', {a: 3}, [4, 5]], 0, -1);
+
+type Slice = typeof slice;
+//=> [1, '2', {readonly a: 3}]
+
+const value = slice[2].a;
+//=> 3
+
+// @ts-expect-error -- TS2493: Tuple type '[1, "2", {readonly a: 3}]' of length '3' has no element at index '3'.
+const invalidIndexAccess = slice[3];
+```
+
+@category Array
+*/
+export type ArraySlice<
+	Array_ extends readonly unknown[],
+	Start extends number = never,
+	End extends number = never,
+> = Array_ extends unknown // To distributive type
+	? IsNever<Start> extends true
+		? IsNever<End> extends true
+			? _ArraySlice<Array_, Start, End>
+			: End extends unknown // To distribute `End`
+				? _ArraySlice<Array_, Start, End>
+				: never // Never happens
+		: IsNever<End> extends true
+			? Start extends unknown // To distribute `Start`
+				? _ArraySlice<Array_, Start, End>
+				: never // Never happens
+			: Start extends unknown // To distribute `Start`
+				? End extends unknown // To distribute `End`
+					? _ArraySlice<Array_, Start, End>
+					: never // Never happens
+				: never // Never happens
+	: never; // Never happens
+
+type _ArraySlice<
+	Array_ extends readonly unknown[],
+	Start extends number = 0,
+	End extends number = Array_['length'],
+> = And<IsEqual<Start, never>, IsEqual<End, never>> extends true
+	? Array_
+	: number extends Array_['length']
+		? VariableLengthArraySliceHelper<Array_, Start, End>
+		: ArraySliceHelper<Array_, IsEqual<Start, never> extends true ? 0 : Start, IsEqual<End, never> extends true ? Array_['length'] : End>;
+
+type VariableLengthArraySliceHelper<
+	Array_ extends readonly unknown[],
+	Start extends number,
+	End extends number,
+> = And<Not<IsNegative<Start>>, IsEqual<End, never>> extends true
+	? ArraySplice<Array_, 0, Start>
+	: And<
+		And<Not<IsNegative<Start>>, Not<IsNegative<End>>>,
+		IsEqual<GreaterThan<End, Start>, true>
+	> extends true
+		? ArraySliceByPositiveIndex<Array_, Start, End>
+		: [];
+
+type ArraySliceHelper<
+	Array_ extends readonly unknown[],
+	Start extends number = 0,
+	End extends number = Array_['length'],
+	TraversedElement extends Array<Array_[number]> = [],
+	Result extends Array<Array_[number]> = [],
+	ArrayLength extends number = Array_['length'],
+	PositiveS extends number = IsNegative<Start> extends true
+		? Sum<ArrayLength, Start> extends infer AddResult extends number
+			? number extends AddResult // (ArrayLength + Start) < 0
+				? 0
+				: GreaterThan<AddResult, 0> extends true ? AddResult : 0
+			: never
+		: Start,
+	PositiveE extends number = IsNegative<End> extends true ? Sum<ArrayLength, End> : End,
+> = true extends [IsNegative<PositiveS>, LessThanOrEqual<PositiveE, PositiveS>, GreaterThanOrEqual<PositiveS, ArrayLength>][number]
+	? []
+	: ArraySliceByPositiveIndex<Array_, TupleMin<[PositiveS, ArrayLength]>, TupleMin<[PositiveE, ArrayLength]>>;
+
+type ArraySliceByPositiveIndex<
+	Array_ extends readonly unknown[],
+	Start extends number,
+	End extends number,
+	Result extends Array<Array_[number]> = [],
+> = Start extends End
+	? Result
+	: ArraySliceByPositiveIndex<Array_, Sum<Start, 1>, End, [...Result, Array_[Start]]>;
+
+export {};

package/source/array-splice.d.ts

@@ -0,0 +1,104 @@
+import type {StaticPartOfArray, VariablePartOfArray} from './internal/index.d.ts';
+import type {GreaterThanOrEqual} from './greater-than-or-equal.d.ts';
+import type {Subtract} from './subtract.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+import type {TupleOf} from './tuple-of.d.ts';
+
+/**
+The implementation of `SplitArrayByIndex` for fixed length arrays.
+*/
+type SplitFixedArrayByIndex<T extends UnknownArray, SplitIndex extends number> =
+SplitIndex extends 0
+	? [[], T]
+	: T extends readonly [...TupleOf<SplitIndex>, ...infer V]
+		? T extends readonly [...infer U, ...V]
+			? [U, V]
+			: [never, never]
+		: [never, never];
+
+/**
+The implementation of `SplitArrayByIndex` for variable length arrays.
+*/
+type SplitVariableArrayByIndex<T extends UnknownArray,
+	SplitIndex extends number,
+	T1 = Subtract<SplitIndex, StaticPartOfArray<T>['length']>,
+	T2 = T1 extends number
+		? TupleOf<GreaterThanOrEqual<T1, 0> extends true ? T1 : number, VariablePartOfArray<T>[number]>
+		: [],
+> =
+SplitIndex extends 0
+	? [[], T]
+	: GreaterThanOrEqual<StaticPartOfArray<T>['length'], SplitIndex> extends true
+		? [
+			SplitFixedArrayByIndex<StaticPartOfArray<T>, SplitIndex>[0],
+			[
+				...SplitFixedArrayByIndex<StaticPartOfArray<T>, SplitIndex>[1],
+				...VariablePartOfArray<T>,
+			],
+		]
+		: [
+			[
+				...StaticPartOfArray<T>,
+				...(T2 extends UnknownArray ? T2 : []),
+			],
+			VariablePartOfArray<T>,
+		];
+
+/**
+Split the given array `T` by the given `SplitIndex`.
+
+@example
+```
+type A = SplitArrayByIndex<[1, 2, 3, 4], 2>;
+// type A = [[1, 2], [3, 4]];
+
+type B = SplitArrayByIndex<[1, 2, 3, 4], 0>;
+// type B = [[], [1, 2, 3, 4]];
+```
+*/
+type SplitArrayByIndex<T extends UnknownArray, SplitIndex extends number> =
+	SplitIndex extends 0
+		? [[], T]
+		: number extends T['length']
+			? SplitVariableArrayByIndex<T, SplitIndex>
+			: SplitFixedArrayByIndex<T, SplitIndex>;
+
+/**
+Create a new array type by adding or removing elements at a specified index range in the original array.
+
+Use-case: Replace or insert items in an array type.
+
+Like [`Array#splice()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) but for types.
+
+@example
+```
+import type {ArraySplice} from 'type-fest';
+
+type SomeMonths0 = ['January', 'April', 'June'];
+type Months0 = ArraySplice<SomeMonths0, 1, 0, ['Feb', 'March']>;
+//=> ['January', 'Feb', 'March', 'April', 'June']
+
+type SomeMonths1 = ['January', 'April', 'June'];
+type Months1 = ArraySplice<SomeMonths1, 1, 1>;
+//=> ['January', 'June']
+
+type SomeMonths2 = ['January', 'Foo', 'April'];
+type Months2 = ArraySplice<SomeMonths2, 1, 1, ['Feb', 'March']>;
+//=> ['January', 'Feb', 'March', 'April']
+```
+
+@category Array
+*/
+export type ArraySplice<
+	T extends UnknownArray,
+	Start extends number,
+	DeleteCount extends number,
+	Items extends UnknownArray = [],
+> =
+	SplitArrayByIndex<T, Start> extends [infer U extends UnknownArray, infer V extends UnknownArray]
+		? SplitArrayByIndex<V, DeleteCount> extends [infer _Deleted extends UnknownArray, infer X extends UnknownArray]
+			? [...U, ...Items, ...X]
+			: never // Should never happen
+		: never; // Should never happen
+
+export {};