TypeScriptの省略可能な引数: ?、デフォルト値、残余引数

引数名のあとに ? を付けると、その引数は省略可能になります。呼び出し側は省略でき、関数の中での型には undefined が含まれます。

function greet(name: string, title?: string): string {
  // title is string | undefined here
  return title ? `Hello, ${title} ${name}` : `Hello, ${name}`;
}

console.log(greet("Lovelace"));          // Hello, Lovelace
console.log(greet("Lovelace", "Lady"));  // Hello, Lady Lovelace

TypeScriptは引数の数をチェックするので、? がなければ最初の呼び出しはコンパイルエラーになります: Expected 2 arguments, but got 1.（TS2554）。

省略可能な引数は undefined かもしれない

呼び出し側が省略できるので、省略可能な引数の関数内での型は T | undefined です。strictNullChecks のもとでは、T として使う前に undefined の場合を処理する必要があります。

function formatPrice(amount: number, currency?: string): string {
  // currency.toUpperCase() here would fail: 'currency' is possibly 'undefined'. (TS18048)
  const code = currency?.toUpperCase() ?? "USD";
  return `${amount.toFixed(2)} ${code}`;
}

console.log(formatPrice(9.5));        // 9.50 USD
console.log(formatPrice(12, "eur"));  // 12.00 EUR

ここでよく使うのはオプショナルチェーン（?.）と Null 合体演算子（??）です。代わりの値が決まっているなら、デフォルト引数のほうが短く書けます。

デフォルト引数

デフォルト値を付けると、呼び出し側にとって引数は省略可能になり、関数の中では undefined を含まない型になります。型はデフォルト値から推論されるので、型注釈はたいてい不要です。

function repeat(text: string, times = 2, separator: string = " "): string {
  // times: number, separator: string (never undefined here)
  return Array.from({ length: times }, () => text).join(separator);
}

console.log(repeat("ha"));              // ha ha
console.log(repeat("ha", 3, "-"));      // ha-ha-ha
console.log(repeat("ha", undefined, "")); // haha

呼び出し側から見たシグネチャは repeat(text: string, times?: number, separator?: string) です。デフォルト値はJavaScriptのルールに従います。引数が undefined のとき（省略した場合も明示的に渡した場合も）に使われ、null のときは使われません。デフォルト値の式では前の引数を使えます: function range(start: number, end = start + 10)。

引数の順序のルール

必須の引数の前にデフォルト値付きの引数を置くのは合法ですが、扱いにくくなります。呼び出し側から見た型は number | undefined になり、プレースホルダーとして undefined を書くのは誰にとっても面倒です。先頭の引数を柔軟にしたいなら、オプションオブジェクトか 関数のオーバーロード を使いましょう。

省略と undefined

x?: number と x: number | undefined は似ていて、関数の中では同じ型です。違うのは呼び出し側です。前者は省略でき、後者は渡さなければなりません。

function a(x?: number) { return x; }
function b(x: number | undefined) { return x; }

console.log(a());          // undefined
console.log(b(undefined)); // undefined
// @ts-expect-error: Expected 1 arguments, but got 0.
b();

値がなくてもよいが必ず渡す引数には | undefined を使い、すべての呼び出し側に考えさせます。省略するのがふつうの呼び出し方なら ? を使います。（メッセージが「1 arguments」となっているのは誤植ではなく、TypeScriptの表記です。）

残余引数

残余引数 ...name: T[] は、任意の数の引数を配列にまとめます。最後の引数でなければなりません。

function sum(...values: number[]): number {
  return values.reduce((total, v) => total + v, 0);
}

function tag(name: string, ...classes: string[]): string {
  return `<${name} class="${classes.join(" ")}">`;
}

console.log(sum());             // 0
console.log(sum(1, 2, 3));      // 6
const scores = [4, 8, 15];
console.log(sum(...scores));    // 27
console.log(tag("div", "card", "wide")); // <div class="card wide">

固定の引数に配列をスプレッドする場合はもっと厳しくなります。残余引数には任意の number[] をスプレッドできますが、(a: number, b: number) と宣言した関数には、長さがわかるタプルしかスプレッドできません:

function point(x: number, y: number) { return { x, y }; }

const list = [3, 4];            // number[]
point(...list);
// error TS2556: A spread argument must either have a tuple type or be passed to a rest parameter.

const pair = [3, 4] as const;   // readonly [3, 4]
point(...pair);                 // fine

残余引数にはタプル型も付けられ、位置ごとに型を指定できます: ...args: [name: string, age?: number]。

オプションオブジェクト

省略可能な引数が2つか3つを超えると、呼び出し側は引数の位置がわからなくなります。デフォルト値付きのオプションオブジェクトを使えば、名前付きで順序を気にしない引数になります。

interface FetchOptions {
  retries?: number;
  timeoutMs?: number;
  verbose?: boolean;
}

function fetchData(url: string, { retries = 3, timeoutMs = 5000, verbose = false }: FetchOptions = {}): string {
  return `${url} retries=${retries} timeout=${timeoutMs} verbose=${verbose}`;
}

console.log(fetchData("/a"));
// /a retries=3 timeout=5000 verbose=false
console.log(fetchData("/b", { verbose: true }));
// /b retries=3 timeout=5000 verbose=true

最後の = {} でオブジェクト全体が省略可能になります。これがないと fetchData("/a") はコンパイルエラー（Expected 2 arguments, but got 1.、TS2554）で、素のJavaScriptでは同じ呼び出しが実行時に TypeError を投げます。分割代入には読み取るオブジェクトが必要だからです。

コールバックの型の中の省略可能な引数

関数型の中の ? は「このコールバックの呼び出し側が渡さないかもしれない」という意味です。「コールバックが無視してよい」という意味ではありません。コールバックは後ろの引数をいつでも無視できます。ハンドラーが少ない引数を取れるようにするためだけに、コールバックの引数を省略可能にしてはいけません。

// Too loose: every handler must now cope with index being undefined
type Visit = (item: string, index?: number) => void;

// Right: the caller always passes both; handlers may use only item
type VisitStrict = (item: string, index: number) => void;
const log: VisitStrict = (item) => console.log(item);