type-fest 5.4.4 → 5.6.0

package/source/set-readonly.d.ts

@@ -3,7 +3,7 @@ import type {HomomorphicPick} from './internal/index.d.ts';
 import type {Simplify} from './simplify.d.ts';
 
 /**
-Create a type that makes the given keys readonly. The remaining keys are kept as is.
+Create a type that makes the given keys readonly, while keeping the remaining keys as is.
 
 Use-case: You want to define a single model where the only thing that changes is whether or not some of the keys are readonly.
 
@@ -18,11 +18,7 @@ type Foo = {
 };
 
 type SomeReadonly = SetReadonly<Foo, 'b' | 'c'>;
-// type SomeReadonly = {
-// 	a: number;
-// 	readonly b: string; // Was already readonly and still is.
-// 	readonly c: boolean; // Is now readonly.
-// }
+//=> {a: number; readonly b: string; readonly c: boolean}
 ```
 
 @category Object
@@ -36,8 +32,8 @@ export type SetReadonly<BaseType, Keys extends keyof BaseType> =
 export type _SetReadonly<BaseType, Keys extends keyof BaseType> =
 	BaseType extends unknown // To distribute `BaseType` when it's a union type.
 		? Simplify<
-			Except<BaseType, Keys> &
-			Readonly<HomomorphicPick<BaseType, Keys>>
+			Except<BaseType, Keys>
+			& Readonly<HomomorphicPick<BaseType, Keys>>
 		>
 		: never;
 

package/source/set-required-deep.d.ts

@@ -8,7 +8,7 @@ import type {RequiredDeep} from './required-deep.d.ts';
 import type {UnknownArray} from './unknown-array.d.ts';
 
 /**
-Create a type that makes the given keys required. You can specify deeply nested key paths. The remaining keys are kept as is.
+Create a type that makes the given keys required, with support for deeply nested key paths, while keeping the remaining keys as is.
 
 Use-case: Selectively make nested properties required in complex types like models.
 

package/source/set-required.d.ts

@@ -6,7 +6,7 @@ import type {Simplify} from './simplify.d.ts';
 import type {UnknownArray} from './unknown-array.d.ts';
 
 /**
-Create a type that makes the given keys required. The remaining keys are kept as is. The sister of the `SetOptional` type.
+Create a type that makes the given keys required, while keeping the remaining keys as is.
 
 Use-case: You want to define a single model where the only thing that changes is whether or not some of the keys are required.
 
@@ -21,11 +21,7 @@ type Foo = {
 };
 
 type SomeRequired = SetRequired<Foo, 'b' | 'c'>;
-// type SomeRequired = {
-// 	a?: number;
-// 	b: string; // Was already required and still is.
-// 	c: boolean; // Is now required.
-// }
+//=> {a?: number; b: string; c: boolean}
 
 // Set specific indices in an array to be required.
 type ArrayExample = SetRequired<[number?, number?, number?], 0 | 1>;
@@ -47,9 +43,9 @@ type _SetRequired<BaseType, Keys extends keyof BaseType> =
 			: never
 		: Simplify<
 		// Pick just the keys that are optional from the base type.
-			Except<BaseType, Keys> &
+			Except<BaseType, Keys>
 		// Pick the keys that should be required from the base type and make them required.
-			Required<HomomorphicPick<BaseType, Keys>>
+			& Required<HomomorphicPick<BaseType, Keys>>
 		>;
 
 /**

package/source/shared-union-fields-deep.d.ts

@@ -89,7 +89,7 @@ function displayPetInfoWithSharedUnionFieldsDeep(petInfo: SharedUnionFieldsDeep<
 export type SharedUnionFieldsDeep<Union, Options extends SharedUnionFieldsDeepOptions = {}> =
 	ApplyDefaultOptions<SharedUnionFieldsDeepOptions, DefaultSharedUnionFieldsDeepOptions, Options> extends infer OptionsWithDefaults extends Required<SharedUnionFieldsDeepOptions>
 	// `Union extends` will convert `Union`
-	// to a [distributive conditionaltype](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
+	// to a [distributive conditional type](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
 	// But this is not what we want, so we need to wrap `Union` with `[]` to prevent it.
 		? [Union] extends [NonRecursiveType | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown>]
 			? Union

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

@@ -66,14 +66,14 @@ function displayPetInfoWithSharedUnionFields(petInfo: SharedUnionFields<Cat | Do
 @category Union
 */
 export type SharedUnionFields<Union> =
-Extract<Union, NonRecursiveType | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | UnknownArray> extends infer SkippedMembers
-	? Exclude<Union, SkippedMembers> extends infer RelevantMembers
-		?
-		| SkippedMembers
-		| (IsNever<RelevantMembers> extends true
-			? never
-			: Simplify<Pick<RelevantMembers, keyof RelevantMembers>>)
-		: never
-	: never;
+	Extract<Union, NonRecursiveType | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown> | UnknownArray> extends infer SkippedMembers
+		? Exclude<Union, SkippedMembers> extends infer RelevantMembers
+			? // eslint-disable-line @stylistic/operator-linebreak
+			| SkippedMembers
+			| (IsNever<RelevantMembers> extends true
+				? never
+				: Simplify<Pick<RelevantMembers, keyof RelevantMembers>>)
+			: never
+		: never;
 
 export {};

package/source/snake-case.d.ts

@@ -16,6 +16,7 @@ import type {SnakeCase} from 'type-fest';
 const someVariable: SnakeCase<'fooBar'> = 'foo_bar';
 const noSplitOnNumbers: SnakeCase<'p2pNetwork'> = 'p2p_network';
 const splitOnNumbers: SnakeCase<'p2pNetwork', {splitOnNumbers: true}> = 'p_2_p_network';
+const splitOnPunctuation: SnakeCase<'div.card::after', {splitOnPunctuation: true}> = 'div_card_after';
 
 // Advanced
 

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

@@ -51,6 +51,13 @@ const splitOnNumbers: SnakeCasedPropertiesDeep<{line1: {line2: [{line3: string}]
 		],
 	},
 };
+
+const splitOnPunctuation: SnakeCasedPropertiesDeep<{'user@info': {'user::id': number; 'user::name': string}}, {splitOnPunctuation: true}> = {
+	'user_info': {
+		'user_id': 1,
+		'user_name': 'Tom',
+	},
+};
 ```
 
 @category Change case

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

@@ -4,7 +4,7 @@ import type {ApplyDefaultOptions} from './internal/index.d.ts';
 import type {WordsOptions} from './words.d.ts';
 
 /**
-Convert object properties to snake case but not recursively.
+Convert top-level object properties to snake case.
 
 This can be useful when, for example, converting some API types from a different style.
 
@@ -28,6 +28,10 @@ const result: SnakeCasedProperties<User> = {
 const splitOnNumbers: SnakeCasedProperties<{line1: string}, {splitOnNumbers: true}> = {
 	'line_1': 'string',
 };
+
+const splitOnPunctuation: SnakeCasedProperties<{'foo::bar': string}, {splitOnPunctuation: true}> = {
+	'foo_bar': 'string',
+};
 ```
 
 @category Change case

package/source/some-extend.d.ts

@@ -0,0 +1,113 @@
+import type {CollapseRestElement} from './internal/array.d.ts';
+import type {ApplyDefaultOptions} from './internal/object.d.ts';
+import type {IfNotAnyOrNever, Not} from './internal/type.d.ts';
+import type {IsAny} from './is-any.d.ts';
+import type {IsNever} from './is-never.d.ts';
+import type {Or} from './or.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+
+/**
+@see {@link SomeExtend}
+*/
+export type SomeExtendOptions = {
+	/**
+	Consider `never` elements to match the target type only if the target type itself is `never` (or `any`).
+
+	- When set to `true` (default), `never` is _not_ treated as a bottom type, instead, it is treated as a type that matches only itself (or `any`).
+	- When set to `false`, `never` is treated as a bottom type, and behaves as it normally would.
+
+	@default true
+
+	@example
+	```
+	import type {SomeExtend} from 'type-fest';
+
+	type A = SomeExtend<[1, 2, never], string, {strictNever: true}>;
+	//=> false
+
+	type B = SomeExtend<[1, 2, never], string, {strictNever: false}>;
+	//=> true
+
+	type C = SomeExtend<[1, never], never, {strictNever: true}>;
+	//=> true
+
+	type D = SomeExtend<[1, never], never, {strictNever: false}>;
+	//=> true
+
+	type E = SomeExtend<[never], any, {strictNever: true}>;
+	//=> true
+
+	type F = SomeExtend<[never], any, {strictNever: false}>;
+	//=> true
+	```
+	*/
+	strictNever?: boolean;
+};
+
+type DefaultSomeExtendOptions = {
+	strictNever: true;
+};
+
+/**
+Returns a boolean for whether some element in an array type extends another type.
+
+@example
+```
+import type {SomeExtend} from 'type-fest';
+
+type A = SomeExtend<['1', '2', 3], number>;
+//=> true
+
+type B = SomeExtend<[1, 2, 3], string>;
+//=> false
+
+type C = SomeExtend<[string, number | string], number>;
+//=> boolean
+
+type D = SomeExtend<[true, boolean, true], false>;
+//=> boolean
+```
+
+Note: Behaviour of optional elements depend on the `exactOptionalPropertyTypes` compiler option. When the option is disabled, the target type must include `undefined` for a successful match.
+
+```
+// @exactOptionalPropertyTypes: true
+import type {SomeExtend} from 'type-fest';
+
+type A = SomeExtend<[1?, 2?, '3'?], string>;
+//=> true
+```
+
+```
+// @exactOptionalPropertyTypes: false
+import type {SomeExtend} from 'type-fest';
+
+type A = SomeExtend<[1?, 2?, '3'?], string>;
+//=> boolean
+
+type B = SomeExtend<[1?, 2?, '3'?], string | undefined>;
+//=> true
+```
+
+@see {@link SomeExtendOptions}
+
+@category Utilities
+@category Array
+*/
+export type SomeExtend<TArray extends UnknownArray, Type, Options extends SomeExtendOptions = {}> =
+	_SomeExtend<CollapseRestElement<TArray>, Type, ApplyDefaultOptions<SomeExtendOptions, DefaultSomeExtendOptions, Options>>;
+
+type _SomeExtend<TArray extends UnknownArray, Type, Options extends Required<SomeExtendOptions>> = IfNotAnyOrNever<TArray,
+	TArray extends readonly [infer First, ...infer Rest]
+		? IsNever<First> extends true
+			? Or<Or<IsNever<Type>, IsAny<Type>>, Not<Options['strictNever']>> extends true
+				// If target `Type` is also `never`, or is `any`, or `strictNever` is disabled, return `true`.
+				? true
+				: _SomeExtend<Rest, Type, Options>
+			: First extends Type
+				? true
+				: _SomeExtend<Rest, Type, Options>
+		: false,
+	false, false>;
+
+export {};

package/source/spread.d.ts

@@ -41,11 +41,7 @@ const bar = {c: false};
 const fooBar = {...foo, ...bar};
 
 type FooBar = Spread<Foo, Bar>;
-// type FooBar = {
-// 	a: number;
-// 	b?: string | number | undefined;
-// 	c: boolean;
-// }
+//=> {a: number; b?: string | number; c: boolean}
 
 declare function baz(argument: FooBar): void;
 

package/source/subtract.d.ts

@@ -1,7 +1,8 @@
-import type {NumberAbsolute, ReverseSign} from './internal/index.d.ts';
+import type {ReverseSign} from './internal/index.d.ts';
 import type {PositiveInfinity, NegativeInfinity, IsNegative} from './numeric.d.ts';
 import type {LessThan} from './less-than.d.ts';
 import type {TupleOf} from './tuple-of.d.ts';
+import type {Absolute} from './absolute.d.ts';
 
 /**
 Returns the difference between two numbers.
@@ -59,9 +60,9 @@ type SubtractPostChecks<A extends number, B extends number, AreNegative = [IsNeg
 		? SubtractPositives<A, B>
 		: AreNegative extends [true, true]
 			// When both numbers are negative we subtract the absolute values and then reverse the sign
-			? ReverseSign<SubtractPositives<NumberAbsolute<A>, NumberAbsolute<B>>>
+			? ReverseSign<SubtractPositives<Absolute<A>, Absolute<B>>>
 			// When the signs are different we can add the absolute values and then reverse the sign if A < B
-			: [...TupleOf<NumberAbsolute<A>>, ...TupleOf<NumberAbsolute<B>>] extends infer R extends unknown[]
+			: [...TupleOf<Absolute<A>>, ...TupleOf<Absolute<B>>] extends infer R extends unknown[]
 				? LessThan<A, B> extends true ? ReverseSign<R['length']> : R['length']
 				: never;
 

package/source/sum.d.ts

@@ -1,7 +1,8 @@
 import type {TupleOf} from './tuple-of.d.ts';
-import type {NumberAbsolute, TupleMax, ReverseSign} from './internal/index.d.ts';
+import type {TupleMax, ReverseSign} from './internal/index.d.ts';
 import type {PositiveInfinity, NegativeInfinity, IsNegative} from './numeric.d.ts';
 import type {Subtract} from './subtract.d.ts';
+import type {Absolute} from './absolute.d.ts';
 
 /**
 Returns the sum of two numbers.
@@ -57,11 +58,11 @@ type SumPostChecks<A extends number, B extends number, AreNegative = [IsNegative
 		? SumPositives<A, B>
 		: AreNegative extends [true, true]
 			// When both numbers are negative we add the absolute values and then reverse the sign
-			? ReverseSign<SumPositives<NumberAbsolute<A>, NumberAbsolute<B>>>
+			? ReverseSign<SumPositives<Absolute<A>, Absolute<B>>>
 			// When the signs are different we can subtract the absolute values, remove the sign
 			// and then reverse the sign if the larger absolute value is negative
-			: NumberAbsolute<Subtract<NumberAbsolute<A>, NumberAbsolute<B>>> extends infer Result extends number
-				? TupleMax<[NumberAbsolute<A>, NumberAbsolute<B>]> extends infer Max_ extends number
+			: Absolute<Subtract<Absolute<A>, Absolute<B>>> extends infer Result extends number
+				? TupleMax<[Absolute<A>, Absolute<B>]> extends infer Max_ extends number
 					? Max_ extends A | B
 						// The larger absolute value is positive, so the result is positive
 						? Result

package/source/tagged.d.ts

@@ -8,12 +8,10 @@ export type TagContainer<Token> = {
 type Tag<Token extends PropertyKey, TagMetadata> = TagContainer<{[K in Token]: TagMetadata}>;
 
 /**
-Attach a "tag" to an arbitrary type. This allows you to create distinct types, that aren't assignable to one another, for distinct concepts in your program that should not be interchangeable, even if their runtime values have the same type. (See examples.)
+Create a [tagged type](https://medium.com/@KevinBGreene/surviving-the-typescript-ecosystem-branding-and-type-tagging-6cf6e516523d) that can support [multiple tags](https://github.com/sindresorhus/type-fest/issues/665) and [per-tag metadata](https://medium.com/@ethanresnick/advanced-typescript-tagged-types-improved-with-type-level-metadata-5072fc125fcf).
 
 A type returned by `Tagged` can be passed to `Tagged` again, to create a type with multiple tags.
 
-[Read more about tagged types.](https://medium.com/@KevinBGreene/surviving-the-typescript-ecosystem-branding-and-type-tagging-6cf6e516523d)
-
 A tag's name is usually a string (and must be a string, number, or symbol), but each application of a tag can also contain an arbitrary type as its "metadata". See {@link GetTagMetadata} for examples and explanation.
 
 A type `A` returned by `Tagged` is assignable to another type `B` returned by `Tagged` if and only if:
@@ -100,7 +98,7 @@ const parsed = parse(x); // The type of `parsed` is { hello: string }
 export type GetTagMetadata<Type extends Tag<TagName, unknown>, TagName extends PropertyKey> = Type[typeof tag][TagName];
 
 /**
-Revert a tagged type back to its original type by removing all tags.
+Get the untagged portion of a tagged type created with `Tagged`.
 
 Why is this necessary?
 
@@ -121,7 +119,7 @@ const moneyByAccountType: Record<UnwrapTagged<AccountType>, number> = {
 // Without UnwrapTagged, the following expression would throw a type error.
 const money = moneyByAccountType.SAVINGS; // TS error: Property 'SAVINGS' does not exist
 
-// Attempting to pass an non-Tagged type to UnwrapTagged will raise a type error.
+// Attempting to pass a non-Tagged type to UnwrapTagged will raise a type error.
 // @ts-expect-error
 type WontWork = UnwrapTagged<string>;
 ```
@@ -129,7 +127,7 @@ type WontWork = UnwrapTagged<string>;
 @category Type
 */
 export type UnwrapTagged<TaggedType extends Tag<PropertyKey, any>> =
-RemoveAllTags<TaggedType>;
+	RemoveAllTags<TaggedType>;
 
 type RemoveAllTags<T> = T extends Tag<PropertyKey, any>
 	? {
@@ -239,7 +237,7 @@ const moneyByAccountType: Record<UnwrapOpaque<AccountType>, number> = {
 // Without UnwrapOpaque, the following expression would throw a type error.
 const money = moneyByAccountType.SAVINGS; // TS error: Property 'SAVINGS' does not exist
 
-// Attempting to pass an non-Opaque type to UnwrapOpaque will raise a type error.
+// Attempting to pass a non-Opaque type to UnwrapOpaque will raise a type error.
 // @ts-expect-error
 type WontWork = UnwrapOpaque<string>;
 

package/source/tsconfig-json.d.ts

@@ -61,6 +61,7 @@ export namespace TsConfigJson {
 			| 'ES2022'
 			| 'ES2023'
 			| 'ES2024'
+			| 'ES2025'
 			| 'ESNext'
 			// Lowercase alternatives
 			| 'es3'
@@ -76,6 +77,7 @@ export namespace TsConfigJson {
 			| 'es2022'
 			| 'es2023'
 			| 'es2024'
+			| 'es2025'
 			| 'esnext';
 
 		type Lib =
@@ -148,6 +150,13 @@ export namespace TsConfigJson {
 			| 'ES2024.Regexp'
 			| 'ES2024.SharedMemory'
 			| 'ES2024.String'
+			| 'ES2025'
+			| 'ES2025.Collection'
+			| 'ES2025.Float16'
+			| 'ES2025.Intl'
+			| 'ES2025.Iterator'
+			| 'ES2025.Promise'
+			| 'ES2025.RegExp'
 			| 'ESNext'
 			| 'ESNext.Array'
 			| 'ESNext.AsyncIterable'
@@ -156,6 +165,7 @@ export namespace TsConfigJson {
 			| 'ESNext.Decorators'
 			| 'ESNext.Disposable'
 			| 'ESNext.Error'
+			| 'ESNext.Float16'
 			| 'ESNext.Intl'
 			| 'ESNext.Iterator'
 			| 'ESNext.Object'
@@ -163,6 +173,7 @@ export namespace TsConfigJson {
 			| 'ESNext.Regexp'
 			| 'ESNext.String'
 			| 'ESNext.Symbol'
+			| 'ESNext.Temporal'
 			| 'ESNext.WeakRef'
 			| 'DOM'
 			| 'DOM.AsyncIterable'
@@ -244,6 +255,13 @@ export namespace TsConfigJson {
 			| 'es2024.regexp'
 			| 'es2024.sharedmemory'
 			| 'es2024.string'
+			| 'es2025'
+			| 'es2025.collection'
+			| 'es2025.float16'
+			| 'es2025.intl'
+			| 'es2025.iterator'
+			| 'es2025.promise'
+			| 'es2025.regexp'
 			| 'esnext'
 			| 'esnext.array'
 			| 'esnext.asynciterable'
@@ -252,6 +270,7 @@ export namespace TsConfigJson {
 			| 'esnext.decorators'
 			| 'esnext.disposable'
 			| 'esnext.error'
+			| 'esnext.float16'
 			| 'esnext.intl'
 			| 'esnext.iterator'
 			| 'esnext.object'
@@ -259,6 +278,7 @@ export namespace TsConfigJson {
 			| 'esnext.regexp'
 			| 'esnext.string'
 			| 'esnext.symbol'
+			| 'esnext.temporal'
 			| 'esnext.weakref'
 			| 'dom'
 			| 'dom.asynciterable'
@@ -326,7 +346,7 @@ export namespace TsConfigJson {
 			| 'legacy'
 			| 'force';
 
-		type IgnoreDeprecations = '5.0';
+		type IgnoreDeprecations = '5.0' | '6.0';
 	}
 
 	type CompilerOptions = {
@@ -479,7 +499,7 @@ export namespace TsConfigJson {
 		/**
 		Specify module code generation: 'None', 'CommonJS', 'AMD', 'System', 'UMD', 'ES6', 'ES2015' or 'ESNext'. Only 'AMD' and 'System' can be used in conjunction with `--outFile`. 'ES6' and 'ES2015' values may be used when targeting 'ES5' or lower.
 
-		@default ['ES3', 'ES5'].includes(target) ? 'CommonJS' : 'ES6'
+		Default: `'ESNext'` since TypeScript 6.0, `['ES3', 'ES5'].includes(target) ? 'CommonJS' : 'ES6'` before.
 		*/
 		module?: CompilerOptions.Module;
 
@@ -587,8 +607,17 @@ export namespace TsConfigJson {
 		*/
 		skipLibCheck?: boolean;
 
+		/**
+		Enforce stable type ordering.
+
+		@default false
+		*/
+		stableTypeOrdering?: boolean;
+
 		/**
 		Concatenate and emit output to single file.
+
+		@deprecated since TypeScript 6.0.
 		*/
 		outFile?: string;
 
@@ -696,7 +725,7 @@ export namespace TsConfigJson {
 		/**
 		Specify ECMAScript target version.
 
-		@default 'es3'
+		Default: Current-year ES version since TypeScript 6.0, `'es3'` before.
 		*/
 		target?: CompilerOptions.Target;
 
@@ -776,7 +805,7 @@ export namespace TsConfigJson {
 		/**
 		Report error if failed to find a source file for a side effect import.
 
-		@default false
+		Default: `true` since TypeScript 6.0, `false` before.
 		*/
 		noUncheckedSideEffectImports?: boolean;
 
@@ -822,6 +851,8 @@ export namespace TsConfigJson {
 
 		/**
 		Base directory to resolve non-relative module names.
+
+		@deprecated since TypeScript 6.0.
 		*/
 		baseUrl?: string;
 
@@ -944,7 +975,7 @@ export namespace TsConfigJson {
 		/**
 		Enable all strict type checking options.
 
-		@default false
+		Default: `true` since TypeScript 6.0, `false` before.
 		*/
 		strict?: boolean;
 
@@ -959,6 +990,7 @@ export namespace TsConfigJson {
 		Provide full support for iterables in `for-of`, spread, and destructuring when targeting `ES5` or `ES3`.
 
 		@default false
+		@deprecated since TypeScript 6.0.
 		*/
 		downlevelIteration?: boolean;
 
@@ -1150,7 +1182,7 @@ export namespace TsConfigJson {
 		/**
 		Enable lib replacement.
 
-		@default true
+		Default: `false` since TypeScript 6.0, `true` before.
 		*/
 		libReplacement?: boolean;
 	};
@@ -1266,7 +1298,7 @@ export namespace TsConfigJson {
 }
 
 /**
-Type for [TypeScript's `tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) (TypeScript 3.7).
+Type for [TypeScript's `tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
 
 @category File
 */

package/source/union-length.d.ts

@@ -0,0 +1,27 @@
+import type {UnionToTuple} from './union-to-tuple.d.ts';
+
+/**
+Returns the length of a union type.
+
+@example
+```
+import type {UnionLength} from 'type-fest';
+
+type T1 = UnionLength<'foo' | 'bar' | 'baz'>;
+//=> 3
+
+type T2 = UnionLength<[string, string, string] | {x: string; y: string; z: string}>;
+//=> 2
+
+type T3 = UnionLength<any>;
+//=> 1
+
+type T4 = UnionLength<never>;
+//=> 0
+```
+
+@category Type
+*/
+export type UnionLength<Union> = UnionToTuple<Union>['length'];
+
+export {};

package/source/union-member.d.ts

@@ -0,0 +1,65 @@
+import type {UnionToIntersection} from './union-to-intersection.d.ts';
+import type {IsNever} from './is-never.d.ts';
+
+/**
+Returns an arbitrary member of a union type.
+
+Use-cases:
+- Implementing recursive type functions that accept a union type.
+
+@example
+```
+import type {UnionMember, IsNever} from 'type-fest';
+
+type UnionLength<T, Acc extends any[] = []> =
+	UnionMember<T> extends infer Member
+		? IsNever<Member> extends false
+			? UnionLength<Exclude<T, Member>, [...Acc, Member]>
+			: Acc['length']
+		: never;
+
+type T1 = UnionLength<'foo' | 'bar' | 'baz'>;
+//=> 3
+
+type T2 = UnionLength<{a: string}>;
+//=> 1
+```
+
+- Picking an arbitrary member from a union
+
+@example
+```
+import type {UnionMember, Primitive, LiteralToPrimitive} from 'type-fest';
+
+type IsHomogenous<T extends Primitive> = [T] extends [LiteralToPrimitive<UnionMember<T>>] ? true : false;
+
+type T1 = IsHomogenous<1 | 2 | 3 | 4>;
+//=> true
+
+type T2 = IsHomogenous<'foo' | 'bar'>;
+//=> true
+
+type T3 = IsHomogenous<'foo' | 'bar' | 1>;
+//=> false
+```
+
+Returns `never` when the input is `never`.
+
+@example
+```
+import type {UnionMember} from 'type-fest';
+
+type LastNever = UnionMember<never>;
+//=> never
+```
+
+@category Type
+*/
+export type UnionMember<T> =
+	IsNever<T> extends true
+		? never
+		: UnionToIntersection<T extends any ? () => T : never> extends () => (infer R)
+			? R
+			: never;
+
+export {};

package/source/union-to-intersection.d.ts

@@ -1,5 +1,5 @@
 /**
-Convert a union type to an intersection type using [distributive conditional types](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
+Convert a union type to an intersection type.
 
 Inspired by [this Stack Overflow answer](https://stackoverflow.com/a/50375286/2172153).