type-fest 5.1.0 → 5.3.0

package/index.d.ts

@@ -141,6 +141,7 @@ export type {ArrayValues} from './source/array-values.d.ts';
 export type {ArraySlice} from './source/array-slice.d.ts';
 export type {ArraySplice} from './source/array-splice.d.ts';
 export type {ArrayTail} from './source/array-tail.d.ts';
+export type {ArrayElement} from './source/array-element.d.ts';
 export type {SetFieldType, SetFieldTypeOptions} from './source/set-field-type.d.ts';
 export type {Paths, PathsOptions} from './source/paths.d.ts';
 export type {AllUnionFields} from './source/all-union-fields.d.ts';
@@ -162,6 +163,7 @@ export type {IsUppercase} from './source/is-uppercase.d.ts';
 export type {IsOptional} from './source/is-optional.d.ts';
 export type {IsNullable} from './source/is-nullable.d.ts';
 export type {TupleOf} from './source/tuple-of.d.ts';
+export type {ExclusifyUnion} from './source/exclusify-union.d.ts';
 
 // Template literal types
 export type {CamelCase, CamelCaseOptions} from './source/camel-case.d.ts';
@@ -202,3 +204,5 @@ export type {TsConfigJson} from './source/tsconfig-json.d.ts';
 export type {ExtendsStrict} from './source/extends-strict.d.ts';
 export type {ExtractStrict} from './source/extract-strict.d.ts';
 export type {ExcludeStrict} from './source/exclude-strict.d.ts';
+
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "5.1.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",
@@ -54,10 +54,15 @@
 	},
 	"devDependencies": {
 		"@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/readme.md

@@ -179,7 +179,7 @@ Click the type names for complete docs.
 - [`DistributedOmit`](source/distributed-omit.d.ts) - Omits keys from a type, distributing the operation over a union.
 - [`DistributedPick`](source/distributed-pick.d.ts) - Picks keys from a type, distributing the operation over a union.
 - [`And`](source/and.d.ts) - Returns a boolean for whether two given types are both true.
-- [`Or`](source/or.d.ts) - Returns a boolean for whether either of two given types are true.
+- [`Or`](source/or.d.ts) - Returns a boolean for whether either of two given types is true.
 - [`Xor`](source/xor.d.ts) - Returns a boolean for whether only one of two given types is true.
 - [`AllExtend`](source/all-extend.d.ts) - Returns a boolean for whether every element in an array type extends another type.
 - [`NonEmptyTuple`](source/non-empty-tuple.d.ts) - Matches any non-empty tuple.
@@ -188,6 +188,7 @@ Click the type names for complete docs.
 - [`FindGlobalInstanceType`](source/find-global-type.d.ts) - Tries to find one or more types from their globally-defined constructors.
 - [`ConditionalSimplify`](source/conditional-simplify.d.ts) - Simplifies a type while including and/or excluding certain types from being simplified.
 - [`ConditionalSimplifyDeep`](source/conditional-simplify-deep.d.ts) - Recursively simplifies a type while including and/or excluding certain types from being simplified.
+- [`ExclusifyUnion`](source/exclusify-union.d.ts) - Ensure mutual exclusivity in object unions by adding other members’ keys as `?: never`.
 
 ### Type Guard
 
@@ -249,6 +250,7 @@ Click the type names for complete docs.
 - [`Includes`](source/includes.d.ts) - Returns a boolean for whether the given array includes the given item.
 - [`Join`](source/join.d.ts) - Join an array of strings and/or numbers using the given string as a delimiter.
 - [`ArraySlice`](source/array-slice.d.ts) - Returns an array slice of a given range, just like `Array#slice()`.
+- [`ArrayElement`](source/array-element.d.ts) - Extracts the element type of an array or tuple.
 - [`LastArrayElement`](source/last-array-element.d.ts) - Extract the type of the last element of an array.
 - [`FixedLengthArray`](source/fixed-length-array.d.ts) - Create a type that represents an array of the given type and length. The `Array` prototype methods that manipulate its length are excluded from the resulting type.
 - [`MultidimensionalArray`](source/multidimensional-array.d.ts) - Create a type that represents a multidimensional array of the given type and dimensions.

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,15 +55,15 @@ 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);
 }
 ```
 
-@see SharedUnionFields
+@see {@link SharedUnionFields}
 
 @category Object
 @category Union

package/source/and.d.ts

@@ -46,6 +46,7 @@ type E = And<boolean, boolean>;
 ```
 
 Note: If either of the types is `never`, the result becomes `false`.
+
 @example
 ```
 import type {And} from 'type-fest';
@@ -73,6 +74,7 @@ type G = And<never, never>;
 ```
 
 @see {@link Or}
+@see {@link Xor}
 */
 export type And<A extends boolean, B extends boolean> = AllExtend<[A, B], true>;
 

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-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

@@ -1,7 +1,7 @@
 /**
 Create a type that represents either the value or an array of the value.
 
-@see Promisable
+@see {@link Promisable}
 
 @example
 ```
@@ -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

@@ -1,12 +1,12 @@
 import type {ApplyDefaultOptions} from './internal/index.d.ts';
-import type {Words} from './words.d.ts';
+import type {Words, WordsOptions} from './words.d.ts';
 
 /**
 CamelCase options.
 
 @see {@link CamelCase}
 */
-export type CamelCaseOptions = {
+export type CamelCaseOptions = WordsOptions & {
 	/**
 	Whether to preserved consecutive uppercase letter.
 
@@ -16,6 +16,7 @@ export type CamelCaseOptions = {
 };
 
 export type _DefaultCamelCaseOptions = {
+	splitOnNumbers: true;
 	preserveConsecutiveUppercase: false;
 };
 
@@ -57,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,
@@ -72,7 +73,7 @@ const dbResult: CamelCasedProperties<RawOptions> = {
 	foo: 123,
 	bar: 'foo',
 	quzQux: 6,
-	otherField: false
+	otherField: false,
 };
 ```
 
@@ -83,7 +84,7 @@ export type CamelCase<Type, Options extends CamelCaseOptions = {}> = Type extend
 	? string extends Type
 		? Type
 		: Uncapitalize<CamelCaseFromArray<
-			Words<Type extends Uppercase<Type> ? Lowercase<Type> : Type>,
+			Words<Type extends Uppercase<Type> ? Lowercase<Type> : Type, Options>,
 			ApplyDefaultOptions<CamelCaseOptions, _DefaultCamelCaseOptions, Options>
 		>>
 	: Type;

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

@@ -7,22 +7,22 @@ Convert object properties to camel case recursively.
 
 This can be useful when, for example, converting some API types from a different style.
 
-@see CamelCasedProperties
-@see CamelCase
+@see {@link CamelCasedProperties}
+@see {@link CamelCase}
 
 @example
 ```
 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

@@ -6,17 +6,17 @@ Convert object properties to camel case but not recursively.
 
 This can be useful when, for example, converting some API types from a different style.
 
-@see CamelCasedPropertiesDeep
-@see CamelCase
+@see {@link CamelCasedPropertiesDeep}
+@see {@link CamelCase}
 
 @example
 ```
 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

@@ -22,7 +22,7 @@ type AssertCondition<Type, Condition, Options extends ConditionalPickDeepOptions
 /**
 ConditionalPickDeep options.
 
-@see ConditionalPickDeep
+@see {@link ConditionalPickDeep}
 */
 export type ConditionalPickDeepOptions = {
 	/**
@@ -40,13 +40,13 @@ type DefaultConditionalPickDeepOptions = {
 /**
 Pick keys recursively from the shape that matches the given condition.
 
-@see ConditionalPick
+@see {@link ConditionalPick}
 
 @example
 ```
 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/conditional-simplify-deep.d.ts

@@ -61,7 +61,7 @@ type SimplifyDeepTypeAB = ConditionalSimplifyDeep<TypeA & TypeB, SomeComplexType
 // }
 ```
 
-@see SimplifyDeep
+@see {@link SimplifyDeep}
 @category Object
 */
 export type ConditionalSimplifyDeep<Type, ExcludeType = never, IncludeType = unknown> = Type extends ExcludeType

package/source/conditional-simplify.d.ts

@@ -38,7 +38,7 @@ type C = Simplify<{a: number} & {b: string}>;
 //=> {a: number; b: string}
 ```
 
-@see ConditionalSimplifyDeep
+@see {@link ConditionalSimplifyDeep}
 @category Object
 */
 export type ConditionalSimplify<Type, ExcludeType = never, IncludeType = unknown> = Type extends ExcludeType

package/source/delimiter-case.d.ts

@@ -27,8 +27,8 @@ Convert a string literal to a custom string delimiter casing.
 
 This can be useful when, for example, converting a camel-cased object property to an oddly cased one.
 
-@see KebabCase
-@see SnakeCase
+@see {@link KebabCase}
+@see {@link SnakeCase}
 
 @example
 ```
@@ -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,
 };
 ```