type-fest 5.2.0 → 5.3.0

package/source/exact.d.ts

@@ -24,9 +24,10 @@ This is useful for function type-guarding to reject arguments with excess proper
 ```
 type OnlyAcceptName = {name: string};
 
-function onlyAcceptName(arguments_: OnlyAcceptName) {}
+declare function onlyAcceptName(arguments_: OnlyAcceptName): void;
 
 // TypeScript complains about excess properties when an object literal is provided.
+// @ts-expect-error
 onlyAcceptName({name: 'name', id: 1});
 //=> `id` is excess
 
@@ -39,13 +40,14 @@ Having `Exact` allows TypeScript to reject excess properties.
 
 @example
 ```
-import {Exact} from 'type-fest';
+import type {Exact} from 'type-fest';
 
 type OnlyAcceptName = {name: string};
 
-function onlyAcceptNameImproved<T extends Exact<OnlyAcceptName, T>>(arguments_: T) {}
+declare function onlyAcceptNameImproved<T extends Exact<OnlyAcceptName, T>>(arguments_: T): void;
 
 const invalidInput = {name: 'name', id: 1};
+// @ts-expect-error
 onlyAcceptNameImproved(invalidInput); // Compilation error
 ```
 

package/source/except.d.ts

@@ -66,12 +66,14 @@ type Foo = {
 type FooWithoutA = Except<Foo, 'a'>;
 //=> {b: string}
 
+// @ts-expect-error
 const fooWithoutA: FooWithoutA = {a: 1, b: '2'};
 //=> errors: 'a' does not exist in type '{ b: string; }'
 
 type FooWithoutB = Except<Foo, 'b', {requireExactProps: true}>;
 //=> {a: number} & Partial<Record<"b", never>>
 
+// @ts-expect-error
 const fooWithoutB: FooWithoutB = {a: 1, b: '2'};
 //=> errors at 'b': Type 'string' is not assignable to type 'undefined'.
 
@@ -88,12 +90,12 @@ type UserData = {
 
 // `Omit` clearly doesn't behave as expected in this case:
 type PostPayload = Omit<UserData, 'email'>;
-//=> type PostPayload = { [x: string]: string; [x: number]: string; }
+//=> { [x: string]: string; [x: number]: string; }
 
 // In situations like this, `Except` works better.
 // It simply removes the `email` key while preserving all the other keys.
-type PostPayload = Except<UserData, 'email'>;
-//=> type PostPayload = { [x: string]: string; name: string; role: 'admin' | 'user'; }
+type PostPayloadFixed = Except<UserData, 'email'>;
+//=> { [x: string]: string; name: string; role: 'admin' | 'user'; }
 ```
 
 @category Object

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

@@ -16,7 +16,7 @@ type T1 = ExcludeRestElement<[number, ...string[], string, 'foo']>;
 type T2 = ExcludeRestElement<[...boolean[], string]>;
 //=> [string]
 
-type T3 = ExcludeRestElement<[...'foo'[], true]>;
+type T3 = ExcludeRestElement<[...Array<'foo'>, true]>;
 //=> [true]
 
 type T4 = ExcludeRestElement<[number, string]>;

package/source/exclude-strict.d.ts

@@ -6,6 +6,7 @@ For example, `ExcludeStrict<string | number | boolean, number | bigint>` will er
 @example
 ```
 // Valid Examples
+import type {ExcludeStrict} from 'type-fest';
 
 type Example1 = ExcludeStrict<{status: 'success'; data: string[]} | {status: 'error'; error: string}, {status: 'success'}>;
 //=> {status: 'error'; error: string}
@@ -20,13 +21,16 @@ type Example3 = ExcludeStrict<{x: number; y: number} | [number, number], unknown
 @example
 ```
 // Invalid Examples
+import type {ExcludeStrict} from 'type-fest';
 
 // `'xxl'` cannot exclude anything from `'xs' | 's' | 'm' | 'l' | 'xl'`
+// @ts-expect-error
 type Example1 = ExcludeStrict<'xs' | 's' | 'm' | 'l' | 'xl', 'xl' | 'xxl'>;
 //                                                           ~~~~~~~~~~~~
 // Error: Type "'xl' | 'xxl'" does not satisfy the constraint 'never'.
 
 // `unknown[]` cannot exclude anything from `{x: number; y: number} | {x: string; y: string}`
+// @ts-expect-error
 type Example2 = ExcludeStrict<{x: number; y: number} | {x: string; y: string}, unknown[]>;
 //                                                                             ~~~~~~~~~
 // Error: Type 'unknown[]' does not satisfy the constraint 'never'.

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

@@ -14,7 +14,7 @@ type T1 = ExtractRestElement<[number, ...string[], string, 'foo']>;
 type T2 = ExtractRestElement<[...boolean[], string]>;
 //=> boolean
 
-type T3 = ExtractRestElement<[...'foo'[], true]>;
+type T3 = ExtractRestElement<[...Array<'foo'>, true]>;
 //=> 'foo'
 
 type T4 = ExtractRestElement<[number, string]>;

package/source/extract-strict.d.ts

@@ -6,6 +6,7 @@ For example, `ExtractStrict<string | number | boolean, number | bigint>` will er
 @example
 ```
 // Valid Examples
+import type {ExtractStrict} from 'type-fest';
 
 type Example1 = ExtractStrict<{status: 'success'; data: string[]} | {status: 'error'; error: string}, {status: 'success'}>;
 //=> {status: 'success'; data: string[]}
@@ -20,13 +21,16 @@ type Example3 = ExtractStrict<{x: number; y: number} | [number, number], unknown
 @example
 ```
 // Invalid Examples
+import type {ExtractStrict} from 'type-fest';
 
 // `'xxl'` cannot extract anything from `'xs' | 's' | 'm' | 'l' | 'xl'`
+// @ts-expect-error
 type Example1 = ExtractStrict<'xs' | 's' | 'm' | 'l' | 'xl', 'xl' | 'xxl'>;
 //                                                           ~~~~~~~~~~~~
 // Error: Type "'xl' | 'xxl'" does not satisfy the constraint 'never'.
 
 // `unknown[]` cannot extract anything from `{x: number; y: number} | {x: string; y: string}`
+// @ts-expect-error
 type Example2 = ExtractStrict<{x: number; y: number} | {x: string; y: string}, unknown[]>;
 //                                                                             ~~~~~~~~~
 // Error: Type 'unknown[]' does not satisfy the constraint 'never'.

package/source/find-global-type.d.ts

@@ -9,12 +9,12 @@ import type {FindGlobalType} from 'type-fest';
 
 declare global {
 	const foo: number; // let and const don't work
-	var bar: string;   // var works
+	var bar: string; // var works
 }
 
-type FooType = FindGlobalType<'foo'>     //=> never (let/const don't work)
-type BarType = FindGlobalType<'bar'>     //=> string
-type OtherType = FindGlobalType<'other'> //=> never (no global named 'other')
+type FooType = FindGlobalType<'foo'>; //=> never (let/const don't work)
+type BarType = FindGlobalType<'bar'>; //=> string
+type OtherType = FindGlobalType<'other'>; //=> never (no global named 'other')
 ```
 
 @category Utilities
@@ -48,7 +48,9 @@ declare global {
 	class Foo {}
 
 	// interface + constructor style works
-	interface Bar {}
+	interface Bar {
+		bar: string;
+	}
 	var Bar: new () => Bar; // Not let or const
 }
 

package/source/fixed-length-array.d.ts

@@ -32,6 +32,7 @@ import type {FixedLengthArray} from 'type-fest';
 
 const color: FixedLengthArray<number, 3> = [255, 128, 64];
 
+// @ts-expect-error
 color.pop();
 //=> Error: Property 'pop' does not exist on type 'FixedLengthArray<number, 3>'.
 ```
@@ -42,6 +43,8 @@ Use-cases:
 
 @example
 ```
+import type {FixedLengthArray} from 'type-fest';
+
 let color: FixedLengthArray<number, 3> = [255, 128, 64];
 
 const red = color[0];
@@ -51,6 +54,7 @@ const green = color[1];
 const blue = color[2];
 //=> number
 
+// @ts-expect-error
 const alpha = color[3];
 //=> Error: Property '3' does not exist on type 'FixedLengthArray<number, 3>'.
 
@@ -60,15 +64,19 @@ color[1] = 64;
 color[2] = 32;
 
 // But you cannot write to out-of-bounds indices.
+// @ts-expect-error
 color[3] = 0.5;
 //=> Error: Property '3' does not exist on type 'FixedLengthArray<number, 3>'.
 
+// @ts-expect-error
 color.push(0.5);
 //=> Error: Property 'push' does not exist on type 'FixedLengthArray<number, 3>'.
 
+// @ts-expect-error
 color = [0, 128, 255, 0.5];
 //=> Error: Type '[number, number, number, number]' is not assignable to type 'FixedLengthArray<number, 3>'. Types of property 'length' are incompatible.
 
+// @ts-expect-error
 color.length = 4;
 //=> Error: Cannot assign to 'length' because it is a read-only property.
 

package/source/get.d.ts

@@ -58,10 +58,10 @@ Splits a dot-prop style path into a tuple comprised of the properties in the pat
 
 @example
 ```
-ToPath<'foo.bar.baz'>
+type A = ToPath<'foo.bar.baz'>;
 //=> ['foo', 'bar', 'baz']
 
-ToPath<'foo[0].bar.baz'>
+type B = ToPath<'foo[0].bar.baz'>;
 //=> ['foo', '0', 'bar', 'baz']
 ```
 */
@@ -84,10 +84,10 @@ Returns true if `LongString` is made up out of `Substring` repeated 0 or more ti
 
 @example
 ```
-ConsistsOnlyOf<'aaa', 'a'> //=> true
-ConsistsOnlyOf<'ababab', 'ab'> //=> true
-ConsistsOnlyOf<'aBa', 'a'> //=> false
-ConsistsOnlyOf<'', 'a'> //=> true
+type A = ConsistsOnlyOf<'aaa', 'a'>; //=> true
+type B = ConsistsOnlyOf<'ababab', 'ab'>; //=> true
+type C = ConsistsOnlyOf<'aBa', 'a'>; //=> false
+type D = ConsistsOnlyOf<'', 'a'>; //=> true
 ```
 */
 type ConsistsOnlyOf<LongString extends string, Substring extends string> =
@@ -168,38 +168,37 @@ Use-case: Retrieve a property from deep inside an API response or some other com
 @example
 ```
 import type {Get} from 'type-fest';
-import * as lodash from 'lodash';
 
-const get = <BaseType, Path extends string | readonly string[]>(object: BaseType, path: Path): Get<BaseType, Path> =>
-	lodash.get(object, path);
+declare function get<BaseType, const Path extends string | readonly string[]>(object: BaseType, path: Path): Get<BaseType, Path>;
 
-interface ApiResponse {
+type ApiResponse = {
 	hits: {
 		hits: Array<{
-			_id: string
+			_id: string;
 			_source: {
 				name: Array<{
-					given: string[]
-					family: string
-				}>
-				birthDate: string
-			}
-		}>
-	}
-}
-
-const getName = (apiResponse: ApiResponse) =>
-	get(apiResponse, 'hits.hits[0]._source.name');
-	//=> Array<{given: string[]; family: string}> | undefined
+					given: string[];
+					family: string;
+				}>;
+				birthDate: string;
+			};
+		}>;
+	};
+};
+
+const getName = (apiResponse: ApiResponse) => get(apiResponse, 'hits.hits[0]._source.name');
+//=> (apiResponse: ApiResponse) => {given: string[]; family: string}[] | undefined
 
 // Path also supports a readonly array of strings
-const getNameWithPathArray = (apiResponse: ApiResponse) =>
-	get(apiResponse, ['hits','hits', '0', '_source', 'name'] as const);
-	//=> Array<{given: string[]; family: string}> | undefined
+const getNameWithPathArray = (apiResponse: ApiResponse) => get(apiResponse, ['hits', 'hits', '0', '_source', 'name']);
+//=> (apiResponse: ApiResponse) => {given: string[]; family: string}[] | undefined
 
 // Non-strict mode:
-Get<string[], '3', {strict: false}> //=> string
-Get<Record<string, string>, 'foo', {strict: true}> // => string
+type A = Get<string[], '3', {strict: false}>;
+//=> string
+
+type B = Get<Record<string, string>, 'foo', {strict: true}>;
+// => string | undefined
 ```
 
 @category Object

package/source/global-this.d.ts

@@ -13,7 +13,8 @@ type ExtraGlobals = GlobalThis & {
 	readonly GLOBAL_TOKEN: string;
 };
 
-(globalThis as ExtraGlobals).GLOBAL_TOKEN;
+const globalToken = (globalThis as ExtraGlobals).GLOBAL_TOKEN;
+//=> string
 ```
 
 @category Type

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

@@ -7,13 +7,13 @@ Returns a boolean for whether a given number is greater than or equal to another
 ```
 import type {GreaterThanOrEqual} from 'type-fest';
 
-GreaterThanOrEqual<1, -5>;
+type A = GreaterThanOrEqual<1, -5>;
 //=> true
 
-GreaterThanOrEqual<1, 1>;
+type B = GreaterThanOrEqual<1, 1>;
 //=> true
 
-GreaterThanOrEqual<1, 5>;
+type C = GreaterThanOrEqual<1, 5>;
 //=> false
 ```
 */

package/source/greater-than.d.ts

@@ -11,13 +11,13 @@ Returns a boolean for whether a given number is greater than another number.
 ```
 import type {GreaterThan} from 'type-fest';
 
-GreaterThan<1, -5>;
+type A = GreaterThan<1, -5>;
 //=> true
 
-GreaterThan<1, 1>;
+type B = GreaterThan<1, 1>;
 //=> false
 
-GreaterThan<1, 5>;
+type C = GreaterThan<1, 5>;
 //=> false
 ```
 */

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

@@ -12,8 +12,8 @@ import type {HasOptionalKeys, OptionalKeysOf} from 'type-fest';
 type UpdateService<Entity extends object> = {
 	removeField: HasOptionalKeys<Entity> extends true
 		? (field: OptionalKeysOf<Entity>) => Promise<void>
-		: never
-}
+		: never;
+};
 ```
 
 @category Utilities

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

@@ -12,8 +12,8 @@ import type {HasReadonlyKeys, ReadonlyKeysOf} from 'type-fest';
 type UpdateService<Entity extends object> = {
 	removeField: HasReadonlyKeys<Entity> extends true
 		? (field: ReadonlyKeysOf<Entity>) => Promise<void>
-		: never
-}
+		: never;
+};
 ```
 
 @category Utilities

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

@@ -16,40 +16,40 @@ type GeneratorOptions<Template extends object> = {
 	? {template: Template}
 	: {template?: Template});
 
-interface Template1 {
+type Template1 = {
 	optionalSubParam?: string;
-}
+};
 
-interface Template2 {
+type Template2 = {
 	requiredSubParam: string;
-}
+};
 
 type Options1 = GeneratorOptions<Template1>;
 type Options2 = GeneratorOptions<Template2>;
 
 const optA: Options1 = {
 	prop1: 0,
-	prop2: 'hi'
+	prop2: 'hi',
 };
 const optB: Options1 = {
 	prop1: 0,
 	prop2: 'hi',
-	template: {}
+	template: {},
 };
 const optC: Options1 = {
 	prop1: 0,
 	prop2: 'hi',
 	template: {
-		optionalSubParam: 'optional value'
-	}
+		optionalSubParam: 'optional value',
+	},
 };
 
 const optD: Options2 = {
 	prop1: 0,
 	prop2: 'hi',
 	template: {
-		requiredSubParam: 'required value'
-	}
+		requiredSubParam: 'required value',
+	},
 };
 
 ```

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

@@ -12,8 +12,8 @@ import type {HasWritableKeys, WritableKeysOf} from 'type-fest';
 type UpdateService<Entity extends object> = {
 	removeField: HasWritableKeys<Entity> extends true
 		? (field: WritableKeysOf<Entity>) => Promise<void>
-		: never
-}
+		: never;
+};
 ```
 
 @category Utilities

package/source/if.d.ts

@@ -12,7 +12,7 @@ Note:
 
 @example
 ```
-import {If} from 'type-fest';
+import type {If} from 'type-fest';
 
 type A = If<true, 'yes', 'no'>;
 //=> 'yes'
@@ -32,7 +32,7 @@ type E = If<never, 'yes', 'no'>;
 
 @example
 ```
-import {If, IsAny, IsNever} from 'type-fest';
+import type {If, IsAny, IsNever} from 'type-fest';
 
 type A = If<IsAny<unknown>, 'is any', 'not any'>;
 //=> 'not any'
@@ -43,7 +43,7 @@ type B = If<IsNever<never>, 'is never', 'not never'>;
 
 @example
 ```
-import {If, IsEqual} from 'type-fest';
+import type {If, IsEqual} from 'type-fest';
 
 type IfEqual<T, U, IfBranch, ElseBranch> = If<IsEqual<T, U>, IfBranch, ElseBranch>;
 

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

@@ -12,22 +12,32 @@ Note: `Start` or `End` must be non-negative and smaller than `999`.
 
 Use-cases:
 1. This can be used to define a set of valid input/output values. for example:
-	```
-	type Age = IntClosedRange<0, 120>; //=> 0 | 1 | 2 | ... | 119 | 120
-	type FontSize = IntClosedRange<10, 20>; //=> 10 | 11 | ... | 19 | 20
-	type EvenNumber = IntClosedRange<0, 10, 2>; //=> 0 | 2 | 4 | 6 | 8 | 10
-	```
+
+@example
+```
+import type {IntClosedRange} from 'type-fest';
+
+type Age = IntClosedRange<0, 120>;
+//=> 0 | 1 | 2 | ... | 119 | 120
+
+type FontSize = IntClosedRange<10, 20>;
+//=> 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20
+
+type EvenNumber = IntClosedRange<0, 10, 2>;
+//=> 0 | 2 | 4 | 6 | 8 | 10
+```
+
 2. This can be used to define random numbers in a range. For example, `type RandomNumber = IntClosedRange<0, 100>;`
 
 @example
 ```
 import type {IntClosedRange} from 'type-fest';
 
-// Create union type `0 | 1 | ... | 9`
 type ZeroToNine = IntClosedRange<0, 9>;
+//=> 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
 
-// Create union type `100 | 200 | 300 | ... | 900`
 type Hundreds = IntClosedRange<100, 900, 100>;
+//=> 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
 ```
 
 @see {@link IntRange}

package/source/int-range.d.ts

@@ -12,22 +12,32 @@ Note: `Start` or `End` must be non-negative and smaller than `1000`.
 
 Use-cases:
 1. This can be used to define a set of valid input/output values. for example:
-	```
-	type Age = IntRange<0, 120>;
-	type FontSize = IntRange<10, 20>;
-	type EvenNumber = IntRange<0, 11, 2>; //=> 0 | 2 | 4 | 6 | 8 | 10
-	```
+
+@example
+```
+import type {IntRange} from 'type-fest';
+
+type Age = IntRange<0, 120>;
+//=> 0 | 1 | 2 | ... | 119
+
+type FontSize = IntRange<10, 20>;
+//=> 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19
+
+type EvenNumber = IntRange<0, 11, 2>;
+//=> 0 | 2 | 4 | 6 | 8 | 10
+```
+
 2. This can be used to define random numbers in a range. For example, `type RandomNumber = IntRange<0, 100>;`
 
 @example
 ```
 import type {IntRange} from 'type-fest';
 
-// Create union type `0 | 1 | ... | 9`
 type ZeroToNine = IntRange<0, 10>;
+//=> 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
 
-// Create union type `100 | 200 | 300 | ... | 900`
 type Hundreds = IntRange<100, 901, 100>;
+//=> 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
 ```
 
 @see {@link IntClosedRange}

package/source/internal/array.d.ts

@@ -65,13 +65,13 @@ Set the given array to readonly if `IsReadonly` is `true`, otherwise set the giv
 
 @example
 ```
-type ReadonlyArray = readonly string[];
-type NormalArray = string[];
+type ReadonlyStringArray = readonly string[];
+type NormalStringArray = string[];
 
-type ReadonlyResult = SetArrayAccess<NormalArray, true>;
+type ReadonlyResult = SetArrayAccess<NormalStringArray, true>;
 //=> readonly string[]
 
-type NormalResult = SetArrayAccess<ReadonlyArray, false>;
+type NormalResult = SetArrayAccess<ReadonlyStringArray, false>;
 //=> string[]
 ```
 */

package/source/internal/numeric.d.ts

@@ -9,13 +9,13 @@ Returns the absolute value of a given value.
 
 @example
 ```
-NumberAbsolute<-1>;
+type A = NumberAbsolute<-1>;
 //=> 1
 
-NumberAbsolute<1>;
+type B = NumberAbsolute<1>;
 //=> 1
 
-NumberAbsolute<NegativeInfinity>
+type C = NumberAbsolute<NegativeInfinity>;
 //=> PositiveInfinity
 ```
 */
@@ -126,16 +126,16 @@ Returns the number with reversed sign.
 
 @example
 ```
-ReverseSign<-1>;
+type A = ReverseSign<-1>;
 //=> 1
 
-ReverseSign<1>;
+type B = ReverseSign<1>;
 //=> -1
 
-ReverseSign<NegativeInfinity>
+type C = ReverseSign<NegativeInfinity>;
 //=> PositiveInfinity
 
-ReverseSign<PositiveInfinity>
+type D = ReverseSign<PositiveInfinity>;
 //=> NegativeInfinity
 ```
 */

package/source/internal/object.d.ts

@@ -1,5 +1,4 @@
 import type {Simplify} from '../simplify.d.ts';
-import type {UnknownArray} from '../unknown-array.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';
@@ -9,7 +8,7 @@ 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 {NonRecursiveType} from './type.d.ts';
+import type {MapsSetsOrArrays, NonRecursiveType} from './type.d.ts';
 import type {ToString} from './string.d.ts';
 
 /**
@@ -40,11 +39,13 @@ export type BuildObject<Key extends PropertyKey, Value, CopiedFrom extends objec
 Returns a boolean for whether the given type is a plain key-value object.
 */
 export type IsPlainObject<T> =
-	T extends NonRecursiveType | UnknownArray | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown>
+	IsNever<T> extends true
 		? false
-		: T extends object
-			? 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.
@@ -135,7 +136,7 @@ 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">;
+type Statuses = ValueOfUnion<{id: 1; status: 'open'} | {id: 2; status: 'closed'}, 'status'>;
 //=> "open" | "closed"
 ```
 */
@@ -148,14 +149,14 @@ Extract all readonly keys from a union of object types.
 @example
 ```
 type User = {
-		readonly id: string;
-		name: string;
+	readonly id: string;
+	name: string;
 };
 
 type Post = {
-		readonly id: string;
-		readonly author: string;
-		body: string;
+	readonly id: string;
+	readonly author: string;
+	body: string;
 };
 
 type ReadonlyKeys = ReadonlyKeysOfUnion<User | Post>;