type-fest 5.2.0 → 5.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "5.2.0",
+	"version": "5.3.0",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",
@@ -25,7 +25,7 @@
 		"node": ">=20"
 	},
 	"scripts": {
-		"test:tsc": "tsc",
+		"test:tsc": "node --max-old-space-size=5120 ./node_modules/.bin/tsc",
 		"test:tsd": "tsd",
 		"test:xo": "xo",
 		"test:linter": "node --test",
@@ -56,10 +56,13 @@
 		"@sindresorhus/tsconfig": "^8.0.1",
 		"@typescript-eslint/parser": "^8.44.0",
 		"eslint": "^9.35.0",
+		"@typescript/vfs": "^1.6.1",
+		"dedent": "^1.7.0",
 		"expect-type": "^1.2.2",
 		"npm-run-all2": "^8.0.4",
 		"tsd": "^0.33.0",
 		"typescript": "^5.9.2",
+		"typescript-eslint": "^8.47.0",
 		"xo": "^1.2.2"
 	},
 	"tsd": {

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

@@ -38,14 +38,15 @@ function displayPetInfo(petInfo: Cat | Dog) {
 	// 	dogType: string;
 	// }
 
-	console.log('name: ', petInfo.name);
-	console.log('type: ', petInfo.type);
+	console.log('name:', petInfo.name);
+	console.log('type:', petInfo.type);
 
 	// TypeScript complains about `catType` and `dogType` not existing on type `Cat | Dog`.
-	console.log('animal type: ', petInfo.catType ?? petInfo.dogType);
+	// @ts-expect-error
+	console.log('animal type:', petInfo.catType ?? petInfo.dogType);
 }
 
-function displayPetInfo(petInfo: AllUnionFields<Cat | Dog>) {
+function displayPetInfoWithAllUnionFields(petInfo: AllUnionFields<Cat | Dog>) {
 	// typeof petInfo =>
 	// {
 	// 	name: string;
@@ -54,11 +55,11 @@ function displayPetInfo(petInfo: AllUnionFields<Cat | Dog>) {
 	// 	dogType?: string;
 	// }
 
-	console.log('name: ', petInfo.name);
-	console.log('type: ', petInfo.type);
+	console.log('name:', petInfo.name);
+	console.log('type:', petInfo.type);
 
 	// No TypeScript error.
-	console.log('animal type: ', petInfo.catType ?? petInfo.dogType);
+	console.log('animal type:', petInfo.catType ?? petInfo.dogType);
 }
 ```
 

package/source/array-slice.d.ts

@@ -7,6 +7,7 @@ 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()`.
@@ -43,14 +44,14 @@ function arraySlice<
 
 const slice = arraySlice([1, '2', {a: 3}, [4, 5]], 0, -1);
 
-typeof slice;
+type Slice = typeof slice;
 //=> [1, '2', { readonly a: 3; }]
 
-slice[2].a;
+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'.
-slice[3];
+const invalidIndexAccess = slice[3];
 ```
 
 @category Array
@@ -60,13 +61,33 @@ export type ArraySlice<
 	Start extends number = never,
 	End extends number = never,
 > = Array_ extends unknown // To distributive type
-	? 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>
+	? 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,

package/source/array-splice.d.ts

@@ -72,17 +72,19 @@ Like [`Array#splice()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/
 
 @example
 ```
+import type {ArraySplice} from 'type-fest';
+
 type SomeMonths0 = ['January', 'April', 'June'];
-type Mouths0 = ArraySplice<SomeMonths0, 1, 0, ['Feb', 'March']>;
-//=> type Mouths0 = ['January', 'Feb', 'March', 'April', 'June'];
+type Months0 = ArraySplice<SomeMonths0, 1, 0, ['Feb', 'March']>;
+//=> ['January', 'Feb', 'March', 'April', 'June'];
 
 type SomeMonths1 = ['January', 'April', 'June'];
-type Mouths1 = ArraySplice<SomeMonths1, 1, 1>;
-//=> type Mouths1 = ['January', 'June'];
+type Months1 = ArraySplice<SomeMonths1, 1, 1>;
+//=> ['January', 'June'];
 
 type SomeMonths2 = ['January', 'Foo', 'April'];
-type Mouths2 = ArraySplice<SomeMonths2, 1, 1, ['Feb', 'March']>;
-//=> type Mouths2 = ['January', 'Feb', 'March', 'April'];
+type Months2 = ArraySplice<SomeMonths2, 1, 1, ['Feb', 'March']>;
+//=> ['January', 'Feb', 'March', 'April'];
 ```
 
 @category Array

package/source/arrayable.d.ts

@@ -13,7 +13,7 @@ function bundle(input: string, output: Arrayable<string>) {
 	// …
 
 	for (const output of outputList) {
-		console.log(`write to: ${output}`);
+		console.log(`write ${input} to: ${output}`);
 	}
 }
 

package/source/async-return-type.d.ts

@@ -8,14 +8,17 @@ There has been [discussion](https://github.com/microsoft/TypeScript/pull/35998)
 @example
 ```ts
 import type {AsyncReturnType} from 'type-fest';
-import {asyncFunction} from 'api';
+
+declare function asyncFunction(): Promise<{foo: string}>;
 
 // This type resolves to the unwrapped return type of `asyncFunction`.
 type Value = AsyncReturnType<typeof asyncFunction>;
+//=> {foo: string}
 
-async function doSomething(value: Value) {}
+declare function doSomething(value: Value): void;
 
-asyncFunction().then(value => doSomething(value));
+const value = await asyncFunction();
+doSomething(value);
 ```
 
 @category Async

package/source/asyncify.d.ts

@@ -9,22 +9,13 @@ Use-case: You have two functions, one synchronous and one asynchronous that do t
 ```
 import type {Asyncify} from 'type-fest';
 
-// Synchronous function.
-function getFooSync(someArg: SomeType): Foo {
-	// …
-}
-
-type AsyncifiedFooGetter = Asyncify<typeof getFooSync>;
-//=> type AsyncifiedFooGetter = (someArg: SomeType) => Promise<Foo>;
-
-// Same as `getFooSync` but asynchronous.
-const getFooAsync: AsyncifiedFooGetter = (someArg) => {
-	// TypeScript now knows that `someArg` is `SomeType` automatically.
-	// It also knows that this function must return `Promise<Foo>`.
-	// If you have `@typescript-eslint/promise-function-async` linter rule enabled, it will even report that "Functions that return promises must be async.".
-
-	// …
-}
+// Synchronous function
+type Config = {featureFlags: Record<string, boolean>};
+
+declare function loadConfigSync(path: string): Config;
+
+type LoadConfigAsync = Asyncify<typeof loadConfigSync>;
+//=> (path: string) => Promise<Config>
 ```
 
 @category Async

package/source/camel-case.d.ts

@@ -58,14 +58,14 @@ type CamelCasedProperties<T> = {
 	[K in keyof T as CamelCase<K>]: T[K]
 };
 
-interface RawOptions {
+type RawOptions = {
 	'dry-run': boolean;
 	'full_family_name': string;
 	foo: number;
 	BAR: string;
 	QUZ_QUX: number;
 	'OTHER-FIELD': boolean;
-}
+};
 
 const dbResult: CamelCasedProperties<RawOptions> = {
 	dryRun: true,
@@ -73,7 +73,7 @@ const dbResult: CamelCasedProperties<RawOptions> = {
 	foo: 123,
 	bar: 'foo',
 	quzQux: 6,
-	otherField: false
+	otherField: false,
 };
 ```
 

package/source/camel-cased-properties-deep.d.ts

@@ -14,15 +14,15 @@ This can be useful when, for example, converting some API types from a different
 ```
 import type {CamelCasedPropertiesDeep} from 'type-fest';
 
-interface User {
+type User = {
 	UserId: number;
 	UserName: string;
-}
+};
 
-interface UserWithFriends {
+type UserWithFriends = {
 	UserInfo: User;
 	UserFriends: User[];
-}
+};
 
 const result: CamelCasedPropertiesDeep<UserWithFriends> = {
 	userInfo: {

package/source/camel-cased-properties.d.ts

@@ -13,10 +13,10 @@ This can be useful when, for example, converting some API types from a different
 ```
 import type {CamelCasedProperties} from 'type-fest';
 
-interface User {
+type User = {
 	UserId: number;
 	UserName: string;
-}
+};
 
 const result: CamelCasedProperties<User> = {
 	userId: 1,

package/source/characters.d.ts

@@ -5,8 +5,10 @@ Matches any uppercase letter in the basic Latin alphabet (A-Z).
 ```
 import type {UppercaseLetter} from 'type-fest';
 
-const a: UppercaseLetter = 'A';  // Valid
-const b: UppercaseLetter = 'a';  // Invalid
+const a: UppercaseLetter = 'A'; // Valid
+// @ts-expect-error
+const b: UppercaseLetter = 'a'; // Invalid
+// @ts-expect-error
 const c: UppercaseLetter = 'AB'; // Invalid
 ```
 
@@ -22,6 +24,7 @@ Matches any lowercase letter in the basic Latin alphabet (a-z).
 import type {LowercaseLetter} from 'type-fest';
 
 const a: LowercaseLetter = 'a'; // Valid
+// @ts-expect-error
 const b: LowercaseLetter = 'A'; // Invalid
 ```
 
@@ -37,7 +40,8 @@ Matches any digit as a string ('0'-'9').
 import type {DigitCharacter} from 'type-fest';
 
 const a: DigitCharacter = '0'; // Valid
-const b: DigitCharacter = 0;   // Invalid
+// @ts-expect-error
+const b: DigitCharacter = 0; // Invalid
 ```
 
 @category Type
@@ -52,6 +56,7 @@ Matches any lowercase letter (a-z), uppercase letter (A-Z), or digit ('0'-'9') i
 import type {Alphanumeric} from 'type-fest';
 
 const a: Alphanumeric = 'A'; // Valid
+// @ts-expect-error
 const b: Alphanumeric = '#'; // Invalid
 ```
 

package/source/conditional-except.d.ts

@@ -11,11 +11,11 @@ This is useful when you want to create a new type with a specific set of keys fr
 import type {Primitive, ConditionalExcept} from 'type-fest';
 
 class Awesome {
-	name: string;
-	successes: number;
-	failures: bigint;
+	constructor(public name: string, public successes: number, public failures: bigint) {}
 
-	run() {}
+	run() {
+		// do something
+	}
 }
 
 type ExceptPrimitivesFromAwesome = ConditionalExcept<Awesome, Primitive>;
@@ -26,12 +26,12 @@ type ExceptPrimitivesFromAwesome = ConditionalExcept<Awesome, Primitive>;
 ```
 import type {ConditionalExcept} from 'type-fest';
 
-interface Example {
+type Example = {
 	a: string;
 	b: string | number;
 	c: () => void;
 	d: {};
-}
+};
 
 type NonStringKeysOnly = ConditionalExcept<Example, string>;
 //=> {b: string | number; c: () => void; d: {}}

package/source/conditional-pick-deep.d.ts

@@ -46,7 +46,7 @@ Pick keys recursively from the shape that matches the given condition.
 ```
 import type {ConditionalPickDeep} from 'type-fest';
 
-interface Example {
+type Example = {
 	a: string;
 	b: string | boolean;
 	c: {
@@ -59,7 +59,7 @@ interface Example {
 		};
 		j: boolean;
 	};
-}
+};
 
 type StringPick = ConditionalPickDeep<Example, string>;
 //=> {a: string; c: {d: string}}

package/source/conditional-pick.d.ts

@@ -10,11 +10,11 @@ This is useful when you want to create a new type from a specific subset of an e
 import type {Primitive, ConditionalPick} from 'type-fest';
 
 class Awesome {
-	name: string;
-	successes: number;
-	failures: bigint;
+	constructor(public name: string, public successes: number, public failures: bigint) {}
 
-	run() {}
+	run() {
+		// do something
+	}
 }
 
 type PickPrimitivesFromAwesome = ConditionalPick<Awesome, Primitive>;
@@ -25,12 +25,12 @@ type PickPrimitivesFromAwesome = ConditionalPick<Awesome, Primitive>;
 ```
 import type {ConditionalPick} from 'type-fest';
 
-interface Example {
+type Example = {
 	a: string;
 	b: string | number;
 	c: () => void;
 	d: {};
-}
+};
 
 type StringKeysOnly = ConditionalPick<Example, string>;
 //=> {a: string}

package/source/delimiter-case.d.ts

@@ -45,16 +45,16 @@ type OddlyCasedProperties<T> = {
 	[K in keyof T as DelimiterCase<K, '#'>]: T[K]
 };
 
-interface SomeOptions {
+type SomeOptions = {
 	dryRun: boolean;
 	includeFile: string;
 	foo: number;
-}
+};
 
 const rawCliOptions: OddlyCasedProperties<SomeOptions> = {
 	'dry#run': true,
 	'include#file': 'bar.js',
-	foo: 123
+	foo: 123,
 };
 ```
 

package/source/delimiter-cased-properties-deep.d.ts

@@ -15,19 +15,19 @@ This can be useful when, for example, converting some API types from a different
 ```
 import type {DelimiterCasedPropertiesDeep} from 'type-fest';
 
-interface User {
+type User = {
 	userId: number;
 	userName: string;
-}
+};
 
-interface UserWithFriends {
+type UserWithFriends = {
 	userInfo: User;
 	userFriends: User[];
-}
+};
 
 const result: DelimiterCasedPropertiesDeep<UserWithFriends, '-'> = {
 	'user-info': {
-	'user-id': 1,
+		'user-id': 1,
 		'user-name': 'Tom',
 	},
 	'user-friends': [
@@ -42,7 +42,7 @@ const result: DelimiterCasedPropertiesDeep<UserWithFriends, '-'> = {
 	],
 };
 
-const splitOnNumbers: DelimiterCasedPropertiesDeep<{line1: { line2: [{ line3: string }] }}, '-', {splitOnNumbers: true}> = {
+const splitOnNumbers: DelimiterCasedPropertiesDeep<{line1: {line2: [{line3: string}]}}, '-', {splitOnNumbers: true}> = {
 	'line-1': {
 		'line-2': [
 			{

package/source/delimiter-cased-properties.d.ts

@@ -14,10 +14,10 @@ This can be useful when, for example, converting some API types from a different
 ```
 import type {DelimiterCasedProperties} from 'type-fest';
 
-interface User {
+type User = {
 	userId: number;
 	userName: string;
-}
+};
 
 const result: DelimiterCasedProperties<User, '-'> = {
 	'user-id': 1,

package/source/distributed-omit.d.ts

@@ -25,15 +25,16 @@ type Union = A | B;
 type OmittedUnion = Omit<Union, 'foo'>;
 //=> {discriminant: 'A' | 'B'}
 
-const omittedUnion: OmittedUnion = createOmittedUnion();
+declare const omittedUnion: OmittedUnion;
 
 if (omittedUnion.discriminant === 'A') {
 	// We would like to narrow `omittedUnion`'s type
 	// to `A` here, but we can't because `Omit`
 	// doesn't distribute over unions.
 
-	omittedUnion.a;
- 	//=> Error: `a` is not a property of `{discriminant: 'A' | 'B'}`
+	// @ts-expect-error
+	const aValue = omittedUnion.a;
+	//=> Error: `a` is not a property of `{discriminant: 'A' | 'B'}`
 }
 ```
 
@@ -41,6 +42,8 @@ While `Except` solves this problem, it restricts the keys you can omit to the on
 
 @example
 ```
+import type {DistributedOmit} from 'type-fest';
+
 type A = {
 	discriminant: 'A';
 	foo: string;
@@ -67,17 +70,19 @@ type Union = A | B | C;
 
 type OmittedUnion = DistributedOmit<Union, 'foo' | 'bar'>;
 
-const omittedUnion: OmittedUnion = createOmittedUnion();
+declare const omittedUnion: OmittedUnion;
 
 if (omittedUnion.discriminant === 'A') {
-	omittedUnion.a;
- 	//=> OK
+	const aValue = omittedUnion.a;
+	//=> OK
 
-	omittedUnion.foo;
- 	//=> Error: `foo` is not a property of `{discriminant: 'A'; a: string}`
+	// @ts-expect-error
+	const fooValue = omittedUnion.foo;
+	//=> Error: `foo` is not a property of `{discriminant: 'A'; a: string}`
 
-	omittedUnion.bar;
- 	//=> Error: `bar` is not a property of `{discriminant: 'A'; a: string}`
+	// @ts-expect-error
+	const barValue = omittedUnion.bar;
+	//=> Error: `bar` is not a property of `{discriminant: 'A'; a: string}`
 }
 ```
 

package/source/distributed-pick.d.ts

@@ -27,20 +27,23 @@ type Union = A | B;
 type PickedUnion = Pick<Union, 'discriminant' | 'foo'>;
 //=> {discriminant: 'A' | 'B', foo: {bar: string} | {baz: string}}
 
-const pickedUnion: PickedUnion = createPickedUnion();
+declare const pickedUnion: PickedUnion;
 
 if (pickedUnion.discriminant === 'A') {
 	// We would like to narrow `pickedUnion`'s type
 	// to `A` here, but we can't because `Pick`
 	// doesn't distribute over unions.
 
-	pickedUnion.foo.bar;
+	// @ts-expect-error
+	const barValue = pickedUnion.foo.bar;
 	//=> Error: Property 'bar' does not exist on type '{bar: string} | {baz: string}'.
 }
 ```
 
 @example
 ```
+import type {DistributedPick} from 'type-fest';
+
 type A = {
 	discriminant: 'A';
 	foo: {
@@ -63,16 +66,18 @@ type Union = A | B;
 
 type PickedUnion = DistributedPick<Union, 'discriminant' | 'foo'>;
 
-const pickedUnion: PickedUnion = createPickedUnion();
+declare const pickedUnion: PickedUnion;
 
 if (pickedUnion.discriminant === 'A') {
-	pickedUnion.foo.bar;
- 	//=> OK
+	const barValue = pickedUnion.foo.bar;
+	//=> OK
 
-	pickedUnion.extraneous;
+	// @ts-expect-error
+	const extraneousValue = pickedUnion.extraneous;
 	//=> Error: Property `extraneous` does not exist on type `Pick<A, 'discriminant' | 'foo'>`.
 
-	pickedUnion.foo.baz;
+	// @ts-expect-error
+	const bazValue = pickedUnion.foo.baz;
 	//=> Error: `bar` is not a property of `{discriminant: 'A'; a: string}`.
 }
 ```

package/source/empty-object.d.ts

@@ -17,8 +17,11 @@ const foo4: {} = {a: 1}; // Pass
 
 // With `EmptyObject` only the first case is valid.
 const bar1: EmptyObject = {}; // Pass
-const bar2: EmptyObject = 42; // Fail
-const bar3: EmptyObject = []; // Fail
+// @ts-expect-error
+const bar2: EmptyObject = []; // Fail
+// @ts-expect-error
+const bar3: EmptyObject = 42; // Fail
+// @ts-expect-error
 const bar4: EmptyObject = {a: 1}; // Fail
 ```
 
@@ -36,8 +39,8 @@ Returns a `boolean` for whether the type is strictly equal to an empty plain obj
 import type {IsEmptyObject} from 'type-fest';
 
 type Pass = IsEmptyObject<{}>; //=> true
-type Fail = IsEmptyObject<[]>; //=> false
-type Fail = IsEmptyObject<null>; //=> false
+type Fail1 = IsEmptyObject<[]>; //=> false
+type Fail2 = IsEmptyObject<null>; //=> false
 ```
 
 @see {@link EmptyObject}

package/source/entries.d.ts

@@ -16,16 +16,16 @@ For example the {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/R
 ```
 import type {Entries} from 'type-fest';
 
-interface Example {
+type Example = {
 	someKey: number;
-}
+};
 
 const manipulatesEntries = (examples: Entries<Example>) => examples.map(example => [
 	// Does some arbitrary processing on the key (with type information available)
 	example[0].toUpperCase(),
 
 	// Does some arbitrary processing on the value (with type information available)
-	example[1].toFixed()
+	example[1].toFixed(0),
 ]);
 
 const example: Example = {someKey: 1};

package/source/entry.d.ts

@@ -17,16 +17,16 @@ For example the {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/R
 ```
 import type {Entry} from 'type-fest';
 
-interface Example {
+type Example = {
 	someKey: number;
-}
+};
 
 const manipulatesEntry = (example: Entry<Example>) => [
 	// Does some arbitrary processing on the key (with type information available)
 	example[0].toUpperCase(),
 
 	// Does some arbitrary processing on the value (with type information available)
-	example[1].toFixed(),
+	example[1].toFixed(0),
 ];
 
 const example: Example = {someKey: 1};