Add ArrayReverse type (#1266)

Co-authored-by: benz <benzaria@users.noreply.github.com>

Author: som-sm

.github/workflows/main.yml

@@ -42,4 +42,4 @@ jobs:
           node-version: 24
       - run: npm install
       - run: npm install typescript@${{ matrix.typescript-version }}
-      - run: NODE_OPTIONS="--max-old-space-size=5120" npx tsc
+      - run: NODE_OPTIONS="--max-old-space-size=6144" npx tsc

.github/workflows/ts-canary.yml

@@ -23,4 +23,4 @@ jobs:
       - run: npm install typescript@${{ matrix.typescript-version }}
       - name: show installed typescript version
         run: npm list typescript --depth=0
-      - run: NODE_OPTIONS="--max-old-space-size=5120" npx tsc
+      - run: NODE_OPTIONS="--max-old-space-size=6144" npx tsc

index.d.ts

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

package.json

@@ -25,9 +25,9 @@
 		"node": ">=20"
 	},
 	"scripts": {
-		"test:tsc": "node --max-old-space-size=5120 ./node_modules/.bin/tsc",
-		"test:tsd": "tsd",
-		"test:xo": "xo",
+		"test:tsc": "node --max-old-space-size=6144 ./node_modules/.bin/tsc",
+		"test:tsd": "node --max-old-space-size=6144 ./node_modules/.bin/tsd",
+		"test:xo": "node --max-old-space-size=6144 ./node_modules/.bin/xo",
 		"test:linter": "node --test",
 		"test": "run-p test:*"
 	},

readme.md

@@ -263,6 +263,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) - Extract 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) - Create a tuple with the [`rest`](https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types) element removed.
+- [`ArrayReverse`](source/array-reverse.d.ts) - Reverse 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';
+
+/**
+Reverse 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, number, ...boolean[]]>;
+//=> readonly [...boolean[], number, 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] | [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 `TArray` is empty (e.g., `[]`),
+		// or `TArray` 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]
+			? IsOptionalKeyOf<TArray, '0'> extends true
+				? _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 {};