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

package/source/exclude-rest-element.d.ts

@@ -27,14 +27,14 @@ type T4 = ExcludeRestElement<[number, string]>;
 @see {@link SplitOnRestElement}
 @category Array
 */
-export type ExcludeRestElement<Array_ extends UnknownArray> = IfNotAnyOrNever<Array_,
-	SplitOnRestElement<Array_> extends infer Result
+export type ExcludeRestElement<Array_ extends UnknownArray> = IfNotAnyOrNever<Array_, {
+	ifNot: SplitOnRestElement<Array_> extends infer Result
 		? Result extends readonly UnknownArray[]
 			? IsArrayReadonly<Array_> extends true
 				? Readonly<[...Result[0], ...Result[2]]>
 				: [...Result[0], ...Result[2]]
 			: never
-		: never
->;
+		: never;
+}>;
 
 export {};

package/source/exclusify-union.d.ts

@@ -125,13 +125,13 @@ type D = ExclusifyUnion<{a?: 1; readonly b: 2} | {d: 4}>;
 @category Object
 @category Union
 */
-export type ExclusifyUnion<Union> = IfNotAnyOrNever<Union,
-	If<IsUnknown<Union>, Union,
+export type ExclusifyUnion<Union> = IfNotAnyOrNever<Union, {
+	ifNot: If<IsUnknown<Union>, Union,
 		Extract<Union, NonRecursiveType | MapsSetsOrArrays> extends infer SkippedMembers
 			? SkippedMembers | _ExclusifyUnion<Exclude<Union, SkippedMembers>>
 			: never
-	>
->;
+	>;
+}>;
 
 type _ExclusifyUnion<Union, UnionCopy = Union> = Union extends unknown // For distributing `Union`
 	? Simplify<

package/source/extends-strict.d.ts

@@ -1,44 +1,151 @@
 import type {IsNever} from './is-never.d.ts';
 import type {IsAny} from './is-any.d.ts';
+import type {ApplyDefaultOptions} from './internal/object.d.ts';
+import type {And} from './and.d.ts';
+import type {Or} from './or.d.ts';
+import type {IsUnknown} from './is-unknown.d.ts';
+import type {OrAll} from './or-all.d.ts';
 
-/**
-A stricter, non-distributive version of `extends` for checking whether one type is assignable to another.
+export type ExtendsStrictOptions = {
+	/**
+	Whether to distribute over unions.
+
+	@default false
+
+	@example
+	```
+	import type {ExtendsStrict} from 'type-fest';
+
+	type T1 = ExtendsStrict<string | number, string, {distributiveUnions: true}>;
+	//=> boolean
+
+	type T2 = ExtendsStrict<string | number, string, {distributiveUnions: false}>;
+	//=> false
+	```
+	*/
+	distributiveUnions?: boolean;
+
+	/**
+	Whether `never` extends every other type.
+
+	When enabled, `never` is not treated as a bottom type and only extends itself (or `any` / `unknown`).
+
+	@default true
+
+	@example
+	```
+	import type {ExtendsStrict} from 'type-fest';
+
+	type T1 = ExtendsStrict<never, number, {strictNever: true}>;
+	//=> false
+
+	type T2 = ExtendsStrict<never, number, {strictNever: false}>;
+	//=> true
+
+	type T3 = ExtendsStrict<never, never, {strictNever: true}>;
+	//=> true
+
+	type T4 = ExtendsStrict<never, any, {strictNever: true}>;
+	//=> true
+
+	type T5 = ExtendsStrict<never, unknown, {strictNever: true}>;
+	//=> true
+	```
+
+	Note: This option only has an effect when checking assignability from `never` (`ExtendsStrict<never, ...>`), and not when checking assignability to `never` (`ExtendsStrict<..., never>`).
+	*/
+	strictNever?: boolean;
+
+	/**
+	Whether `any` extends every other type.
+
+	When enabled, `any` does not extend every other type, it only extends itself (or `unknown`).
+
+	@default false
 
-Unlike the built-in `extends` keyword, `ExtendsStrict`:
+	@example
+	```
+	import type {ExtendsStrict} from 'type-fest';
 
-1. Prevents distribution over union types by wrapping both types in tuples. For example, `ExtendsStrict<string | number, number>` returns `false`, whereas `string | number extends number` would result in `boolean`.
+	type T1 = ExtendsStrict<any, number, {strictAny: true}>;
+	//=> false
 
-2. Treats `never` as a special case: `never` doesn't extend every other type, it only extends itself (or `any`). For example, `ExtendsStrict<never, number>` returns `false` whereas `never extends number` would result in `true`.
+	type T2 = ExtendsStrict<any, number, {strictAny: false; distributiveUnions: false}>;
+	//=> true
+
+	type T3 = ExtendsStrict<any, any, {strictAny: true}>;
+	//=> true
+
+	type T4 = ExtendsStrict<any, unknown, {strictAny: true}>;
+	//=> true
+	```
+
+	Note: If `strictAny` is `false` and `distributiveUnions` is `true`, then `any` would distribute and the result would be the `boolean` type, except when checking assignability to `any` or `unknown`.
+
+	@example
+	```
+	import type {ExtendsStrict} from 'type-fest';
+
+	type T1 = ExtendsStrict<any, number, {strictAny: false; distributiveUnions: true}>;
+	//=> boolean
+
+	type T2 = ExtendsStrict<any, any, {strictAny: false; distributiveUnions: true}>;
+	//=> true
+
+	type T3 = ExtendsStrict<any, unknown, {strictAny: false; distributiveUnions: true}>;
+	//=> true
+	```
+
+	Note: This option only has an effect when checking assignability from `any` (`ExtendsStrict<any, ...>`), and not when checking assignability to `any` (`ExtendsStrict<..., any>`).
+	*/
+	strictAny?: boolean;
+};
+
+type DefaultExtendsStrictOptions = {
+	distributiveUnions: false;
+	strictNever: true;
+	strictAny: false;
+};
+
+/**
+A customizable version of `extends` for checking whether one type is assignable to another.
+
+Refer {@link ExtendsStrictOptions} for the different ways you can customize the behavior of this type.
 
 @example
 ```
 import type {ExtendsStrict} from 'type-fest';
 
-type T1 = ExtendsStrict<number | string, string>;
+type T1 = ExtendsStrict<number | string, string, {distributiveUnions: false}>;
 //=> false
 
-type T2 = ExtendsStrict<never, number>;
+type T2 = ExtendsStrict<never, number, {strictNever: true}>;
 //=> false
 
-type T3 = ExtendsStrict<never, never>;
-//=> true
-
-type T4 = ExtendsStrict<string, number | string>;
-//=> true
-
-type T5 = ExtendsStrict<string, string>;
-//=> true
+type T3 = ExtendsStrict<any, number, {strictAny: true}>;
+//=> false
 ```
 
+@see {@link ExtendsStrictOptions}
+
 @category Improved Built-in
 */
-export type ExtendsStrict<Left, Right> =
-	IsAny<Left | Right> extends true
-		? true
+export type ExtendsStrict<Left, Right, Options extends ExtendsStrictOptions = {}> =
+	_ExtendsStrict<Left, Right, ApplyDefaultOptions<ExtendsStrictOptions, DefaultExtendsStrictOptions, Options>>;
+
+type _ExtendsStrict<Left, Right, Options extends Required<ExtendsStrictOptions>> =
+	And<IsAny<Left>, Options['strictAny']> extends true
+		? Or<IsAny<Right>, IsUnknown<Right>>
 		: IsNever<Left> extends true
-			? IsNever<Right>
-			: [Left] extends [Right]
-				? true
-				: false;
+			? Options['strictNever'] extends true
+				? OrAll<[IsNever<Right>, IsAny<Right>, IsUnknown<Right>]>
+				: true
+			: Options['distributiveUnions'] extends true
+				? Left extends Right
+					? true
+					: false
+				: [Left] extends [Right]
+					? true
+					: false;
 
 export {};

package/source/extract-exactly.d.ts

@@ -0,0 +1,56 @@
+import type {IsAny} from './is-any.d.ts';
+import type {If} from './if.d.ts';
+import type {IsEqual} from './is-equal.d.ts';
+import type {IfNotAnyOrNever} from './internal/type.d.ts';
+
+/**
+A stricter version of `Extract<T, U>` that extracts types only when they are exactly identical.
+
+@example
+```
+import type {ExtractExactly} from 'type-fest';
+
+type TestExtract1 = Extract<'a' | 'b' | 'c' | 1 | 2 | 3, string>;
+//=> 'a' | 'b' | 'c'
+
+type TestExtractExactly1 = ExtractExactly<'a' | 'b' | 'c' | 1 | 2 | 3, string>;
+//=> never
+
+type TestExtract2 = Extract<'a' | 'b' | 'c' | 1 | 2 | 3, any>;
+//=> 'a' | 'b' | 'c' | 1 | 2 | 3
+
+type TestExtractExactly2 = ExtractExactly<'a' | 'b' | 'c' | 1 | 2 | 3, any>;
+//=> never
+
+type TestExtract3 = Extract<{a: string} | {a: string; b: string}, {a: string}>;
+//=> {a: string} | {a: string; b: string}
+
+type TestExtractExactly3 = ExtractExactly<{a: string} | {a: string; b: string}, {a: string}>;
+//=> {a: string}
+```
+
+@category Improved Built-in
+*/
+export type ExtractExactly<Union, Match> =
+	IfNotAnyOrNever<Union, {
+		ifNot: _ExtractExactly<Union, Match>;
+		// If `Union` is `any`, then if `Match` is `any`, return `any`, else return `never`.
+		ifAny: If<IsAny<Match>, Union, never>;
+		// If `Union` is `never`, return `never`, doesn't matter what `Match` is.
+		ifNever: never;
+	}>;
+
+type _ExtractExactly<Union, Match> =
+	IfNotAnyOrNever<Match, {
+		ifNot: Union extends unknown // For distributing `Union`
+			? [Match extends unknown // For distributing `Match`
+				? If<IsEqual<Union, Match>, true, never>
+				: never] extends [never] ? never : Union
+			: never;
+		// If `Match` is `any` or `never`, then return `never`,
+		// because `Union` cannot be `any` or `never` here.
+		ifAny: never;
+		ifNever: never;
+	}>;
+
+export {};

package/source/get.d.ts

@@ -161,7 +161,7 @@ type PropertyOf<BaseType, Key extends string, Options extends Required<GetOption
 
 // This works by first splitting the path based on `.` and `[...]` characters into a tuple of string keys. Then it recursively uses the head key to get the next property of the current object, until there are no keys left. Number keys extract the item type from arrays, or are converted to strings to extract types from tuples and dictionaries with number keys.
 /**
-Get a deeply-nested property from an object using a key path, like Lodash's `.get()` function.
+Get a deeply-nested property from an object using a key path, like [Lodash's `.get()`](https://lodash.com/docs#get) function.
 
 Use-case: Retrieve a property from deep inside an API response or some other complex object.
 

package/source/greater-than-or-equal.d.ts

@@ -16,9 +16,42 @@ type B = GreaterThanOrEqual<1, 1>;
 type C = GreaterThanOrEqual<1, 5>;
 //=> false
 ```
+
+Note: If either argument is the non-literal `number` type, the result is `boolean`.
+
+@example
+```
+import type {GreaterThanOrEqual} from 'type-fest';
+
+type A = GreaterThanOrEqual<number, 1>;
+//=> boolean
+
+type B = GreaterThanOrEqual<1, number>;
+//=> boolean
+
+type C = GreaterThanOrEqual<number, number>;
+//=> boolean
+```
+
+@example
+```
+import type {GreaterThanOrEqual} from 'type-fest';
+
+// Use `GreaterThanOrEqual` to constrain a function parameter to non-negative numbers.
+declare function setNonNegative<N extends number>(value: GreaterThanOrEqual<N, 0> extends true ? N : never): void;
+
+setNonNegative(0); // ✅ Allowed
+setNonNegative(1); // ✅ Allowed
+
+// @ts-expect-error
+setNonNegative(-1);
+
+// @ts-expect-error
+setNonNegative(-2);
+```
 */
 export type GreaterThanOrEqual<A extends number, B extends number> = number extends A | B
-	? never
+	? boolean
 	: A extends number // For distributing `A`
 		? B extends number // For distributing `B`
 			? A extends B

package/source/greater-than.d.ts

@@ -1,8 +1,9 @@
-import type {NumberAbsolute, PositiveNumericStringGt} from './internal/index.d.ts';
+import type {PositiveNumericStringGt} from './internal/index.d.ts';
 import type {IsEqual} from './is-equal.d.ts';
 import type {PositiveInfinity, NegativeInfinity, IsNegative} from './numeric.d.ts';
 import type {And} from './and.d.ts';
 import type {Or} from './or.d.ts';
+import type {Absolute} from './absolute.d.ts';
 
 /**
 Returns a boolean for whether a given number is greater than another number.
@@ -20,12 +21,45 @@ type B = GreaterThan<1, 1>;
 type C = GreaterThan<1, 5>;
 //=> false
 ```
+
+Note: If either argument is the non-literal `number` type, the result is `boolean`.
+
+@example
+```
+import type {GreaterThan} from 'type-fest';
+
+type A = GreaterThan<number, 1>;
+//=> boolean
+
+type B = GreaterThan<1, number>;
+//=> boolean
+
+type C = GreaterThan<number, number>;
+//=> boolean
+```
+
+@example
+```
+import type {GreaterThan} from 'type-fest';
+
+// Use `GreaterThan` to constrain a function parameter to positive numbers.
+declare function setPositive<N extends number>(value: GreaterThan<N, 0> extends true ? N : never): void;
+
+setPositive(1); // ✅ Allowed
+setPositive(2); // ✅ Allowed
+
+// @ts-expect-error
+setPositive(0);
+
+// @ts-expect-error
+setPositive(-1);
+```
 */
 export type GreaterThan<A extends number, B extends number> =
 	A extends number // For distributing `A`
 		? B extends number // For distributing `B`
 			? number extends A | B
-				? never
+				? boolean
 				: [
 					IsEqual<A, PositiveInfinity>, IsEqual<A, NegativeInfinity>,
 					IsEqual<B, PositiveInfinity>, IsEqual<B, NegativeInfinity>,
@@ -49,7 +83,7 @@ export type GreaterThan<A extends number, B extends number> =
 											? true
 											: [false, false] extends R
 												? PositiveNumericStringGt<`${A}`, `${B}`>
-												: PositiveNumericStringGt<`${NumberAbsolute<B>}`, `${NumberAbsolute<A>}`>
+												: PositiveNumericStringGt<`${Absolute<B>}`, `${Absolute<A>}`>
 									: never
 					: never
 			: never // Should never happen

package/source/has-optional-keys.d.ts

@@ -1,7 +1,7 @@
 import type {OptionalKeysOf} from './optional-keys-of.d.ts';
 
 /**
-Creates a type that represents `true` or `false` depending on whether the given type has any optional fields.
+Returns a boolean for whether the given type has any optional fields.
 
 This is useful when you want to create an API whose behavior depends on the presence or absence of optional fields.
 

package/source/has-readonly-keys.d.ts

@@ -1,7 +1,7 @@
 import type {ReadonlyKeysOf} from './readonly-keys-of.d.ts';
 
 /**
-Creates a type that represents `true` or `false` depending on whether the given type has any readonly fields.
+Returns a boolean for whether the given type has any readonly fields.
 
 This is useful when you want to create an API whose behavior depends on the presence or absence of readonly fields.
 

package/source/has-required-keys.d.ts

@@ -1,7 +1,7 @@
 import type {RequiredKeysOf} from './required-keys-of.d.ts';
 
 /**
-Creates a type that represents `true` or `false` depending on whether the given type has any required fields.
+Returns a boolean for whether the given type has any required fields.
 
 This is useful when you want to create an API whose behavior depends on the presence or absence of required fields.
 

package/source/has-writable-keys.d.ts

@@ -1,7 +1,7 @@
 import type {WritableKeysOf} from './writable-keys-of.d.ts';
 
 /**
-Creates a type that represents `true` or `false` depending on whether the given type has any writable fields.
+Returns a boolean for whether the given type has any writable fields.
 
 This is useful when you want to create an API whose behavior depends on the presence or absence of writable fields.
 

package/source/int-closed-range.d.ts

@@ -2,9 +2,7 @@ import type {IntRange} from './int-range.d.ts';
 import type {Sum} from './sum.d.ts';
 
 /**
-Generate a union of numbers.
-
-The numbers are created from the given `Start` (inclusive) parameter to the given `End` (inclusive) parameter.
+Generate a union of numbers between a specified start and end (both inclusive), with an optional step.
 
 You skip over numbers using the `Step` parameter (defaults to `1`). For example, `IntClosedRange<0, 10, 2>` will create a union of `0 | 2 | 4 | 6 | 8 | 10`.
 

package/source/int-range.d.ts

@@ -2,9 +2,7 @@ import type {TupleOf} from './tuple-of.d.ts';
 import type {Subtract} from './subtract.d.ts';
 
 /**
-Generate a union of numbers.
-
-The numbers are created from the given `Start` (inclusive) parameter to the given `End` (exclusive) parameter.
+Generate a union of numbers between a specified start (inclusive) and end (exclusive), with an optional step.
 
 You skip over numbers using the `Step` parameter (defaults to `1`). For example, `IntRange<0, 10, 2>` will create a union of `0 | 2 | 4 | 6 | 8`.
 
@@ -56,9 +54,9 @@ type PrivateIntRange<
 	// The final `List` is `[...StartLengthTuple, ...[number, ...GapLengthTuple], ...[number, ...GapLengthTuple], ... ...]`, so can initialize the `List` with `[...StartLengthTuple]`
 	List extends unknown[] = TupleOf<Start, never>,
 	EndLengthTuple extends unknown[] = TupleOf<End>,
-> = Gap extends 0 ?
+> = Gap extends 0
 	// Handle the case that without `Step`
-	List['length'] extends End // The result of "List[length] === End"
+	? List['length'] extends End // The result of "List[length] === End"
 		? Exclude<List[number], never> // All unused elements are `never`, so exclude them
 		: PrivateIntRange<Start, End, Step, Gap, [...List, List['length'] ]>
 	// Handle the case that with `Step`

package/source/internal/array.d.ts

@@ -4,13 +4,6 @@ import type {OptionalKeysOf} from '../optional-keys-of.d.ts';
 import type {UnknownArray} from '../unknown-array.d.ts';
 import type {IsExactOptionalPropertyTypesEnabled, IfNotAnyOrNever} from './type.d.ts';
 
-/**
-Infer the length of the given array `<T>`.
-
-@link https://itnext.io/implementing-arithmetic-within-typescripts-type-system-a1ef140a6f6f
-*/
-type ArrayLength<T extends readonly unknown[]> = T extends {readonly length: infer L} ? L : never;
-
 /**
 Matches any unknown array or tuple.
 */
@@ -36,8 +29,8 @@ type B = StaticPartOfArray<A>;
 */
 export type StaticPartOfArray<T extends UnknownArray, Result extends UnknownArray = []> =
 	T extends unknown
-		? number extends T['length'] ?
-			T extends readonly [infer U, ...infer V]
+		? number extends T['length']
+			? T extends readonly [infer U, ...infer V]
 				? StaticPartOfArray<V, [...Result, U]>
 				: Result
 			: T
@@ -76,11 +69,11 @@ type NormalResult = SetArrayAccess<ReadonlyStringArray, false>;
 ```
 */
 export type SetArrayAccess<T extends UnknownArray, IsReadonly extends boolean> =
-T extends readonly [...infer U] ?
-	IsReadonly extends true
-		? readonly [...U]
-		: [...U]
-	: T;
+	T extends readonly [...infer U]
+		? IsReadonly extends true
+			? readonly [...U]
+			: [...U]
+		: T;
 
 /**
 Returns whether the given array `T` is readonly.
@@ -118,7 +111,7 @@ type B = CollapseRestElement<[string?, string?, ...number[]]>;
 //=> [string | undefined, string | undefined, number]
 ```
 */
-export type CollapseRestElement<TArray extends UnknownArray> = IfNotAnyOrNever<TArray, _CollapseRestElement<TArray>>;
+export type CollapseRestElement<TArray extends UnknownArray> = IfNotAnyOrNever<TArray, {ifNot: _CollapseRestElement<TArray>}>;
 
 type _CollapseRestElement<
 	TArray extends UnknownArray,

package/source/internal/keys.d.ts

@@ -87,14 +87,14 @@ type Key4 = ExactKey<Object, 1>;
 @category Object
 */
 export type ExactKey<T extends object, Key extends PropertyKey> =
-Key extends keyof T
-	? Key
-	: ToString<Key> extends keyof T
-		? ToString<Key>
-		: Key extends `${infer NumberKey extends number}`
-			? NumberKey extends keyof T
-				? NumberKey
-				: never
-			: never;
+	Key extends keyof T
+		? Key
+		: ToString<Key> extends keyof T
+			? ToString<Key>
+			: Key extends `${infer NumberKey extends number}`
+				? NumberKey extends keyof T
+					? NumberKey
+					: never
+				: never;
 
 export {};

package/source/internal/numeric.d.ts

@@ -1,26 +1,8 @@
 import type {IsNever} from '../is-never.d.ts';
 import type {Finite, NegativeInfinity, PositiveInfinity} from '../numeric.d.ts';
 import type {UnknownArray} from '../unknown-array.d.ts';
-import type {StringToNumber} from './string.d.ts';
 import type {IfNotAnyOrNever, IsAnyOrNever} from './type.d.ts';
 
-/**
-Returns the absolute value of a given value.
-
-@example
-```
-type A = NumberAbsolute<-1>;
-//=> 1
-
-type B = NumberAbsolute<1>;
-//=> 1
-
-type C = NumberAbsolute<NegativeInfinity>;
-//=> PositiveInfinity
-```
-*/
-export type NumberAbsolute<N extends number> = `${N}` extends `-${infer StringPositiveN}` ? StringToNumber<StringPositiveN> : N;
-
 /**
 Check whether the given type is a number or a number string.
 
@@ -44,11 +26,13 @@ type E = IsNumberLike<'a'>;
 //=> false
 */
 export type IsNumberLike<N> =
-	IfNotAnyOrNever<N,
-		N extends number | `${number}`
+	IfNotAnyOrNever<N, {
+		ifNot: N extends number | `${number}`
 			? true
-			: false,
-		boolean, false>;
+			: false;
+		ifAny: boolean;
+		ifNever: false;
+	}>;
 
 /**
 Returns the minimum number in the given union of numbers.
@@ -142,10 +126,18 @@ type D = ReverseSign<PositiveInfinity>;
 */
 export type ReverseSign<N extends number> =
 	// Handle edge cases
-	N extends 0 ? 0 : N extends PositiveInfinity ? NegativeInfinity : N extends NegativeInfinity ? PositiveInfinity :
-	// Handle negative numbers
-	`${N}` extends `-${infer P extends number}` ? P
-		// Handle positive numbers
-		: `-${N}` extends `${infer R extends number}` ? R : never;
+	N extends 0
+		? 0
+		: N extends PositiveInfinity
+			? NegativeInfinity
+			: N extends NegativeInfinity
+				? PositiveInfinity
+				// Handle negative numbers
+				: `${N}` extends `-${infer P extends number}`
+					? P
+					// Handle positive numbers
+					: `-${N}` extends `${infer R extends number}`
+						? R
+						: never;
 
 export {};