feat: add reverse type

Author: som-sm

index.d.ts

@@ -162,6 +162,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 {ArrayReverse} from './source/array-reverse.d.ts';
 
 // Template literal types
 export type {CamelCase, CamelCaseOptions} from './source/camel-case.d.ts';

readme.md

@@ -261,6 +261,7 @@ Click the type names for complete docs.
 - [`SplitOnRestElement`](source/split-on-rest-element.d.ts) - Splits an array into three parts, where the first contains all elements before the rest element, the second is the [`rest`](https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types) element itself, and the third contains all elements after the rest element.
 - [`ExtractRestElement`](source/extract-rest-element.d.ts) - Extracts the [`rest`](https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types) element type from an array.
 - [`ExcludeRestElement`](source/exclude-rest-element.d.ts) - Creates a tuple with the [`rest`](https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types) element removed.
+- [`ArrayReverse`](source/array-reverse.d.ts) - Reverses the order of elements in a tuple type.
 
 ### Numeric
 

source/array-reverse.d.ts

@@ -0,0 +1,84 @@
+import type {If} from './if.d.ts';
+import type {IsArrayReadonly} from './internal/array.d.ts';
+import type {IfNotAnyOrNever, IsExactOptionalPropertyTypesEnabled} from './internal/type.d.ts';
+import type {IsOptionalKeyOf} from './is-optional-key-of.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+
+/**
+Reverses the order of elements in a tuple type.
+
+@example
+```ts
+import type {ArrayReverse} from 'type-fest';
+
+type A = ArrayReverse<[string, number, boolean]>;
+//=> [boolean, number, string]
+
+type B = ArrayReverse<readonly [string, string, ...number[]]>;
+//=> readonly [...number[], string, string]
+
+type C = ArrayReverse<["foo", "bar"] | readonly [1, 2, 3]>;
+//=> ["bar", "foo"] | readonly [3, 2, 1]
+
+type D = ArrayReverse<string[]>;
+//=> string[]
+
+type E = ArrayReverse<[]>;
+//=> []
+```
+
+Note: If the tuple contains optional elements, the result will be a union of tuples, refer to the examples below:
+
+@example
+```ts
+import type {ArrayReverse} from 'type-fest';
+
+type A = ArrayReverse<[string, number, boolean?]>;
+//=> [boolean, number, string] | [number, string]
+
+type B = ArrayReverse<[string, number?, boolean?]>;
+//=> [boolean, number, string] | [number, string] | [string]
+
+type C = ArrayReverse<[string?, number?, boolean?]>;
+//=> [boolean, number, string] | [number, string] | [string] | []
+
+type D = ArrayReverse<[string, number?, ...boolean[]]>;
+//=> [...boolean[], number, string] | [string]
+
+type E = ArrayReverse<[string?, number?, ...boolean[]]>;
+//=> [...boolean[], number, string] | [number, string] | [string] | []
+```
+
+@category Array
+*/
+export type ArrayReverse<TArray extends UnknownArray> = IfNotAnyOrNever<TArray,
+	TArray extends unknown // For distributing `TArray`
+		? _ArrayReverse<TArray> extends infer Result
+			? If<IsArrayReadonly<TArray>, Readonly<Result>, Result>
+			: never // Should never happen
+		: never>; // Should never happen
+
+type _ArrayReverse<
+	TArray extends UnknownArray,
+	BeforeRestAcc extends UnknownArray = [],
+	AfterRestAcc extends UnknownArray = [],
+	Result extends UnknownArray = never,
+> =
+	keyof TArray & `${number}` extends never
+        // Enters this branch, if `Array_` is empty (e.g., `[]`),
+		// or `Array_` contains no non-rest elements preceding the rest element (e.g., `[...string[]]` or `[...string[], string]`).
+		? TArray extends readonly [...infer Rest, infer Last]
+			? _ArrayReverse<Rest, BeforeRestAcc, [...AfterRestAcc, Last], Result> // Accumulate elements that are present after the rest element in reverse order.
+			: Result | [...AfterRestAcc, ...TArray, ...BeforeRestAcc] // Add the rest element between the accumulated elements.
+		: TArray extends readonly [(infer First)?, ...infer Rest]
+			? If<IsOptionalKeyOf<TArray, '0'>,
+				_ArrayReverse<
+					Rest,
+					[First | (If<IsExactOptionalPropertyTypesEnabled, never, undefined>), ...BeforeRestAcc], // Add `| undefined` for optional elements, if `exactOptionalPropertyTypes` is disabled.
+					AfterRestAcc,
+                    Result | BeforeRestAcc
+				>,
+				_ArrayReverse<Rest, [First, ...BeforeRestAcc], AfterRestAcc, Result>>
+			: never; // Should never happen, since `readonly [(infer First)?, ...infer Rest]` is a top-type for arrays.
+
+export {};

test-d/array-reverse.ts

@@ -0,0 +1,68 @@
+import {expectType} from 'tsd';
+import type {ArrayReverse} from '../source/array-reverse.d.ts';
+
+// Empty & single-element tuples
+expectType<[]>({} as ArrayReverse<[]>);
+expectType<readonly []>({} as ArrayReverse<readonly []>);
+expectType<[string]>({} as ArrayReverse<[string]>);
+expectType<readonly [number]>({} as ArrayReverse<readonly [number]>);
+expectType<[any]>({} as ArrayReverse<[any]>);
+expectType<[never]>({} as ArrayReverse<[never]>);
+
+// Only required elements
+expectType<[3, 2, 1]>({} as ArrayReverse<[1, 2, 3]>);
+expectType<readonly [string, number, boolean, bigint]>({} as ArrayReverse<readonly [bigint, boolean, number, string]>);
+expectType<['a' | 1, 2, 'c' | 3]>({} as ArrayReverse<['c' | 3, 2, 'a' | 1]>);
+
+// Required and rest element
+expectType<readonly [...string[], 3, 2, 1]>({} as ArrayReverse<readonly [1, 2, 3, ...string[]]>); // Rest element at the end
+expectType<['z', 'y', 'x', ...boolean[], 3, 2, 1]>({} as ArrayReverse<[1, 2, 3, ...boolean[], 'x', 'y', 'z']>); // Rest element in the middle
+expectType<readonly [string, ...bigint[]]>({} as ArrayReverse<readonly [...bigint[], string]>); // Rest element at the start
+
+// Required and optional elements
+expectType<[3, 2, 1] | [2, 1]>({} as ArrayReverse<[1, 2, 3?]>);
+expectType<readonly [3, 2, 1] | readonly [2, 1] | readonly [1]>({} as ArrayReverse<readonly [1, 2?, 3?]>);
+expectType<[number, boolean, bigint, number, string] | [boolean, bigint, number, string] | [bigint, number, string] | [number, string]>(
+	{} as ArrayReverse<[string, number, bigint?, boolean?, number?]>,
+);
+
+// Only optional elements
+expectType<['a'] | []>({} as ArrayReverse<['a'?]>);
+expectType<readonly [{data: string[]}] | readonly []>({} as ArrayReverse<readonly [{data: string[]}?]>);
+expectType<[bigint, boolean, string] | [boolean, string] | [string] | []>({} as ArrayReverse<[string?, boolean?, bigint?]>);
+
+// Required, optional, and rest element
+expectType<[...string[], 3, 2, 1] | [2, 1]>({} as ArrayReverse<[1, 2, 3?, ...string[]]>);
+expectType<readonly [...string[], string, number] | readonly [number]>({} as ArrayReverse<readonly [number, string?, ...string[]]>);
+
+// Optional and rest element
+expectType<readonly [...string[], 1] | readonly []>({} as ArrayReverse<readonly [1?, ...string[]]>);
+expectType<[...number[], 3, 2, 1] | [2, 1] | [1] | []>({} as ArrayReverse<[1?, 2?, 3?, ...number[]]>);
+
+// Nested tuples
+expectType<[6, 5, [3, 4], [1, 2]]>({} as ArrayReverse<[[1, 2], [3, 4], 5, 6]>);
+expectType<[Array<{y: string}>, Array<{x: string}>]>({} as ArrayReverse<[Array<{x: string}>, Array<{y: string}>]>);
+expectType<[3, [1, 2]] | [[1, 2]] | []>({} as ArrayReverse<[[1, 2]?, 3?]>);
+
+// Unions
+expectType<[3, 2, 1] | readonly ['b', 'a']>({} as ArrayReverse<[1, 2, 3] | readonly ['a', 'b']>);
+expectType<readonly [number, string] | number[]>({} as ArrayReverse<readonly [string, number] | number[]>);
+expectType<readonly [3, 2, 1] | readonly [2, 1] | readonly [1] | ['b', 'a'] | ['a'] | [] | [number, string]>(
+	{} as ArrayReverse<readonly [1, 2?, 3?] | ['a'?, 'b'?] | [string, number]>,
+);
+
+// Labelled tuples
+expectType<[number, number]>({} as ArrayReverse<[x: number, y: number]>);
+expectType<readonly [number, string] | readonly [string]>({} as ArrayReverse<readonly [x: string, y?: number]>);
+expectType<[...number[], string]>({} as ArrayReverse<[x: string, ...rest: number[]]>);
+
+// Non-tuple arrays
+expectType<string[]>({} as ArrayReverse<string[]>);
+expectType<readonly number[]>({} as ArrayReverse<readonly number[]>);
+expectType<ReadonlyArray<number | bigint>>({} as ArrayReverse<ReadonlyArray<number | bigint>>);
+expectType<any[]>({} as ArrayReverse<any[]>);
+expectType<never[]>({} as ArrayReverse<never[]>);
+
+// Boundary cases
+expectType<never>({} as ArrayReverse<never>);
+expectType<any>({} as ArrayReverse<any>);