UNPKG

type-fest

Version:

A collection of essential TypeScript types

161 lines (115 loc) • 5.28 kB
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` 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)}`; } 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]; // @ts-expect-error 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 an array of coordinates with a static length, for example, length of 3 for a 3D vector. @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 // @ts-expect-error 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. // @ts-expect-error color[3] = 0.5; // Error: Property '3' does not exist on type 'FixedLengthArray<number, 3>'. // @ts-expect-error color.push(0.5); // Error: Property 'push' does not exist on type 'FixedLengthArray<number, 3>'. // @ts-expect-error 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. // @ts-expect-error color.length = 4; // Error: Cannot assign to 'length' because it is a read-only property. function toHex([r, g, b]: readonly [number, number, number]) { return `#${r.toString(16)}${g.toString(16)}${b.toString(16)}`; } console.log(toHex(color)); // `FixedLengthArray<number, 3>` is assignable to `readonly [number, number, number]`. ``` Note: A non-literal length, such as `number` or `any`, gives `never`, because the length is not known and so the array is not fixed. A `never` length is an exception and gives an empty tuple. @example ``` import type {FixedLengthArray} from 'type-fest'; type NotFixed = FixedLengthArray<string, number>; //=> never ``` Note: TypeScript cannot infer a literal `Length` from a `FixedLengthArray` value, so a generic helper must specify `Length` explicitly. @example ``` import type {FixedLengthArray} from 'type-fest'; declare function getFirstItem<Item, Length extends number>(values: FixedLengthArray<Item, Length>): Item; const rgb: FixedLengthArray<number, 3> = [255, 128, 64]; // @ts-expect-error `Length` is inferred as `number`, which is not a literal. getFirstItem(rgb); const red = getFirstItem<number, 3>(rgb); //=> number ``` Note: Indexing with a non-literal `number` is not allowed, since the index could be out of bounds. Use `for...of`, `.entries()`, or another array method to go through the items. @example ``` import type {FixedLengthArray} from 'type-fest'; const color: FixedLengthArray<number, 3> = [255, 128, 64]; declare const randomIndex: number; // @ts-expect-error const item = color[randomIndex]; // Error: Element implicitly has an 'any' type because expression of type 'number' can't be used to index type 'FixedLengthArray<number, 3>'. for (const [index, value] of color.entries()) { console.log(index, value); } ``` Note: Spreading the array into an array literal results in `any[]`. TypeScript reads the element type from the `number` index signature, which the type does not have. Use `Array.from()` or `.slice()` to copy it instead. @example ``` import type {FixedLengthArray} from 'type-fest'; const color: FixedLengthArray<number, 3> = [255, 128, 64]; const copy = [...color]; //=> any[] ``` @category Array */ export type FixedLengthArray<Element, Length extends number> = _FixedLengthArray<TupleOf<Length, Element>>; type _FixedLengthArray<Tuple extends unknown[]> = Tuple extends unknown // Keep each tuple's indices paired with its length so that checking `length` narrows a union. // `TupleOf` gives a plain array for a non-literal length, also when a brand is unwrapped, so only a real tuple describes a fixed length. ? number extends Tuple['length'] ? never // Read the length back off the built tuple so it stays consistent with the actual elements. `TupleOf` ignores a decimal part and turns a negative length into an empty tuple. : Omit<Tuple, ArrayLengthMutationKeys | number | 'length'> & {readonly length: Tuple['length']} : never; // Should never happen export {};