FixedLengthArray: Fix element type (#1246)

Author: som-sm

readme.md

@@ -249,7 +249,7 @@ Click the type names for complete docs.
 - [`Join`](source/join.d.ts) - Join an array of strings and/or numbers using the given string as a delimiter.
 - [`ArraySlice`](source/array-slice.d.ts) - Returns an array slice of a given range, just like `Array#slice()`.
 - [`LastArrayElement`](source/last-array-element.d.ts) - Extracts the type of the last element of an array.
-- [`FixedLengthArray`](source/fixed-length-array.d.ts) - Create a type that represents an array of the given type and length.
+- [`FixedLengthArray`](source/fixed-length-array.d.ts) - Create a type that represents an array of the given type and length. The `Array` prototype methods that manipulate its length are excluded from the resulting type.
 - [`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.

source/fixed-length-array.d.ts

@@ -1,45 +1,89 @@
+import type {Except} from './except.d.ts';
+import type {TupleOf} from './tuple-of.d.ts';
+
 /**
 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.
+Create a type that represents an array of the given type and length. The `Array` prototype methods that manipulate its length are excluded from the resulting type.
+
+The problem with the built-in tuple type is that it allows mutating methods like `push`, `pop` etc, which can cause issues, like in the following example:
+
+@example
+```
+const color: [number, number, number] = [255, 128, 64];
+
+function toHex([r, g, b]: readonly [number, number, number]) {
+	return `#${r.toString(16)}${g.toString(16)}${b.toString(16)}`;
+}
 
-Please participate in [this issue](https://github.com/microsoft/TypeScript/issues/26223) if you want to have a similar type built into TypeScript.
+color.pop(); // Allowed
+
+console.log(toHex(color)); // Compiles fine, but fails at runtime since index `2` no longer contains a `number`.
+```
+
+`ArrayLengthMutationKeys` solves this problem by excluding methods like `push`, `pop` etc from the resulting type.
+
+@example
+```
+import type {FixedLengthArray} from 'type-fest';
+
+const color: FixedLengthArray<number, 3> = [255, 128, 64];
+
+color.pop();
+//=> Error: Property 'pop' does not exist on type 'FixedLengthArray<number, 3>'.
+```
 
 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.
 
-Note: This type does not prevent out-of-bounds access. Prefer `ReadonlyTuple` unless you need mutability.
-
 @example
 ```
-import type {FixedLengthArray} from 'type-fest';
+let color: FixedLengthArray<number, 3> = [255, 128, 64];
+
+const red = color[0];
+//=> number
+const green = color[1];
+//=> number
+const blue = color[2];
+//=> number
+
+const alpha = color[3];
+//=> Error: Property '3' does not exist on type 'FixedLengthArray<number, 3>'.
+
+// You can write to valid indices.
+color[0] = 128;
+color[1] = 64;
+color[2] = 32;
+
+// But you cannot write to out-of-bounds indices.
+color[3] = 0.5;
+//=> Error: Property '3' does not exist on type 'FixedLengthArray<number, 3>'.
+
+color.push(0.5);
+//=> Error: Property 'push' does not exist on type 'FixedLengthArray<number, 3>'.
 
-type FencingTeam = FixedLengthArray<string, 3>;
+color = [0, 128, 255, 0.5];
+//=> Error: Type '[number, number, number, number]' is not assignable to type 'FixedLengthArray<number, 3>'. Types of property 'length' are incompatible.
 
-const guestFencingTeam: FencingTeam = ['Josh', 'Michael', 'Robert'];
+color.length = 4;
+//=> Error: Cannot assign to 'length' because it is a read-only property.
 
-const homeFencingTeam: FencingTeam = ['George', 'John'];
-//=> error TS2322: Type string[] is not assignable to type 'FencingTeam'
+function toHex([r, g, b]: readonly [number, number, number]) {
+	return `#${r.toString(16)}${g.toString(16)}${b.toString(16)}`;
+}
 
-guestFencingTeam.push('Sam');
-//=> error TS2339: Property 'push' does not exist on type 'FencingTeam'
+console.log(toHex(color)); // `FixedLengthArray<number, 3>` is assignable to `readonly [number, number, number]`.
 ```
 
 @category Array
-@see ReadonlyTuple
 */
-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;
-};
+export type FixedLengthArray<Element, Length extends number> =
+	Except<TupleOf<Length, Element>, ArrayLengthMutationKeys | number | 'length'>
+	& {readonly length: Length}
+	& (number extends Length ? {[n: number]: Element} : {}); // Add `number` index signature only for non-tuple arrays.
 
 export {};

test-d/fixed-length-array.ts

@@ -1,11 +1,86 @@
-import {expectAssignable, expectNotAssignable} from 'tsd';
+import {expectAssignable, expectNotAssignable, expectType} from 'tsd';
 import type {FixedLengthArray} from '../index.d.ts';
 
 type FixedToThreeStrings = FixedLengthArray<string, 3>;
+declare const fixedToThreeStrings: FixedToThreeStrings;
 
 expectAssignable<FixedToThreeStrings>(['a', 'b', 'c']);
+expectAssignable<readonly [string, string, string]>({} as FixedToThreeStrings);
+expectAssignable<readonly string[]>({} as FixedToThreeStrings);
+
+// Reading within bounds
+expectType<string>({} as FixedToThreeStrings[0]);
+expectType<string>({} as FixedToThreeStrings[1]);
+expectType<string>({} as FixedToThreeStrings[2]);
+
+// Reading out of bounds
+// @ts-expect-error
+type OutOfBounds = FixedToThreeStrings[3];
+
+// Writing within bounds
+fixedToThreeStrings[0] = 'a';
+fixedToThreeStrings[1] = 'b';
+fixedToThreeStrings[2] = 'c';
+
+// Writing out of bounds
+// @ts-expect-error
+fixedToThreeStrings[3] = 'd';
+
+expectType<3>({} as FixedToThreeStrings['length']);
+
+// @ts-expect-error
+type NoSplice = FixedToThreeStrings['splice'];
+// @ts-expect-error
+type NoPush = FixedToThreeStrings['push'];
+// @ts-expect-error
+type NoPop = FixedToThreeStrings['pop'];
+// @ts-expect-error
+type NoShift = FixedToThreeStrings['shift'];
+// @ts-expect-error
+type NoUnshift = FixedToThreeStrings['unshift'];
 
 expectNotAssignable<FixedToThreeStrings>(['a', 'b', 123]);
 expectNotAssignable<FixedToThreeStrings>(['a']);
 expectNotAssignable<FixedToThreeStrings>(['a', 'b']);
 expectNotAssignable<FixedToThreeStrings>(['a', 'b', 'c', 'd']);
+
+type FixedLength = FixedLengthArray<string, number>;
+declare const fixedLength: FixedLength;
+
+expectAssignable<FixedLength>({} as string[]);
+expectAssignable<readonly string[]>({} as FixedLength);
+
+// Reading
+// Note: The extra `undefined` is only present when `noUncheckedIndexedAccess` is enabled.
+expectType<string | undefined>(fixedLength[0]);
+expectType<string | undefined>(fixedLength[100]);
+// Note: Reading directly from the type doesn't include `undefined`.
+expectType<string>({} as FixedLength[100]);
+
+// Writing
+// This is allowed for now, refer https://github.com/sindresorhus/type-fest/pull/1246#discussion_r2384018774
+fixedLength[0] = 'a';
+fixedLength[100] = 'b';
+
+// @ts-expect-error
+type NoSplice = FixedLength['splice'];
+// @ts-expect-error
+type NoPush = FixedLength['push'];
+// @ts-expect-error
+type NoPop = FixedLength['pop'];
+// @ts-expect-error
+type NoShift = FixedLength['shift'];
+// @ts-expect-error
+type NoUnshift = FixedLength['unshift'];
+
+expectAssignable<FixedLengthArray<string | number, 3>>(['a', 'b', 'c']);
+expectAssignable<FixedLengthArray<string | number, 3>>([3, 2, 1]);
+expectAssignable<FixedLengthArray<string | number, 3>>(['a', 'b', 3]);
+expectAssignable<FixedLengthArray<string | number, 3>>([1, 'b', 3]);
+expectNotAssignable<FixedLengthArray<string | number, 3>>([1, 'b', 3, 4]);
+expectNotAssignable<FixedLengthArray<string | number, 3>>([1, 'b', true]);
+
+expectAssignable<FixedLengthArray<string, 2 | 3>>(['a', 'b']);
+expectAssignable<FixedLengthArray<string, 2 | 3>>(['a', 'b', 'c']);
+expectNotAssignable<FixedLengthArray<string, 2 | 3>>(['a']);
+expectNotAssignable<FixedLengthArray<string, 2 | 3>>([1, 2]);