Add a generic way to specify length of a tuple type

[AlCalzone]

Search Terms

tuple, type, length

Suggestion

I'd like to see a way to specify the length of a tuple or array type when declaring it. For short tuples, it may be viable to write them out by hand like [number, number], but whenever the length is longer (say 10+), it becomes a chore.

Using the following approach to define a fixed-length tuple

// @ts-ignore interface can only extend interface or class
interface FixedLengthArray<T extends any[], L extends number> extends T {
	length: L;
}

has a few drawbacks:
1.: we cannot extend T because its not an interface or class.
2.: when ignoring that error, tuple literals are not inferred as tuples but as arrays when assigning them:

type Foo = FixedLengthArray<number[], 5>;
const foo1: Foo = [1, 2, 3, 4, 5]; // error: length is not compatible, number not assignable to 5
const foo2: Foo = [1, 2, 3, 4, 5] as [1, 2, 3, 4, 5]; // works, but defeats the purpose of that fixed-length

On the other hand, when using manually-written tuples, this works:

type Bar = [number, number, number, number, number];
const bar1: Bar = [1, 2, 3, 4, 5]; // no error

Use Cases

• Declaring fixed-length tuples or arrays with a large number of items
• Creating a Range union (e.g. 0 | 1 | 2 | 3 | 4 from the keys of such a type) without having to resort to recursive types (currently broken, see TSServer hangs when using recursive types on tuples and pressing "," #26155)

Examples

I'll leave the syntax up for discussion, and provide the length in the square brackets for now:

type T1 = number[3]; // equals [number, number, number]
type K1 = keyof T1; // 0 | 1 | 2
type T2 = number[100]; // equals [number, number, ..., number] (100 items total)
type K2 = keyof T2; // 0 | 1 | ... | 99
type T3 = any[0]; // equals [ ], type annotation is somewhat obsolete here
type K3 = keyof T3; // never

The basic rules for tuple assignability should apply, as if the types were written out by hand.

Related:

#24350
#18471

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript / JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. new expression-level syntax)

[j-oliveras]

You can already do it:

interface FixedLengthArray<T extends any, L extends number> extends Array<T> {
 0: T;
	length: L;
}

type Foo = FixedLengthArray<number, 5>;
const foo1: Foo = [1, 2, 3, 4, 5];

At playground.

[AlCalzone]

Oh I must have missed the trick with the 0 index. However it's not quite there, as keyof does not work like it does with tuples:

interface FixedLengthArray<T extends any, L extends number> extends Array<T> {
 "0": T;
 length: L;
}

type Foo = FixedLengthArray<number, 5>;
type Bar = [number, number, number, number, number];
type FooKey = Exclude<keyof Foo, keyof []>; // "0"
type BarKey = Exclude<keyof Bar, keyof []>; // "0" | "1" | "2" | "3" | "4"

[jcready]

@AlCalzone arrays can be sparse, tuples cannot:

const array = new Array(5)
const tuple = [1, 2, 3, 4, 5]

array.length === tuple.length // true

Object.keys(array) // []
Object.keys(tuple) // ["0", "1", "2", "3", "4"]

let arrayCount = 0
let tupleCount = 0

for (let i in array) { arrayCount++ }
for (let i in tuple) { tupleCount++ }

console.log(arrayCount, tupleCount); // 0 5

[AlCalzone]

@jcready I know, but I think you missed my point. I'm asking for a way to define a large tuple type for a generic length that behaves just like the ones we can write out by hand - except without writing them out by hand. See my OP:

type T1 = number[3]; // equals [number, number, number]
type K1 = keyof T1; // 0 | 1 | 2

or maybe

type T1 = Tuple<number, 3>; // equals [number, number, number]
type K1 = keyof T1; // 0 | 1 | 2

type T2 = Tuple<number, 100>; // equals [number, number, ..., number] (100 items total)
type K2 = keyof T2; // 0 | 1 | ... | 99

in case this makes the intent clearer.

I edited the issue title to reflect this intent, as sparse arrays do actually work.

[AlCalzone]

Some more context: It is currently possible to create a tuple of the type [N, N-1, ..., 0] using this code:

/**
 * Creates a union from the types of an Array or tuple
 */
type UnionOf<T extends any[]> = T[number];

/**
 * Returns the length of an array or tuple
 */
type LengthOf<T extends any[]> = T["length"];

/**
 * Returns all but the first item's type in a tuple/array
 */
export type Tail<T extends any[]> =
	((...args: T) => any) extends ((head: any, ...tail: infer R) => any) ? R : never;

/**
 * Returns the given tuple/array with the item type prepended to it
 */
type Unshift<List extends any[], Item> =
	((first: Item, ...rest: List) => any) extends ((...list: infer R) => any) ? R : never;

/**
 * Tests if two types are equal
 */
type Equals<T, S> =
	[T] extends [S] ? (
		[S] extends [T] ? true : false
	) : false;

type Range<N, T extends number[] = []> = {
	0: T,
	1: Range<N, Unshift<T, LengthOf<T>>>,
}[Equals<LengthOf<Tail<T>>, N> extends true ? 0 : 1];

For example:

type T1 = Range<3>; // [3, 2, 1, 0]
type K1 = UnionOf<T1>; // 0 | 1 | 2 | 3

but this stops working for N > 98 and often freezes TypeScript while editing (#26155)

[jcalz]

Those of us who want full-blown dependent types for tuples (for things like type-safe immutable tuple push/pop/concat/split/etc) should give this a big 👍 .

Is there a canonical issue for dependent types for tuples? Probably needs something like one or more of:

• compile-time number arithmetic (e.g., Add<2,2> ~ 4)
• compile-time number comparison (e.g., LessThan<0,3> ~ true)
• compile-time conversion between numeric string literals and number literals, (e.g., StrToNum<"0"> ~ 0)
• compile-time specification of strict tuples of a given length (e.g., TupleLen<3, string> ~ [string, string, string]) ← we are here
• compile-time specification of open-ended tuples of a given prefix length (e.g., OpenTupleLen<1, string> ~ [string, ...string[]])
• compile-time specification of (strict or open) tuples with optional elements starting at some index (e.g., TupleLenOptional<3, string, 1> ~ [string, string?, string?])

Most of the above can be faked up, at least for nonnegative integers less than some bound, via a bunch of hardcoded lookup types (or via the "scary" recursion of the form type R<T> ={0: B, 1: R<F<T>>}[T extends U ? 0 : 1]), but it would be amazing if it were officially supported by the language.

[AlCalzone]

Assume for my answers that:

• Tuple<T, 3> is equal to [T, T, T],
• Concat<A, B> is equal to [...A, ...B]. Does not work yet, but can be done using two recursive types (very prone to breaking).
• Range<N> returns a union 0 | 1 | ... | N

compile-time number arithmetic (e.g., Add<2,2> ~ 4)

LengthOf<Concat< Tuple<any, 2>, Tuple<any, 2> >>
Subtraction can probably done if mapped tuples support dropping values (#26190)

compile-time number comparison (e.g., LessThan<0,3> ~ true)

Works but suffers from the neccesity for recursive definition of Range<N>:

/** Tests if N > M */
type IsGreaterThan<N, M> = N extends Exclude<Range<N>, Range<M>> ? true : false;
/** Tests if N <= M */
type IsLessThanOrEqual<N, M> = Not<IsGreaterThan<N, M>>;
/** Tests if N < M */
type IsLessThan<N, M> = M extends Exclude<Range<M>, Range<N>> ? true : false;
/** Tests if N >= M */
type IsGreaterThanOrEqual<N, M> = Not<IsLessThan<N, M>>;

compile-time conversion between numeric string literals and number literals

Yes, please!

compile-time specification of open-ended tuples of a given prefix length
and: compile-time specification of (strict or open) tuples with optional elements starting at some index

Could be done by concatenation of a fixed-length tuple and an array (when that works): [...fixed, ...array] or [...fixed, ...optional]

[KiaraGrouwstra]

well, here's my scary recursive tuple generator @AlCalzone: Vector.
It predated features like conditional types, so shinier (and more importantly, more robust) versions may be doable now.

Add<2,2> ~ 4 - LengthOf<Concat<Tuple<any, 2>, Tuple<any, 2>>>

That's pretty creative 😄, if we had recursion-free Concat ([...T]) and Tuple then we'd have a recursion-free Add too!

others mentioned by @jcalz I recall hacky / legit implementations for:

• LessThan
• StrToNum
• OpenTupleLen - Tuples in rest parameters and spread expressions #24897's "Optional elements in tuple types"
• TupleLenOptional - Tuples in rest parameters and spread expressions #24897's "Rest elements in tuple types"