type-fest 5.2.0 → 5.3.0

package/source/internal/string.d.ts

@@ -51,16 +51,16 @@ Returns a boolean for whether the given string `S` starts with the given string
 
 @example
 ```
-StartsWith<'abcde', 'abc'>;
+type A = StartsWith<'abcde', 'abc'>;
 //=> true
 
-StartsWith<'abcde', 'bc'>;
+type B = StartsWith<'abcde', 'bc'>;
 //=> false
 
-StartsWith<string, 'bc'>;
+type C = StartsWith<string, 'bc'>;
 //=> never
 
-StartsWith<'abcde', string>;
+type D = StartsWith<'abcde', string>;
 //=> never
 ```
 
@@ -78,10 +78,10 @@ Returns an array of the characters of the string.
 
 @example
 ```
-StringToArray<'abcde'>;
+type A = StringToArray<'abcde'>;
 //=> ['a', 'b', 'c', 'd', 'e']
 
-StringToArray<string>;
+type B = StringToArray<string>;
 //=> never
 ```
 
@@ -98,10 +98,10 @@ Returns the length of the given string.
 
 @example
 ```
-StringLength<'abcde'>;
+type A = StringLength<'abcde'>;
 //=> 5
 
-StringLength<string>;
+type B = StringLength<string>;
 //=> never
 ```
 
@@ -137,10 +137,10 @@ Returns a boolean for whether `A` represents a number greater than `B`, where `A
 
 @example
 ```
-SameLengthPositiveNumericStringGt<'50', '10'>;
+type A = SameLengthPositiveNumericStringGt<'50', '10'>;
 //=> true
 
-SameLengthPositiveNumericStringGt<'10', '10'>;
+type B = SameLengthPositiveNumericStringGt<'10', '10'>;
 //=> false
 ```
 */
@@ -159,13 +159,13 @@ Returns a boolean for whether `A` is greater than `B`, where `A` and `B` are bot
 
 @example
 ```
-PositiveNumericStringGt<'500', '1'>;
+type A = PositiveNumericStringGt<'500', '1'>;
 //=> true
 
-PositiveNumericStringGt<'1', '1'>;
+type B = PositiveNumericStringGt<'1', '1'>;
 //=> false
 
-PositiveNumericStringGt<'1', '500'>;
+type C = PositiveNumericStringGt<'1', '500'>;
 //=> false
 ```
 */
@@ -184,10 +184,10 @@ Returns a boolean for whether `A` represents a number greater than `B`, where `A
 
 @example
 ```
-PositiveNumericCharacterGt<'5', '1'>;
+type A = PositiveNumericCharacterGt<'5', '1'>;
 //=> true
 
-PositiveNumericCharacterGt<'1', '1'>;
+type B = PositiveNumericCharacterGt<'1', '1'>;
 //=> false
 ```
 */

package/source/internal/tuple.d.ts

@@ -17,7 +17,7 @@ type Array = TupleLength<string[]>;
 //=> never
 
 // Supports union types.
-type Union = TupleLength<[] | [1, 2, 3] | Array<number>>;
+type Union = TupleLength<[] | [1, 2, 3] | number[]>;
 //=> 1 | 3
 ```
 */
@@ -38,10 +38,10 @@ Note:
 
 @example
 ```
-ArrayMax<[1, 2, 5, 3]>;
+type A = TupleMax<[1, 2, 5, 3]>;
 //=> 5
 
-ArrayMax<[1, 2, 5, 3, 99, -1]>;
+type B = TupleMax<[1, 2, 5, 3, 99, -1]>;
 //=> 99
 ```
 */
@@ -61,10 +61,10 @@ Note:
 
 @example
 ```
-ArrayMin<[1, 2, 5, 3]>;
+type A = TupleMin<[1, 2, 5, 3]>;
 //=> 1
 
-ArrayMin<[1, 2, 5, 3, -5]>;
+type B = TupleMin<[1, 2, 5, 3, -5]>;
 //=> -5
 ```
 */

package/source/internal/type.d.ts

@@ -12,7 +12,7 @@ export type BuiltIns = Primitive | void | Date | RegExp;
 /**
 Matches non-recursive types.
 */
-export type NonRecursiveType = BuiltIns | Function | (new (...arguments_: any[]) => unknown);
+export type NonRecursiveType = BuiltIns | Function | (new (...arguments_: any[]) => unknown) | Promise<unknown>;
 
 /**
 Matches maps, sets, or arrays.
@@ -55,13 +55,13 @@ Returns a boolean for whether the given type is primitive value or primitive typ
 
 @example
 ```
-IsPrimitive<'string'>
+type A = IsPrimitive<'string'>;
 //=> true
 
-IsPrimitive<string>
+type B = IsPrimitive<string>;
 //=> true
 
-IsPrimitive<Object>
+type C = IsPrimitive<Object>;
 //=> false
 ```
 */
@@ -72,10 +72,10 @@ Returns a boolean for whether A is false.
 
 @example
 ```
-Not<true>;
+type A = Not<true>;
 //=> false
 
-Not<false>;
+type B = Not<false>;
 //=> true
 ```
 */

package/source/invariant-of.d.ts

@@ -12,23 +12,28 @@ Use-case:
 import type {InvariantOf} from 'type-fest';
 
 class Animal {
-	constructor(public name: string){}
+	constructor(public name: string) {}
 }
 
 class Cat extends Animal {
-	meow() {}
+	meow() {
+		// do something
+	}
 }
 
-let animalArray: Animal[] = [animal];
-let catArray: Cat[] = [cat];
+let animalArray: Animal[] = [new Animal('jerry')];
+const catArray: Cat[] = [new Cat('tom')];
 
 animalArray = catArray; // Okay if covariant
 animalArray.push(new Animal('another animal')); // Pushed an animal into catArray
-catArray.forEach(c => c.meow()); // Allowed but, error at runtime
+for (const c of catArray) {
+	c.meow();
+} // Allowed but, error at runtime
 
-let invariantAnimalArray: InvariantOf<Animal>[] = [animal] as InvariantOf<Animal>[];
-let invariantCatArray: InvariantOf<Cat>[] = [cat] as InvariantOf<Cat>[];
+let invariantAnimalArray: Array<InvariantOf<Animal>> = [new Animal('jerry')] as Array<InvariantOf<Animal>>;
+const invariantCatArray: Array<InvariantOf<Cat>> = [new Cat('tom')] as Array<InvariantOf<Cat>>;
 
+// @ts-expect-error
 invariantAnimalArray = invariantCatArray; // Error: Type 'InvariantOf<Cat>[]' is not assignable to type 'InvariantOf<Animal>[]'.
 ```
 
@@ -38,24 +43,24 @@ import type {InvariantOf} from 'type-fest';
 
 // In covariance (default)
 
-interface FooBar {
+type FooBar = {
 	foo: number;
-	bar: string
-}
+	bar: string;
+};
 
-interface FooBarBaz extends FooBar {
-	baz: boolean
-}
+type FooBarBaz = {
+	baz: boolean;
+} & FooBar;
 
-declare const fooBar: FooBar
-declare const fooBarBaz: FooBarBaz
+declare const fooBar: FooBar;
+declare const fooBarBaz: FooBarBaz;
 
 function keyOfFooBar(fooBar: FooBar) {
-	return Object.keys(fooBar) as (keyof FooBar)[]
+	return Object.keys(fooBar) as Array<keyof FooBar>;
 }
 
-keyOfFooBar(fooBar) //=> (keyof FooBar)[]
-keyOfFooBar(fooBarBaz) //=> (keyof FooBar)[] but, (keyof FooBarBaz)[] at runtime
+keyOfFooBar(fooBar); //=> (keyof FooBar)[]
+keyOfFooBar(fooBarBaz); //=> (keyof FooBar)[] but, (keyof FooBarBaz)[] at runtime
 
 // In invariance
 
@@ -64,10 +69,12 @@ export function invariantOf<Type>(value: Type): InvariantOf<Type> {
 }
 
 function keyOfInvariantFooBar(fooBar: InvariantOf<FooBar>) {
-	return Object.keys(fooBar) as (keyof FooBar)[]
+	return Object.keys(fooBar) as Array<keyof FooBar>;
 }
 
 keyOfInvariantFooBar(invariantOf(fooBar)); // (keyof FooBar)[]
+
+// @ts-expect-error
 keyOfInvariantFooBar(invariantOf(fooBarBaz)); // Error: Argument of type 'InvariantOf<FooBarBaz>' is not assignable to parameter of type 'InvariantOf<FooBar>'.
 ```
 

package/source/is-any.d.ts

@@ -12,8 +12,8 @@ import type {IsAny} from 'type-fest';
 const typedObject = {a: 1, b: 2} as const;
 const anyObject: any = {a: 1, b: 2};
 
-function get<O extends (IsAny<O> extends true ? {} : Record<string, number>), K extends keyof O = keyof O>(obj: O, key: K) {
-	return obj[key];
+function get<O extends (IsAny<O> extends true ? {} : Record<string, number>), K extends keyof O = keyof O>(object: O, key: K) {
+	return object[key];
 }
 
 const typedA = get(typedObject, 'a');

package/source/is-equal.d.ts

@@ -26,14 +26,10 @@ type Includes<Value extends readonly any[], Item> =
 @category Utilities
 */
 export type IsEqual<A, B> =
-	[A, B] extends [infer AA, infer BB]
-		? [AA] extends [never]
-			? [BB] extends [never]
-				? true
-				: false
-			: [BB] extends [never]
-				? false
-				: _IsEqual<AA, BB>
+	[A] extends [B]
+		? [B] extends [A]
+			? _IsEqual<A, B>
+			: false
 		: false;
 
 // This version fails the `equalWrappedTupleIntersectionToBeNeverAndNeverExpanded` test in `test-d/is-equal.ts`.

package/source/is-integer.d.ts

@@ -30,7 +30,7 @@ type E = IsInteger<0o10>;
 type F = IsInteger<0x10>;
 //=> true
 
-type G = IsInteger<1.23+21>;
+type G = IsInteger<1.23e+21>;
 //=> true
 
 type H = IsInteger<1.5>;

package/source/is-literal.d.ts

@@ -11,13 +11,13 @@ Returns a boolean for whether the given type `T` is the specified `LiteralType`.
 
 @example
 ```
-LiteralCheck<1, number>
+type A = LiteralCheck<1, number>;
 //=> true
 
-LiteralCheck<number, number>
+type B = LiteralCheck<number, number>;
 //=> false
 
-LiteralCheck<1, string>
+type C = LiteralCheck<1, string>;
 //=> false
 ```
 */
@@ -38,13 +38,13 @@ Returns a boolean for whether the given type `T` is one of the specified literal
 
 @example
 ```
-LiteralChecks<1, Numeric>
+type A = LiteralChecks<1, Numeric>;
 //=> true
 
-LiteralChecks<1n, Numeric>
+type B = LiteralChecks<1n, Numeric>;
 //=> true
 
-LiteralChecks<bigint, Numeric>
+type C = LiteralChecks<bigint, Numeric>;
 //=> false
 ```
 */
@@ -136,7 +136,7 @@ Useful for:
 
 @example
 ```
-import type {IsNumericLiteral} from 'type-fest';
+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> =
@@ -161,7 +161,7 @@ function endsWith<Input extends string | number, End extends string>(input: Inpu
 endsWith('abc', 'c');
 //=> true
 
-endsWith(123456, '456');
+endsWith(123_456, '456');
 //=> true
 
 const end = '123' as string;
@@ -226,17 +226,17 @@ Useful for:
 ```
 import type {IsSymbolLiteral} from 'type-fest';
 
-type Get<Obj extends Record<symbol, number>, Key extends keyof Obj> =
+type Get<Object_ extends Record<symbol, number>, Key extends keyof Object_> =
 	IsSymbolLiteral<Key> extends true
-		? Obj[Key]
+		? Object_[Key]
 		: number;
 
-function get<Obj extends Record<symbol, number>, Key extends keyof Obj>(o: Obj, key: Key) {
-	return o[key] as Get<Obj, Key>;
+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');
-const symbolValue: symbol = Symbol('value');
+const symbolValue = Symbol('value');
 
 get({[symbolLiteral]: 1} as const, symbolLiteral);
 //=> 1

package/source/is-lowercase.d.ts

@@ -7,13 +7,13 @@ Returns a boolean for whether the given string literal is lowercase.
 ```
 import type {IsLowercase} from 'type-fest';
 
-IsLowercase<'abc'>;
+type A = IsLowercase<'abc'>;
 //=> true
 
-IsLowercase<'Abc'>;
+type B = IsLowercase<'Abc'>;
 //=> false
 
-IsLowercase<string>;
+type C = IsLowercase<string>;
 //=> boolean
 ```
 */

package/source/is-never.d.ts

@@ -11,29 +11,41 @@ Useful in type utilities, such as checking if something does not occur.
 ```
 import type {IsNever, And} from 'type-fest';
 
-// https://github.com/andnp/SimplyTyped/blob/master/src/types/strings.ts
-type AreStringsEqual<A extends string, B extends string> =
-	And<
-		IsNever<Exclude<A, B>> extends true ? true : false,
-		IsNever<Exclude<B, A>> extends true ? true : false
-	>;
-
-type EndIfEqual<I extends string, O extends string> =
-	AreStringsEqual<I, O> extends true
-		? never
-		: void;
-
-function endIfEqual<I extends string, O extends string>(input: I, output: O): EndIfEqual<I, O> {
-	if (input === output) {
-		process.exit(0);
-	}
-}
-
-endIfEqual('abc', 'abc');
-//=> never
-
-endIfEqual('abc', '123');
-//=> void
+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>;
+//   ^? type A = 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>;
+//   ^? type B = false
 ```
 
 @category Type Guard

package/source/is-null.d.ts

@@ -11,7 +11,7 @@ type Example1 = NonNullFallback<null, string>;
 //=> string
 
 type Example2 = NonNullFallback<number, string>;
-//=? number
+//=> number
 ```
 
 @category Type Guard

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

@@ -9,17 +9,17 @@ This is useful when writing utility types or schema validators that need to diff
 ```
 import type {IsOptionalKeyOf} from 'type-fest';
 
-interface User {
+type User = {
 	name: string;
 	surname: string;
 
 	luckyNumber?: number;
-}
+};
 
-interface Admin {
+type Admin = {
 	name: string;
 	surname?: string;
-}
+};
 
 type T1 = IsOptionalKeyOf<User, 'luckyNumber'>;
 //=> true

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

@@ -10,17 +10,17 @@ This is useful when writing utility types or schema validators that need to diff
 ```
 import type {IsReadonlyKeyOf} from 'type-fest';
 
-interface User {
+type User = {
 	name: string;
 	surname: string;
 
 	readonly id: number;
-}
+};
 
-interface Admin {
+type Admin = {
 	name: string;
 	id: string;
-}
+};
 
 type T1 = IsReadonlyKeyOf<User, 'id'>;
 //=> true

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

@@ -11,17 +11,17 @@ This is useful when writing utility types or schema validators that need to diff
 ```
 import type {IsRequiredKeyOf} from 'type-fest';
 
-interface User {
+type User = {
 	name: string;
 	surname: string;
 
 	luckyNumber?: number;
-}
+};
 
-interface Admin {
+type Admin = {
 	name: string;
 	surname?: string;
-}
+};
 
 type T1 = IsRequiredKeyOf<User, 'name'>;
 //=> true

package/source/is-unknown.d.ts

@@ -11,34 +11,23 @@ Useful in type utilities, such as when dealing with unknown data from API calls.
 ```
 import type {IsUnknown} from 'type-fest';
 
-// https://github.com/pajecawav/tiny-global-store/blob/master/src/index.ts
-type Action<TState, TPayload = void> =
-	IsUnknown<TPayload> extends true
-		? (state: TState) => TState,
-		: (state: TState, payload: TPayload) => TState;
+type A = IsUnknown<unknown>;
+//=> unknown
 
-class Store<TState> {
-	constructor(private state: TState) {}
+type B = IsUnknown<any>;
+//=> false
 
-	execute<TPayload = void>(action: Action<TState, TPayload>, payload?: TPayload): TState {
-		this.state = action(this.state, payload);
-		return this.state;
-	}
+type C = IsUnknown<never>;
+//=> false
 
-	// ... other methods
-}
+type D = IsUnknown<unknown[]>;
+//=> false
 
-const store = new Store({value: 1});
-declare const someExternalData: unknown;
+type E = IsUnknown<object>;
+//=> false
 
-store.execute(state => ({value: state.value + 1}));
-//=> `TPayload` is `void`
-
-store.execute((state, payload) => ({value: state.value + payload}), 5);
-//=> `TPayload` is `5`
-
-store.execute((state, payload) => ({value: state.value + payload}), someExternalData);
-//=> Errors: `action` is `(state: TState) => TState`
+type F = IsUnknown<string>;
+//=> false
 ```
 
 @category Utilities

package/source/is-uppercase.d.ts

@@ -7,13 +7,13 @@ Returns a boolean for whether the given string literal is uppercase.
 ```
 import type {IsUppercase} from 'type-fest';
 
-IsUppercase<'ABC'>;
+type A = IsUppercase<'ABC'>;
 //=> true
 
-IsUppercase<'Abc'>;
+type B = IsUppercase<'Abc'>;
 //=> false
 
-IsUppercase<string>;
+type C = IsUppercase<string>;
 //=> boolean
 ```
 */

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

@@ -11,17 +11,17 @@ This is useful when writing utility types or schema validators that need to diff
 ```
 import type {IsWritableKeyOf} from 'type-fest';
 
-interface User {
+type User = {
 	name: string;
 	surname: string;
 
 	readonly id: number;
-}
+};
 
-interface Admin {
+type Admin = {
 	name: string;
 	id: string;
-}
+};
 
 type T1 = IsWritableKeyOf<User, 'name'>;
 //=> true

package/source/iterable-element.d.ts

@@ -16,7 +16,7 @@ function * iAmGenerator() {
 	yield 2;
 }
 
-type MeNumber = IterableElement<ReturnType<typeof iAmGenerator>>
+type MeNumber = IterableElement<ReturnType<typeof iAmGenerator>>;
 ```
 
 And here is an example with an async generator:
@@ -30,7 +30,7 @@ async function * iAmGeneratorAsync() {
 	yield true;
 }
 
-type MeStringOrBoolean = IterableElement<ReturnType<typeof iAmGeneratorAsync>>
+type MeStringOrBoolean = IterableElement<ReturnType<typeof iAmGeneratorAsync>>;
 ```
 
 Many types in JavaScript/TypeScript are iterables. This type works on all types that implement those interfaces.
@@ -41,7 +41,7 @@ An example with an array of strings:
 ```
 import type {IterableElement} from 'type-fest';
 
-type MeString = IterableElement<string[]>
+type MeString = IterableElement<string[]>;
 ```
 
 @example