From f445cc690c4dac6c8fe3d58512d1fcf967f73e6c Mon Sep 17 00:00:00 2001
From: Davide Menegatti <d.menegatti@recrosoftware.com>
Date: Tue, 24 May 2022 15:20:19 +0200
Subject: [PATCH] Add `ReadonlyTuple` type (#383)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>
---
 index.d.ts                     |  1 +
 readme.md                      |  1 +
 source/fixed-length-array.d.ts |  3 +++
 source/readonly-tuple.d.ts     | 41 ++++++++++++++++++++++++++++++++++
 test-d/readonly-tuple.ts       | 16 +++++++++++++
 5 files changed, 62 insertions(+)
 create mode 100644 source/readonly-tuple.d.ts
 create mode 100644 test-d/readonly-tuple.ts

diff --git a/index.d.ts b/index.d.ts
index 37a841f30..8937b6937 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -56,6 +56,7 @@ export {
 } from './source/numeric';
 export {StringKeyOf} from './source/string-key-of';
 export {Exact} from './source/exact';
+export {ReadonlyTuple} from './source/readonly-tuple';
 
 // Template literal types
 export {CamelCase} from './source/camel-case';
diff --git a/readme.md b/readme.md
index 5636533c2..3d9ac2f54 100644
--- a/readme.md
+++ b/readme.md
@@ -219,6 +219,7 @@ Click the type names for complete docs.
 - [`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.
 - [`MultidimensionalReadonlyArray`](source/multidimensional-readonly-array.d.ts) - Create a type that represents a multidimensional readonly array of the given type and dimensions.
+- [`ReadonlyTuple`](source/readonly-tuple.d.ts) - Create a type that represents a read-only tuple of the given type and length.
 
 ### Numeric
 
diff --git a/source/fixed-length-array.d.ts b/source/fixed-length-array.d.ts
index 18ce559f7..9152e906b 100644
--- a/source/fixed-length-array.d.ts
+++ b/source/fixed-length-array.d.ts
@@ -13,6 +13,8 @@ Use-cases:
 - Creating a range union (for example, `0 | 1 | 2 | 3 | 4` from the keys of such a type) without having to resort to recursive types.
 - Creating an array of coordinates with a static length, for example, length of 3 for a 3D vector.
 
+Note: This type does not prevent out-of-bounds access. Prefer `ReadonlyTuple` unless you need mutability.
+
 @example
 ```
 import type {FixedLengthArray} from 'type-fest';
@@ -29,6 +31,7 @@ guestFencingTeam.push('Sam');
 ```
 
 @category Array
+@see ReadonlyTuple
 */
 export type FixedLengthArray<Element, Length extends number, ArrayPrototype = [Element, ...Element[]]> = Pick<
 	ArrayPrototype,
diff --git a/source/readonly-tuple.d.ts b/source/readonly-tuple.d.ts
new file mode 100644
index 000000000..fd110733a
--- /dev/null
+++ b/source/readonly-tuple.d.ts
@@ -0,0 +1,41 @@
+/**
+Creates a read-only tuple of type `Element` and with the length of `Length`.
+
+@private
+@see `ReadonlyTuple` which is safer because it tests if `Length` is a specific finite number.
+*/
+type BuildTupleHelper<Element, Length extends number, Rest extends Element[]> =
+	Rest['length'] extends Length ?
+		readonly [...Rest] : // Terminate with readonly array (aka tuple)
+		BuildTupleHelper<Element, Length, [Element, ...Rest]>;
+
+/**
+Create a type that represents a read-only tuple of the given type and length.
+
+Use-cases:
+- Declaring fixed-length tuples with a large number of items.
+- Creating a range union (for example, `0 | 1 | 2 | 3 | 4` from the keys of such a type) without having to resort to recursive types.
+- Creating a tuple of coordinates with a static length, for example, length of 3 for a 3D vector.
+
+@example
+```
+import {ReadonlyTuple} from 'type-fest';
+
+type FencingTeam = ReadonlyTuple<string, 3>;
+
+const guestFencingTeam: FencingTeam = ['Josh', 'Michael', 'Robert'];
+
+const homeFencingTeam: FencingTeam = ['George', 'John'];
+//=> error TS2322: Type string[] is not assignable to type 'FencingTeam'
+
+guestFencingTeam.push('Sam');
+//=> error TS2339: Property 'push' does not exist on type 'FencingTeam'
+```
+
+@category Utilities
+*/
+export type ReadonlyTuple<Element, Length extends number> =
+	number extends Length
+		// Because `Length extends number` and `number extends Length`, then `Length` is not a specific finite number.
+		? readonly Element[] // It's not fixed length.
+		: BuildTupleHelper<Element, Length, []>; // Otherwise it is a fixed length tuple.
diff --git a/test-d/readonly-tuple.ts b/test-d/readonly-tuple.ts
new file mode 100644
index 000000000..b9cc55a55
--- /dev/null
+++ b/test-d/readonly-tuple.ts
@@ -0,0 +1,16 @@
+import {expectAssignable, expectError, expectNotAssignable} from 'tsd';
+import {ReadonlyTuple} from '../index';
+
+type TupleOfThreeStrings = ReadonlyTuple<string, 3>;
+
+expectAssignable<TupleOfThreeStrings>(['a', 'b', 'c']);
+
+expectNotAssignable<TupleOfThreeStrings>(['a', 'b', 123]);
+expectNotAssignable<TupleOfThreeStrings>(['a']);
+expectNotAssignable<TupleOfThreeStrings>(['a', 'b']);
+expectNotAssignable<TupleOfThreeStrings>(['a', 'b', 'c', 'd']);
+
+declare const test: TupleOfThreeStrings;
+
+expectError(test.push);
+expectError(test[2] = 'a');