TypeScriptのタプル: 構文、ラベル、省略可能・残余要素

TypeScriptのタプルは、要素数が決まっていて、位置ごとに型を持つ配列です。[string, number] は、最初が文字列で次が数値の、ちょうど2つの要素を表します。値が並ぶ順に、型を角かっこの中に書きます。

// A tuple type: position 0 is a string, position 1 is a number
let user: [string, number] = ["Ada", 36];

const userName = user[0]; // string
const age = user[1];      // number
console.log(userName.toUpperCase(), age + 1); // ADA 37

// Destructuring gives each element its own type
const [n, a] = user;
console.log(`${n} is ${a}`); // Ada is 36

user = ["Grace", 85];     // fine: same shape
console.log(user, user.length); // [ 'Grace', 85 ] 2

実行時のタプルはただのJavaScriptの配列です。タプルが加えるもの（固定の長さと各位置の型）はすべてコンパイラーがチェックし、そのあと消去されます。

タプルの構文

それぞれの書き方は以下で説明します。length の型に注目してください。固定のタプルではリテラル型なので、コンパイラーは pair.length がちょうど 2 だと知っています。

コンパイラーがチェックすること

タプル型は要素の数、順序、各位置の型を固定します。どれかを間違えるとコンパイルエラーです:

// This does not compile: wrong length, wrong order, index out of range.
const tooShort: [string, number] = ["Ada"];
const swapped: [string, number] = [36, "Ada"];
const ok: [string, number] = ["Ada", 36];
console.log(ok[2]);

index.ts(2,7): error TS2322: Type '[string]' is not assignable to type '[string, number]'.
  Source has 1 element(s) but target requires 2.
index.ts(3,36): error TS2322: Type 'number' is not assignable to type 'string'.
index.ts(3,40): error TS2322: Type 'string' is not assignable to type 'number'.
index.ts(5,16): error TS2493: Tuple type '[string, number]' of length '2' has no element at index '2'.

普通の配列では最後のエラーは検出できません。string[] では arr[2] はただの string で、実行時にたまたま undefined になるだけです。

ラベル付きタプル要素

ラベルは各位置の意味を示します。型やインデックスでのアクセスは何も変わりませんが、エディターのホバーやシグネチャのヒントに表示されるので、[number, number] がぐっとわかりやすくなります。

type Point = [x: number, y: number];
type Span = [start: number, end: number];
type HttpResult = [status: number, body: string];

function distance([x1, y1]: Point, [x2, y2]: Point): number {
    return Math.hypot(x2 - x1, y2 - y1);
}

const start: Point = [0, 0];
console.log(distance(start, [3, 4])); // 5

const result: HttpResult = [404, "Not Found"];
const [code, text] = result;
console.log(code, text); // 404 Not Found

TypeScript 5.2 からは、[first: string, number] のように一部の位置にだけラベルを付けられます。ラベルは読む人のためだけのものです。[x: number, y: number] と [number, number] は同じ型で、互いに代入できます。

省略可能な要素

要素の型のあとに ? を付けると、その位置は省略可能になります。省略可能な要素は必須の要素のあとに置く必要があり、そのたびに length の型が広がります。

type Rgb = [red: number, green: number, blue: number, alpha?: number];

const solid: Rgb = [255, 128, 0];
const faded: Rgb = [255, 128, 0, 0.5];

function toCss([r, g, b, a = 1]: Rgb): string {
    return `rgba(${r}, ${g}, ${b}, ${a})`;
}

console.log(toCss(solid)); // rgba(255, 128, 0, 1)
console.log(toCss(faded)); // rgba(255, 128, 0, 0.5)

const alpha = faded[3];   // number | undefined
const len = solid.length; // 3 | 4
console.log(alpha, len);  // 0.5 3

省略可能な要素を読むと T | undefined になるので、計算の前に分割代入のデフォルト値（a = 1）かチェックが必要です。

残余要素

残余要素 ...T[] は、T 型の要素が任意の個数並ぶことを表します。末尾、先頭、途中のどこにでも置けますが、1つのタプルにつき1つまでです。

// A label, then any number of scores
type Row = [name: string, ...scores: number[]];
const rows: Row[] = [["Ada", 90, 85], ["Grace", 77], ["Alan"]];

for (const [name, ...scores] of rows) {
    const avg = scores.length ? scores.reduce((a, b) => a + b, 0) / scores.length : 0;
    console.log(name, scores, avg);
}

// Any number of strings, then a number at the end
type PathAndSize = [...segments: string[], bytes: number];
const file: PathAndSize = ["home", "ada", "notes.txt", 2048];
console.log(file.at(-1)); // 2048

残余要素を持つタプルの length は、サイズが固定でなくなるので number です。固定されたままなのは、型の付いた位置がどこにあるかです。

readonly タプルと as const

readonly [T, U] は push、pop、splice、インデックスへの代入を取り除きます。長さが固定された値は本来こうあるべきです。配列リテラルのあとに as const と書くと、リテラル型の readonly タプルと推論されます。

const pair: readonly [string, number] = ["x", 1];
// @ts-expect-error: Cannot assign to '0' because it is a read-only property.
pair[0] = "y";
console.log(pair); // [ 'y', 1 ]: not frozen at runtime

// as const: a readonly tuple with the exact literal values
const corner = [10, 20] as const; // readonly [10, 20]
const [cx, cy] = corner;          // cx: 10, cy: 20
console.log(cx + cy);             // 30

// Useful for fixed lists of allowed values
const SIZES = ["small", "medium", "large"] as const;
type Size = (typeof SIZES)[number]; // "small" | "medium" | "large"
const pick: Size = "medium";
console.log(SIZES.length, pick);   // 3 medium

(typeof SIZES)[number] はタプルを要素の型のユニオンに変えます。このパターンはインデックスアクセス型で説明しています。readonly タプルは変更可能なタプルとして型付けされたパラメーターには渡せないので、読むだけの関数は readonly [number, number] を受け取るようにしましょう。

readonly のチェックはコンパイル時だけです。実行時の配列は凍結されていない（出力のとおり、上の代入は実際に実行されました）ので、実行時にも保証が必要なら Object.freeze を使います。

関数からタプルを返す

複数の値をタプルとして返すのは、React の useState のしくみです（const [value, setValue] = useState(0)）。落とし穴は、return の配列リテラルがタプルではなく配列と推論されることです。

// This does not compile: the return type was inferred as an array.
function useCounter(start: number) {
    let count = start;
    const increment = () => ++count;
    return [count, increment];
}

const [count, increment] = useCounter(10);
console.log(count + 1);
increment();

index.ts(9,13): error TS2365: Operator '+' cannot be applied to types 'number | (() => number)' and 'number'.
index.ts(10,1): error TS2349: This expression is not callable.
  Not all constituents of type 'number | (() => number)' are callable.
    Type 'number' has no call signatures.

この関数は (number | (() => number))[] を返すので、分割代入した2つの名前はどちらもユニオン型になります。直し方は2つあります。戻り値の型を書くか、as const を付けます。

// Fix 1: annotate the return type as a tuple
function useCounter(start: number): [number, () => number] {
    let count = start;
    return [count, () => ++count];
}

// Fix 2: as const infers readonly [boolean, () => boolean]
function useToggle(initial: boolean) {
    let on = initial;
    return [on, () => (on = !on)] as const;
}

const [count, increment] = useCounter(10);
console.log(count + 1, increment()); // 11 11

const [on, toggle] = useToggle(false);
console.log(on, toggle(), toggle()); // false true false

戻り値をタプルにすると、呼び出し側は各部分に好きな名前を付けられます。値が3つ以上ある場合や順序がわかりにくい場合は、代わりにオブジェクトを返しましょう。{ count, increment } なら説明がなくても意味がわかります。

関数のパラメーターとしてのタプル

タプルで型付けした残余パラメーターは、省略可能な引数も含めて引数リスト全体を表します。組み込みのユーティリティ型 Parameters<T> は、この方法で関数のパラメーターを表します。

function greet(...args: [name: string, times?: number]) {
    const [name, times = 1] = args;
    console.log(Array(times).fill(`Hi ${name}`).join(", "));
}

greet("Ada");     // Hi Ada
greet("Ada", 2);  // Hi Ada, Hi Ada

type GreetArgs = Parameters<typeof greet>; // [name: string, times?: number | undefined]
const saved: GreetArgs = ["Grace", 3];
greet(...saved); // Hi Grace, Hi Grace, Hi Grace

タプルを呼び出しにスプレッドすると、各引数が位置ごとに型チェックされます。(string | number)[] のスプレッドではこうはいきません。

タプルと配列の違い

タプルは組み込みの型にも登場します。Object.entries(obj) は [string, T][] を返し、Map は [key, value] のタプルから作られます:

const stock = { apples: 3, pears: 0 };

for (const [fruit, qty] of Object.entries(stock)) { // [string, number]
    console.log(fruit, qty > 0 ? "in stock" : "sold out");
}

const prices = new Map<string, number>([["tea", 2.5], ["coffee", 3.2]]);
const entries: [string, number][] = [...prices];
console.log(entries); // [ [ 'tea', 2.5 ], [ 'coffee', 3.2 ] ]

落とし穴がひとつあります。変更可能なタプルは配列のメソッドをすべて持っているので、[string, number] に対して pair.push(3) もコンパイルが通り、型は2つと言っているのに要素が3つの配列が黙って作られます。タプルを readonly で宣言すればこの穴はふさがります。また、型は消去されるので、プログラムの外から来るデータ（JSON や API）は実行時にタプル型でチェックされません。信頼する前に長さと要素の型を検証してください。

可変長タプル型

タプル型はほかのタプル型を [...T, ...U] のようにスプレッドできます。ジェネリクスと組み合わせると、すべての位置を保ったまま連結したり先頭に追加したりする関数に型を付けられます:

function concat<T extends unknown[], U extends unknown[]>(a: [...T], b: [...U]): [...T, ...U] {
    return [...a, ...b];
}

const joined = concat([1, "a"], [true]); // [number, string, boolean]
const [num, str, flag] = joined;
console.log(num.toFixed(1), str.toUpperCase(), !flag); // 1.0 A false

type WithId<T extends unknown[]> = [id: number, ...rest: T];
const row: WithId<[string, boolean]> = [7, "Ada", true];
console.log(row);

ライブラリの型もタプルの推論に頼っています。Promise.all([fetchUser(), fetchPosts()]) は、入力の Promise ごとにひとつの型を持つタプルに解決されます。