type-fest
Version:
A collection of essential TypeScript types
112 lines (82 loc) • 3.44 kB
TypeScript
import type {If} from './if.d.ts';
import type {IfNotAnyOrNever} from './internal/type.d.ts';
import type {IsReadonlyArray} from './is-readonly-array.d.ts';
import type {TupleOf} from './tuple-of.d.ts';
import type {UnknownArray} from './unknown-array.d.ts';
import type {ArrayIndices} from './array-indices.d.ts'; // For `@link`
/**
Create a tuple type of the indices of a constant array or tuple.
Use-cases:
- Type a value that lists every index of a tuple.
- Pair each element of a dense tuple with its literal index in a mapped type.
@example
```
import type {IndexTuple} from 'type-fest';
type FruitIndices = IndexTuple<['apple', 'banana', 'plum']>;
//=> [0, 1, 2]
type FruitIndex = FruitIndices[number];
//=> 0 | 1 | 2
```
@example
```
import type {IndexTuple} from 'type-fest';
const values = ['a', 'b', 'c'] as const;
const positions: IndexTuple<typeof values> = [0, 1, 2];
```
@example
```
import type {IndexTuple, UnknownArray} from 'type-fest';
type Positioned<Tuple extends UnknownArray> = {
[Index in keyof Tuple]: [IndexTuple<Tuple>[Index & keyof IndexTuple<Tuple>], Tuple[Index]];
};
type FruitPositions = Positioned<['apple', 'banana', 'plum']>;
//=> [[0, 'apple'], [1, 'banana'], [2, 'plum']]
```
Note: The `Positioned` pattern above is only valid for a dense tuple. A tuple with optional elements gives a union of tuples, and indexing that union can pair an element with an index where it cannot appear.
Note: A variable-length array has no fixed length, so the result is `number[]` (or `readonly number[]`).
@example
```
import type {IndexTuple} from 'type-fest';
type AnyIndices = IndexTuple<string[]>;
//=> number[]
```
Note: A tuple with optional elements and no rest element gives a union of tuples, one per possible length.
@example
```
import type {IndexTuple} from 'type-fest';
type PartialIndices = IndexTuple<[string, number?]>;
//=> [0] | [0, 1]
```
Note: When the tuple's length is the non-literal `number` type (for example, it contains `...number[]`), the result is `number[]` instead of a tuple.
@example
```
import type {IndexTuple} from 'type-fest';
type RestIndices = IndexTuple<[string, ...number[]]>;
//=> number[]
```
Note: A readonly tuple or array gives a readonly result. A type that is not assignable to a mutable array, such as `FixedLengthArray`, also gives a readonly result.
@example
```
import type {IndexTuple} from 'type-fest';
type ReadonlyIndices = IndexTuple<readonly ['a', 'b']>;
//=> readonly [0, 1]
```
`IndexTuple` builds a tuple with `Element['length']` positions using `{@link TupleOf}`, then maps each position to its numeric index. A non-literal `number` length gives an array, and a union length gives a union of tuples.
@see {@link ArrayIndices} for the union of valid indices
@category Array
*/
export type IndexTuple<Element extends UnknownArray> = IfNotAnyOrNever<Element, {
ifNot: Element extends unknown // For distributing `Element`
? IndicesOfTuple<TupleOf<Element['length']>> extends infer Result
? If<IsReadonlyArray<Element>, Readonly<Result>, Result>
: never // Should never happen
: never; // Should never happen
ifAny: number[];
}>;
/**
Maps each key of a tuple to its numeric literal index, and an array's numeric index to `number`, so the result keeps the input's shape.
*/
type IndicesOfTuple<Tuple extends UnknownArray> = {
[Key in keyof Tuple]: Key extends `${infer Index extends number}` ? Index : number;
};
export {};