Add ArrayElement type (#1270)

Co-authored-by: Som Shekhar Mukherjee <49264891+som-sm@users.noreply.github.com>

Author: sindresorhus

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

readme.md

@@ -249,6 +249,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.

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 {};

source/exact.d.ts

@@ -1,4 +1,5 @@
-import type {ArrayElement, ObjectValue} from './internal/index.d.ts';
+import type {ObjectValue} from './internal/index.d.ts';
+import type {ArrayElement} from './array-element.d.ts';
 import type {IsEqual} from './is-equal.d.ts';
 import type {KeysOfUnion} from './keys-of-union.d.ts';
 import type {IsUnknown} from './is-unknown.d.ts';

source/internal/array.d.ts

@@ -24,15 +24,6 @@ export type FirstArrayElement<TArray extends UnknownArrayOrTuple> = TArray exten
 	? THead
 	: never;
 
-/**
-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;
-
 /**
 Returns the static, fixed-length portion of the given array, excluding variable-length parts.
 

test-d/array-element.ts

@@ -0,0 +1,51 @@
+import {expectType} from 'tsd';
+import type {ArrayElement} from '../index.d.ts';
+
+// Basic array
+expectType<string>({} as ArrayElement<string[]>);
+expectType<number>({} as ArrayElement<number[]>);
+
+// Tuple
+expectType<1 | 2 | 3>({} as ArrayElement<[1, 2, 3]>);
+expectType<'a' | 'b' | 'c'>({} as ArrayElement<['a', 'b', 'c']>);
+
+// Const tuple
+expectType<'foo' | 'bar' | 'baz'>({} as ArrayElement<readonly ['foo', 'bar', 'baz']>);
+expectType<1 | 2 | 3>({} as ArrayElement<readonly [1, 2, 3]>);
+
+// Mixed types
+expectType<string | number>({} as ArrayElement<[string, number]>);
+expectType<string | number>({} as ArrayElement<[string, number]>);
+
+// Readonly array
+expectType<string>({} as ArrayElement<readonly string[]>);
+expectType<1 | 2 | 3>({} as ArrayElement<readonly [1, 2, 3]>);
+
+// Empty array
+expectType<never>({} as ArrayElement<[]>);
+expectType<never>({} as ArrayElement<readonly []>);
+
+// Union of arrays
+expectType<1 | 2 | 3 | 4>({} as ArrayElement<[1, 2] | [3, 4]>);
+
+// Function use case
+declare function getRandomElement<T extends readonly unknown[]>(array: T): ArrayElement<T>;
+
+expectType<number>(getRandomElement([1, 2, 3]));
+expectType<'foo' | 'bar' | 'baz'>(getRandomElement(['foo', 'bar', 'baz'] as const));
+expectType<string>(getRandomElement(['foo', 'bar', 'baz']));
+
+// Edge cases
+expectType<any>({} as ArrayElement<any>);
+expectType<never>({} as ArrayElement<never>);
+expectType<unknown>({} as ArrayElement<unknown[]>);
+
+// Non-arrays return never
+expectType<never>({} as ArrayElement<string>);
+expectType<never>({} as ArrayElement<{a: string}>);
+
+// Optional and rest elements
+expectType<1 | 2 | 3 | undefined>(1 as ArrayElement<[1, 2, 3?]>);
+expectType<string | number>(1 as ArrayElement<[string, ...number[]]>);
+expectType<1 | 2 | string>(1 as ArrayElement<[1, 2, ...string[]]>);
+expectType<1 | 2 | undefined | string>(1 as ArrayElement<[1, 2?, ...string[]]>);