Expose ArrayElement type

index.d.ts

@@ -122,6 +122,7 @@ export type {ArrayIndices} from './source/array-indices';
 export type {ArrayValues} from './source/array-values';
 export type {ArraySlice} from './source/array-slice';
 export type {ArraySplice} from './source/array-splice';
+export type {ArrayElement} from './source/array-element';
 export type {SetFieldType} from './source/set-field-type';
 export type {Paths} from './source/paths';
 export type {SharedUnionFieldsDeep} from './source/shared-union-fields-deep';

readme.md

@@ -194,6 +194,7 @@ Click the type names for complete docs.
 - [`ArrayIndices`](source/array-indices.d.ts) - Provides valid indices for a constant array or tuple.
 - [`ArrayValues`](source/array-values.d.ts) - Provides all values for a constant array or tuple.
 - [`ArraySplice`](source/array-splice.d.ts) - Creates a new array type by adding or removing elements at a specified index range in the original array.
+- [`ArrayElement`](source/array-element.d.ts) - Extracts the element type of an array or union of arrays.
 - [`SetFieldType`](source/set-field-type.d.ts) - Create a type that changes the type of the given keys.
 - [`Paths`](source/paths.d.ts) - Generate a union of all possible paths to properties in the given object.
 - [`SharedUnionFieldsDeep`](source/shared-union-fields-deep.d.ts) - Create a type with shared fields from a union of object types, deeply traversing nested structures.

source/array-element.d.ts

@@ -0,0 +1,28 @@
+/**
+Extracts the element type of an array or union of arrays.
+
+Returns `never` if T is not an array.
+
+It creates a type-safe way to access the element type of `unknown` type.
+
+@example
+```
+import type {ArrayElement} from 'type-fest';
+
+declare const getMostCommonElement: <T>(array: T[]) => ArrayElement<typeof array>;
+
+getMostCommonElement([1, 2, 3]);
+//=> 1 | 2 | 3
+
+getMostCommonElement(['foo', 'bar', 'baz'] as const);
+//=> 'foo' | 'bar' | 'baz'
+```
+
+@see {@link ArrayValues} for when you know that the input is an array.
+
+@category Array
+*/
+export type ArrayElement<ArrayType extends readonly unknown[]> =
+	ArrayType extends ReadonlyArray<infer ElementType>
+		? ElementType
+		: never;

source/exact.d.ts

@@ -1,4 +1,5 @@
-import type {ArrayElement, ObjectValue} from './internal';
+import type {ObjectValue} from './internal';
+import type {ArrayElement} from './array-element';
 import type {IsEqual} from './is-equal';
 import type {KeysOfUnion} from './keys-of-union';
 import type {IsUnknown} from './is-unknown';
@@ -61,7 +62,7 @@
 			: ParameterType extends Function ? ParameterType
 				: IsEqual<ParameterType, InputType> extends true ? ParameterType
 					// Convert union of array to array of union: A[] & B[] => (A & B)[]
 					: ParameterType extends unknown[] ? Array<Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>>
 						// In TypeScript, Array is a subtype of ReadonlyArray, so always test Array before ReadonlyArray.
 						: ParameterType extends readonly unknown[] ? ReadonlyArray<Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>>
 							: ExactObject<ParameterType, InputType>;

source/internal.d.ts

@@ -277,15 +277,6 @@ Extracts the type of an array or tuple minus the first element.
 */
 export type ArrayTail<TArray extends UnknownArrayOrTuple> = TArray extends readonly [unknown, ...infer TTail] ? TTail : [];
 
-/**
-Extract the element of an array that also works for array union.
-
-Returns `never` if T is not an array.
-
-It creates a type-safe way to access the element type of `unknown` type.
-*/
-export type ArrayElement<T> = T extends readonly unknown[] ? T[0] : never;
-
 /**
 Extract the object field type if T is an object and K is a key of T, return `never` otherwise.
 

test-d/array-element.ts

@@ -0,0 +1,14 @@
+import {expectType} from 'tsd';
+import type {ArrayElement} from '../index';
+
+declare const getArrayElement: <T extends readonly unknown[]>(array: T) => ArrayElement<T>;
+
+expectType<string>(getArrayElement(['a', 'b', 'c']));
+expectType<'a' | 'b' | 'c'>(getArrayElement(['a', 'b', 'c'] as const));
+expectType<number>(getArrayElement([1, 2, 3]));
+expectType<string | number>(getArrayElement(['a', 1]));
+
+declare const notArray: ArrayElement<unknown>;
+
+expectType<never>(getArrayElement([]));
+expectType<never>(notArray);