type-fest
Version:
A collection of essential TypeScript types
83 lines (57 loc) • 2.45 kB
TypeScript
import type {NonEmptyTuple} from './non-empty-tuple.d.ts'; // For `@link`
import type {TupleOf} from './tuple-of.d.ts';
/**
Create an array type with at least the given number of elements of the given type.
Use-cases:
- Model data that requires a minimum number of items, like a sports team with at least 3 players or an auction with at least 2 competing bids.
- Type rest parameters to require a minimum number of arguments.
@example
```
import type {MinimumLengthArray} from 'type-fest';
type FencingTeam = MinimumLengthArray<string, 3>;
//=> [string, string, string, ...string[]]
const homeFencingTeam: FencingTeam = ['Josh', 'Michael', 'Robert'];
// @ts-expect-error
const awayFencingTeam: FencingTeam = ['George', 'John'];
// Error: Type '[string, string]' is not assignable to type '[string, string, string, ...string[]]'. Source has 2 element(s) but target requires 3.
```
@example
```
import type {MinimumLengthArray} from 'type-fest';
const average = (...numbers: MinimumLengthArray<number, 2>): number => numbers.reduce((total, value) => total + value, 0) / numbers.length;
average(1, 2);
// Ok
average(1, 2, 3);
// Ok
// @ts-expect-error
average(1);
// Error: Expected at least 2 arguments, but got 1.
```
Note: If the specified minimum is the non-literal `number` type, the result will not be a tuple but a regular array, since a minimum cannot be enforced for it.
@example
```
import type {MinimumLengthArray} from 'type-fest';
type StringArray = MinimumLengthArray<string, number>;
//=> string[]
```
Note: If the specified minimum is negative, the result will be a regular array.
@example
```
import type {MinimumLengthArray} from 'type-fest';
type NegativeMinimum = MinimumLengthArray<string, -3>;
//=> string[]
```
Note: If the specified minimum has a decimal part, the decimal part will be ignored.
@example
```
import type {MinimumLengthArray} from 'type-fest';
type DecimalMinimum = MinimumLengthArray<string, 2.5>;
//=> [string, string, ...string[]]
```
Note: If you need a readonly tuple, simply wrap this type with `Readonly`, for example, to create `readonly [string, string, ...string[]]` use `Readonly<MinimumLengthArray<string, 2>>`.
@see {@link TupleOf} for a tuple of an exact length.
@see {@link NonEmptyTuple} for a readonly tuple with one or more elements.
@category Array
*/
export type MinimumLengthArray<Element, Length extends number> = [...TupleOf<Length, Element>, ...Element[]];
export {};