Add ReadonlyTuple type (#383)

Co-authored-by: Sindre Sorhus <sindresorhus@gmail.com>

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

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
 

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,

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.

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