Add ReadonlyTuple type

index.d.ts

@@ -54,6 +54,7 @@ export {
 	NonNegativeInteger,
 } from './source/numeric';
 export {StringKeyOf} from './source/string-key-of';
+export {ReadonlyTuple} from './source/readonly-tuple';
 
 // Template literal types
 export {CamelCase} from './source/camel-case';

readme.md

@@ -150,6 +150,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 readonly tuple of the given type and length.
 
 ### Numeric
 

source/fixed-length-array.d.ts

@@ -28,6 +28,8 @@ guestFencingTeam.push('Sam');
 //=> error TS2339: Property 'push' does not exist on type 'FencingTeam'
 ```
 
+@deprecated This type doesn't prevent you to access values outside the array length via index (see issue#284),
+            use ReadonlyTuple instead.
 @category Array
 */
 export type FixedLengthArray<Element, Length extends number, ArrayPrototype = [Element, ...Element[]]> = Pick<

source/readonly-tuple.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Creates a readonly tuple of <Element> and length '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 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 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');