Add ArrayFlat type

Author: Emiyaaaaa

index.d.ts

@@ -129,6 +129,7 @@ export type {ArrayValues} from './source/array-values';
 export type {ArraySlice} from './source/array-slice';
 export type {ArraySplice} from './source/array-splice';
 export type {ArrayTail} from './source/array-tail';
+export type {ArrayFlat} from './source/array-flat';
 export type {SetFieldType} from './source/set-field-type';
 export type {Paths} from './source/paths';
 export type {AllUnionFields} from './source/all-union-fields';

readme.md

@@ -285,6 +285,7 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 - [`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()`.
+- [`ArrayFlat`](source/array-flat.d.ts) - Creates a new array type by flattening an array to a specified depth, just like `Array#flat()`.
 - [`LastArrayElement`](source/last-array-element.d.ts) - Extracts 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.
 - [`MultidimensionalArray`](source/multidimensional-array.d.ts) - Create a type that represents a multidimensional array of the given type and dimensions.

source/array-flat.d.ts

@@ -0,0 +1,56 @@
+import type {IsAny} from './is-any';
+import type {IsNever} from './is-never';
+import type {Or} from './or';
+import type {Subtract} from './subtract';
+import type {UnknownArray} from './unknown-array';
+
+/**
+Creates a new array type by flattening an array to a specified depth.
+
+Use-case: Flatten an array type to a specified depth.
+
+Like [`Array#flat()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat) but for types.
+
+@example
+```
+import type {ArrayFlat, PositiveInfinity} from 'type-fest';
+
+type FlatArr0 = ArrayFlat<[[0, 1], [2, 3], [4, 5]]>;
+//=> type FlatArr0 = [0, 1, 2, 3, 4, 5];
+
+// Flatten to depth
+type Arr1 = [[0, [1, [2, [3, [4, [5]]]]]]];
+type FlatArr1 = ArrayFlat<Arr1, 1>;
+//=> type FlatArr1 = [0, [1, [2, [3, [4, [5]]]]]];
+
+type FlatArr2 = ArrayFlat<Arr1, 3>;
+//=> type FlatArr2 = [0, 1, 2, [3, [4, [5]]]];
+
+// Flatten to depth Infinity
+type FlatArr3 = ArrayFlat<Arr1, PositiveInfinity>;
+//=> type FlatArr3 = [0, 1, 2, 3, 4, 5];
+```
+
+@category Array
+*/
+export type ArrayFlat<T, Depth extends number = 1> = InternalArrayFlat<T, Depth>;
+
+// Internal implementation
+type InternalArrayFlat<T, Depth extends number = 1, Result extends UnknownArray = [] > =
+T extends UnknownArray
+	? T['length'] extends 0
+		? [...Result, ...T]
+		: Depth extends 0
+			? [...Result, ...T]
+			: T extends readonly [infer ArrayItem, ...infer Last]
+				?	ArrayItem extends UnknownArray
+					? InternalArrayFlat<Last, Depth, [...Result, ...InternalArrayFlat<ArrayItem, Subtract<Depth, 1>>]>
+					: InternalArrayFlat<Last, Depth, [...Result, ArrayItem]>
+				: T extends Array<infer ArrayItem2>
+					? Or<IsAny<ArrayItem2>, IsNever<ArrayItem2>> extends true
+						? [...Result, ...ArrayItem2[]] // Return never/any[] when input is never/any[]
+						: ArrayItem2 extends UnknownArray
+							? InternalArrayFlat<ArrayItem2, Subtract<Depth, 1>, Result>
+							: [...Result, ...ArrayItem2[]]
+					: [...Result, ...T]
+	: T;

test-d/array-flat.ts

@@ -0,0 +1,60 @@
+import {expectType} from 'tsd';
+import type {ArrayFlat, PositiveInfinity} from '../index';
+
+// Basic flattening tests
+expectType<ArrayFlat<[]>>([]);
+expectType<ArrayFlat<[1, 2, 3]>>([1, 2, 3]);
+expectType<ArrayFlat<[[1, 2], [3, 4]]>>([1, 2, 3, 4]);
+expectType<ArrayFlat<[1, [2, 3], 4]>>([1, 2, 3, 4]);
+expectType<ArrayFlat<[1, [2, [3]], 4]>>([1, 2, [3], 4]);
+
+// Test with explicit depth
+// eslint-disable-next-line unicorn/prevent-abbreviations
+type Arr = [[0, [1, [2, [3, [4, [5]]]]]]];
+expectType<ArrayFlat<Arr, 0>>(null! as Arr);
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments
+expectType<ArrayFlat<Arr, 1>>([0, [1, [2, [3, [4, [5]]]]]]);
+expectType<ArrayFlat<Arr, 2>>([0, 1, [2, [3, [4, [5]]]]]);
+expectType<ArrayFlat<Arr, 3>>([0, 1, 2, [3, [4, [5]]]]);
+expectType<ArrayFlat<Arr, 4>>([0, 1, 2, 3, [4, [5]]]);
+expectType<ArrayFlat<Arr, 5>>([0, 1, 2, 3, 4, [5]]);
+expectType<ArrayFlat<Arr, 6>>([0, 1, 2, 3, 4, 5]);
+expectType<ArrayFlat<Arr, 7>>([0, 1, 2, 3, 4, 5]);
+expectType<ArrayFlat<Arr, PositiveInfinity>>([0, 1, 2, 3, 4, 5]);
+
+// Test with Infinity depth
+expectType<ArrayFlat<[1, [2, [3, [4]]]], PositiveInfinity>>([1, 2, 3, 4]);
+expectType<ArrayFlat<[[[[[1]]]]], PositiveInfinity>>([1]);
+
+// Test with different element types
+expectType<ArrayFlat<[string, [number, boolean]]>>([null! as string, null! as number, null! as boolean]);
+expectType<ArrayFlat<[{a: number}, [{b: string}]]>>([null! as {a: number}, null! as {b: string}]);
+
+// Test with union types
+expectType<ArrayFlat<[1, 2] | [[3, 4]]>>([1, 2] as [1, 2] | [3, 4]);
+expectType<ArrayFlat<[1, [2]] | [[3], 4]>>([1, 2] as [1, 2] | [3, 4]);
+
+// Test with rest elements
+expectType<ArrayFlat<[...Array<[number, string]>]>>([null! as number, null! as string]);
+expectType<ArrayFlat<[1, 2, ...Array<[string, boolean]>]>>([1, 2, null! as string, null! as boolean]);
+expectType<ArrayFlat<[1, [2, ...Array<3>], 4]>>([1, 2, ...(null! as Array<3>), 4]);
+
+// Test with mixed arrays and tuples
+expectType<ArrayFlat<[1, number[], 3]>>([1, ...(null! as number[]), 3]);
+expectType<ArrayFlat<[string, [number, ...boolean[]]]>>([null! as string, null! as number, ...(null! as boolean[])]);
+
+// Test with deeply nested structures
+expectType<ArrayFlat<[1, [2, [3, [4, [5]]]]], 3>>([1, 2, 3, 4, [5]]);
+
+// Test with readonly arrays
+expectType<ArrayFlat<readonly [1, readonly [2, 3]]>>([1, 2, 3]);
+expectType<ArrayFlat<readonly [readonly [1, 2], readonly [3, 4]]>>([1, 2, 3, 4]);
+
+// Edge cases
+expectType<ArrayFlat<Array<[]>>>([]);
+expectType<ArrayFlat<[[]]>>([]);
+expectType<ArrayFlat<[[], []]>>([]);
+expectType<ArrayFlat<undefined[]>>(null! as undefined[]);
+expectType<ArrayFlat<any[]>>(null! as any[]);
+expectType<ArrayFlat<unknown[]>>(null! as unknown[]);
+expectType<ArrayFlat<never[]>>(null! as never[]);