TypeScriptの関数オーバーロード: シグネチャの書き方

TypeScriptの関数オーバーロードとは、1つの関数に呼び出しシグネチャを複数書き、そのあとに実装を1つだけ書くことです。シグネチャごとに引数の型と戻り値の型の組み合わせを変えられ、呼び出し側は正確な型を受け取れます。

// Overload signatures: what callers see
function parse(input: string): number;
function parse(input: string[]): number[];
// Implementation: one body that handles every case
function parse(input: string | string[]): number | number[] {
  return Array.isArray(input) ? input.map(Number) : Number(input);
}

const one = parse("42");          // one: number
const many = parse(["1", "2.5"]); // many: number[]

console.log(one + 1);             // 43
console.log(many.map((n) => n * 2)); // [ 2, 5 ]

オーバーロードがなければ、parse はどの呼び出しでも number | number[] を返し、自分で結果を絞り込むまで one + 1 はエラーになります。

オーバーロードシグネチャと実装

オーバーロードされた関数は2つの部分からできています:

1. オーバーロードシグネチャ: 本体のない宣言で、対応する呼び出しの形ごとに1つ書きます。呼び出し側が使えるのはこのシグネチャだけです。
2. 実装シグネチャ: 本体を持つ最後の宣言です。引数はオーバーロードが受け付けるものをすべて受け付け、戻り値の型はすべてのオーバーロードの戻り値の型を含まなければなりません。外からは見えません。

型はコンパイル時にしか存在しないので、実行時のJavaScriptの関数は1つだけです。実装は引数を調べて（typeof、Array.isArray、arguments.length など）何をするかを決めます。オーバーロードと実装が一致しているかはコンパイラーがチェックします:

function format(value: string): string;
function format(value: number): number {
  return value;
}
// error TS2394: This overload signature is not compatible with its implementation signature.

実装の型を広げれば解決します: function format(value: string | number): string | number。

実装シグネチャは呼び出せない

いちばん意外に感じられるルールです。呼び出しは、オーバーロードシグネチャのどれか1つにそれだけで一致しなければなりません。TypeScriptはシグネチャを組み合わせてはくれません。

// This does not compile: no single overload takes string | string[].
function parse(input: string): number;
function parse(input: string[]): number[];
function parse(input: string | string[]): number | number[] {
  return Array.isArray(input) ? input.map(Number) : Number(input);
}

function readInput(multi: boolean): string | string[] {
  return multi ? ["1", "2"] : "3";
}

console.log(parse(readInput(true)));

コンパイラーの出力は次のとおりです:

index.ts(12,19): error TS2769: No overload matches this call.
  The last overload gave the following error.
    Argument of type 'string | string[]' is not assignable to parameter of type 'string[]'.
      Type 'string' is not assignable to type 'string[]'.

実装は string | string[] を受け付けますが、呼び出し側からは見えません。ユニオン型を受け取ってユニオン型を返す3つ目のオーバーロードを追加すると、呼び出しはコンパイルでき、[ 1, 2 ] が出力されます:

function parse(input: string): number;
function parse(input: string[]): number[];
function parse(input: string | string[]): number | number[];
function parse(input: string | string[]): number | number[] {
  return Array.isArray(input) ? input.map(Number) : Number(input);
}

引数の数が違う場合

オーバーロードは引数の数が違う呼び出しも表せます。次の例では、日付をタイムスタンプからも、年・月・日からも作れますが、2つの数値からは作れません:

function makeDate(timestamp: number): Date;
function makeDate(year: number, month: number, day: number): Date;
function makeDate(a: number, month?: number, day?: number): Date {
  if (month !== undefined && day !== undefined) {
    return new Date(Date.UTC(a, month - 1, day));
  }
  return new Date(a);
}

console.log(makeDate(0).toISOString());          // 1970-01-01T00:00:00.000Z
console.log(makeDate(2024, 3, 15).toISOString()); // 2024-03-15T00:00:00.000Z

// @ts-expect-error: No overload expects 2 arguments, but overloads do exist that expect either 1 or 3 arguments.
makeDate(2024, 3);

省略可能な引数を2つ持つ1つのシグネチャでは makeDate(2024, 3) が通ってしまい、黙って間違った日付が作られます。オーバーロードならこれがコンパイルエラー（TS2575）になります。

順序が重要

TypeScriptはオーバーロードを上から順に試し、最初に一致したものを選びます。具体的なシグネチャを先に書きましょう。広いオーバーロードを先に書くと、後ろのシグネチャ向けの呼び出しまで吸い込んでしまいます:

function describe(value: unknown): string;   // matches everything
function describe(value: string): "text";    // never chosen
function describe(value: unknown): string {
  return typeof value === "string" ? "text" : "other";
}

const d = describe("hi"); // d: string, not "text"

最初の2つのシグネチャを入れ替えると、describe("hi") の型は "text" になります。

オーバーロードかユニオン型の引数か

オーバーロードが行数に見合うのは、引数の型によって戻り値の型が変わるときです。そうでなければ、ユニオン型の引数を持つ1つのシグネチャのほうが短く読みやすく、オーバーロードでは拒否されるユニオン型の引数も受け付けます。

// Overloads that add nothing: the return type is always number
function lengthOfA(x: string): number;
function lengthOfA(x: unknown[]): number;
function lengthOfA(x: string | unknown[]): number {
  return x.length;
}

// Better: one signature
function lengthOf(x: string | unknown[]): number {
  return x.length;
}

function pick(useList: boolean): string | number[] {
  return useList ? [1, 2, 3] : "abc";
}

const input = pick(true);
console.log(lengthOf(input)); // 3 (lengthOfA(input) would be TS2769)
console.log(lengthOfA("abcd")); // 4

ジェネリクスと 条件型 を組み合わせると、一部のオーバーロードは1つのシグネチャで表せますが、ケースが2つか3つならオーバーロードのほうがたいてい読みやすくなります。

メソッドとコンストラクターのオーバーロード

クラスの中のメソッドも同じパターンで書きます。オーバーロードシグネチャのあとに本体を持つメソッドを書きます。コンストラクターも同じようにオーバーロードできます。

class Money {
  readonly cents: number;

  constructor(cents: number);
  constructor(amount: string);
  constructor(value: number | string) {
    this.cents = typeof value === "number" ? value : Math.round(parseFloat(value) * 100);
  }

  add(other: Money): Money;
  add(cents: number): Money;
  add(value: Money | number): Money {
    const extra = typeof value === "number" ? value : value.cents;
    return new Money(this.cents + extra);
  }
}

const price = new Money("19.99");
console.log(price.add(1).cents);               // 2000
console.log(price.add(new Money(1)).cents);    // 2000

インターフェースやオブジェクト型でも、複数の呼び出しシグネチャや同じ名前の複数のメソッドシグネチャとしてオーバーロードを宣言できます。組み込み関数の多くはこの方法で宣言されています。エディターで配列の reduce にカーソルを合わせると「+2 overloads」と表示されます。