Add FixedLengthArray type (#106)

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

Author: kainiedziela

index.d.ts

@@ -23,6 +23,7 @@ export {ConditionalKeys} from './source/conditional-keys';
 export {ConditionalPick} from './source/conditional-pick';
 export {UnionToIntersection} from './source/union-to-intersection';
 export {Stringified} from './source/stringified';
+export {FixedLengthArray} from './source/fixed-length-array';
 
 // Miscellaneous
 export {PackageJson} from './source/package-json';

readme.md

@@ -82,6 +82,7 @@ Click the type names for complete docs.
 - [`ConditionalExcept`](source/conditional-except.d.ts) - Like `Omit` except it removes properties from a shape where the values extend the given `Condition` type.
 - [`UnionToIntersection`](source/union-to-intersection.d.ts) - Convert a union type to an intersection type.
 - [`Stringified`](source/stringified.d.ts) - Create a type with the keys of the given type changed to `string` type.
+- [`FixedLengthArray`](source/fixed-length-array.d.ts) - Create a type that represents an array of the given type and length.
 
 ### Miscellaneous
 

source/fixed-length-array.d.ts

@@ -0,0 +1,38 @@
+/**
+Methods to exclude.
+*/
+type ArrayLengthMutationKeys = 'splice' | 'push' | 'pop' | 'shift' | 'unshift';
+
+/**
+Create a type that represents an array of the given type and length. The array's length and the `Array` prototype methods that manipulate its length are excluded in the resulting type.
+
+Please participate in [this issue](https://github.com/microsoft/TypeScript/issues/26223) if you want to have a similiar type built into TypeScript.
+
+Use-cases:
+- Declaring fixed-length tuples or arrays 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 an array of coordinates with a static length, for example, length of 3 for a 3D vector.
+
+@example
+```
+import {FixedLengthArray} from 'type-fest';
+
+type FencingTeam = FixedLengthArray<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'
+```
+*/
+export type FixedLengthArray<Element, Length extends number, ArrayPrototype = [Element, ...Element[]]> = Pick<
+	ArrayPrototype,
+	Exclude<keyof ArrayPrototype, ArrayLengthMutationKeys>
+> & {
+	[index: number]: Element;
+	[Symbol.iterator]: () => IterableIterator<Element>;
+	readonly length: Length;
+};

test-d/fixed-length-array.ts

@@ -0,0 +1,11 @@
+import {expectAssignable, expectNotAssignable} from 'tsd';
+import {FixedLengthArray} from '..';
+
+type FixedToThreeStrings = FixedLengthArray<string, 3>;
+
+expectAssignable<FixedToThreeStrings>(['a', 'b', 'c']);
+
+expectNotAssignable<FixedToThreeStrings>(['a', 'b', 123]);
+expectNotAssignable<FixedToThreeStrings>(['a']);
+expectNotAssignable<FixedToThreeStrings>(['a', 'b']);
+expectNotAssignable<FixedToThreeStrings>(['a', 'b', 'c', 'd']);